include/mtd/ubi-user.h

   1 /*
   2  * Copyright (c) International Business Machines Corp., 2006
   3  *
   4  * SPDX-License-Identifier:     GPL-2.0+
   5  *
   6  * Author: Artem Bityutskiy (Битюцкий Артём)
   7  */
   8
   9 #ifndef __UBI_USER_H__
  10 #define __UBI_USER_H__
  11
  12 /*
  13  * UBI device creation (the same as MTD device attachment)
  14  * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  15  *
  16  * MTD devices may be attached using %UBI_IOCATT ioctl command of the UBI
  17  * control device. The caller has to properly fill and pass
  18  * &struct ubi_attach_req object - UBI will attach the MTD device specified in
  19  * the request and return the newly created UBI device number as the ioctl
  20  * return value.
  21  *
  22  * UBI device deletion (the same as MTD device detachment)
  23  * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  24  *
  25  * An UBI device maybe deleted with %UBI_IOCDET ioctl command of the UBI
  26  * control device.
  27  *
  28  * UBI volume creation
  29  * ~~~~~~~~~~~~~~~~~~~
  30  *
  31  * UBI volumes are created via the %UBI_IOCMKVOL IOCTL command of UBI character
  32  * device. A &struct ubi_mkvol_req object has to be properly filled and a
  33  * pointer to it has to be passed to the IOCTL.
  34  *
  35  * UBI volume deletion
  36  * ~~~~~~~~~~~~~~~~~~~
  37  *
  38  * To delete a volume, the %UBI_IOCRMVOL IOCTL command of the UBI character
  39  * device should be used. A pointer to the 32-bit volume ID hast to be passed
  40  * to the IOCTL.
  41  *
  42  * UBI volume re-size
  43  * ~~~~~~~~~~~~~~~~~~
  44  *
  45  * To re-size a volume, the %UBI_IOCRSVOL IOCTL command of the UBI character
  46  * device should be used. A &struct ubi_rsvol_req object has to be properly
  47  * filled and a pointer to it has to be passed to the IOCTL.
  48  *
  49  * UBI volume update
  50  * ~~~~~~~~~~~~~~~~~
  51  *
  52  * Volume update should be done via the %UBI_IOCVOLUP IOCTL command of the
  53  * corresponding UBI volume character device. A pointer to a 64-bit update
  54  * size should be passed to the IOCTL. After this, UBI expects user to write
  55  * this number of bytes to the volume character device. The update is finished
  56  * when the claimed number of bytes is passed. So, the volume update sequence
  57  * is something like:
  58  *
  59  * fd = open("/dev/my_volume");
  60  * ioctl(fd, UBI_IOCVOLUP, &image_size);
  61  * write(fd, buf, image_size);
  62  * close(fd);
  63  *
  64  * Atomic eraseblock change
  65  * ~~~~~~~~~~~~~~~~~~~~~~~~
  66  *
  67  * Atomic eraseblock change operation is done via the %UBI_IOCEBCH IOCTL
  68  * command of the corresponding UBI volume character device. A pointer to
  69  * &struct ubi_leb_change_req has to be passed to the IOCTL. Then the user is
  70  * expected to write the requested amount of bytes. This is similar to the
  71  * "volume update" IOCTL.
  72  */
  73
  74 /*
  75  * When a new UBI volume or UBI device is created, users may either specify the
  76  * volume/device number they want to create or to let UBI automatically assign
  77  * the number using these constants.
  78  */
  79 #define UBI_VOL_NUM_AUTO (-1)
  80 #define UBI_DEV_NUM_AUTO (-1)
  81
  82 /* Maximum volume name length */
  83 #define UBI_MAX_VOLUME_NAME 127
  84
  85 /* IOCTL commands of UBI character devices */
  86
  87 #define UBI_IOC_MAGIC 'o'
  88
  89 /* Create an UBI volume */
  90 #define UBI_IOCMKVOL _IOW(UBI_IOC_MAGIC, 0, struct ubi_mkvol_req)
  91 /* Remove an UBI volume */
  92 #define UBI_IOCRMVOL _IOW(UBI_IOC_MAGIC, 1, int32_t)
  93 /* Re-size an UBI volume */
  94 #define UBI_IOCRSVOL _IOW(UBI_IOC_MAGIC, 2, struct ubi_rsvol_req)
  95
  96 /* IOCTL commands of the UBI control character device */
  97
  98 #define UBI_CTRL_IOC_MAGIC 'o'
  99
 100 /* Attach an MTD device */
 101 #define UBI_IOCATT _IOW(UBI_CTRL_IOC_MAGIC, 64, struct ubi_attach_req)
 102 /* Detach an MTD device */
 103 #define UBI_IOCDET _IOW(UBI_CTRL_IOC_MAGIC, 65, int32_t)
 104
 105 /* IOCTL commands of UBI volume character devices */
 106
 107 #define UBI_VOL_IOC_MAGIC 'O'
 108
 109 /* Start UBI volume update */
 110 #define UBI_IOCVOLUP _IOW(UBI_VOL_IOC_MAGIC, 0, int64_t)
 111 /* An eraseblock erasure command, used for debugging, disabled by default */
 112 #define UBI_IOCEBER _IOW(UBI_VOL_IOC_MAGIC, 1, int32_t)
 113 /* An atomic eraseblock change command */
 114 #define UBI_IOCEBCH _IOW(UBI_VOL_IOC_MAGIC, 2, int32_t)
 115
 116 /* Maximum MTD device name length supported by UBI */
 117 #define MAX_UBI_MTD_NAME_LEN 127
 118
 119 /*
 120  * UBI data type hint constants.
 121  *
 122  * UBI_LONGTERM: long-term data
 123  * UBI_SHORTTERM: short-term data
 124  * UBI_UNKNOWN: data persistence is unknown
 125  *
 126  * These constants are used when data is written to UBI volumes in order to
 127  * help the UBI wear-leveling unit to find more appropriate physical
 128  * eraseblocks.
 129  */
 130 enum {
 131         UBI_LONGTERM  = 1,
 132         UBI_SHORTTERM = 2,
 133         UBI_UNKNOWN   = 3,
 134 };
 135
 136 /*
 137  * UBI volume type constants.
 138  *
 139  * @UBI_DYNAMIC_VOLUME: dynamic volume
 140  * @UBI_STATIC_VOLUME:  static volume
 141  */
 142 enum {
 143         UBI_DYNAMIC_VOLUME = 3,
 144         UBI_STATIC_VOLUME  = 4,
 145 };
 146
 147 /**
 148  * struct ubi_attach_req - attach MTD device request.
 149  * @ubi_num: UBI device number to create
 150  * @mtd_num: MTD device number to attach
 151  * @vid_hdr_offset: VID header offset (use defaults if %0)
 152  * @padding: reserved for future, not used, has to be zeroed
 153  *
 154  * This data structure is used to specify MTD device UBI has to attach and the
 155  * parameters it has to use. The number which should be assigned to the new UBI
 156  * device is passed in @ubi_num. UBI may automatically assign the number if
 157  * @UBI_DEV_NUM_AUTO is passed. In this case, the device number is returned in
 158  * @ubi_num.
 159  *
 160  * Most applications should pass %0 in @vid_hdr_offset to make UBI use default
 161  * offset of the VID header within physical eraseblocks. The default offset is
 162  * the next min. I/O unit after the EC header. For example, it will be offset
 163  * 512 in case of a 512 bytes page NAND flash with no sub-page support. Or
 164  * it will be 512 in case of a 2KiB page NAND flash with 4 512-byte sub-pages.
 165  *
 166  * But in rare cases, if this optimizes things, the VID header may be placed to
 167  * a different offset. For example, the boot-loader might do things faster if the
 168  * VID header sits at the end of the first 2KiB NAND page with 4 sub-pages. As
 169  * the boot-loader would not normally need to read EC headers (unless it needs
 170  * UBI in RW mode), it might be faster to calculate ECC. This is weird example,
 171  * but it real-life example. So, in this example, @vid_hdr_offer would be
 172  * 2KiB-64 bytes = 1984. Note, that this position is not even 512-bytes
 173  * aligned, which is OK, as UBI is clever enough to realize this is 4th sub-page
 174  * of the first page and add needed padding.
 175  */
 176 struct ubi_attach_req {
 177         int32_t ubi_num;
 178         int32_t mtd_num;
 179         int32_t vid_hdr_offset;
 180         uint8_t padding[12];
 181 };
 182
 183 /**
 184  * struct ubi_mkvol_req - volume description data structure used in
 185  *                        volume creation requests.
 186  * @vol_id: volume number
 187  * @alignment: volume alignment
 188  * @bytes: volume size in bytes
 189  * @vol_type: volume type (%UBI_DYNAMIC_VOLUME or %UBI_STATIC_VOLUME)
 190  * @padding1: reserved for future, not used, has to be zeroed
 191  * @name_len: volume name length
 192  * @padding2: reserved for future, not used, has to be zeroed
 193  * @name: volume name
 194  *
 195  * This structure is used by user-space programs when creating new volumes. The
 196  * @used_bytes field is only necessary when creating static volumes.
 197  *
 198  * The @alignment field specifies the required alignment of the volume logical
 199  * eraseblock. This means, that the size of logical eraseblocks will be aligned
 200  * to this number, i.e.,
 201  *      (UBI device logical eraseblock size) mod (@alignment) = 0.
 202  *
 203  * To put it differently, the logical eraseblock of this volume may be slightly
 204  * shortened in order to make it properly aligned. The alignment has to be
 205  * multiple of the flash minimal input/output unit, or %1 to utilize the entire
 206  * available space of logical eraseblocks.
 207  *
 208  * The @alignment field may be useful, for example, when one wants to maintain
 209  * a block device on top of an UBI volume. In this case, it is desirable to fit
 210  * an integer number of blocks in logical eraseblocks of this UBI volume. With
 211  * alignment it is possible to update this volume using plane UBI volume image
 212  * BLOBs, without caring about how to properly align them.
 213  */
 214 struct ubi_mkvol_req {
 215         int32_t vol_id;
 216         int32_t alignment;
 217         int64_t bytes;
 218         int8_t vol_type;
 219         int8_t padding1;
 220         int16_t name_len;
 221         int8_t padding2[4];
 222         char name[UBI_MAX_VOLUME_NAME + 1];
 223 } __attribute__ ((packed));
 224
 225 /**
 226  * struct ubi_rsvol_req - a data structure used in volume re-size requests.
 227  * @vol_id: ID of the volume to re-size
 228  * @bytes: new size of the volume in bytes
 229  *
 230  * Re-sizing is possible for both dynamic and static volumes. But while dynamic
 231  * volumes may be re-sized arbitrarily, static volumes cannot be made to be
 232  * smaller then the number of bytes they bear. To arbitrarily shrink a static
 233  * volume, it must be wiped out first (by means of volume update operation with
 234  * zero number of bytes).
 235  */
 236 struct ubi_rsvol_req {
 237         int64_t bytes;
 238         int32_t vol_id;
 239 } __attribute__ ((packed));
 240
 241 /**
 242  * struct ubi_leb_change_req - a data structure used in atomic logical
 243  *                             eraseblock change requests.
 244  * @lnum: logical eraseblock number to change
 245  * @bytes: how many bytes will be written to the logical eraseblock
 246  * @dtype: data type (%UBI_LONGTERM, %UBI_SHORTTERM, %UBI_UNKNOWN)
 247  * @padding: reserved for future, not used, has to be zeroed
 248  */
 249 struct ubi_leb_change_req {
 250         int32_t lnum;
 251         int32_t bytes;
 252         uint8_t dtype;
 253         uint8_t padding[7];
 254 } __attribute__ ((packed));
 255
 256 #endif /* __UBI_USER_H__ */