diff options
Diffstat (limited to 'include/mtd')
-rw-r--r-- | include/mtd/Kbuild | 2 | ||||
-rw-r--r-- | include/mtd/mtd-abi.h | 1 | ||||
-rw-r--r-- | include/mtd/ubi-header.h | 360 | ||||
-rw-r--r-- | include/mtd/ubi-user.h | 161 |
4 files changed, 524 insertions, 0 deletions
diff --git a/include/mtd/Kbuild b/include/mtd/Kbuild index e0fe92b03a4e..4d46b3bdebd8 100644 --- a/include/mtd/Kbuild +++ b/include/mtd/Kbuild | |||
@@ -3,3 +3,5 @@ header-y += jffs2-user.h | |||
3 | header-y += mtd-abi.h | 3 | header-y += mtd-abi.h |
4 | header-y += mtd-user.h | 4 | header-y += mtd-user.h |
5 | header-y += nftl-user.h | 5 | header-y += nftl-user.h |
6 | header-y += ubi-header.h | ||
7 | header-y += ubi-user.h | ||
diff --git a/include/mtd/mtd-abi.h b/include/mtd/mtd-abi.h index 8e501a75a764..f71dac420394 100644 --- a/include/mtd/mtd-abi.h +++ b/include/mtd/mtd-abi.h | |||
@@ -24,6 +24,7 @@ struct mtd_oob_buf { | |||
24 | #define MTD_NORFLASH 3 | 24 | #define MTD_NORFLASH 3 |
25 | #define MTD_NANDFLASH 4 | 25 | #define MTD_NANDFLASH 4 |
26 | #define MTD_DATAFLASH 6 | 26 | #define MTD_DATAFLASH 6 |
27 | #define MTD_UBIVOLUME 7 | ||
27 | 28 | ||
28 | #define MTD_WRITEABLE 0x400 /* Device is writeable */ | 29 | #define MTD_WRITEABLE 0x400 /* Device is writeable */ |
29 | #define MTD_BIT_WRITEABLE 0x800 /* Single bits can be flipped */ | 30 | #define MTD_BIT_WRITEABLE 0x800 /* Single bits can be flipped */ |
diff --git a/include/mtd/ubi-header.h b/include/mtd/ubi-header.h new file mode 100644 index 000000000000..fa479c71aa34 --- /dev/null +++ b/include/mtd/ubi-header.h | |||
@@ -0,0 +1,360 @@ | |||
1 | /* | ||
2 | * Copyright (c) International Business Machines Corp., 2006 | ||
3 | * | ||
4 | * This program is free software; you can redistribute it and/or modify | ||
5 | * it under the terms of the GNU General Public License as published by | ||
6 | * the Free Software Foundation; either version 2 of the License, or | ||
7 | * (at your option) any later version. | ||
8 | * | ||
9 | * This program is distributed in the hope that it will be useful, | ||
10 | * but WITHOUT ANY WARRANTY; without even the implied warranty of | ||
11 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See | ||
12 | * the GNU General Public License for more details. | ||
13 | * | ||
14 | * You should have received a copy of the GNU General Public License | ||
15 | * along with this program; if not, write to the Free Software | ||
16 | * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA | ||
17 | * | ||
18 | * Authors: Artem Bityutskiy (Битюцкий Артём) | ||
19 | * Thomas Gleixner | ||
20 | * Frank Haverkamp | ||
21 | * Oliver Lohmann | ||
22 | * Andreas Arnez | ||
23 | */ | ||
24 | |||
25 | /* | ||
26 | * This file defines the layout of UBI headers and all the other UBI on-flash | ||
27 | * data structures. May be included by user-space. | ||
28 | */ | ||
29 | |||
30 | #ifndef __UBI_HEADER_H__ | ||
31 | #define __UBI_HEADER_H__ | ||
32 | |||
33 | #include <asm/byteorder.h> | ||
34 | |||
35 | /* The version of UBI images supported by this implementation */ | ||
36 | #define UBI_VERSION 1 | ||
37 | |||
38 | /* The highest erase counter value supported by this implementation */ | ||
39 | #define UBI_MAX_ERASECOUNTER 0x7FFFFFFF | ||
40 | |||
41 | /* The initial CRC32 value used when calculating CRC checksums */ | ||
42 | #define UBI_CRC32_INIT 0xFFFFFFFFU | ||
43 | |||
44 | /* Erase counter header magic number (ASCII "UBI#") */ | ||
45 | #define UBI_EC_HDR_MAGIC 0x55424923 | ||
46 | /* Volume identifier header magic number (ASCII "UBI!") */ | ||
47 | #define UBI_VID_HDR_MAGIC 0x55424921 | ||
48 | |||
49 | /* | ||
50 | * Volume type constants used in the volume identifier header. | ||
51 | * | ||
52 | * @UBI_VID_DYNAMIC: dynamic volume | ||
53 | * @UBI_VID_STATIC: static volume | ||
54 | */ | ||
55 | enum { | ||
56 | UBI_VID_DYNAMIC = 1, | ||
57 | UBI_VID_STATIC = 2 | ||
58 | }; | ||
59 | |||
60 | /* | ||
61 | * Compatibility constants used by internal volumes. | ||
62 | * | ||
63 | * @UBI_COMPAT_DELETE: delete this internal volume before anything is written | ||
64 | * to the flash | ||
65 | * @UBI_COMPAT_RO: attach this device in read-only mode | ||
66 | * @UBI_COMPAT_PRESERVE: preserve this internal volume - do not touch its | ||
67 | * physical eraseblocks, don't allow the wear-leveling unit to move them | ||
68 | * @UBI_COMPAT_REJECT: reject this UBI image | ||
69 | */ | ||
70 | enum { | ||
71 | UBI_COMPAT_DELETE = 1, | ||
72 | UBI_COMPAT_RO = 2, | ||
73 | UBI_COMPAT_PRESERVE = 4, | ||
74 | UBI_COMPAT_REJECT = 5 | ||
75 | }; | ||
76 | |||
77 | /* | ||
78 | * ubi16_t/ubi32_t/ubi64_t - 16, 32, and 64-bit integers used in UBI on-flash | ||
79 | * data structures. | ||
80 | */ | ||
81 | typedef struct { | ||
82 | uint16_t int16; | ||
83 | } __attribute__ ((packed)) ubi16_t; | ||
84 | |||
85 | typedef struct { | ||
86 | uint32_t int32; | ||
87 | } __attribute__ ((packed)) ubi32_t; | ||
88 | |||
89 | typedef struct { | ||
90 | uint64_t int64; | ||
91 | } __attribute__ ((packed)) ubi64_t; | ||
92 | |||
93 | /* | ||
94 | * In this implementation of UBI uses the big-endian format for on-flash | ||
95 | * integers. The below are the corresponding conversion macros. | ||
96 | */ | ||
97 | #define cpu_to_ubi16(x) ((ubi16_t){__cpu_to_be16(x)}) | ||
98 | #define ubi16_to_cpu(x) ((uint16_t)__be16_to_cpu((x).int16)) | ||
99 | |||
100 | #define cpu_to_ubi32(x) ((ubi32_t){__cpu_to_be32(x)}) | ||
101 | #define ubi32_to_cpu(x) ((uint32_t)__be32_to_cpu((x).int32)) | ||
102 | |||
103 | #define cpu_to_ubi64(x) ((ubi64_t){__cpu_to_be64(x)}) | ||
104 | #define ubi64_to_cpu(x) ((uint64_t)__be64_to_cpu((x).int64)) | ||
105 | |||
106 | /* Sizes of UBI headers */ | ||
107 | #define UBI_EC_HDR_SIZE sizeof(struct ubi_ec_hdr) | ||
108 | #define UBI_VID_HDR_SIZE sizeof(struct ubi_vid_hdr) | ||
109 | |||
110 | /* Sizes of UBI headers without the ending CRC */ | ||
111 | #define UBI_EC_HDR_SIZE_CRC (UBI_EC_HDR_SIZE - sizeof(ubi32_t)) | ||
112 | #define UBI_VID_HDR_SIZE_CRC (UBI_VID_HDR_SIZE - sizeof(ubi32_t)) | ||
113 | |||
114 | /** | ||
115 | * struct ubi_ec_hdr - UBI erase counter header. | ||
116 | * @magic: erase counter header magic number (%UBI_EC_HDR_MAGIC) | ||
117 | * @version: version of UBI implementation which is supposed to accept this | ||
118 | * UBI image | ||
119 | * @padding1: reserved for future, zeroes | ||
120 | * @ec: the erase counter | ||
121 | * @vid_hdr_offset: where the VID header starts | ||
122 | * @data_offset: where the user data start | ||
123 | * @padding2: reserved for future, zeroes | ||
124 | * @hdr_crc: erase counter header CRC checksum | ||
125 | * | ||
126 | * The erase counter header takes 64 bytes and has a plenty of unused space for | ||
127 | * future usage. The unused fields are zeroed. The @version field is used to | ||
128 | * indicate the version of UBI implementation which is supposed to be able to | ||
129 | * work with this UBI image. If @version is greater then the current UBI | ||
130 | * version, the image is rejected. This may be useful in future if something | ||
131 | * is changed radically. This field is duplicated in the volume identifier | ||
132 | * header. | ||
133 | * | ||
134 | * The @vid_hdr_offset and @data_offset fields contain the offset of the the | ||
135 | * volume identifier header and user data, relative to the beginning of the | ||
136 | * physical eraseblock. These values have to be the same for all physical | ||
137 | * eraseblocks. | ||
138 | */ | ||
139 | struct ubi_ec_hdr { | ||
140 | ubi32_t magic; | ||
141 | uint8_t version; | ||
142 | uint8_t padding1[3]; | ||
143 | ubi64_t ec; /* Warning: the current limit is 31-bit anyway! */ | ||
144 | ubi32_t vid_hdr_offset; | ||
145 | ubi32_t data_offset; | ||
146 | uint8_t padding2[36]; | ||
147 | ubi32_t hdr_crc; | ||
148 | } __attribute__ ((packed)); | ||
149 | |||
150 | /** | ||
151 | * struct ubi_vid_hdr - on-flash UBI volume identifier header. | ||
152 | * @magic: volume identifier header magic number (%UBI_VID_HDR_MAGIC) | ||
153 | * @version: UBI implementation version which is supposed to accept this UBI | ||
154 | * image (%UBI_VERSION) | ||
155 | * @vol_type: volume type (%UBI_VID_DYNAMIC or %UBI_VID_STATIC) | ||
156 | * @copy_flag: if this logical eraseblock was copied from another physical | ||
157 | * eraseblock (for wear-leveling reasons) | ||
158 | * @compat: compatibility of this volume (%0, %UBI_COMPAT_DELETE, | ||
159 | * %UBI_COMPAT_IGNORE, %UBI_COMPAT_PRESERVE, or %UBI_COMPAT_REJECT) | ||
160 | * @vol_id: ID of this volume | ||
161 | * @lnum: logical eraseblock number | ||
162 | * @leb_ver: version of this logical eraseblock (IMPORTANT: obsolete, to be | ||
163 | * removed, kept only for not breaking older UBI users) | ||
164 | * @data_size: how many bytes of data this logical eraseblock contains | ||
165 | * @used_ebs: total number of used logical eraseblocks in this volume | ||
166 | * @data_pad: how many bytes at the end of this physical eraseblock are not | ||
167 | * used | ||
168 | * @data_crc: CRC checksum of the data stored in this logical eraseblock | ||
169 | * @padding1: reserved for future, zeroes | ||
170 | * @sqnum: sequence number | ||
171 | * @padding2: reserved for future, zeroes | ||
172 | * @hdr_crc: volume identifier header CRC checksum | ||
173 | * | ||
174 | * The @sqnum is the value of the global sequence counter at the time when this | ||
175 | * VID header was created. The global sequence counter is incremented each time | ||
176 | * UBI writes a new VID header to the flash, i.e. when it maps a logical | ||
177 | * eraseblock to a new physical eraseblock. The global sequence counter is an | ||
178 | * unsigned 64-bit integer and we assume it never overflows. The @sqnum | ||
179 | * (sequence number) is used to distinguish between older and newer versions of | ||
180 | * logical eraseblocks. | ||
181 | * | ||
182 | * There are 2 situations when there may be more then one physical eraseblock | ||
183 | * corresponding to the same logical eraseblock, i.e., having the same @vol_id | ||
184 | * and @lnum values in the volume identifier header. Suppose we have a logical | ||
185 | * eraseblock L and it is mapped to the physical eraseblock P. | ||
186 | * | ||
187 | * 1. Because UBI may erase physical eraseblocks asynchronously, the following | ||
188 | * situation is possible: L is asynchronously erased, so P is scheduled for | ||
189 | * erasure, then L is written to,i.e. mapped to another physical eraseblock P1, | ||
190 | * so P1 is written to, then an unclean reboot happens. Result - there are 2 | ||
191 | * physical eraseblocks P and P1 corresponding to the same logical eraseblock | ||
192 | * L. But P1 has greater sequence number, so UBI picks P1 when it attaches the | ||
193 | * flash. | ||
194 | * | ||
195 | * 2. From time to time UBI moves logical eraseblocks to other physical | ||
196 | * eraseblocks for wear-leveling reasons. If, for example, UBI moves L from P | ||
197 | * to P1, and an unclean reboot happens before P is physically erased, there | ||
198 | * are two physical eraseblocks P and P1 corresponding to L and UBI has to | ||
199 | * select one of them when the flash is attached. The @sqnum field says which | ||
200 | * PEB is the original (obviously P will have lower @sqnum) and the copy. But | ||
201 | * it is not enough to select the physical eraseblock with the higher sequence | ||
202 | * number, because the unclean reboot could have happen in the middle of the | ||
203 | * copying process, so the data in P is corrupted. It is also not enough to | ||
204 | * just select the physical eraseblock with lower sequence number, because the | ||
205 | * data there may be old (consider a case if more data was added to P1 after | ||
206 | * the copying). Moreover, the unclean reboot may happen when the erasure of P | ||
207 | * was just started, so it result in unstable P, which is "mostly" OK, but | ||
208 | * still has unstable bits. | ||
209 | * | ||
210 | * UBI uses the @copy_flag field to indicate that this logical eraseblock is a | ||
211 | * copy. UBI also calculates data CRC when the data is moved and stores it at | ||
212 | * the @data_crc field of the copy (P1). So when UBI needs to pick one physical | ||
213 | * eraseblock of two (P or P1), the @copy_flag of the newer one (P1) is | ||
214 | * examined. If it is cleared, the situation* is simple and the newer one is | ||
215 | * picked. If it is set, the data CRC of the copy (P1) is examined. If the CRC | ||
216 | * checksum is correct, this physical eraseblock is selected (P1). Otherwise | ||
217 | * the older one (P) is selected. | ||
218 | * | ||
219 | * Note, there is an obsolete @leb_ver field which was used instead of @sqnum | ||
220 | * in the past. But it is not used anymore and we keep it in order to be able | ||
221 | * to deal with old UBI images. It will be removed at some point. | ||
222 | * | ||
223 | * There are 2 sorts of volumes in UBI: user volumes and internal volumes. | ||
224 | * Internal volumes are not seen from outside and are used for various internal | ||
225 | * UBI purposes. In this implementation there is only one internal volume - the | ||
226 | * layout volume. Internal volumes are the main mechanism of UBI extensions. | ||
227 | * For example, in future one may introduce a journal internal volume. Internal | ||
228 | * volumes have their own reserved range of IDs. | ||
229 | * | ||
230 | * The @compat field is only used for internal volumes and contains the "degree | ||
231 | * of their compatibility". It is always zero for user volumes. This field | ||
232 | * provides a mechanism to introduce UBI extensions and to be still compatible | ||
233 | * with older UBI binaries. For example, if someone introduced a journal in | ||
234 | * future, he would probably use %UBI_COMPAT_DELETE compatibility for the | ||
235 | * journal volume. And in this case, older UBI binaries, which know nothing | ||
236 | * about the journal volume, would just delete this volume and work perfectly | ||
237 | * fine. This is similar to what Ext2fs does when it is fed by an Ext3fs image | ||
238 | * - it just ignores the Ext3fs journal. | ||
239 | * | ||
240 | * The @data_crc field contains the CRC checksum of the contents of the logical | ||
241 | * eraseblock if this is a static volume. In case of dynamic volumes, it does | ||
242 | * not contain the CRC checksum as a rule. The only exception is when the | ||
243 | * data of the physical eraseblock was moved by the wear-leveling unit, then | ||
244 | * the wear-leveling unit calculates the data CRC and stores it in the | ||
245 | * @data_crc field. And of course, the @copy_flag is %in this case. | ||
246 | * | ||
247 | * The @data_size field is used only for static volumes because UBI has to know | ||
248 | * how many bytes of data are stored in this eraseblock. For dynamic volumes, | ||
249 | * this field usually contains zero. The only exception is when the data of the | ||
250 | * physical eraseblock was moved to another physical eraseblock for | ||
251 | * wear-leveling reasons. In this case, UBI calculates CRC checksum of the | ||
252 | * contents and uses both @data_crc and @data_size fields. In this case, the | ||
253 | * @data_size field contains data size. | ||
254 | * | ||
255 | * The @used_ebs field is used only for static volumes and indicates how many | ||
256 | * eraseblocks the data of the volume takes. For dynamic volumes this field is | ||
257 | * not used and always contains zero. | ||
258 | * | ||
259 | * The @data_pad is calculated when volumes are created using the alignment | ||
260 | * parameter. So, effectively, the @data_pad field reduces the size of logical | ||
261 | * eraseblocks of this volume. This is very handy when one uses block-oriented | ||
262 | * software (say, cramfs) on top of the UBI volume. | ||
263 | */ | ||
264 | struct ubi_vid_hdr { | ||
265 | ubi32_t magic; | ||
266 | uint8_t version; | ||
267 | uint8_t vol_type; | ||
268 | uint8_t copy_flag; | ||
269 | uint8_t compat; | ||
270 | ubi32_t vol_id; | ||
271 | ubi32_t lnum; | ||
272 | ubi32_t leb_ver; /* obsolete, to be removed, don't use */ | ||
273 | ubi32_t data_size; | ||
274 | ubi32_t used_ebs; | ||
275 | ubi32_t data_pad; | ||
276 | ubi32_t data_crc; | ||
277 | uint8_t padding1[4]; | ||
278 | ubi64_t sqnum; | ||
279 | uint8_t padding2[12]; | ||
280 | ubi32_t hdr_crc; | ||
281 | } __attribute__ ((packed)); | ||
282 | |||
283 | /* Internal UBI volumes count */ | ||
284 | #define UBI_INT_VOL_COUNT 1 | ||
285 | |||
286 | /* | ||
287 | * Starting ID of internal volumes. There is reserved room for 4096 internal | ||
288 | * volumes. | ||
289 | */ | ||
290 | #define UBI_INTERNAL_VOL_START (0x7FFFFFFF - 4096) | ||
291 | |||
292 | /* The layout volume contains the volume table */ | ||
293 | |||
294 | #define UBI_LAYOUT_VOL_ID UBI_INTERNAL_VOL_START | ||
295 | #define UBI_LAYOUT_VOLUME_EBS 2 | ||
296 | #define UBI_LAYOUT_VOLUME_NAME "layout volume" | ||
297 | #define UBI_LAYOUT_VOLUME_COMPAT UBI_COMPAT_REJECT | ||
298 | |||
299 | /* The maximum number of volumes per one UBI device */ | ||
300 | #define UBI_MAX_VOLUMES 128 | ||
301 | |||
302 | /* The maximum volume name length */ | ||
303 | #define UBI_VOL_NAME_MAX 127 | ||
304 | |||
305 | /* Size of the volume table record */ | ||
306 | #define UBI_VTBL_RECORD_SIZE sizeof(struct ubi_vtbl_record) | ||
307 | |||
308 | /* Size of the volume table record without the ending CRC */ | ||
309 | #define UBI_VTBL_RECORD_SIZE_CRC (UBI_VTBL_RECORD_SIZE - sizeof(ubi32_t)) | ||
310 | |||
311 | /** | ||
312 | * struct ubi_vtbl_record - a record in the volume table. | ||
313 | * @reserved_pebs: how many physical eraseblocks are reserved for this volume | ||
314 | * @alignment: volume alignment | ||
315 | * @data_pad: how many bytes are unused at the end of the each physical | ||
316 | * eraseblock to satisfy the requested alignment | ||
317 | * @vol_type: volume type (%UBI_DYNAMIC_VOLUME or %UBI_STATIC_VOLUME) | ||
318 | * @upd_marker: if volume update was started but not finished | ||
319 | * @name_len: volume name length | ||
320 | * @name: the volume name | ||
321 | * @padding2: reserved, zeroes | ||
322 | * @crc: a CRC32 checksum of the record | ||
323 | * | ||
324 | * The volume table records are stored in the volume table, which is stored in | ||
325 | * the layout volume. The layout volume consists of 2 logical eraseblock, each | ||
326 | * of which contains a copy of the volume table (i.e., the volume table is | ||
327 | * duplicated). The volume table is an array of &struct ubi_vtbl_record | ||
328 | * objects indexed by the volume ID. | ||
329 | * | ||
330 | * If the size of the logical eraseblock is large enough to fit | ||
331 | * %UBI_MAX_VOLUMES records, the volume table contains %UBI_MAX_VOLUMES | ||
332 | * records. Otherwise, it contains as many records as it can fit (i.e., size of | ||
333 | * logical eraseblock divided by sizeof(struct ubi_vtbl_record)). | ||
334 | * | ||
335 | * The @upd_marker flag is used to implement volume update. It is set to %1 | ||
336 | * before update and set to %0 after the update. So if the update operation was | ||
337 | * interrupted, UBI knows that the volume is corrupted. | ||
338 | * | ||
339 | * The @alignment field is specified when the volume is created and cannot be | ||
340 | * later changed. It may be useful, for example, when a block-oriented file | ||
341 | * system works on top of UBI. The @data_pad field is calculated using the | ||
342 | * logical eraseblock size and @alignment. The alignment must be multiple to the | ||
343 | * minimal flash I/O unit. If @alignment is 1, all the available space of | ||
344 | * the physical eraseblocks is used. | ||
345 | * | ||
346 | * Empty records contain all zeroes and the CRC checksum of those zeroes. | ||
347 | */ | ||
348 | struct ubi_vtbl_record { | ||
349 | ubi32_t reserved_pebs; | ||
350 | ubi32_t alignment; | ||
351 | ubi32_t data_pad; | ||
352 | uint8_t vol_type; | ||
353 | uint8_t upd_marker; | ||
354 | ubi16_t name_len; | ||
355 | uint8_t name[UBI_VOL_NAME_MAX+1]; | ||
356 | uint8_t padding2[24]; | ||
357 | ubi32_t crc; | ||
358 | } __attribute__ ((packed)); | ||
359 | |||
360 | #endif /* !__UBI_HEADER_H__ */ | ||
diff --git a/include/mtd/ubi-user.h b/include/mtd/ubi-user.h new file mode 100644 index 000000000000..fe06ded0e6b8 --- /dev/null +++ b/include/mtd/ubi-user.h | |||
@@ -0,0 +1,161 @@ | |||
1 | /* | ||
2 | * Copyright (c) International Business Machines Corp., 2006 | ||
3 | * | ||
4 | * This program is free software; you can redistribute it and/or modify | ||
5 | * it under the terms of the GNU General Public License as published by | ||
6 | * the Free Software Foundation; either version 2 of the License, or | ||
7 | * (at your option) any later version. | ||
8 | * | ||
9 | * This program is distributed in the hope that it will be useful, | ||
10 | * but WITHOUT ANY WARRANTY; without even the implied warranty of | ||
11 | * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See | ||
12 | * the GNU General Public License for more details. | ||
13 | * | ||
14 | * You should have received a copy of the GNU General Public License | ||
15 | * along with this program; if not, write to the Free Software | ||
16 | * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA | ||
17 | * | ||
18 | * Author: Artem Bityutskiy (Битюцкий Артём) | ||
19 | */ | ||
20 | |||
21 | #ifndef __UBI_USER_H__ | ||
22 | #define __UBI_USER_H__ | ||
23 | |||
24 | /* | ||
25 | * UBI volume creation | ||
26 | * ~~~~~~~~~~~~~~~~~~~ | ||
27 | * | ||
28 | * UBI volumes are created via the %UBI_IOCMKVOL IOCTL command of UBI character | ||
29 | * device. A &struct ubi_mkvol_req object has to be properly filled and a | ||
30 | * pointer to it has to be passed to the IOCTL. | ||
31 | * | ||
32 | * UBI volume deletion | ||
33 | * ~~~~~~~~~~~~~~~~~~~ | ||
34 | * | ||
35 | * To delete a volume, the %UBI_IOCRMVOL IOCTL command of the UBI character | ||
36 | * device should be used. A pointer to the 32-bit volume ID hast to be passed | ||
37 | * to the IOCTL. | ||
38 | * | ||
39 | * UBI volume re-size | ||
40 | * ~~~~~~~~~~~~~~~~~~ | ||
41 | * | ||
42 | * To re-size a volume, the %UBI_IOCRSVOL IOCTL command of the UBI character | ||
43 | * device should be used. A &struct ubi_rsvol_req object has to be properly | ||
44 | * filled and a pointer to it has to be passed to the IOCTL. | ||
45 | * | ||
46 | * UBI volume update | ||
47 | * ~~~~~~~~~~~~~~~~~ | ||
48 | * | ||
49 | * Volume update should be done via the %UBI_IOCVOLUP IOCTL command of the | ||
50 | * corresponding UBI volume character device. A pointer to a 64-bit update | ||
51 | * size should be passed to the IOCTL. After then, UBI expects user to write | ||
52 | * this number of bytes to the volume character device. The update is finished | ||
53 | * when the claimed number of bytes is passed. So, the volume update sequence | ||
54 | * is something like: | ||
55 | * | ||
56 | * fd = open("/dev/my_volume"); | ||
57 | * ioctl(fd, UBI_IOCVOLUP, &image_size); | ||
58 | * write(fd, buf, image_size); | ||
59 | * close(fd); | ||
60 | */ | ||
61 | |||
62 | /* | ||
63 | * When a new volume is created, users may either specify the volume number they | ||
64 | * want to create or to let UBI automatically assign a volume number using this | ||
65 | * constant. | ||
66 | */ | ||
67 | #define UBI_VOL_NUM_AUTO (-1) | ||
68 | |||
69 | /* Maximum volume name length */ | ||
70 | #define UBI_MAX_VOLUME_NAME 127 | ||
71 | |||
72 | /* IOCTL commands of UBI character devices */ | ||
73 | |||
74 | #define UBI_IOC_MAGIC 'o' | ||
75 | |||
76 | /* Create an UBI volume */ | ||
77 | #define UBI_IOCMKVOL _IOW(UBI_IOC_MAGIC, 0, struct ubi_mkvol_req) | ||
78 | /* Remove an UBI volume */ | ||
79 | #define UBI_IOCRMVOL _IOW(UBI_IOC_MAGIC, 1, int32_t) | ||
80 | /* Re-size an UBI volume */ | ||
81 | #define UBI_IOCRSVOL _IOW(UBI_IOC_MAGIC, 2, struct ubi_rsvol_req) | ||
82 | |||
83 | /* IOCTL commands of UBI volume character devices */ | ||
84 | |||
85 | #define UBI_VOL_IOC_MAGIC 'O' | ||
86 | |||
87 | /* Start UBI volume update */ | ||
88 | #define UBI_IOCVOLUP _IOW(UBI_VOL_IOC_MAGIC, 0, int64_t) | ||
89 | /* An eraseblock erasure command, used for debugging, disabled by default */ | ||
90 | #define UBI_IOCEBER _IOW(UBI_VOL_IOC_MAGIC, 1, int32_t) | ||
91 | |||
92 | /* | ||
93 | * UBI volume type constants. | ||
94 | * | ||
95 | * @UBI_DYNAMIC_VOLUME: dynamic volume | ||
96 | * @UBI_STATIC_VOLUME: static volume | ||
97 | */ | ||
98 | enum { | ||
99 | UBI_DYNAMIC_VOLUME = 3, | ||
100 | UBI_STATIC_VOLUME = 4 | ||
101 | }; | ||
102 | |||
103 | /** | ||
104 | * struct ubi_mkvol_req - volume description data structure used in | ||
105 | * volume creation requests. | ||
106 | * @vol_id: volume number | ||
107 | * @alignment: volume alignment | ||
108 | * @bytes: volume size in bytes | ||
109 | * @vol_type: volume type (%UBI_DYNAMIC_VOLUME or %UBI_STATIC_VOLUME) | ||
110 | * @padding1: reserved for future, not used | ||
111 | * @name_len: volume name length | ||
112 | * @padding2: reserved for future, not used | ||
113 | * @name: volume name | ||
114 | * | ||
115 | * This structure is used by userspace programs when creating new volumes. The | ||
116 | * @used_bytes field is only necessary when creating static volumes. | ||
117 | * | ||
118 | * The @alignment field specifies the required alignment of the volume logical | ||
119 | * eraseblock. This means, that the size of logical eraseblocks will be aligned | ||
120 | * to this number, i.e., | ||
121 | * (UBI device logical eraseblock size) mod (@alignment) = 0. | ||
122 | * | ||
123 | * To put it differently, the logical eraseblock of this volume may be slightly | ||
124 | * shortened in order to make it properly aligned. The alignment has to be | ||
125 | * multiple of the flash minimal input/output unit, or %1 to utilize the entire | ||
126 | * available space of logical eraseblocks. | ||
127 | * | ||
128 | * The @alignment field may be useful, for example, when one wants to maintain | ||
129 | * a block device on top of an UBI volume. In this case, it is desirable to fit | ||
130 | * an integer number of blocks in logical eraseblocks of this UBI volume. With | ||
131 | * alignment it is possible to update this volume using plane UBI volume image | ||
132 | * BLOBs, without caring about how to properly align them. | ||
133 | */ | ||
134 | struct ubi_mkvol_req { | ||
135 | int32_t vol_id; | ||
136 | int32_t alignment; | ||
137 | int64_t bytes; | ||
138 | int8_t vol_type; | ||
139 | int8_t padding1; | ||
140 | int16_t name_len; | ||
141 | int8_t padding2[4]; | ||
142 | char name[UBI_MAX_VOLUME_NAME+1]; | ||
143 | } __attribute__ ((packed)); | ||
144 | |||
145 | /** | ||
146 | * struct ubi_rsvol_req - a data structure used in volume re-size requests. | ||
147 | * @vol_id: ID of the volume to re-size | ||
148 | * @bytes: new size of the volume in bytes | ||
149 | * | ||
150 | * Re-sizing is possible for both dynamic and static volumes. But while dynamic | ||
151 | * volumes may be re-sized arbitrarily, static volumes cannot be made to be | ||
152 | * smaller then the number of bytes they bear. To arbitrarily shrink a static | ||
153 | * volume, it must be wiped out first (by means of volume update operation with | ||
154 | * zero number of bytes). | ||
155 | */ | ||
156 | struct ubi_rsvol_req { | ||
157 | int64_t bytes; | ||
158 | int32_t vol_id; | ||
159 | } __attribute__ ((packed)); | ||
160 | |||
161 | #endif /* __UBI_USER_H__ */ | ||