Changes between Version 15 and Version 16 of linux/ubi


Ignore:
Timestamp:
04/24/2019 08:04:52 PM (6 years ago)
Author:
Tim Harvey
Comment:

use 'large' and 'normal' flash geometry names instead of flash sizes; general cleanup

Legend:

Unmodified
Added
Removed
Modified

  • linux/ubi

    v15 v16  
    11[[PageOutline]]
    22
    3 = Unsorted Block Images (UBI) =
     3= Unsorted Block Images (UBI)
    44Unsorted block images (UBI) is an erase block management layer for flash memory devices such as raw NAND devices. UBI serves two purposes:
    55 * tracking NAND flash bad blocks
    … …  
    1414
    1515
    16 = FLASH chip geometry =
     16= FLASH chip geometry
    1717[=#flashgeometry]
    1818Because UBI takes care of bad block tracking and wear leveling, it needs to know some details about the geometry of the raw FLASH device when creating an image.
    1919
    20 The geometry data can be found in the datasheet for the specific flash device used. Gateworks uses two different sized devices which do not share geometries.
    21 
    22 
    23 = UBI use on Gateworks Ventana =
    24 UBI is used on the Gateworks Ventana for raw NAND storage. Prior Gateworks product families typically JFFS2.
     20The geometry data can be found in the datasheet for the specific flash device used. Gateworks uses a variety of NAND Flash devices that fall within two different unique geometries we refer to as 'normal' and 'large' which references the erase block size:
     21||= NAND Part =||= NAND Size =||= Page Size (Bytes) =||= Block Size =||= Logical Erase Block Size =||= Blocks =||= READ_ID Bytes =||= Gateworks Geometry Name =||
     22|| Cypress S34ML16G202 || 2GiB || 2048 || 128KiB || 124KiB || 16384 || 0x01 0xd5 0xd2 0x95 || normal ||
     23|| Micron MT29F2G08  || 256MiB || 2048 || 128KiB || 124KiB || 2048 || 0x2c 0x90 0x95 0x06 || normal ||
     24|| Micron MT29F16G08 || 2GiB || 4096 || 256KiB || 248KiB || 8192 || 0x2c 0xd5 0xd1 0xa6 || large ||
     25|| Micron MT29F8G08  || 1GiB || 4906 || 256KiB || 248KiB || 4096 || 0x2c 0xdc 0x00 0x15 || large ||
     26 * The 'Page Size', 'Block Size', and max blocks are specified by the NAND datasheet. The Logical Erase Block size can be calculated as: (Block Size) - 2 * (Page Size)
     27
     28
     29mkfs.ubifs important arguments:
     30 * **-r** Build file system from directory DIR
     31 * **-F**  The -F option causes mkfs.ubifs to set a special flag in the superblock, which triggers a "free space fixup" procedure in the kernel the very first time the filesystem is mounted. This fixup procedure involves finding all empty pages in the UBIFS file system and re-erasing them. This ensures that NAND pages which contain all 0xFF data get fully erased, which removes any problematic non-0xFF data from their OOB areas.
     32 * **-m** Minimum I/O unit size (this is the Page Size)
     33 * **-e** Logical erase block size (UBI requires 2 minimum I/O units out of each Physical Erase Block (PEB) for overhead thus this is the 'Block Size' minus 2x the Page Size
     34 * **-c** Maximum logical erase block count (Number of Blocks; use the largest of the chips in the same geometry in order to create a ubifs that works on all the above NAND devices)
     35 * **-x** Compression type - "lzo", "favor_lzo", "zlib" or "none" (default: "lzo")
     36 * **-o** Output to FILENAME
     37 * **-h** Help, provides full list of options
     38
     39ubinize important arguments:
     40 * **-o** Output file
     41 * **-p** Size of the physical eraseblock of the flash in bytes, KiB, or MiB
     42 * **-m** Minimum input/output unit size of the flash in bytes (this is the Page Size)
     43
     44= UBI/UBIFS use on Gateworks Ventana
     45UBI is used on the Gateworks Ventana for raw NAND storage. Other Gateworks Product families used NOR FLASH and eMMC.
    2546
    2647The Gateworks Ventana default U-Boot environment scripts make a few assumptions about booting from NAND flash:
    … …  
    3556
    3657
    37 == Creating a UBI using existing rootfs, kernel, and device-tree blobs ==
     58
    3859[=#creatingubi]
     60== Creating a UBI/UBIFS using existing rootfs, kernel, and device-tree blobs
    3961To create a UBI image suitable for booting on a standard Gateworks Ventana bootloader (taking into account the assumptions above) you can do the following on a Linux system provided you have a root filesystem ({{{myrootfs.tar.gz}}}), kernel ({{{uImage}}}), and device-tree dtb files ({{{imx6*-gw*.dtb}}}).
    4062
    4163
    42 === 256MB FLASH devices ===
    43 To create a UBI image suitable for the 256MB FLASH devices:
     64=== 'normal' geometry FLASH devices (2048 byte page size)
     65To create a UBI image suitable for raw NAND FLASH devices with a 2048 byte page size:
    44661. create a temporary directory for our rootfs and untar your filesystem to it
    4567{{{#!bash
    … …  
    5375cp uImage imx6*-gw*.dtb 6x_bootscript-ventana tmp/boot/
    5476}}}
    55 3. create a ubifs image for the 256MB device geometry:
    56 {{{#!bash
    57 mkfs.ubifs -F -m 2048 -e 124KiB -c 1912 -x zlib -o root.ubifs -d tmp
    58 }}}
    59 4. use {{{ubinize}}} to create ubi images for the 256MB device geometry which can be written to a suitable raw NAND devices in U-Boot using {{{nand write}}}:
    60 {{{#!bash
    61 # for the small layout device
     773. create a ubifs image for the 2048 byte page size 'normal' device geometry:
     78{{{#!bash
     79mkfs.ubifs -F -m 2048 -e 124KiB -c 16248 -o root.ubifs -d tmp
     80}}}
     81 * the -c parameter (max-peb-count) of 16248 assures that the filesystem can be sized up to 16248*124KiB or 1.9GiB provided there is remaining space in the ubi
     824. use {{{ubinize}}} to create a ubi image (which can be written to a suitable raw NAND device in U-Boot using {{{nand write}}} or in Linux via {{{ubiformat}}}):
     83{{{#!bash
    6284cat <<EOF > ubinize.cfg
    6385[ubifs]
    … …  
    6991vol_flags=autoresize
    7092EOF
    71 ubinize -m 2048 -p 128KiB -s 2048 -o image.ubi ubinize.cfg
    72 }}}
    73 
    74 
    75 === 1GB or 2GB FLASH devices ===
    76 To create a UBI image suitable for the 1GB or larger FLASH devices (Note that the parameters to {{{mkfs.ubifs}}} and {{{ubinize}}} change):
     93# create ubi suitable for 2048byte page size and 128KiB block size devices
     94ubinize -m 2048 -p 128KiB -o image.ubi ubinize.cfg
     95}}}
     96
     97
     98=== 'large' geometry FLASH devices (4096 byte page size)
     99To create a UBI image suitable for raw NAND FLASH devices with a 4096 byte page size:
    771001. create a temporary directory for our rootfs and untar your filesystem to it
    78101{{{#!bash
    … …  
    86109cp uImage imx6*-gw*.dtb 6x_bootscript-ventana tmp/boot/
    87110}}}
    88 3. create ubifs images for the 'large' device geometry:
    89 {{{#!bash
    90 mkfs.ubifs -F -m 4096 -e 248KiB -c 8124 -x zlib -o root.ubifs -d tmp
    91 }}}
    92 4. use {{{ubinize}}} to create ubi image for the 'large' device geometry which can be written to a suitable raw NAND devices in U-Boot using nand write:
    93 {{{#!bash
    94 # for the small layout device
     1113. create ubifs images for the 4096 byte page size 'large' device geometry:
     112{{{#!bash
     113mkfs.ubifs -F -m 4096 -e 248KiB -c 8124 -o root.ubifs -d tmp
     114}}}
     115 * the -c parameter (max-peb-count) of 8124 assures that the filesystem can be sized up to 8124*248KiB or 1.9GiB provided there is remaining space in the ubi
     1164. use {{{ubinize}}} to create ubi image (which can be written to a suitable raw NAND device in U-Boot using {{{nand write}} or in Linux via {{{ubiformat}}}:
     117{{{#!bash
    95118cat <<EOF > ubinize.cfg
    96119[ubifs]
    … …  
    102125vol_flags=autoresize
    103126EOF
    104 ubinize -m 4096 -p 256KiB -s 4096 -o image.ubi ubinize.cfg
    105 }}}
    106 
    107 === Creating your own .ubifs file
    108 {{{#!bash
    109 sudo mkfs.ubifs -d /your/rootfs/ -F -m 4096 -e 248KiB -c 8124 -x zlib -o A_large.ubifs
    110 }}}
    111 
    112 Essentials:
    113 
    114  * **-r** Build file system from directory DIR
    115  * **-F**  The -F option causes mkfs.ubifs to set a special flag in the superblock, which triggers a "free space fixup" procedure in the kernel the very first time the filesystem is mounted. This fixup procedure involves finding all empty pages in the UBIFS file system and re-erasing them. This ensures that NAND pages which contain all 0xFF data get fully erased, which removes any problematic non-0xFF data from their OOB areas.
    116  * **-m**  Minimum I/O unit size
    117  * **-e**  Logical erase block size
    118  * **-c** Maximum logical erase block count
    119  * **-x** Compression type - "lzo", "favor_lzo", "zlib" or "none" (default: "lzo")
    120  * **-o** Output to FILENAME
    121  * **-h** Help, provides full list of options
     127# create ubi suitable for 4096byte page size and 256KiB block size devices
     128ubinize -m 4096 -p 256KiB -o image.ubi ubinize.cfg
     129}}}
     130
     131
     132
    122133=== Bad blocks
    123134
    124 NAND flashes have a random amount of initial bad eraseblocks. This means that different devices may have slightly different volume sizes (especially if the UBI auto-resize feature is used).
    125 
    126 
    127 == Working with a UBI in Linux OS (extracting or manipulating contents) ==
     135NAND flashes have a random amount of initial bad blocks. This means that different devices may have slightly different volume sizes (especially if the UBI auto-resize feature is used).
     136
     137
     138== Working with a UBI in Linux OS (extracting or manipulating contents)
    128139[=#ubiinlinux]
    129140Linux has support for ubi:
    … …  
    161172
    162173
    163 === On a (NAND-less) Linux Development Host ===
     174=== On a (NAND-less) Linux Development Host using nandsim
    164175[=#ubiondevhost]
    165176Often you want to work with UBI and UBIFS images on a Linux Development Host which has no NAND itself. While it is not currently possible to mount a UBI or UBIFS as a loopback device (commonly used for other types of block devices) you can use the nandsim kernel module to simulate a NAND device on a NAND-less Linux development host.
    … …  
    169180To create a virtual NAND device on a NAND-less Linux development system:
    1701811. load {{{nandsim}}} module with parameters for specific flash device simulating:
    171  * 256MB FLASH (what we refer to as the 'normal' flash device):
     182 * 256MiB MT29F2G08 FLASH
    172183{{{#!bash
    173184sudo rmmod nandsim
    … …  
    178189  fourth_id_byte=0x95
    179190}}}
    180  * 1GB or 2GB FLASH (what we refer to as the 'large' flash device):
     191 * 2GiB Cyrpess S34ML16G202 FLASH
     192{{{#!bash
     193sudo rmmod nandsim
     194sudo modprobe nandsim \
     195  first_id_byte=0x01 \
     196  second_id_byte=0xd5 \
     197  third_id_byte=0xd2 \
     198  fourth_id_byte=0x95
     199}}}
     200 * 2GiB Micron MT29F16G08 FLASH:
    181201{{{#!bash
    182202sudo rmmod nandsim
    … …  
    199219{{{#!bash
    200220sudo modprobe ubi
    201 sudo ubiattach /dev/ubi_ctrl -m0 -O2048
     221sudo ubiattach /dev/ubi_ctrl -m0
    202222sudo ubiinfo -a # optionally show info about the UBI
    203223}}}
    … …  
    232252
    233253
    234 === On a target board with NAND FLASH ===
     254=== On a target board with NAND FLASH
    235255[=#ubiontarget]
    236256To extract or manipulate the contents of a UBI within the NAND Flash of a Linux system, Linux must be booted from a secondary medium without the NAND FLASH partition being mounted.
    … …  
    294314setenv ipaddr 192.168.1.1
    295315setenv serverip 192.168.1.254
    296 tftp ${loadaddr} image.ubi && \
     316tftpboot ${loadaddr} image.ubi && \
    297317  nand erase.part rootfs && \
    298318  nand write ${loadaddr} rootfs ${filesize}
    … …  
    348368{{{#!bash
    349369setenv serverip 192.168.1.100
    350 tftp nand_split_update.scr
     370tftpboot nand_split_update.scr
    351371source $loadaddr
    352372}}}
    … …  
    369389
    370390[=#uboot-ubifs]
    371 === Updating NAND FLASH with a ubifs image ===
     391=== Updating NAND FLASH with a ubifs image
    372392To update the contents of a ubi with a ubifs in U-Boot:
    373393{{{#!bash
    … …  
    376396ubi remove rootfs # remove rootfs volume
    377397ubi create rootfs a00000 static # create a 10MB volume named rootfs
    378 tftp ${loadaddr} ventana/root.ubifs && ubi write ${loadaddr} rootfs ${filesize}
     398tftpboot ${loadaddr} ventana/root.ubifs && ubi write ${loadaddr} rootfs ${filesize}
    379399ubifsmount ubi0:rootfs # mount rootfs volume from ubi
    380400ubifsls /