home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / mtd / ubi-user.h < prev   
Encoding:
C/C++ Source or Header  |  2008-11-13  |  11.8 KB  |  323 lines
  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 device creation (the same as MTD device attachment)
  26.  * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  27.  *
  28.  * MTD devices may be attached using %UBI_IOCATT ioctl command of the UBI
  29.  * control device. The caller has to properly fill and pass
  30.  * &struct ubi_attach_req object - UBI will attach the MTD device specified in
  31.  * the request and return the newly created UBI device number as the ioctl
  32.  * return value.
  33.  *
  34.  * UBI device deletion (the same as MTD device detachment)
  35.  * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  36.  *
  37.  * An UBI device maybe deleted with %UBI_IOCDET ioctl command of the UBI
  38.  * control device.
  39.  *
  40.  * UBI volume creation
  41.  * ~~~~~~~~~~~~~~~~~~~
  42.  *
  43.  * UBI volumes are created via the %UBI_IOCMKVOL IOCTL command of UBI character
  44.  * device. A &struct ubi_mkvol_req object has to be properly filled and a
  45.  * pointer to it has to be passed to the IOCTL.
  46.  *
  47.  * UBI volume deletion
  48.  * ~~~~~~~~~~~~~~~~~~~
  49.  *
  50.  * To delete a volume, the %UBI_IOCRMVOL IOCTL command of the UBI character
  51.  * device should be used. A pointer to the 32-bit volume ID hast to be passed
  52.  * to the IOCTL.
  53.  *
  54.  * UBI volume re-size
  55.  * ~~~~~~~~~~~~~~~~~~
  56.  *
  57.  * To re-size a volume, the %UBI_IOCRSVOL IOCTL command of the UBI character
  58.  * device should be used. A &struct ubi_rsvol_req object has to be properly
  59.  * filled and a pointer to it has to be passed to the IOCTL.
  60.  *
  61.  * UBI volumes re-name
  62.  * ~~~~~~~~~~~~~~~~~~~
  63.  *
  64.  * To re-name several volumes atomically at one go, the %UBI_IOCRNVOL command
  65.  * of the UBI character device should be used. A &struct ubi_rnvol_req object
  66.  * has to be properly filled and a pointer to it has to be passed to the IOCTL.
  67.  *
  68.  * UBI volume update
  69.  * ~~~~~~~~~~~~~~~~~
  70.  *
  71.  * Volume update should be done via the %UBI_IOCVOLUP IOCTL command of the
  72.  * corresponding UBI volume character device. A pointer to a 64-bit update
  73.  * size should be passed to the IOCTL. After this, UBI expects user to write
  74.  * this number of bytes to the volume character device. The update is finished
  75.  * when the claimed number of bytes is passed. So, the volume update sequence
  76.  * is something like:
  77.  *
  78.  * fd = open("/dev/my_volume");
  79.  * ioctl(fd, UBI_IOCVOLUP, &image_size);
  80.  * write(fd, buf, image_size);
  81.  * close(fd);
  82.  *
  83.  * Atomic eraseblock change
  84.  * ~~~~~~~~~~~~~~~~~~~~~~~~
  85.  *
  86.  * Atomic eraseblock change operation is done via the %UBI_IOCEBCH IOCTL
  87.  * command of the corresponding UBI volume character device. A pointer to
  88.  * &struct ubi_leb_change_req has to be passed to the IOCTL. Then the user is
  89.  * expected to write the requested amount of bytes. This is similar to the
  90.  * "volume update" IOCTL.
  91.  */
  92.  
  93. /*
  94.  * When a new UBI volume or UBI device is created, users may either specify the
  95.  * volume/device number they want to create or to let UBI automatically assign
  96.  * the number using these constants.
  97.  */
  98. #define UBI_VOL_NUM_AUTO (-1)
  99. #define UBI_DEV_NUM_AUTO (-1)
  100.  
  101. /* Maximum volume name length */
  102. #define UBI_MAX_VOLUME_NAME 127
  103.  
  104. /* IOCTL commands of UBI character devices */
  105.  
  106. #define UBI_IOC_MAGIC 'o'
  107.  
  108. /* Create an UBI volume */
  109. #define UBI_IOCMKVOL _IOW(UBI_IOC_MAGIC, 0, struct ubi_mkvol_req)
  110. /* Remove an UBI volume */
  111. #define UBI_IOCRMVOL _IOW(UBI_IOC_MAGIC, 1, int32_t)
  112. /* Re-size an UBI volume */
  113. #define UBI_IOCRSVOL _IOW(UBI_IOC_MAGIC, 2, struct ubi_rsvol_req)
  114. /* Re-name volumes */
  115. #define UBI_IOCRNVOL _IOW(UBI_IOC_MAGIC, 3, struct ubi_rnvol_req)
  116.  
  117. /* IOCTL commands of the UBI control character device */
  118.  
  119. #define UBI_CTRL_IOC_MAGIC 'o'
  120.  
  121. /* Attach an MTD device */
  122. #define UBI_IOCATT _IOW(UBI_CTRL_IOC_MAGIC, 64, struct ubi_attach_req)
  123. /* Detach an MTD device */
  124. #define UBI_IOCDET _IOW(UBI_CTRL_IOC_MAGIC, 65, int32_t)
  125.  
  126. /* IOCTL commands of UBI volume character devices */
  127.  
  128. #define UBI_VOL_IOC_MAGIC 'O'
  129.  
  130. /* Start UBI volume update */
  131. #define UBI_IOCVOLUP _IOW(UBI_VOL_IOC_MAGIC, 0, int64_t)
  132. /* An eraseblock erasure command, used for debugging, disabled by default */
  133. #define UBI_IOCEBER _IOW(UBI_VOL_IOC_MAGIC, 1, int32_t)
  134. /* An atomic eraseblock change command */
  135. #define UBI_IOCEBCH _IOW(UBI_VOL_IOC_MAGIC, 2, int32_t)
  136.  
  137. /* Maximum MTD device name length supported by UBI */
  138. #define MAX_UBI_MTD_NAME_LEN 127
  139.  
  140. /* Maximum amount of UBI volumes that can be re-named at one go */
  141. #define UBI_MAX_RNVOL 32
  142.  
  143. /*
  144.  * UBI data type hint constants.
  145.  *
  146.  * UBI_LONGTERM: long-term data
  147.  * UBI_SHORTTERM: short-term data
  148.  * UBI_UNKNOWN: data persistence is unknown
  149.  *
  150.  * These constants are used when data is written to UBI volumes in order to
  151.  * help the UBI wear-leveling unit to find more appropriate physical
  152.  * eraseblocks.
  153.  */
  154. enum {
  155.     UBI_LONGTERM  = 1,
  156.     UBI_SHORTTERM = 2,
  157.     UBI_UNKNOWN   = 3,
  158. };
  159.  
  160. /*
  161.  * UBI volume type constants.
  162.  *
  163.  * @UBI_DYNAMIC_VOLUME: dynamic volume
  164.  * @UBI_STATIC_VOLUME:  static volume
  165.  */
  166. enum {
  167.     UBI_DYNAMIC_VOLUME = 3,
  168.     UBI_STATIC_VOLUME  = 4,
  169. };
  170.  
  171. /**
  172.  * struct ubi_attach_req - attach MTD device request.
  173.  * @ubi_num: UBI device number to create
  174.  * @mtd_num: MTD device number to attach
  175.  * @vid_hdr_offset: VID header offset (use defaults if %0)
  176.  * @padding: reserved for future, not used, has to be zeroed
  177.  *
  178.  * This data structure is used to specify MTD device UBI has to attach and the
  179.  * parameters it has to use. The number which should be assigned to the new UBI
  180.  * device is passed in @ubi_num. UBI may automatically assign the number if
  181.  * @UBI_DEV_NUM_AUTO is passed. In this case, the device number is returned in
  182.  * @ubi_num.
  183.  *
  184.  * Most applications should pass %0 in @vid_hdr_offset to make UBI use default
  185.  * offset of the VID header within physical eraseblocks. The default offset is
  186.  * the next min. I/O unit after the EC header. For example, it will be offset
  187.  * 512 in case of a 512 bytes page NAND flash with no sub-page support. Or
  188.  * it will be 512 in case of a 2KiB page NAND flash with 4 512-byte sub-pages.
  189.  *
  190.  * But in rare cases, if this optimizes things, the VID header may be placed to
  191.  * a different offset. For example, the boot-loader might do things faster if
  192.  * the VID header sits at the end of the first 2KiB NAND page with 4 sub-pages.
  193.  * As the boot-loader would not normally need to read EC headers (unless it
  194.  * needs UBI in RW mode), it might be faster to calculate ECC. This is weird
  195.  * example, but it real-life example. So, in this example, @vid_hdr_offer would
  196.  * be 2KiB-64 bytes = 1984. Note, that this position is not even 512-bytes
  197.  * aligned, which is OK, as UBI is clever enough to realize this is 4th
  198.  * sub-page of the first page and add needed padding.
  199.  */
  200. struct ubi_attach_req {
  201.     int32_t ubi_num;
  202.     int32_t mtd_num;
  203.     int32_t vid_hdr_offset;
  204.     int8_t padding[12];
  205. };
  206.  
  207. /**
  208.  * struct ubi_mkvol_req - volume description data structure used in
  209.  *                        volume creation requests.
  210.  * @vol_id: volume number
  211.  * @alignment: volume alignment
  212.  * @bytes: volume size in bytes
  213.  * @vol_type: volume type (%UBI_DYNAMIC_VOLUME or %UBI_STATIC_VOLUME)
  214.  * @padding1: reserved for future, not used, has to be zeroed
  215.  * @name_len: volume name length
  216.  * @padding2: reserved for future, not used, has to be zeroed
  217.  * @name: volume name
  218.  *
  219.  * This structure is used by user-space programs when creating new volumes. The
  220.  * @used_bytes field is only necessary when creating static volumes.
  221.  *
  222.  * The @alignment field specifies the required alignment of the volume logical
  223.  * eraseblock. This means, that the size of logical eraseblocks will be aligned
  224.  * to this number, i.e.,
  225.  *    (UBI device logical eraseblock size) mod (@alignment) = 0.
  226.  *
  227.  * To put it differently, the logical eraseblock of this volume may be slightly
  228.  * shortened in order to make it properly aligned. The alignment has to be
  229.  * multiple of the flash minimal input/output unit, or %1 to utilize the entire
  230.  * available space of logical eraseblocks.
  231.  *
  232.  * The @alignment field may be useful, for example, when one wants to maintain
  233.  * a block device on top of an UBI volume. In this case, it is desirable to fit
  234.  * an integer number of blocks in logical eraseblocks of this UBI volume. With
  235.  * alignment it is possible to update this volume using plane UBI volume image
  236.  * BLOBs, without caring about how to properly align them.
  237.  */
  238. struct ubi_mkvol_req {
  239.     int32_t vol_id;
  240.     int32_t alignment;
  241.     int64_t bytes;
  242.     int8_t vol_type;
  243.     int8_t padding1;
  244.     int16_t name_len;
  245.     int8_t padding2[4];
  246.     char name[UBI_MAX_VOLUME_NAME + 1];
  247. } __attribute__ ((packed));
  248.  
  249. /**
  250.  * struct ubi_rsvol_req - a data structure used in volume re-size requests.
  251.  * @vol_id: ID of the volume to re-size
  252.  * @bytes: new size of the volume in bytes
  253.  *
  254.  * Re-sizing is possible for both dynamic and static volumes. But while dynamic
  255.  * volumes may be re-sized arbitrarily, static volumes cannot be made to be
  256.  * smaller then the number of bytes they bear. To arbitrarily shrink a static
  257.  * volume, it must be wiped out first (by means of volume update operation with
  258.  * zero number of bytes).
  259.  */
  260. struct ubi_rsvol_req {
  261.     int64_t bytes;
  262.     int32_t vol_id;
  263. } __attribute__ ((packed));
  264.  
  265. /**
  266.  * struct ubi_rnvol_req - volumes re-name request.
  267.  * @count: count of volumes to re-name
  268.  * @padding1:  reserved for future, not used, has to be zeroed
  269.  * @vol_id: ID of the volume to re-name
  270.  * @name_len: name length
  271.  * @padding2:  reserved for future, not used, has to be zeroed
  272.  * @name: new volume name
  273.  *
  274.  * UBI allows to re-name up to %32 volumes at one go. The count of volumes to
  275.  * re-name is specified in the @count field. The ID of the volumes to re-name
  276.  * and the new names are specified in the @vol_id and @name fields.
  277.  *
  278.  * The UBI volume re-name operation is atomic, which means that should power cut
  279.  * happen, the volumes will have either old name or new name. So the possible
  280.  * use-cases of this command is atomic upgrade. Indeed, to upgrade, say, volumes
  281.  * A and B one may create temporary volumes %A1 and %B1 with the new contents,
  282.  * then atomically re-name A1->A and B1->B, in which case old %A and %B will
  283.  * be removed.
  284.  *
  285.  * If it is not desirable to remove old A and B, the re-name request has to
  286.  * contain 4 entries: A1->A, A->A1, B1->B, B->B1, in which case old A1 and B1
  287.  * become A and B, and old A and B will become A1 and B1.
  288.  *
  289.  * It is also OK to request: A1->A, A1->X, B1->B, B->Y, in which case old A1
  290.  * and B1 become A and B, and old A and B become X and Y.
  291.  *
  292.  * In other words, in case of re-naming into an existing volume name, the
  293.  * existing volume is removed, unless it is re-named as well at the same
  294.  * re-name request.
  295.  */
  296. struct ubi_rnvol_req {
  297.     int32_t count;
  298.     int8_t padding1[12];
  299.     struct {
  300.         int32_t vol_id;
  301.         int16_t name_len;
  302.         int8_t  padding2[2];
  303.         char    name[UBI_MAX_VOLUME_NAME + 1];
  304.     } ents[UBI_MAX_RNVOL];
  305. } __attribute__ ((packed));
  306.  
  307. /**
  308.  * struct ubi_leb_change_req - a data structure used in atomic logical
  309.  *                             eraseblock change requests.
  310.  * @lnum: logical eraseblock number to change
  311.  * @bytes: how many bytes will be written to the logical eraseblock
  312.  * @dtype: data type (%UBI_LONGTERM, %UBI_SHORTTERM, %UBI_UNKNOWN)
  313.  * @padding: reserved for future, not used, has to be zeroed
  314.  */
  315. struct ubi_leb_change_req {
  316.     int32_t lnum;
  317.     int32_t bytes;
  318.     int8_t  dtype;
  319.     int8_t  padding[7];
  320. } __attribute__ ((packed));
  321.  
  322. #endif /* __UBI_USER_H__ */
  323.