From 518f0970cca2f2766807871b3abb5467846be212 Mon Sep 17 00:00:00 2001 From: Trevor Woerner Date: Sun, 27 Oct 2019 23:22:08 -0400 Subject: [PATCH] ubi.xml: many wording and spelling cleanups Signed-off-by: Trevor Woerner Signed-off-by: David Oberhollenzer --- doc/ubi.xml | 913 ++++++++++++++++++++++++++-------------------------- 1 file changed, 450 insertions(+), 463 deletions(-) diff --git a/doc/ubi.xml b/doc/ubi.xml index f20e1aa..568a66e 100644 --- a/doc/ubi.xml +++ b/doc/ubi.xml @@ -1,6 +1,5 @@ - @@ -16,7 +15,7 @@
  • Big red note
  • Overview
  • Power-cuts tolerance
    • -
  • Source code
    • +
  • Kernel source code
  • Mailing list
  • User-space tools
  • UBI headers
    • @@ -57,8 +56,8 @@

    Big red note

    -

    People are often confused about what UBI is, which was the reason for -creating this section. Please, realize that:

    +

    People are often confused about UBI, which is why this section was created. +Please, realize that:

    • UBI is not a Flash Translation Layer (FTL), and it has @@ -74,7 +73,7 @@ creating this section. Please, realize that:

      Please, do not be confused. Read here for more information about how -raw flash devices are different to FTL devices.

      +raw flash devices are different from FTL devices.

      @@ -89,68 +88,70 @@ wear-leveling) across whole flash chip.

      (LVM). Whereas LVM maps logical sectors to physical sectors, UBI maps logical eraseblocks to physical eraseblocks. But besides the mapping, UBI implements -global wear-leveling and transparent I/O errors handling.

      +global wear-leveling and transparent error handling.

      An UBI volume is a set of consecutive logical eraseblocks -(LEBs). Each logical eraseblock may be mapped to any physical eraseblock -(PEB). This mapping is managed by UBI, it is hidden from users and it is -the base mechanism to provide global wear-leveling (along with per-physical -eraseblock erase counters and the ability to transparently move data from more -worn-out physical eraseblocks to less worn-out ones).

      - -

      UBI volume size is specified when the volume is created and may later be +(LEBs). Each logical eraseblock is dynamically mapped to a physical +eraseblock (PEB). This mapping is managed by UBI and is hidden from +users and higher-level software. UBI is the base mechanism which provides +global wear-leveling, per-physical eraseblock erase counters, and the +ability to transparently move data from more worn-out physical eraseblocks +to less worn-out ones.

      + +

      The UBI volume size is specified when a volume is created, but may later be changed (volumes are dynamically re-sizable). There are user-space tools which may be used to manipulate UBI volumes.

      -

      There are 2 types of UBI volumes - dynamic volumes and static +

      There are 2 types of UBI volumes: dynamic volumes and static volumes. Static volumes are read-only and their contents are protected by CRC-32 checksums, while dynamic volumes are read-write and the upper layers (e.g., a file-system) are responsible for ensuring data integrity.

      -

      UBI is aware of bad eraseblocks (e.g., NAND flash may have them) and frees -the upper layers from any bad block handling. UBI has a pool of reserved physical -eraseblocks, and when a physical eraseblock becomes bad, it transparently -substitutes it with a good physical eraseblock. UBI moves good data from the -newly appeared bad physical eraseblocks to good ones. The result is that users -of UBI volumes do not notice I/O errors as UBI takes care of them.

      - -

      NAND flashes may have bit-flips which occur on read and write operations. -Bit-flips are corrected by ECC checksums, but they may accumulate over -time and cause data loss. UBI handles this by moving data from physical -eraseblocks which have bit-flips to other physical eraseblocks. This process is -called scrubbing. Scrubbing is done transparently in background and is -hidden from upper layers.

      - -

      Here is a short list of the main UBI features:

      +

      UBI is aware of bad eraseblocks (i.e. portions of flash which wear +out over time) and frees upper-level software from having to handle bad +eraseblocks itself. UBI has a pool of reserved physical eraseblocks, and +when a physical eraseblock becomes bad, it transparently substitutes +it with a good physical eraseblock. UBI moves the data from newly +discovered bad physical eraseblocks to good ones. The result is that users +of UBI volumes do not notice I/O errors since UBI takes care of them +transparently.

      + +

      NAND flashes are also susceptible to bit-flip errors which occur on read +and write operations. Bit-flips are corrected by ECC checksums, but they +may accumulate over time and cause data loss. UBI handles this by moving +data from physical eraseblocks which have bit-flips to other physical +eraseblocks. This process is called scrubbing. Scrubbing is done +transparently in the background and is hidden from upper layers.

      + +

      Here is a short list of UBI's main features:

      • UBI provides volumes which may be dynamically created, removed, or re-sized;
        • -
      • UBI implements wear-leveling across whole flash device (i.e., you - may continuously write/erase only one logical eraseblock - of an UBI volume, but UBI will spread this to all physical +
      • UBI implements wear-leveling across the entire flash device (i.e., + you might think you're continuously writing/erasing the same logical + eraseblock of an UBI volume, but UBI will spread this to all physical eraseblocks of the flash chip);
      • UBI transparently handles bad physical eraseblocks;
        • -
      • UBI minimizes chances to lose data by means of scrubbing.
        • +
      • UBI minimizes the chances of losing data by means of scrubbing.

      Here is a comparison of MTD partitions and UBI volumes. They are somewhat -because:

      +similar because:

        -
      • both consist of eraseblocks - logical eraseblocks in case of UBI - volumes, and physical eraseblocks in case of MTD partitions;
        • -
      • both support three basic operations - read, write, and erase.
        • +
      • both consist of eraseblocks - logical eraseblocks in the case of UBI + volumes, and physical eraseblocks in the case of MTD partitions;
        • +
      • both support three basic operations: read, write, and erase.

      But UBI volumes have the following advantages over MTD partitions:

        -
      • UBI volumes have no eraseblock wear-leveling constraints, so users - do not have to care about this at all, which means the upper level - software may be simpler;
        • +
      • UBI implements wear-leveling, so users do not have to care about + this at all, which means the upper level software may be simpler;
        • -
      • UBI volumes have no bad eraseblocks, which also leads to simpler - upper level software;
        • +
      • UBI handles bad eraseblocks, which also leads to simpler + upper-level software;
      • UBI volumes are dynamic in a sense that they may be created, removed or re-sized dynamically, while MTD partitions are static;
        • @@ -163,16 +164,16 @@ because:

        and recover;
      • UBI provides an atomic logical - eraseblock change operation which allows to change the contents of + eraseblock change operation which allows changing the contents of a logical eraseblock without loosing the data if an unclean reboot - happens during the operation; this is might be very useful for the + happens during the operation; this might be very useful for the upper-level software (e.g., for a file-system);
      • UBI has an un-map operation, which just un-maps a logical eraseblock from the physical eraseblock, - schedules the physical eraseblock for erasure and returns; this is very + schedules the physical eraseblock for erasure, and returns; this is very quick and frees upper level software from implementing their own - mechanisms to defer erasures (e.g., JFFS2 has to implements such + mechanisms to defer erasures (e.g., JFFS2 has to implement such mechanisms).
      @@ -197,30 +198,15 @@ technology imposes.

      UBI has an internal debugging infrastructure that can emulate power failures for testing. The advantage of the emulation is that it emulates power failures at the critical points where control data structures are -written to the device whereas the probability of interrupting the system at -those precise moments with physical power cut testing is rather low.

      - -

      Source code

      - -

      UBI is in the main-line Linux kernel starting from version -2.6.22. But it is recommended to use the latest UBI, because we -have fixed many bugs since that time, made many improvements and added new -features. The UBI git tree may be found at:

      +written to the device, whereas the probability of interrupting the system at +those precise moments with physical power-cut testing is rather low.

      -git://git.infradead.org/ubi-2.6.git +

      Kernel source code

      -

      Here is the -corresponding Git-web view.

      - -

      The git tree has 2 branches - the master branch and -linux-next branches. The master branch contains the -most recent stuff which is often incomplete, buggy, or has not been tested very -well. This branch is re-based from time to time. Please, do not use it unless -you are an UBI developer. The linux-next branch contains stable -UBI changes which are going to be merged upstream soon. This branch is included -to the linux-next -git tree. Please, use this branch unless you are an UBI developer.

      +

      UBI has been added to the main-line Linux kernel since version +2.6.22. The UBI git tree may be found at:

      +https://git.kernel.org/pub/scm/linux/kernel/git/rw/ubifs.git/

      Mailing list

      @@ -233,12 +219,11 @@ git tree. Please, use this branch unless you are an UBI developer.

      User-space tools

      UBI user-space tools, as well as other MTD user-space tools, are available -from the the following git repository:

      +from the following git repository:

      -git://git.infradead.org/mtd-utils.git +http://git.infradead.org/mtd-utils.git -

      Please, clone it and compile using make from the root mtd-utils -directory. This section +

      This section provides information about how to compile the whole mtd-utils repository tree. You should find the UBI tools under the ubi-utils sub-directory.

      @@ -248,7 +233,7 @@ sub-directory.

    • ubinfo - provides information about UBI devices and volumes found in the system;
    • ubiattach - attaches MTD devices (which describe raw - flash) to UBI and creates corresponding UBI devices;
      • + flash) with UBI which creates corresponding UBI devices;
    • ubidetach - detaches MTD devices from UBI devices (the opposite to what ubiattach does);
    • ubimkvol - creates UBI volumes on UBI devices;
      • @@ -268,12 +253,12 @@ sub-directory.

      found in the system.
    -

    All UBI tools support "-h" option and print sufficient usage +

    All UBI tools support an "-h" option which prints basic usage information.

    Note, the ubiattach and ubidetach tools won't work if the kernel version is less than 2.6.25, because corresponding -UBI features did not exist in the older kernels.

    +UBI features did not exist in these older kernels.

    @@ -284,71 +269,71 @@ eraseblock:

    • erase counter header (or EC header) which contains - the erase counter of the physical eraseblock (PEB) plus some other not - so important information;
      • + the erase counter of the physical eraseblock (PEB) plus other + information;
    • volume identifier header (or VID header) which stores - volume ID and logical eraseblock (LEB) number this PEB belongs to (plus - some other not so important information).
      • + the volume ID and the logical eraseblock (LEB) number to which this PEB + belongs.

    This is why logical eraseblocks are smaller than physical eraseblock - the headers take some flash space.

    -

    All UBI headers are protected by the CRC-32 checksum. Please, -refer the drivers/mtd/ubi/ubi-media.h file in the linux kernel for +

    All UBI headers are protected by a CRC-32 checksum. Please, +refer to the drivers/mtd/ubi/ubi-media.h file in the linux kernel for more information about the header's contents.

    When UBI attaches an MTD device, it has to scan it, read all headers, check the CRC-32 checksums, and store erase counters and the -logical-to-physical eraseblock mapping information in RAM. Please, refer +logical-to-physical eraseblock mapping information in RAM. Please, refer to this section for information about scalability issues related to this.

    -

    After UBI has erased a PEB, it writes the EC header with increased erase -counter value. This means that PEBs always have the EC header, except for the -short period of time after the erasure and before the EC header is written. -Should an unclean reboot happen during this short period of time, the EC header -is lost or becomes corrupted. In this case UBI writes new EC header with an +

    After UBI has erased a PEB, it increments the erase counter value and writes it +to the EC header. This means that PEBs always have a valid EC header, except for +the short period of time after the erasure and before the EC header is written. +Should an unexpected reboot happen during this short period of time, the EC header +is lost or becomes corrupted. In this case UBI writes a new EC header with an average erase counter just after the MTD device scanning is done.

    The VID header is written to the PEB when UBI associates it with an LEB. -Let's consider what happens to the headers in case of some UBI operations.

    +Let's consider what happens to the headers during some UBI operations.

      -
    • The LEB un-map operation just un-maps +
    • The LEB un-map operation simply un-maps the LEB from the PEB and schedules the PEB for erasure. When the PEB is - erased, the EC header is written straight away. The VID header is not + erased, the EC header is written immediately. The VID header is not written.
    • The LEB map operation or a write operation to an un-mapped LEB makes UBI find an appropriate PEB and - write the VID header to it (the EC header must already be there). Note, - the write operation to an already mapped LEB just writes the data - straight to PEB and does not change the UBI headers.
      • + writes the VID header to it (the EC header must already be there). Note, + the write operation to an already-mapped LEB just writes the data + straight to the PEB and does not change the UBI headers.

    UBI maintains two per-PEB headers because it needs to write different -information on flash at different moments of time:

    +information to flash at different moments of time:

      -
    • after a PEB is erased, the EC header is written straight away, +
    • after a PEB is erased, the EC header is written immediately, which minimizes the probability of losing the erase counter due to - unclean reboots;
      • + unexpected reboots;
    • when UBI associates a PEB with an LEB, the VID header is written to the PEB.

    When the EC header is written to a PEB, UBI does not yet know the volume ID -and LEB number this PEB will be associated with. This is why UBI needs to do +nor the LEB number to which this PEB will be associated. This is why UBI needs to do two separate write operations and to have two separate headers.

    UBI volume table

    -

    Volume table is an on-flash data structure which contains information +

    The volume table is an on-flash data structure which contains information about each volume on this UBI device. The volume table is an array of volume table records. Each record contains the following information:

    @@ -357,36 +342,36 @@ table records. Each record contains the following information:

  • volume name;
  • volume type (dynamic or static);
  • volume alignment;
    • -
  • update marker (set for volumes - which had interrupted updates;
    • +
  • update marker (set on a volume + when an update is initiated and cleared when successfully completed);
  • auto-resize flag;
  • CRC-32 checksum for this record.
    • -

    Each record describes one UBI volume and record index in the volume table -array corresponds to the volume ID. I.e, UBI volume 0 is described by record 0 -in the volume table, and so on. Count of records in the volume table is limited -by the LEB size, but cannot be greater than 128. This means that UBI devices -cannot have more than 128 volumes.

    +

    Each record describes one UBI volume. The record index in the volume table +array corresponds to the volume ID it describes. I.e, UBI volume 0 is described +by record 0 in the volume table, and so on. The total number of records in the +volume table is limited by the LEB size, and cannot be greater than 128. This +means that UBI devices cannot have more than 128 volumes.

    Every time an UBI volume is created, removed, re-sized, re-named or updated, the corresponding volume table record is changed. UBI maintains two copies of -the volume for reliability and power-cut tolerance reasons.

    +the volume table for reasons of reliability and power-cut tolerance.

    Implementation details

    Internally, the volume table resides in a special-purpose UBI volume which -is called layout volume. This volume consists of 2 LEBs - one for each +is called the layout volume. This volume consists of 2 LEBs - one for each copy of the volume table. The layout volume is an "internal" UBI volume, and -the users do not see it and cannot access it. When reading or writing the +users do not see it nor access it. When reading or writing the layout volume, UBI uses the same mechanisms which are used for normal user volumes.

    -

    UBI uses the following algorithm when updating a volume table record.

    +

    UBI uses the following algorithm when updating a volume table record:

      -
    • Prepare in-memory buffer with the new volume table contents.
      • +
    • Prepare an in-memory buffer with the new volume table contents.
    • Un-map LEB0 of the layout volume.
    • Write the new volume table to LEB0.
      • @@ -399,8 +384,10 @@ volumes.

      When attaching the MTD device, UBI makes sure that the 2 volume table copies are equivalent. If they are not equivalent, which may be caused by an unclean reboot, UBI picks the one from LEB0 and copies it to LEB1 of the layout volume -(because it is newer). If one of the volume table copies is corrupted, UBI -restores it from the other volume table copy.

      +(because, according to the algorithm specified above, LEB0 is the one that is +updated first and therefore considered to have the most up-to-date information). +If one of the volume table copies is corrupted, UBI restores it from the other +volume table copy.

      @@ -411,37 +398,38 @@ flash (or MTD device) consists of eraseblocks, which may be good or bad. Each good eraseblock may be read from, written to, or erased. Good eraseblocks may also be marked as bad.

      -

      Flash reads and writes may only be done in portions of minimum -input/output unit size, which depends on flash type.

      +

      Flash reads and writes may only be done in multiples of the minimum +input/output unit size, which depends on the flash type.

        -
      • NOR flashes usually have min. I/O unit size of 1 byte, because NOR +
      • NOR flashes usually have a minimum I/O unit size of 1 byte, because NOR flashes usually allow reading and writing single bytes (in fact, it is even be possible to change individual bits).
        • -
      • Some NOR flashes may have other min. I/O unit sizes, e.g. 16 or 32 - bytes in case of ECC'd NOR flashes.
        • +
      • Some NOR flashes may have other minimum I/O unit sizes, e.g. 16 or 32 + bytes in the case of ECC'd NOR flashes.
        • -
      • NAND flashes usually have 512, 2048 or 4096 byte min. I/O. unit - size, which corresponds to NAND page size. NAND flashes store per-NAND - page ECC codes in the OOB area, which means that whole NAND page has to - be written at once to calculate the ECC code, and whole NAND page has to - be read at once to check the ECC code.
        • +
      • NAND flashes usually have minimum I/O sizes of 512, 2048 or 4096 bytes, + which corresponds to their page size. NAND flashes store per-page + ECC codes in the OOB area, which means that whole NAND pages have to + be written at once to calculate the ECC, and whole NAND pages have to + be read at once to check the ECC.
      -

      The min. I/O unit size is a very important characteristic of the MTD device. +

      The minimum I/O unit size is a very important characteristic of the MTD device. It affects many things, e.g.:

        -
      • physical position of the VID - header depends on the min. I/O unit size, which means that LEB size - also depends on it; generally, the larger is the min. I/O unit size, - the less is LEB size, and the greater is UBI flash space overhead;
        • - -
      • all writes to LEBs should be aligned to min. I/O unit size, and - should be multiple of the min. I/O unit size; this does not apply to +
      • the physical position of the VID + header depends on the minimum I/O unit size, which means that the + LEB size also depends on it; generally, the larger the minimum I/O unit + size, the smaller the LEB size, and therefore the greater the UBI flash + space overhead;
        • + +
      • all writes to LEBs should be aligned to the minimum I/O unit size, + and should be multiples of the minimum I/O unit size; this does not apply to reads, but bear in mind that on the MTD level all reads are done in - fractions of min. I/O unit size anyway; this is just hidden from users + multiples of the minimum I/O unit size anyway; this is just hidden from users by buffering the read data and copying only the requested amount of bytes to the user buffer.
      @@ -450,58 +438,57 @@ It affects many things, e.g.:

      NAND flash sub-pages

      -

      As it is said here, all UBI I/O -should be done in fractions of min. I/O unit size, which is equivalent to NAND -page size in case of NAND flash. However, some SLC NAND flashes allow for -smaller I/O units, which are called sub-pages in MTD terminology. Not -all NANDs have sub-pages.

      +

      As mentioned earlier, all UBI I/O +is be performed in multiples of the minimum I/O unit size, which is equivalent +to the NAND device's page size (in the case of NAND flash). However, some SLC NAND +flashes allow for smaller I/O units, which are called sub-pages in MTD +terminology. Not all NAND devices have sub-pages.

        -
      • MLC NANDs do not have sub-pages, at least to the date of writing - of this piece of documentation (April 2009).
        • +
      • MLC NANDs do not have sub-pages (at least as of April 2009).
      • SLC NANDs usually do have sub-pages. E.g., 512-byte NAND pages usually consist of 2x256-byte sub-pages, and 2048-byte NAND pages - consist of 4x512-byte sub-pages.
        • -
      • SLC OneNAND chips with 2048 bytes NAND page size have 4x512-byte + usually consist of 4x512-byte sub-pages.
        • +
      • SLC OneNAND chips with 2048-byte NAND pages have 4x512-byte sub-pages.
      -

      If the NAND flash supports sub-pages, then what can be done is ECC codes -can be calculated on per-sub-page basis, instead of per-NAND page basis. -In this case it becomes possible to read and write sub-pages independently.

      +

      If the NAND flash supports sub-pages, then ECC codes can be calculated on a +per-sub-page basis, instead of a per-page basis. In this case it becomes +possible to read and write sub-pages independently.

      -

      But obviously, even though the NAND chip may support sub-pages, the NAND -controller may disallow them. Indeed, if the flash is managed by a controller -which calculates ECC codes on per-NAND page basis, then it is impossible to -do I/O in sub-page fractions. E.g. this is the case for the +

      However, even though the NAND chip may support sub-pages, the NAND controller +of your SoC might not. If the flash is managed by a controller +which calculates ECC codes only on a per-page basis, then it is impossible to +do I/O in sub-page chunks. E.g. this is the case for the OLPC XO-1 laptop) - its NAND chip supports sub-pages, but the NAND controller does not.

      -

      Note, sub-page is an MTD term, but this is also referred to as "NOP" which -stands for "number of partial programs". NOP1 NAND flashes have no sub-pages - -UBI treats them as NANDS with sub-page size equivalent to NAND page size. NOP2 -NAND flashes have 2 sub-pages (half a NAND page each), NOP4 flashes have 4 -sub-pages (quarter of a NAND page each).

      - -

      UBI utilizes sub-pages to lessen flash space overhead. The overhead is less -if NAND flash supports sub-pages (see here). -Indeed, let's consider a NAND flash with 128KiB eraseblocks and 2048-byte pages. -If it does not have sub-pages, UBI puts the the VID header at physical -offset 2048, so LEB size becomes 124KiB (128KiB minus one NAND page which stores -the EC header and minus another NAND page which stores the VID header. In -opposite, if the NAND flash does have sub-pages, UBI puts the VID header at -physical offset 512 (the second sub-page), so LEB size becomes 126KiB +

      Note, the phrase "sub-page" is an MTD term, but this is also referred to as +"NOP" which stands for "number of partial programs". NOP1 NAND flashes have no +sub-pages - UBI treats them as NANDS with sub-page size equivalent to the NAND page +size. NOP2 NAND flashes have 2 sub-pages (half a NAND page each), and NOP4 +flashes have 4 sub-pages (a quarter of a NAND page each).

      + +

      UBI utilizes sub-pages to reduce flash space overhead. This overhead is +reduced if sub-pages can be used (see here). +Consider a NAND flash with 128KiB eraseblocks and 2048-byte pages. +If it does not have sub-pages, UBI puts the VID header at physical +offset 2048, so the LEB size becomes 124KiB (128KiB minus one NAND page which stores +the EC header and minus another NAND page which stores the VID header). +Conversely, if the NAND flash does have sub-pages, UBI puts the VID header at +physical offset 512 (the second sub-page), so the LEB size becomes 126KiB (128KiB minus one NAND page which is used for storing both UBI headers). See this section for more information about where the UBI headers are stored.

      -

      Sub-pages are used by UBI only internally, and only for storing the headers. -UBI API does not allow users doing I/O in sub-page units. One of the reasons for +

      Sub-pages are only used by UBI internally, and only for storing the headers. +The UBI API does not allow users to perform I/O to sub-page units. One of the reasons for this is that sub-page writes may be slow. To write a sub-page, the driver may -actually write whole NAND page, but put 0xFF bytes to the sub-pages -which are not relevant to this operation. E.g., this means that writing 4 -sub-pages may be 4 times slower than writing whole NAND page at once. Thus, -UBI does use sub-pages for the headers, but this notion does not exist in the +actually write the whole NAND page, but put 0xFF bytes in the sub-pages +which are not relevant to this operation. If this is the case, writing 4 +sub-pages will be 4 times slower than writing the whole NAND page at once. Thus, +UBI does use sub-pages for the headers, but this trick does not extend to the UBI API.

      @@ -509,18 +496,18 @@ UBI API.

      UBI headers position

      The EC header always resides at offset 0 and takes 64 bytes, the VID header -resides at the next available min. I/O unit +resides at the next available minimum I/O unit or sub-page, and also takes 64 bytes. For example:

        -
      • in case of NOR flash which has 1 byte min. I/O unit, the VID header +
      • in the case of NOR flash, which has a 1-byte minimum I/O unit, the VID header resides at offset 64;
        • -
      • in case of NAND flash which does not have sub-pages, the VID header +
      • in the case of a NAND flash which does not have sub-pages, the VID header resides at the second NAND page;
        • -
      • in case of NAND flash which has sub-pages, the VID header resides at +
      • in the case of a NAND flash which has sub-pages, the VID header resides at the second sub-page.
      @@ -537,13 +524,13 @@ amount of flash space available for UBI users. Namely:

    • 1 PEB is reserved for wear-leveling purposes;
    • 1 PEB is reserved for the atomic LEB change operation;
      • -
    • some amount of PEBs is reserved - for bad PEB handling; this is applicable for NAND flash, but not for +
    • some amount of PEBs are reserved + for bad PEB handling; this is applicable for NAND flash but not for NOR flash; the amount of reserved PEBs is configurable and is equal to 20 blocks per 1024 blocks by default;
    • UBI stores the EC and VID headers at the beginning of each - PEB; the amount of bytes used for these purposes depends on the flash + PEB; the number of bytes used for these purposes depends on the flash type and is explained below.
    @@ -553,13 +540,13 @@ amount of flash space available for UBI users. Namely:

  • W - total number of physical eraseblocks on the flash chip (NB: the entire chip, not the MTD partition);
  • P - total number of physical eraseblocks on the MTD - partition);
    • + partition;
  • SP - physical eraseblock size;
  • SL - logical eraseblock size;
  • BB - number of bad blocks on the MTD partition;
  • BR - number of PEBs reserved for bad PEB - handling. it is 20 * W/1024 for NAND by default, and 0 for NOR - and other flash types which do not have bad PEBs;
    • + handling (it is 20 * W/1024 for NAND by default, and 0 for NOR + and other flash types which do not have bad PEBs);
  • B - MAX(BR,BB);
  • O - the overhead related to storing EC and VID headers in bytes, i.e. O = SP - SL.
    • @@ -571,23 +558,23 @@ i.e., this amount of bytes will not be accessible for users. O is different for different flashes:

      -
    • in case of NOR flash which has 1 byte - minimum input/output unit, +
    • in the case of NOR flash, which has a 1-byte + minimum I/O unit, O is 128 bytes;
      • -
    • in case of NAND flash which does not have +
    • in the case of a NAND flash which does not have sub-pages (e.g., MLC NAND), O - is 2 NAND pages, i.e. 4KiB in case of 2KiB NAND page and 1KiB in case - of 512 bytes NAND page;
      • + is 2 NAND pages, i.e. 4KiB in the case of 2KiB NAND pages and 1KiB in the case + of 512-byte NAND pages; -
    • in case of NAND flash which has sub-pages, UBI optimizes its +
    • in the case of a NAND flash which has sub-pages, UBI optimizes its on-flash layout and puts the EC and VID headers at the same NAND page, but different sub-pages; in this case O is only one NAND page;
      • -
    • for other flashes the overhead should be 2 min. I/O units if the - min. I/O unit size is greater or equivalent to 64 bytes, and 2 times - 64 bytes aligned to the min. I/O unit size if the min. I/O unit size +
    • for other flashes the overhead should be 2 minimum I/O units if the + minimum I/O unit size is greater or equivalent to 64 bytes, and 2 times + 64 bytes aligned to the minimum I/O unit size if the minimum I/O unit size is less than 64 bytes.
    @@ -600,35 +587,35 @@ UBI overhead is: (B - BB + 4) * SP +

    Saving erase counters

    When working with UBI, it is important to realize that UBI stores erase -counters on the flash media. Namely, each physical eraseblock has so-called -erase counter header which stores the amount of times this physical eraseblock -has been erased (see here). And of course, -it is important not to lose the erase counters, which means that the tools -you use to erase the flash and to write UBI images have to be UBI-aware. The +counters on the flash media. Namely, each physical eraseblock has an EC +(erase counter) header which stores the amount of times this physical eraseblock +has been erased (see here). +It is important not to lose the erase counters, which means the tools +you use to erase the flash and to write the UBI images have to be UBI-aware. The mtd-utils repository contains the -ubiformat utility which takes things right.

    +ubiformat utility which does things properly.

    -

    How UBI flasher should work

    +

    How a UBI flasher should work

    -

    The following is a list of what the UBI flasher program has to do when -erasing the flash or when flashing UBI images.

    +

    The following is a list of what a UBI flasher program has to do when +erasing the flash or when writing UBI images.

      -
    • First of all, scan the flash and collect the erase counters. Namely, - it read the EC header from each PEB, check the CRC-32 - checksum of the header, and save the erase counter in a RAM. It is not - necessary to read VID headers. Bad PEBs should be skipped.
      • +
    • First, scan the flash and collect the erase counters. Namely, + it reads the EC header from each PEB, checks the CRC-32 + checksum of the header, and saves the erase counter in RAM. It is not + necessary to read the VID headers. Bad PEBs should be skipped.
      • -
    • Calculate average erase counter. It should be used for PEBs with - corrupted or missing EC headers. Such PEBs may be there because of - unclean reboots, but there shouldn't be too many of them.
      • +
    • Next, calculate the average erase counter. This will be used for PEBs with + corrupted or missing EC headers. Such PEBs may occur due to + unexpected reboots, but there shouldn't be too many of them.
    • If the intention is to just erase the flash, then each PEB has to - be erased and proper EC header has to be written at the beginning of - the PEB. The EC header should contain incremented erase counter. Bad - PEBs should be just skipped. For NAND flashes, in case of I/O errors + be erased and a proper EC header has to be written at the beginning of + the PEB. The EC header should contain the updated erase counter. Bad + PEBs should be skipped. For NAND flashes, in the case of I/O errors while erasing or writing, the PEB should be marked as bad (see - here for more information how UBI + here for more information on how UBI marks PEBs as bad).
    • If the intention is to flash an UBI image, then the flasher should @@ -637,9 +624,8 @@ erasing the flash or when flashing UBI images.

      • Read the contents of this PEB from the UBI image (PEB size bytes) into a buffer.
        • -
      • Stripe min. I/O units full of 0xFF bytes from - the end of the buffer (the details are given below in this - section).
        • +
      • Strip minimum I/O units full of 0xFF bytes from + the end of the buffer (the details are given below).
      • Erase the PEB.
      • Change the EC header in the buffer - put the new erase counter value there and re-calculate the CRC-32 @@ -647,8 +633,8 @@ erasing the flash or when flashing UBI images.

      • Write the buffer to the physical eraseblock.
      - As usually, bad PEBs should be just skipped. And for NAND flashes, in - case I/O errors while erasing or writing, the PEB should be marked as + As always, bad PEBs should be skipped, and for NAND flashes, in the + case of I/O errors while erasing or writing, the PEB should be marked as bad.
    @@ -657,20 +643,20 @@ flasher has to flash the used PEBs properly, and erase the unused PEBs properly.

    Note, when writing an UBI image, it does not matter where eraseblocks from -the input UBI image will be written. For example, the first input eraseblock may +the input UBI image are written. For example, the first input eraseblock may be written to the first PEB, or to the second one, or to the last one.

    -

    Also note, if you implement a flasher which writes UBI images at the -production line, i.e., only once, then the flasher does not have to change EC -headers of the input UBI image, because this is new flash and each PEB has -zero erase counter anyway. This means the production line flasher may be -simpler.

    +

    Also note, if you create a flasher to write UBI images at the time of +production, (i.e., new flash, only once) then the flasher does not have to +change the EC headers of the input UBI image, because this is new flash and +each PEB has zero erase counter anyway. This means the production-line flasher +may be simpler.

    -

    If your UBI image contains UBIFS file system, and -your flash is NAND, you may have to drop 0xFF bytes the end of -input PEB data. This is very important, although not required for all NAND +

    If your UBI image contains a UBIFS file system, and +your flash is NAND, you may have to insert 0xFF bytes at the end of +your input PEB data. This is very important, although not required for all NAND flashes. Sometimes a failure to do this may result in very unpleasant problems -which might be difficult to debug later. So we recommend to always do this.

    +which might be difficult to debug later on. So we recommend to always do this.

    The reason for this is that UBIFS treats NAND pages which contain only 0xFF bytes (let's refer them to as empty NAND pages) as free. @@ -685,10 +671,10 @@ written only once, even if the data contains only 0xFF bytes.

    To put it differently, writing 0xFF bytes may have side-effects. What the flasher has to do is to drop all empty NAND pages from the end of the PEB buffer before writing it. It is not necessary to drop all empty NAND pages, -just the last ones. This means that the flasher does not have to scan whole -buffer for 0xFF's. It is enough to scan the buffer from the end +just the last ones. This means that the flasher does not have to scan the whole +buffer for 0xFF's. It is enough to scan the buffer from the end, and stop on the first non-0xFF byte. This is much faster. Here -is the code from UBI which does the right thing.

    +is the code from UBI which does the right thing:

     /**
@@ -719,12 +705,12 @@ int ubi_calc_data_len(const struct ubi_device *ubi, const void *buf,
 
    This function is called before writing the buf buffer to the
 PEB. The purpose of this function is to drop 0xFF's from the end
 and prevent the situation described above. The ubi->min_io_size
-is the minimal input/output unit size which is equivalent to NAND page size.
    
+is the minimal I/O unit size, which is equivalent to the NAND page size.
    
 
-
    By the way, we experienced the similar problems with JFFS2. The JFFS2 images
+
    By the way, we experienced similar problems with JFFS2. The JFFS2 images
 generated by the mkfs.jffs2 program were padded to the physical
-eraseblock size and were later flashed to our NAND. The flasher did not bother
-skipping empty NAND pages. When JFFS2 was mounted, it wrote to those NAND pages,
+eraseblock size and were later flashed to our NAND. The flasher did not bother to
+skip empty NAND pages. When JFFS2 was mounted, it wrote to those NAND pages,
 and the writes did not fail. But later we observed weird ECC errors. It took a
 while to find out the problem. In other words, this is also relevant to JFFS2
 images.
    
@@ -740,19 +726,19 @@ programmer to write a UBI image.  More information is available
 
 
    Marking eraseblocks as bad
    
 
-
    This section is relevant for NAND flashes and other flashes which admit of
-bad eraseblocks. UBI marks physical eraseblocks as bad on 2 occasions:
    
+
    This section is relevant for NAND flashes as well as other flashes which exhibit
+bad eraseblocks. UBI marks physical eraseblocks as bad in the following 2 scenarios:
    
 
 
      
-	
    1. eraseblock write operation failed, in which case UBI moves the
+	
    2. an eraseblock write operation failed, in which case UBI moves the
 	data from this PEB to some other PEB (data recovery) and schedules this
 	PEB for torturing;
      3. 
-	
    3. erase operation failed with EIO error, in which case
-	the eraseblock s marked as bad straight away.
      4. 
+	
    4. the erase operation failed with EIO error, in which case
+	the eraseblock s marked as bad immediately.
      5. 
 
    
 
-
    The torturing is done in background with the purpose of detecting whether the
-physical eraseblock is really bad. The write failure might have happened because
+
    The torturing is done in the background for the purpose of detecting whether the
+physical eraseblock is actually bad. The write failure could have occurred for one
 of many reasons, including bugs in the driver or in the upper level stuff like
 the file system (e.g., the FS mistakenly writes many times to the same NAND
 page). During the torturing UBI does the following:
    
@@ -766,20 +752,20 @@ page). During the torturing UBI does the following:
    
 	0x5A, 0x00).
 
 
-
    The eraseblock is not marked as bad if it survives the torture test. Note, a
-bit-flip during the torture test is treated as a good reason to mark the
-eraseblock bad as well. Please, refer the torture_peb() function
+
    The eraseblock is not marked as bad if it survives the torture test. However,
+a bit-flip during the torture test is a good reason to mark the
+eraseblock as bad. Please, refer to the torture_peb() function
 for detailed information.
    
 
 
 
 
    Scalability issues
    
 
-
    Unfortunately, UBI scales linearly in terms of flash size. UBI
-initialization time linearly depends on the number of physical eraseblocks on
-the flash. This means that the larger is the flash, the more time it takes for
-UBI to initialize (i.e., to attach the MTD device).
-Note: Starting with Linux v3.7 UBI offers an optional and experimental feature,
+
    Unfortunately, UBI performance scales linearly with flash size. UBI
+initialization time is directly proportional to the number of physical
+eraseblocks on the flash. This means that the larger the flash, the more time
+it takes for UBI to initialize (i.e., to attach the MTD device).
+Note: Starting with Linux v3.7 UBI offers an optional and experimental feature
 called "fastmap", which allows attaching in nearly constant time,
 see Fastmap.
 The initialization time depends on the flash I/O speed and (slightly) on the
@@ -789,24 +775,24 @@ CPU speed, because:
    
 	
  • UBI scans the MTD device when attaching - it reads the erase EC and
 	VID headers from every single PEB;
 	the headers are small (64 bytes each), so this means reading 128 bytes
-	from each PEB in case of NOR flash or one or two NAND pages in case of
-	NAND flash (this depends on whether the NAND flash supports
-	sub-pages or not); this is anyway much
-	less than JFFS2 needs to read when it mounts MTD devices, so UBI
+	from each PEB in the case of NOR flash or one or two NAND pages in the
+	case of NAND flash (this depends on whether the NAND flash supports
+	sub-pages or not); in any case this is
+	much less time than JFFS2 needs to read when it mounts MTD devices, so UBI
 	attaches MTD devices many times faster than JFFS2 would mount a file
 	system on the same MTD device;
    • 
 
-	
  • UBI calculates CRC-32 checksum of each EC and VID
-	header, which consumes CPU, although this is usually minor comparing to
+	
  • UBI calculates the CRC-32 checksum of each EC and VID
+	header, which consumes CPU, although this is usually minor compared to
 	the flash I/O overhead.
    • 
 
 
 
    Here are some figures:
    
 
      
-	
    • a 256MiB OneNAND flash found in Nokia N800 devices is attached for
-	less than 1 sec; the flash does support sub-pages so UBI has to read
-	the first 2KiB NAND page of each PEB while scanning;
      • 
-	
    • a 1GiB NAND flash found in OLPC XO-1 devices is attached for about 2
+	
    • a 256MiB OneNAND flash found in Nokia N800 devices attaches in
+	less than 1 sec; the flash does support sub-pages so UBI only has
+	to read the first 2KiB NAND page of each PEB while scanning;
      • 
+	
    • a 1GiB NAND flash found in OLPC XO-1 devices attaches in about 2
 	seconds; the flash is an SLC NAND and supports sub-pages, but the Cafe
 	controller which is used in the laptop does not allow sub-page writes,
 	so UBI has to read two 2KiB NAND pages from each PEB.
      • 
@@ -826,40 +812,40 @@ to us via the MTD mailing list.
      
 	reading an LEB, UBI first looks up the table to find the corresponding
 	PEB number, then reads from this PEB;
 	
    • erase counters (EC) table which contains the erase counter
-	value for each physical eraseblock; UBI wear-leveling sub-system uses
+	value for each physical eraseblock; the UBI wear-leveling sub-system uses
 	this table when it needs to find, for example, a highly worn-out
 	LEB;
      • 
 
    
 
-
    The volume table is maintained on flash. It changes only when UBI volumes are
-created, deleted and re-sized, which are rare and not time-critical operations,
-and UBI can afford a slow and simple method of the volume table management.
    
+
    The volume table is maintained on-flash. It changes only when UBI volumes are
+created, deleted, or re-sized, which are rare and not time-critical operations,
+when UBI can afford slow and simple volume table management.
    
 
 
    The EBA and EC tables are changed every time an LEB is mapped to a PEB or a
 PEB is erased, which happens quite often and means that the table management
 methods should be fast and efficient.
    
 
-
    UBI could maintain on the EBA and EC tables on the flash media, but this
+
    UBI could maintain the EBA and EC tables on the flash media, but this
 would inevitably involve journaling, journal replay, journal commit, etc. In
 other words, this would introduce a lot of complexity. But UBI would be
 logarithmically scalable in this case.
    
 
 
    One of the UBI requirements was simplicity of the on-flash format, because
 UBI authors had to read UBI volumes from the boot-loader and they had very
-tough constraints on the boot-loader code size. It was basically impossible
+tight constraints on the boot-loader code size. It was basically impossible
 to add complex journal scanning and replay code to the boot-loader.
    
 
-
    So UBI does not maintain the EBA and EC tables on the flash media. Instead,
+
    Therefore UBI does not maintain the EBA and EC tables on the flash media. Instead,
 it builds them in RAM each time it attaches the MTD device. This means that UBI
-has to scan whole flash and read the EC and VID headers from each PEB in
-order to build in-RAM EC and EBA tables.
    
+has to scan the entire flash and read the EC and VID headers from each PEB in
+order to build the in-RAM EC and EBA tables.
    
 
 
    The drawbacks of this design are poor scalability and relatively high
 overhead on NAND flashes (e.g., the overhead is 1.5%-3% of flash space in case
-of a NAND flash with 2KiB NAND page and 128KiB eraseblock). The advantages are
-simple binary format and robustness, as the result of simplicity.
    
+of a NAND flash with 2KiB NAND page and a 128KiB eraseblock). The advantages
+of this simplicity are a simple binary format as well as robustness.
    
 
-
    Nonetheless, it is always possible to create UBI2 which would maintain the
+
    Nonetheless, someday we might see a "UBI2" which would maintain the
 tables in separate flash areas. UBI2 would not be compatible with UBI because
 of completely different on-flash formats, but the user interfaces would stay the
 same, which would guarantee compatibility of all the software built on top of
@@ -871,20 +857,20 @@ UBI.
    
 
 
    It is well-known that NAND chips have some amount of physical eraseblocks
 marked as bad by the manufacturer. During the lifetime of the NAND device,
-other bad blocks may appear. Although, manufacturers usually guarantee that
-the first few physical eraseblocks are not bad and the total amount of bad PEBs
+other bad blocks may appear. Nonetheless, manufacturers usually guarantee that
+the first few physical eraseblocks are not bad and that the total number of bad PEBs
 will not exceed certain number. For example, a 256MiB (2048 128KiB PEBs)
 Samsung OneNAND chip is guaranteed to have not more than 40 128KiB PEBs during
 its endurance lifetime. This is a very common value for NAND devices:
 20/1024 PEB, which is about 2% of flash size.
    
 
 
    This ratio of 20/1024 is the default number of blocks that UBI reserves for
-a UBI device. It means that if there's 2 UBI devices on a 4096 PEB NAND, 80 PEB
-for each UBI device will be reserved. This may appear as a waste of
-space, but as far as bad blocks can appear everywhere on the NAND flash, and
-are not equally disposed on the whole device, it's the safer way. So instead of
-using several UBI devices on a NAND flash, it's more space efficient to use only
-one UBI device and several UBI volumes.
    
+a UBI device. This means that if there are 2 UBI devices on a 4096 PEB NAND, 80 PEB
+for each UBI device will be reserved. This may appear to be a waste of
+space, but, given that bad blocks can appear anywhere on the NAND flash, and
+are not equally distributed on the whole device, it's the safer way. So instead of
+using several UBI devices on a NAND flash, it's more space-efficient to use only
+one UBI device which contains several UBI volumes.
    
 
    The default value of 20 PEB reserved per 1024 PEB is a kernel config option.
 For each UBI device, this value can be adjusted via a kernel parameter or an
 ubiattach parameter (since kernel 3.7).
    
@@ -894,19 +880,20 @@ ubiattach parameter (since kernel 3.7).
    
 
 
    Volume auto-resize
    
 
-
    When it is needed to create an UBI image which will be flashed to the end
-user devices in production line, you should define exact sizes of all volumes
-(the sizes are stored in the UBI volume table). But usually, in the embedded
-world, we like to have one (read only) volume for the root file system and
-one read write volume for the rest (logs, user data, etc.). If the size of the
-root file system is fixed, the size of the second one can vary from one product
-to another (different flash sizes) and we just want all space left.
    
+
    When a UBI image is to be flashed during production, one should specify
+exact sizes for all volumes (the sizes are stored in the UBI volume table).
+However, in practice, in the embedded world, we like to have one read only
+volume for the root file system and one read/write volume for however much
+space is left (logs, user data, etc.). If the size of the root file system is
+fixed, the size of the second one can vary from one product to another (given
+different flash sizes).
    
 
-
    That what the auto-resize is about. If the volume has the auto-resize
-mark, its size will be enlarged when UBI is run for the first time. After the
-volume size is adjusted, UBI removes the auto-resize mark and the volume is
-not re-sized anymore. The auto-resize flag is stored in the volume table and
-only one volume may be marked as auto-resize.
    
+
    This is the purpose of the auto-resize flag. If the volume has the
+auto-resize flag enabled, its size will expand to fill the remaining
+unused space when UBI is run for the first time. After the volume size is
+adjusted, UBI removes the auto-resize flag and the volume is not re-sized
+anymore. The auto-resize flag is stored in the volume table and only one
+volume may be marked as auto-resize.
    
 
 
 
@@ -916,7 +903,7 @@ only one volume may be marked as auto-resize.
    
 
 
    The LEB un-map operation is implemented by the
 ubi_leb_unmap() UBI kernel API function. And starting from kernel
-version 2.6.29 the un-map operation is available to the user-space
+version 2.6.29 the un-map operation is available to user-space
 programs via the UBI_IOCEBUNMAP ioctl command. The ioctl should be
 called for UBI volume character devices.
    
 
@@ -925,31 +912,31 @@ called for UBI volume character devices.
    
 	
  • first un-maps the LEB from the corresponding PEB;
    • 
 	
  • then schedules the PEB for erasure and returns; it does not wait
 	for the erasure of the PEB to be finished; the PEB is instead erased
-	in context of the UBI background thread;
    • 
+	by the UBI background thread;
 
 
 
    UBI returns all 0xFF bytes when an un-mapped LEB is read, so
 the un-map operation may be considered as a very fast erase operation. But there
-is one aspect UBI programmers have to be well aware of.
    
+is one aspect to which UBI programmers have to be aware:
    
 
 
    Suppose you un-map LEB L which is mapped to PEB P. Since
 P is not synchronously erased, but just scheduled for erasure, there
-might be "surprises" in case of unclean reboots: if the reboot happens before
+might be "surprises" in the case of unclean reboots: if a reboot happens before
 P has been physically erased, L will be mapped to P again
-when UBI attaches the MTD device after the unclean reboot. Indeed, UBI will
-scan the MTD device and find P which refers L, and it will
+when UBI attaches the MTD device at the next bootup. Indeed, UBI will
+scan the MTD device and find the P which refers to L, and it will
 add this mapping information to the
 EBA table.
    
 
-
    But once you write any data to L, or map it using the
-LEB map operation, it gets mapped to a new PEB
-and the old contents goes forever, because even in case of an unclean reboot UBI
-would pick the newer mapping for L.
    
+
    However, once you write any data to L, or map it using the LEB map operation, it gets mapped to a new PEB and
+the old contents are gone forever, because even in the case of an unclean
+reboot UBI would pick the newer mapping for L.
    
 
 
    Implementation details
    
 
 
    This section describes how UBI distinguishes between older and newer
-versions of an LEB in case of an unclean reboot. Suppose we un-map LEB
+versions of an LEB in the case of an unclean reboot. Suppose we un-map LEB
 L which is mapped to PEB P1, which means UBI schedules
 P1 for erasure. Then we write some data to L, which
 means that UBI finds another PEB P2, maps L to
@@ -959,56 +946,56 @@ after the write operation, we end up with 2 PEBs (P1 and
 P2) mapped to the same LEB L.
    
 
 
    To handle situations like this, UBI maintains a global 64-bit sequence
-number variable. The sequence number variable is increased each time a PEB
+number variable. The sequence number variable is incremented each time a PEB
 is mapped to a LEB and its value is stored in the
 VID header of the PEB. So each VID header
-has a unique sequence number, and the larger is the sequence number, the
-"younger" is the VID header. When UBI attaches MTD devices, it initializes the
-global sequence number variable to the highest value found in existing VID
+has a unique sequence number, and the larger the sequence number, the
+"younger" the VID header. When UBI attaches MTD devices, it initializes the
+global sequence number variable to the highest value found in the existing VID
 headers plus one.
    
 
-
    In the above situation, UBI just selects a PEB with higher sequence number
-(P2) and drops the PEB with lower sequence number
+
    In the above situation, UBI simply selects a PEB with the highest sequence number
+(P2) and drops the PEB with the lower sequence number
 (P1).
    
 
 
    Note, the situation is more difficult if an unclean reboot happens when UBI
-moves the contents of one PEB to another for a wear-leveling purposes, or when
-it happens during the atomic LEB change
+moves the contents of one PEB to another for wear-leveling purposes, or when
+the unclean reboot happens during an atomic LEB change
 operation. In this case it is not enough to just pick the newer PEB, it is also
-necessary to make sure the data reached the the new PEB.
    
+necessary to make sure the data reached the new PEB.
    
 
 
 
 
    LEB map
    
 
 
    The LEB map operation maps a previously
-un-mapped logical eraseblock to a physical
-eraseblock. For example, if the operation is run for LEB A, UBI will
-find appropriate PEB, write VID header to
+un-mapped logical eraseblock (LEB) to a physical
+eraseblock (PEB). For example, if the operation is run for LEB A, UBI will
+find an appropriate PEB, write a VID header to
 the PEB, and amend the in-memory
-EBA table. The VID header will
-refer LEB A. After this operation all I/O to LEB A will actually
+EBA table. The VID header will now
+refer to LEB A. After this operation all I/O to LEB A will actually
 go to the mapped PEB.
    
 
 
    The LEB map operation is available via the ubi_leb_map()
 UBI kernel API function, or via the UBI_IOCEBMAP volume character
-device ioctl command. However, thie ioctl interface is available only starting
+device ioctl command. However, this ioctl interface is available only starting
 from kernel version 2.6.29.
    
 
-
    One of the possible use-cases of the LEB map operation is making sure the
-old LEB contents goes away forever. As it was explained in
+
    One of the functions of the LEB map operation is to make sure
+old LEB contents are removed. As was explained in
 this section, when an LEB is un-mapped, the
-corresponding PEB is not erased straight away. And if an unclean reboot happens,
-the LEB may becomes mapped to the same PEB again, after the UBI attaches the
-MTD device. So, if you map the LEB just after un-mapping it, you are guaranteed
-that the old LEB contents never comes back. In other words, the LEB is guaranteed
+corresponding PEB is not erased immediately. If an unclean reboot happens,
+the LEB may become mapped to the same PEB again, after the UBI attaches the
+MTD device. So, if you map the LEB immediately after un-mapping it, you are guaranteed
+that the old LEB contents are deleted. In other words, the LEB is guaranteed
 to contain only 0xFF bytes after the map operation returns, even in case of an
 unclean reboot.
    
 
-
    Please, use the LEB map operation carefully. Do not use this unless it is
+
    Please, use the LEB map operation sparingly. Do not use it unless it is
 really needed, because mapped LEBs add more overhead on the UBI wear-leveling
 sub-system, comparing to un-mapped LEBs. Indeed, if an LEB is un-mapped, there
-is no PEB which contains LEB's data, and the wear-leveling sub-system does not
+is no PEB which contains this LEB's data, and the wear-leveling sub-system does not
 have to move any data to maintain wear-leveling. Conversely, if the LEB is
 mapped to a PEB, there is one more PEB for the wear-leveling sub-system to care
 about, and one more LEB to re-map to another PEB if the erase counter of the
@@ -1019,26 +1006,27 @@ erase counter and the old PEB is used for other operations).
    
 
 
    Volume update
    
 
-
    The volume update operation is be useful for device software updates.
-The operation changes the contents of whole UBI volume with new contents. But if
+
    The volume update operation is useful for device software updates.
+The operation changes the contents of the whole UBI volume with new contents. But if
 it gets interrupted in the middle of the update, the volume goes into the
 "corrupted" state and further I/O on the volume ends up with an
-EBADF error. And the only way to get the volume back to the normal
+EBADF error. The only way to get the volume back to the normal
 state is to start a new volume update operation and finish it.
    
 
-
    The volume update operation allows detecting interrupted updates and
-re-starting it with help of, for example, a "mirror" volume which would have the
-same contents or by showing a dialog window which would inform the user
-about the problem and request flashing. In contrast, it is difficult to
-detect interrupted updates in case of raw MTD partitions.
    
+
    The volume update operation can detect interrupted updates and re-start
+the update with the help of, for example, a "mirror" volume which would have
+the same contents or by showing a dialog window which would inform the user
+about the problem and request re-flashing. In contrast, it is difficult to
+detect interrupted updates when using raw MTD partitions.
    
 
 
    The volume update operation is available via the user-space UBI interface and
 not available via the UBI kernel API. To update a volume, you first have to call
-the UBI_IOCVOLUP ioctl of the corresponding UBI volume character
-device and pass it a pointer to a 64-bit value containing the length of the new
-volume contents in bytes. Then this amount of bytes has to be written to the
-volume character device. Once the last byte has been send to the character
-device, the update operation is finished. Schematically, the sequence is:
    
+the UBI_IOCVOLUP ioctl on the corresponding UBI volume character
+device node and pass it a pointer to a 64-bit value containing the length of the new
+volume contents in bytes. Then this number of bytes has to be written to the
+volume character device node. Once the last byte has been sent to the character
+device node, the update operation is finished. Conceptually, the sequence (in
+pseudo-code) is:
    
 
 
     fd = open("/dev/my_volume");
@@ -1048,59 +1036,57 @@ close(fd);
 
    
 
 
    See include/mtd/ubi-user.h for more details. Bear in mind, the
-old contents of the volume is not preserved in case of an interrupted update.
-Also, you do not have to write all new data at one go. It is OK to call
-the write() function arbitrary number of times and pass arbitrary
-amount of data each time. The operation will be finished after all the data
-have been written. If the last write operation contains more bytes than UBI
-expects, the extra data are just ignored.
    
-
-
    Special case of the volume update operation is what we call volume
-truncation, which is done by the same ioctl command if the data length is
-zero. In this case the volume is just wiped out and will contain all
+old contents of the volume are not preserved if the update is interrupted.
+Also, you do not have to write all the new data in one go. It is OK to call
+the write() function an arbitrary number of times and pass arbitrary
+amounts of data each time. The operation will be finished after all the data
+has been written. If the last write operation contains more bytes than UBI
+expects, the extra is ignored.
    
+
+
    A Special case of the volume update operation is what we call volume
+truncation, which is done by the same ioctl command when the data length is
+zero. In this case the volume is wiped out and will contain all
 0xFF bytes (all LEBs will be un-mapped).
    
 
 
    Note, the /sys/class/ubi/ubiX_X/corrupted sysfs file reflects
 the "corrupted" state of the volume: it contains ASCII "0\n" if the volume is OK
-and "1\n" if it is corrupted (because volume update had started but was not
-finished).
    
+and "1\n" if it is corrupted (i.e. if a volume update was started but was not
+completed).
    
 
-
    The volume update operation does not preserve the old volume contents if it
-is interrupted, so it is not atomic. However, UBI also provides atomic volume
+
    The volume update operation does not preserve its previous contents if the
+update is interrupted; it is not atomic. However, UBI does provide atomic volume
 updates by means of the volume re-name operation.
    
 
-
    The volume update is implemented with help of so-called update
-marker. Once the user has issued the UBI_IOCVOLUP ioctl, UBI
+
    Volume updates are implemented with the help of update
+markers. Once the user has issued the UBI_IOCVOLUP ioctl, UBI
 sets the update marker flag for the volume in the corresponding record of the
-UBI volume table. Then the volume is wiped
-out and UBI waits for the the user to pass the data. Once all the data have
-arrived and have been written to the flash, the update marker is cleaned. But
-in case of an interruption (e.g., unclean reboot, crash of the update
-application, etc.), the update marker is not cleaned and the volume is treated
-as "corrupted". Only a new successful update operation may clean the update
-marker.
    
+UBI volume table. At this point the volume
+is wiped, and UBI waits for the user to send the data. Only when all the data
+has been sent and has been written to the flash successfully, will the update
+marker be cleared. If the update is interrupted (e.g., unclean reboot, crash
+of the update application, etc.), the update marker is not cleared and the
+volume is treated as "corrupted". Only once a successful update operation has
+occurred will the update marker be cleared.
    
 
 
 
 
    Atomic LEB change
    
 
 
    The atomic LEB change operation changes the contents of an LEB
-atomically, so that the old contents is preserved if the operation is
-interrupted. In other words, the result of the operation is that the LEB either
-has the old contents or the new contents.
    
-
-
    The operation is available via the ubi_leb_change() kernel API
-call. The user-space interface for this operation exists starting from kernel
-version 2.6.25.
    
-
-
    The user-space atomic LEB change operation is run via the
-UBI_IOCEBCH ioctl command. You have to pass a pointer to a properly
-filled request object of struct ubi_leb_change_req type. The
-object stores the LEB number to change and the length of the new contents. Then
-you have to write the specified amount of bytes to the volume character device.
-Notice some similarity to the user-space interface of the
-volume update operation. Schematically,
-the sequence is:
    
+atomically, so that the old contents are preserved should the operation be
+interrupted. In other words, the LEB will always contain either the old
+contents or the new contents. This functionality is available via the
+ubi_leb_change() kernel API call.
    
+
+
    The user-space interface for this operation was added in kernel version
+2.6.25. Its functionality is available to user-space via the
+UBI_IOCEBCH ioctl command. You have to pass a pointer to a
+properly-filled request object of struct ubi_leb_change_req
+type. This object stores the LEB number to change and the length of
+the new contents. Then you have to write the specified number of
+bytes to the volume character device. Note the similarity to the
+volume update operation. Conceptually, the
+sequence (in pseudo-code) is:
    
 
 
     struct ubi_leb_change_req req;
@@ -1113,29 +1099,29 @@ write(fd, data_buf, data_len);
 close(fd);
 
    
 
-
    If for some reason the user does not write the declared amount of bytes
-and closes the file, the operation is canceled and the old contents of the LEB
-is preserved.
    
+
    If, for some reason, the user does not write the specified number of bytes to
+the file descriptor before closing the file, the operation is cancelled and
+the old contents of the LEB are preserved.
    
 
-
    Similarly tho the volume update operation it does not matter how many times
+
    Similarly to the volume update operation, it does not matter how many times
 the write() function is called and how much data it passes to the
-UBI volume each time. The atomic LEB change operation finishes once the last
+UBI volume each time. The atomic LEB change operation finishes only once the last
 data byte has arrived.
    
 
-
    The atomic LEB change operation might be very useful for file-systems, for
-example UBIFS uses this operation as the last resort
-when it commits the file-system index. This operation may also be exploited
-to create an FTL layer on top of UBI (see 
-here for the description of the idea).
    
+
    The atomic LEB change operation might be very useful for file-systems,
+for example UBIFS uses this functionality when it
+commits the file-system index. This behaviour could also be used to create an
+FTL layer on top of UBI (see
+
+here for a description of the idea).
    
 
 
    Keep in mind that the atomic LEB change operation calculates the
-CRC-32 checksum of the new data, so it has some overhead comparing
-to the LEB erase plus LEB write sequence. The volume update operation does not
-calculate data CRC-32, so it is faster to update the volume than to
-atomically change all its eraseblocks. This additional overhead has to be
-remembered about and the operation should not be used if the atomicity is not
-really needed.
    
+CRC-32 checksum of the new data, so it has some overhead compared
+to the "LEB erase" + "LEB write" sequence. The volume update operation does
+not calculate the data's CRC-32 checksum, so it is faster to
+update the volume than it is to atomically change all its eraseblocks. Keep
+this overhead in mind and be sure to only use this operation if/when atomicity
+is really needed.
    
 
 
    Implementation details
    
 
@@ -1143,33 +1129,33 @@ really needed.
    
 physical eraseblock P1. First of all, UBI always has one free
 PEB reserved for the atomic LEB change operation, let it be
 P2. Before the operation, P1 stores the
-contents of the LEB L and P2 is free (it contains only
-the EC header and 0xFF bytes). The new data are written to
+current contents of the LEB L and P2 is free (it contains only
+the EC header and 0xFF bytes). The new data is written to
 P2, not to P1, so should anything go wrong,
-the old contents of the LEB is always there.
    
+the old contents of the LEB are maintained.
    
 
 
    When the operation finishes, UBI un-maps L from P1,
 maps in to P2, and schedules P1 for erasure.
-If the operation is interrupted, L stays being mapped to
+If the operation is interrupted, L continues to be mapped to
 P1 and P2 is scheduled for erasure.
    
 
 
    If an unclean reboot happens half way through the atomic LEB change
 operation, it is obvious that UBI has to preserve the
-L -> P1 mapping and erase P2 when it is
-attaches the MTD device next time. But if the unclean reboot happens just after
+L -> P1 mapping and erase P2 when it
+attaches the MTD device on the next reboot. But if an unclean reboot happens just after
 the atomic LEB change operation finishes, but before P1 is
-physically erased, it is obvious that UBI has to preserve
+physically erased, it is obvious that UBI has to preserve the
 L -> P2 mapping and erase P1.
    
 
-
    To resolve situations like that, UBI calculates CRC-32 checksum
-of the new contents of the LEB before it is written to flash, and stores it in
+
    To resolve situations like that, UBI calculates the CRC-32 checksum
+of the new contents of the LEB before it is written to the flash, and stores it in
 the VID header (together with data length). When UBI finds 2 PEBs
 P1 and P2 mapped to the same LEB L
-during the initialization, it selects the one with higher sequence number
-(P2) only if the data CRC-32 is correct (which
+during the initialization, it selects the one with the higher sequence number
+(P2) only if the data CRC-32 checksum is correct (which
 means that all data has been written to the flash media), otherwise it selects
 the PEB with lower sequence number(P1). Of course, UBI has to
-read the LEB contents in order to check the CRC-32 checksum.
    
+read the LEB contents in order to verify the CRC-32 checksum.
    
 
 
 
@@ -1178,8 +1164,8 @@ read the LEB contents in order to check the CRC-32 checksum.
    
 by setting CONFIG_MTD_UBI_FASTMAP to 'y'. Once enabled UBI evaluates the module
 parameter "fm_autoconvert". If it is set to 1 (default is 0) UBI automatically
 enables fastmap for any attached image. This means UBI creates a new internal
-volume with the fastmap data such that next time the fast attach mode can be
-used.
    
+volume with the fastmap data such that next time the image is attached, the
+fast attach mode can be used.
    
 
 
    In the default configuration UBI will use the information stored in this
 fastmap volume to accelerate the attach procedure. If you want to test
@@ -1204,15 +1190,15 @@ fastmap, set fm_autoconvert to 1 and attach a volume.
    
 
 y
 0
-UBI will attach by fastmap if one exists on an image,
-but no fastmap will be installed on images without a fastmap
+UBI will use the fastmap data if it exists on an image,
+but will not install a fastmap on images that don't already have it
 
 
 
 y
 1
-UBI will attach by fastmap if one exists on an image, a fastmap
-is automatically installed on all attached images
+UBI will use the fastmap data if it exists on an image, and a fastmap
+is automatically created on all attached images
 
 
 
@@ -1220,30 +1206,30 @@ is automatically installed on all attached images
 
    Backwards compatibility
    
 
 
    The fastmap on-disk data structure makes use of delete compatible volumes,
-therefore fastmap enabled images are fully backwards compatible with UBI
+therefore fastmap-enabled images are fully backwards compatible with UBI
 implementations which do not support fastmap. The kernel will remove the
-fastmap volumes and continue with scanning. This includes not only v3.6- but
-also v3.7+ with this option disabled.
    
+fastmap volumes and continue with scanning. This includes not only kernel
+version v3.6- but also v3.7+ with this option disabled.
    
 
 
    Technical design
    
 
-
    A on-disk fastmap contains all information needed to attach the whole image,
-namely all erase counter values, a list of all PEBs and their state, a list of
-all volumes and their current EBA, ...
+
    An on-disk fastmap contains all the information required to attach the whole image,
+including: all erase counter values, a list of all PEBs and their state, a list of
+all volumes and their current EBA, etc...
 To avoid too many writes of the fastmap, it also contains a list of PEBs which
 may have changed and need a full scan while attaching.
-This list is called "fastmap pool" and has a fixed sized, 5% of the total
-amount of PEBs. Using this technique UBI needs to write the fastmap only if the
+This list is called the "fastmap pool" and has a fixed size of 5% of the total
+number of PEBs. By design UBI needs to write the fastmap data only if the
 pool contains no free PEBs. Otherwise it would have to write the fastmap each
 time the EBA of a volume has changed.
    
 
-
    A fastmap consists of a super block (also known as anchor PEB) and payload
+
    A fastmap consists of a super-block (also known as an anchor PEB) and payload
 data which can live on any PEB.
 The anchor PEB has to be located within the first 64 PEBs on the MTD device.
 It contains pointers to the remaining PEBs which carry the actual fastmap
 data. On modern NAND chips the whole fastmap fits into a single PEB.
 Hence, the anchor PEB points to itself.
-After loading the fastmap data, UBI attach information structure is created
+After loading the fastmap data, the UBI attach information structure is created
 from it.
    
 
 
    The attach process works as follows:
    
@@ -1257,44 +1243,45 @@ from it.
    
 	instead of all PEBs
 
 
-
    If UBI detects that the used fastmap is invalid or corrupted it
+
    If UBI detects that the fastmap data is invalid or corrupt it
 automatically falls back to scanning mode and performs a full scan. Using a
 CRC32 checksum and consistency checks of the internal UBI structures UBI is
-able to detect whether a fastmap is invalid or not.
    
+able to detect whether the fastmap data is invalid or not.
    
 
-
    A fastmap is written to the devices each time the fastmap pool becomes full
-(no free PEBs are available), the volume layout changes or the image is
-detached. One may wonder why writing at detach time is needed.  If UBI would
-not write a new fastmap at detach time all erase counter modifications since
-the last fastmap write are lost.
    
+
    The fastmap data is written to the device: each time the fastmap pool becomes full
+(i.e. no free PEBs are available), the volume layout changes, or the image is
+detached. If you are wondering why the fastmap data needs to be written at
+detach time, it is because otherwise all erase counter modifications since
+the last fastmap write would be lost.
    
 
 
    Overhead
    
 
-
    If fastmap enabled UBI will reserve enough PEBs to carry two complete
+
    A fastmap-enabled UBI will reserve enough PEBs to carry two complete
 fastmaps. In practice on modern NAND chips two PEBs are reserved for fastmap.
    
 
-
    There is also some runtime overhead, to guarantee that the new fastmap is valid
-and conistent UBI has to take care that all IO which would cause EBA changes
-are blocked while attaching. Depending on flash chips this can take up to one
-second. Therefore, fastmap makes only sense on fast and large flash devices
-where a full scan takes too long. E.g. On 4GiB NAND chips a full scan takes
-several seconds whereas a fast attach needs less than one second.
    
+
    There is also some runtime overhead. In order to guarantee that the new fastmap is valid
+and consistent, UBI needs to make sure that all I/O which would cause EBA changes
+are blocked while attaching. Depending on the specific flash chips, this can take up to one
+second. Therefore, fastmap only makes sense on fast and large flash devices
+where a full scan would otherwise take too long. For example: on 4GiB NAND
+chips a full scan takes several seconds, whereas a fast attach needs less than
+one second.
    
 
 
 
    Notes
    
 
-
    Enabling fastmap does not guarantee that every attach process can be done
-in a fast way. In some situations a full scan is still needed.
-This can happen in two cases, (i) if a power cut occurred while a fastmap was
-written to the flash or (ii) UBI ran out of PEBs while writing the fastmap.
-The latter case can happen if a massive amount of IO errors happen while writing
-and UBI cannot find an usable PEB.
+
    Enabling fastmap does not guarantee that every attach process will be done
+in optimal time. In some situations a full scan is still needed.
+This can happen in two cases: (i) if an unexpected reboot occurs while a fastmap is being
+written to the flash or (ii) UBI runs out of PEBs while writing the fastmap.
+The latter case can happen if a massive amount of I/O errors happen while writing,
+and UBI cannot find enough usable PEBs.
 
    
 
 
 
    R/O block devices on top of UBI volumes
    
 
-
    UBI allows to create block devices on top of UBI volumes with
+
    UBI allows the creation of block devices on top of UBI volumes with
 the following limitations:
    
 
 
      
@@ -1303,11 +1290,11 @@ the following limitations:
      
 	    already serializes all I/O too.
 
    
 
-
    Despite these limitations, a block device is still very useful to mount
-read-only, regular file systems on top of UBI volumes. This is the case
-of squashfs, which can be used as a lightweigth read-only rootfs on a NAND
-device. The UBI layer will take care of things like bit-flips handling and
-wear-levelling.
    
+
    Despite these limitations, a block device is still very useful for the
+purpose of mounting read-only, regular file systems on top of UBI volumes.
+Take, for example, squashfs, which can be used as a lightweight read-only
+rootfs on top of a NAND device. In this case, the UBI layer will take care of
+low-level details such as bit-flip handling and wear-levelling.
    
 
 
 
    Usage
    
@@ -1316,13 +1303,13 @@ wear-levelling.
    
 attaching MTD devices to UBI. You can either use the block UBI
 module parameter or use the "ubiblock" user-space tool.
    
 
-
    In order to create a block device on bootup time (e.g. to mount the rootfs
+
    In order to create a block device at bootup time (e.g. to mount the rootfs
 on such a block device) you can specify the block parameter as
-a kernel boot arguments:
    
+a kernel boot argument:
    
 
 ubi.mtd=5 ubi.block=0,0 root=/dev/ubiblock0_0
 
-
    There are several ways if specifying a volume:
    
+
    There are several ways of specifying a volume:
    
 
      
 	
    • Using the UBI volume path:
      
 	ubi.block=/dev/ubi0_0
      • 
@@ -1330,11 +1317,11 @@ a kernel boot arguments:
      
 	
    • Using the UBI device, and the volume name:
      
 	ubi.block=0,rootfs
      • 
 
-	
    • Using both UBI device number and UBI volume number:
      
+	
    • Using both the UBI device number and the UBI volume number:
      
 	ubi.block=0,0
      • 
 
    
 
-
    If you've built UBI as a module you can use this parameter at module
+
    If you've built UBI as a module you can use the following parameters at module
 load time:
    
 
 
    @@ -1352,11 +1339,12 @@ $ ubiblock --remove /dev/ubi0_0
 
 
    UBI stress testing
    
 
-
    If enabled, mtd-utils include user-space tools that can be used to stress
-test the UBI stack. This is useful if you want to test the stability and
-correctness of your particular UBI stack implementation.
    
+
    If enabled when configuring (right before building the code), mtd-utils
+includes user-space tools that can be used to stress test the UBI stack.
+This is useful if you want to test the stability and correctness of your
+particular UBI stack implementation.
    
 
-
    Example, running various UBI tests:
    
+
    Example: running various UBI tests:
    
 
 
     $ flash_erase /dev/mtd3 0 0
@@ -1367,25 +1355,24 @@ $ /usr/libexec/mtd-utils/runubitests.sh /dev/ubi0
 
 
    More documentation
    
 
-
    Unfortunately, there are no thorough and strict UBI documents. But there is
-an old UBI design document which has some out-of-date information, but is still
-useful: ubidesign.pdf.
    
+
    Unfortunately, no complete, up-to-date design documents exist for UBI. But there is
+an old UBI design document which has some out-of-date information which might
+still be of limited use: ubidesign.pdf.
    
 
 
    There is also a PowerPoint UBI presentation available:
-ubi.ppt. Note, this document has to be looked at
-in Windows, because it contains a lot of animation and Open Office cannot
-properly show it. Use slide show (F5 key) when you look, because
-otherwise the animation is not shown.
    
+ubi.ppt. Note, this document contains a lot of
+animations, so be sure to view it in "slide show" mode (F5 key)
+so that the animations will be played.
    
 
-
    Many useful information may be found at the
+
    More information may be found in the
 FAQ section.
    
 
-
    And of course just reading the UBI interface C header files which contains
-quite a few commentaries may help: include/mtd/ubi-user.h
+
    And of course just reading the UBI interface C header files (which are
+well commented) may help: include/mtd/ubi-user.h
 contains the user-space interface definition (namely, it defines UBI ioctl
-commands and the involved data structures),
-include/linux/mtd/ubi.h defines the kernel API and the
-drivers/mtd/ubi/kapi.c file contains comments for each kernel API
+commands and the associated data structures),
+include/linux/mtd/ubi.h defines the kernel API, and
+drivers/mtd/ubi/kapi.c contains comments for each kernel API
 function (just above the body of the function).
    
 
 
-- 
2.49.0