blob: cd81ef965c84f7517051f61af9e2a40c7d09372f [file] [log] [blame]
Tom Rini83d290c2018-05-06 17:58:06 -04001/* SPDX-License-Identifier: GPL-2.0+ */
Kyungmin Park47ae6692008-11-19 16:36:36 +01002/*
Heiko Schocherff94bc42014-06-24 10:10:04 +02003 * Copyright © International Business Machines Corp., 2006
Kyungmin Park47ae6692008-11-19 16:36:36 +01004 *
Kyungmin Park47ae6692008-11-19 16:36:36 +01005 * Author: Artem Bityutskiy (Битюцкий Артём)
6 */
7
8#ifndef __UBI_USER_H__
9#define __UBI_USER_H__
10
Heiko Schocherff94bc42014-06-24 10:10:04 +020011#include <linux/types.h>
12
Kyungmin Park47ae6692008-11-19 16:36:36 +010013/*
14 * UBI device creation (the same as MTD device attachment)
15 * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
16 *
17 * MTD devices may be attached using %UBI_IOCATT ioctl command of the UBI
18 * control device. The caller has to properly fill and pass
19 * &struct ubi_attach_req object - UBI will attach the MTD device specified in
20 * the request and return the newly created UBI device number as the ioctl
21 * return value.
22 *
23 * UBI device deletion (the same as MTD device detachment)
24 * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
25 *
26 * An UBI device maybe deleted with %UBI_IOCDET ioctl command of the UBI
27 * control device.
28 *
29 * UBI volume creation
30 * ~~~~~~~~~~~~~~~~~~~
31 *
Heiko Schocherff94bc42014-06-24 10:10:04 +020032 * UBI volumes are created via the %UBI_IOCMKVOL ioctl command of UBI character
Kyungmin Park47ae6692008-11-19 16:36:36 +010033 * device. A &struct ubi_mkvol_req object has to be properly filled and a
Heiko Schocherff94bc42014-06-24 10:10:04 +020034 * pointer to it has to be passed to the ioctl.
Kyungmin Park47ae6692008-11-19 16:36:36 +010035 *
36 * UBI volume deletion
37 * ~~~~~~~~~~~~~~~~~~~
38 *
Heiko Schocherff94bc42014-06-24 10:10:04 +020039 * To delete a volume, the %UBI_IOCRMVOL ioctl command of the UBI character
Kyungmin Park47ae6692008-11-19 16:36:36 +010040 * device should be used. A pointer to the 32-bit volume ID hast to be passed
Heiko Schocherff94bc42014-06-24 10:10:04 +020041 * to the ioctl.
Kyungmin Park47ae6692008-11-19 16:36:36 +010042 *
43 * UBI volume re-size
44 * ~~~~~~~~~~~~~~~~~~
45 *
Heiko Schocherff94bc42014-06-24 10:10:04 +020046 * To re-size a volume, the %UBI_IOCRSVOL ioctl command of the UBI character
Kyungmin Park47ae6692008-11-19 16:36:36 +010047 * device should be used. A &struct ubi_rsvol_req object has to be properly
Heiko Schocherff94bc42014-06-24 10:10:04 +020048 * filled and a pointer to it has to be passed to the ioctl.
49 *
50 * UBI volumes re-name
51 * ~~~~~~~~~~~~~~~~~~~
52 *
53 * To re-name several volumes atomically at one go, the %UBI_IOCRNVOL command
54 * of the UBI character device should be used. A &struct ubi_rnvol_req object
55 * has to be properly filled and a pointer to it has to be passed to the ioctl.
Kyungmin Park47ae6692008-11-19 16:36:36 +010056 *
57 * UBI volume update
58 * ~~~~~~~~~~~~~~~~~
59 *
Heiko Schocherff94bc42014-06-24 10:10:04 +020060 * Volume update should be done via the %UBI_IOCVOLUP ioctl command of the
Kyungmin Park47ae6692008-11-19 16:36:36 +010061 * corresponding UBI volume character device. A pointer to a 64-bit update
Heiko Schocherff94bc42014-06-24 10:10:04 +020062 * size should be passed to the ioctl. After this, UBI expects user to write
Kyungmin Park47ae6692008-11-19 16:36:36 +010063 * this number of bytes to the volume character device. The update is finished
64 * when the claimed number of bytes is passed. So, the volume update sequence
65 * is something like:
66 *
67 * fd = open("/dev/my_volume");
68 * ioctl(fd, UBI_IOCVOLUP, &image_size);
69 * write(fd, buf, image_size);
70 * close(fd);
71 *
Heiko Schocherff94bc42014-06-24 10:10:04 +020072 * Logical eraseblock erase
Kyungmin Park47ae6692008-11-19 16:36:36 +010073 * ~~~~~~~~~~~~~~~~~~~~~~~~
74 *
Heiko Schocherff94bc42014-06-24 10:10:04 +020075 * To erase a logical eraseblock, the %UBI_IOCEBER ioctl command of the
76 * corresponding UBI volume character device should be used. This command
77 * unmaps the requested logical eraseblock, makes sure the corresponding
78 * physical eraseblock is successfully erased, and returns.
79 *
80 * Atomic logical eraseblock change
81 * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
82 *
83 * Atomic logical eraseblock change operation is called using the %UBI_IOCEBCH
84 * ioctl command of the corresponding UBI volume character device. A pointer to
85 * a &struct ubi_leb_change_req object has to be passed to the ioctl. Then the
86 * user is expected to write the requested amount of bytes (similarly to what
87 * should be done in case of the "volume update" ioctl).
88 *
89 * Logical eraseblock map
90 * ~~~~~~~~~~~~~~~~~~~~~
91 *
92 * To map a logical eraseblock to a physical eraseblock, the %UBI_IOCEBMAP
93 * ioctl command should be used. A pointer to a &struct ubi_map_req object is
94 * expected to be passed. The ioctl maps the requested logical eraseblock to
95 * a physical eraseblock and returns. Only non-mapped logical eraseblocks can
96 * be mapped. If the logical eraseblock specified in the request is already
97 * mapped to a physical eraseblock, the ioctl fails and returns error.
98 *
99 * Logical eraseblock unmap
100 * ~~~~~~~~~~~~~~~~~~~~~~~~
101 *
102 * To unmap a logical eraseblock to a physical eraseblock, the %UBI_IOCEBUNMAP
103 * ioctl command should be used. The ioctl unmaps the logical eraseblocks,
104 * schedules corresponding physical eraseblock for erasure, and returns. Unlike
105 * the "LEB erase" command, it does not wait for the physical eraseblock being
106 * erased. Note, the side effect of this is that if an unclean reboot happens
107 * after the unmap ioctl returns, you may find the LEB mapped again to the same
108 * physical eraseblock after the UBI is run again.
109 *
110 * Check if logical eraseblock is mapped
111 * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
112 *
113 * To check if a logical eraseblock is mapped to a physical eraseblock, the
114 * %UBI_IOCEBISMAP ioctl command should be used. It returns %0 if the LEB is
115 * not mapped, and %1 if it is mapped.
116 *
117 * Set an UBI volume property
118 * ~~~~~~~~~~~~~~~~~~~~~~~~~
119 *
120 * To set an UBI volume property the %UBI_IOCSETPROP ioctl command should be
121 * used. A pointer to a &struct ubi_set_vol_prop_req object is expected to be
122 * passed. The object describes which property should be set, and to which value
123 * it should be set.
Heiko Schocher4e67c572014-07-15 16:08:43 +0200124 *
125 * Block devices on UBI volumes
126 * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
127 *
128 * To create a R/O block device on top of an UBI volume the %UBI_IOCVOLCRBLK
129 * should be used. A pointer to a &struct ubi_blkcreate_req object is expected
130 * to be passed, which is not used and reserved for future usage.
131 *
132 * Conversely, to remove a block device the %UBI_IOCVOLRMBLK should be used,
133 * which takes no arguments.
Kyungmin Park47ae6692008-11-19 16:36:36 +0100134 */
135
136/*
137 * When a new UBI volume or UBI device is created, users may either specify the
138 * volume/device number they want to create or to let UBI automatically assign
139 * the number using these constants.
140 */
141#define UBI_VOL_NUM_AUTO (-1)
142#define UBI_DEV_NUM_AUTO (-1)
143
144/* Maximum volume name length */
145#define UBI_MAX_VOLUME_NAME 127
146
Heiko Schocherff94bc42014-06-24 10:10:04 +0200147/* ioctl commands of UBI character devices */
Kyungmin Park47ae6692008-11-19 16:36:36 +0100148
149#define UBI_IOC_MAGIC 'o'
150
151/* Create an UBI volume */
152#define UBI_IOCMKVOL _IOW(UBI_IOC_MAGIC, 0, struct ubi_mkvol_req)
153/* Remove an UBI volume */
Heiko Schocherff94bc42014-06-24 10:10:04 +0200154#define UBI_IOCRMVOL _IOW(UBI_IOC_MAGIC, 1, __s32)
Kyungmin Park47ae6692008-11-19 16:36:36 +0100155/* Re-size an UBI volume */
156#define UBI_IOCRSVOL _IOW(UBI_IOC_MAGIC, 2, struct ubi_rsvol_req)
Heiko Schocherff94bc42014-06-24 10:10:04 +0200157/* Re-name volumes */
158#define UBI_IOCRNVOL _IOW(UBI_IOC_MAGIC, 3, struct ubi_rnvol_req)
Kyungmin Park47ae6692008-11-19 16:36:36 +0100159
Heiko Schocherff94bc42014-06-24 10:10:04 +0200160/* ioctl commands of the UBI control character device */
Kyungmin Park47ae6692008-11-19 16:36:36 +0100161
162#define UBI_CTRL_IOC_MAGIC 'o'
163
164/* Attach an MTD device */
165#define UBI_IOCATT _IOW(UBI_CTRL_IOC_MAGIC, 64, struct ubi_attach_req)
166/* Detach an MTD device */
Heiko Schocherff94bc42014-06-24 10:10:04 +0200167#define UBI_IOCDET _IOW(UBI_CTRL_IOC_MAGIC, 65, __s32)
Kyungmin Park47ae6692008-11-19 16:36:36 +0100168
Heiko Schocherff94bc42014-06-24 10:10:04 +0200169/* ioctl commands of UBI volume character devices */
Kyungmin Park47ae6692008-11-19 16:36:36 +0100170
171#define UBI_VOL_IOC_MAGIC 'O'
172
Heiko Schocherff94bc42014-06-24 10:10:04 +0200173/* Start UBI volume update
174 * Note: This actually takes a pointer (__s64*), but we can't change
175 * that without breaking the ABI on 32bit systems
176 */
177#define UBI_IOCVOLUP _IOW(UBI_VOL_IOC_MAGIC, 0, __s64)
178/* LEB erasure command, used for debugging, disabled by default */
179#define UBI_IOCEBER _IOW(UBI_VOL_IOC_MAGIC, 1, __s32)
180/* Atomic LEB change command */
181#define UBI_IOCEBCH _IOW(UBI_VOL_IOC_MAGIC, 2, __s32)
182/* Map LEB command */
183#define UBI_IOCEBMAP _IOW(UBI_VOL_IOC_MAGIC, 3, struct ubi_map_req)
184/* Unmap LEB command */
185#define UBI_IOCEBUNMAP _IOW(UBI_VOL_IOC_MAGIC, 4, __s32)
186/* Check if LEB is mapped command */
187#define UBI_IOCEBISMAP _IOR(UBI_VOL_IOC_MAGIC, 5, __s32)
188/* Set an UBI volume property */
189#define UBI_IOCSETVOLPROP _IOW(UBI_VOL_IOC_MAGIC, 6, \
190 struct ubi_set_vol_prop_req)
Heiko Schocher4e67c572014-07-15 16:08:43 +0200191/* Create a R/O block device on top of an UBI volume */
192#define UBI_IOCVOLCRBLK _IOW(UBI_VOL_IOC_MAGIC, 7, struct ubi_blkcreate_req)
193/* Remove the R/O block device */
194#define UBI_IOCVOLRMBLK _IO(UBI_VOL_IOC_MAGIC, 8)
Kyungmin Park47ae6692008-11-19 16:36:36 +0100195
196/* Maximum MTD device name length supported by UBI */
197#define MAX_UBI_MTD_NAME_LEN 127
198
Heiko Schocherff94bc42014-06-24 10:10:04 +0200199/* Maximum amount of UBI volumes that can be re-named at one go */
200#define UBI_MAX_RNVOL 32
Kyungmin Park47ae6692008-11-19 16:36:36 +0100201
202/*
203 * UBI volume type constants.
204 *
205 * @UBI_DYNAMIC_VOLUME: dynamic volume
206 * @UBI_STATIC_VOLUME: static volume
207 */
208enum {
209 UBI_DYNAMIC_VOLUME = 3,
210 UBI_STATIC_VOLUME = 4,
211};
212
Heiko Schocherff94bc42014-06-24 10:10:04 +0200213/*
214 * UBI set volume property ioctl constants.
215 *
216 * @UBI_VOL_PROP_DIRECT_WRITE: allow (any non-zero value) or disallow (value 0)
217 * user to directly write and erase individual
218 * eraseblocks on dynamic volumes
219 */
220enum {
221 UBI_VOL_PROP_DIRECT_WRITE = 1,
222};
223
Kyungmin Park47ae6692008-11-19 16:36:36 +0100224/**
225 * struct ubi_attach_req - attach MTD device request.
226 * @ubi_num: UBI device number to create
227 * @mtd_num: MTD device number to attach
228 * @vid_hdr_offset: VID header offset (use defaults if %0)
Heiko Schocherff94bc42014-06-24 10:10:04 +0200229 * @max_beb_per1024: maximum expected number of bad PEB per 1024 PEBs
Kyungmin Park47ae6692008-11-19 16:36:36 +0100230 * @padding: reserved for future, not used, has to be zeroed
231 *
232 * This data structure is used to specify MTD device UBI has to attach and the
233 * parameters it has to use. The number which should be assigned to the new UBI
234 * device is passed in @ubi_num. UBI may automatically assign the number if
235 * @UBI_DEV_NUM_AUTO is passed. In this case, the device number is returned in
236 * @ubi_num.
237 *
238 * Most applications should pass %0 in @vid_hdr_offset to make UBI use default
239 * offset of the VID header within physical eraseblocks. The default offset is
240 * the next min. I/O unit after the EC header. For example, it will be offset
241 * 512 in case of a 512 bytes page NAND flash with no sub-page support. Or
242 * it will be 512 in case of a 2KiB page NAND flash with 4 512-byte sub-pages.
243 *
244 * But in rare cases, if this optimizes things, the VID header may be placed to
Heiko Schocherff94bc42014-06-24 10:10:04 +0200245 * a different offset. For example, the boot-loader might do things faster if
246 * the VID header sits at the end of the first 2KiB NAND page with 4 sub-pages.
247 * As the boot-loader would not normally need to read EC headers (unless it
248 * needs UBI in RW mode), it might be faster to calculate ECC. This is weird
249 * example, but it real-life example. So, in this example, @vid_hdr_offer would
250 * be 2KiB-64 bytes = 1984. Note, that this position is not even 512-bytes
251 * aligned, which is OK, as UBI is clever enough to realize this is 4th
252 * sub-page of the first page and add needed padding.
253 *
254 * The @max_beb_per1024 is the maximum amount of bad PEBs UBI expects on the
255 * UBI device per 1024 eraseblocks. This value is often given in an other form
256 * in the NAND datasheet (min NVB i.e. minimal number of valid blocks). The
257 * maximum expected bad eraseblocks per 1024 is then:
258 * 1024 * (1 - MinNVB / MaxNVB)
259 * Which gives 20 for most NAND devices. This limit is used in order to derive
260 * amount of eraseblock UBI reserves for handling new bad blocks. If the device
261 * has more bad eraseblocks than this limit, UBI does not reserve any physical
262 * eraseblocks for new bad eraseblocks, but attempts to use available
263 * eraseblocks (if any). The accepted range is 0-768. If 0 is given, the
264 * default kernel value of %CONFIG_MTD_UBI_BEB_LIMIT will be used.
Kyungmin Park47ae6692008-11-19 16:36:36 +0100265 */
266struct ubi_attach_req {
Heiko Schocherff94bc42014-06-24 10:10:04 +0200267 __s32 ubi_num;
268 __s32 mtd_num;
269 __s32 vid_hdr_offset;
270 __s16 max_beb_per1024;
271 __s8 padding[10];
Kyungmin Park47ae6692008-11-19 16:36:36 +0100272};
273
274/**
275 * struct ubi_mkvol_req - volume description data structure used in
276 * volume creation requests.
277 * @vol_id: volume number
278 * @alignment: volume alignment
279 * @bytes: volume size in bytes
280 * @vol_type: volume type (%UBI_DYNAMIC_VOLUME or %UBI_STATIC_VOLUME)
281 * @padding1: reserved for future, not used, has to be zeroed
282 * @name_len: volume name length
283 * @padding2: reserved for future, not used, has to be zeroed
284 * @name: volume name
285 *
286 * This structure is used by user-space programs when creating new volumes. The
287 * @used_bytes field is only necessary when creating static volumes.
288 *
289 * The @alignment field specifies the required alignment of the volume logical
290 * eraseblock. This means, that the size of logical eraseblocks will be aligned
291 * to this number, i.e.,
292 * (UBI device logical eraseblock size) mod (@alignment) = 0.
293 *
294 * To put it differently, the logical eraseblock of this volume may be slightly
295 * shortened in order to make it properly aligned. The alignment has to be
296 * multiple of the flash minimal input/output unit, or %1 to utilize the entire
297 * available space of logical eraseblocks.
298 *
299 * The @alignment field may be useful, for example, when one wants to maintain
300 * a block device on top of an UBI volume. In this case, it is desirable to fit
301 * an integer number of blocks in logical eraseblocks of this UBI volume. With
302 * alignment it is possible to update this volume using plane UBI volume image
303 * BLOBs, without caring about how to properly align them.
304 */
305struct ubi_mkvol_req {
Heiko Schocherff94bc42014-06-24 10:10:04 +0200306 __s32 vol_id;
307 __s32 alignment;
308 __s64 bytes;
309 __s8 vol_type;
310 __s8 padding1;
311 __s16 name_len;
312 __s8 padding2[4];
Kyungmin Park47ae6692008-11-19 16:36:36 +0100313 char name[UBI_MAX_VOLUME_NAME + 1];
Heiko Schocherff94bc42014-06-24 10:10:04 +0200314} __packed;
Kyungmin Park47ae6692008-11-19 16:36:36 +0100315
316/**
317 * struct ubi_rsvol_req - a data structure used in volume re-size requests.
318 * @vol_id: ID of the volume to re-size
319 * @bytes: new size of the volume in bytes
320 *
321 * Re-sizing is possible for both dynamic and static volumes. But while dynamic
322 * volumes may be re-sized arbitrarily, static volumes cannot be made to be
Heiko Schocherff94bc42014-06-24 10:10:04 +0200323 * smaller than the number of bytes they bear. To arbitrarily shrink a static
Kyungmin Park47ae6692008-11-19 16:36:36 +0100324 * volume, it must be wiped out first (by means of volume update operation with
325 * zero number of bytes).
326 */
327struct ubi_rsvol_req {
Heiko Schocherff94bc42014-06-24 10:10:04 +0200328 __s64 bytes;
329 __s32 vol_id;
330} __packed;
Kyungmin Park47ae6692008-11-19 16:36:36 +0100331
332/**
Heiko Schocherff94bc42014-06-24 10:10:04 +0200333 * struct ubi_rnvol_req - volumes re-name request.
334 * @count: count of volumes to re-name
335 * @padding1: reserved for future, not used, has to be zeroed
336 * @vol_id: ID of the volume to re-name
337 * @name_len: name length
338 * @padding2: reserved for future, not used, has to be zeroed
339 * @name: new volume name
340 *
341 * UBI allows to re-name up to %32 volumes at one go. The count of volumes to
342 * re-name is specified in the @count field. The ID of the volumes to re-name
343 * and the new names are specified in the @vol_id and @name fields.
344 *
345 * The UBI volume re-name operation is atomic, which means that should power cut
346 * happen, the volumes will have either old name or new name. So the possible
347 * use-cases of this command is atomic upgrade. Indeed, to upgrade, say, volumes
348 * A and B one may create temporary volumes %A1 and %B1 with the new contents,
349 * then atomically re-name A1->A and B1->B, in which case old %A and %B will
350 * be removed.
351 *
352 * If it is not desirable to remove old A and B, the re-name request has to
353 * contain 4 entries: A1->A, A->A1, B1->B, B->B1, in which case old A1 and B1
354 * become A and B, and old A and B will become A1 and B1.
355 *
356 * It is also OK to request: A1->A, A1->X, B1->B, B->Y, in which case old A1
357 * and B1 become A and B, and old A and B become X and Y.
358 *
359 * In other words, in case of re-naming into an existing volume name, the
360 * existing volume is removed, unless it is re-named as well at the same
361 * re-name request.
362 */
363struct ubi_rnvol_req {
364 __s32 count;
365 __s8 padding1[12];
366 struct {
367 __s32 vol_id;
368 __s16 name_len;
369 __s8 padding2[2];
370 char name[UBI_MAX_VOLUME_NAME + 1];
371 } ents[UBI_MAX_RNVOL];
372} __packed;
373
374/**
375 * struct ubi_leb_change_req - a data structure used in atomic LEB change
376 * requests.
Kyungmin Park47ae6692008-11-19 16:36:36 +0100377 * @lnum: logical eraseblock number to change
378 * @bytes: how many bytes will be written to the logical eraseblock
Heiko Schocherff94bc42014-06-24 10:10:04 +0200379 * @dtype: pass "3" for better compatibility with old kernels
Kyungmin Park47ae6692008-11-19 16:36:36 +0100380 * @padding: reserved for future, not used, has to be zeroed
Heiko Schocherff94bc42014-06-24 10:10:04 +0200381 *
382 * The @dtype field used to inform UBI about what kind of data will be written
383 * to the LEB: long term (value 1), short term (value 2), unknown (value 3).
384 * UBI tried to pick a PEB with lower erase counter for short term data and a
385 * PEB with higher erase counter for long term data. But this was not really
386 * used because users usually do not know this and could easily mislead UBI. We
387 * removed this feature in May 2012. UBI currently just ignores the @dtype
388 * field. But for better compatibility with older kernels it is recommended to
389 * set @dtype to 3 (unknown).
Kyungmin Park47ae6692008-11-19 16:36:36 +0100390 */
391struct ubi_leb_change_req {
Heiko Schocherff94bc42014-06-24 10:10:04 +0200392 __s32 lnum;
393 __s32 bytes;
394 __s8 dtype; /* obsolete, do not use! */
395 __s8 padding[7];
396} __packed;
397
398/**
399 * struct ubi_map_req - a data structure used in map LEB requests.
400 * @dtype: pass "3" for better compatibility with old kernels
401 * @lnum: logical eraseblock number to unmap
402 * @padding: reserved for future, not used, has to be zeroed
403 */
404struct ubi_map_req {
405 __s32 lnum;
406 __s8 dtype; /* obsolete, do not use! */
407 __s8 padding[3];
408} __packed;
409
410
411/**
412 * struct ubi_set_vol_prop_req - a data structure used to set an UBI volume
413 * property.
414 * @property: property to set (%UBI_VOL_PROP_DIRECT_WRITE)
415 * @padding: reserved for future, not used, has to be zeroed
416 * @value: value to set
417 */
418struct ubi_set_vol_prop_req {
419 __u8 property;
420 __u8 padding[7];
421 __u64 value;
422} __packed;
Kyungmin Park47ae6692008-11-19 16:36:36 +0100423
Heiko Schocher4e67c572014-07-15 16:08:43 +0200424/**
425 * struct ubi_blkcreate_req - a data structure used in block creation requests.
426 * @padding: reserved for future, not used, has to be zeroed
427 */
428struct ubi_blkcreate_req {
429 __s8 padding[128];
430} __packed;
431
Kyungmin Park47ae6692008-11-19 16:36:36 +0100432#endif /* __UBI_USER_H__ */