doc/README.ubi

   1 -------------------
   2 UBI usage in U-Boot
   3 -------------------
   4
   5 UBI support in U-Boot is broken down into five separate commands.
   6 The first is the ubi command, which has six subcommands:
   7
   8 => help ubi
   9 ubi - ubi commands
  10
  11 Usage:
  12 ubi part [part] [offset]
  13  - Show or set current partition (with optional VID header offset)
  14 ubi info [l[ayout]] - Display volume and ubi layout information
  15 ubi create[vol] volume [size] [type] - create volume name with size
  16 ubi write[vol] address volume size - Write volume from address with size
  17 ubi write.part address volume size [fullsize]
  18  - Write part of a volume from address
  19 ubi read[vol] address volume [size] - Read volume to address with size
  20 ubi remove[vol] volume - Remove volume
  21 [Legends]
  22  volume: character name
  23  size: specified in bytes
  24  type: s[tatic] or d[ynamic] (default=dynamic)
  25
  26
  27 The first command that is needed to be issues is "ubi part" to connect
  28 one mtd partition to the UBI subsystem. This command will either create
  29 a new UBI device on the requested MTD partition. Or it will attach a
  30 previously created UBI device. The other UBI commands will only work
  31 when such a UBI device is attached (via "ubi part"). Here an example:
  32
  33 => mtdparts
  34
  35 device nor0 <1fc000000.nor_flash>, # parts = 6
  36  #: name                size            offset          mask_flags
  37  0: kernel              0x00200000      0x00000000      0
  38  1: dtb                 0x00040000      0x00200000      0
  39  2: root                0x00200000      0x00240000      0
  40  3: user                0x01ac0000      0x00440000      0
  41  4: env                 0x00080000      0x01f00000      0
  42  5: u-boot              0x00080000      0x01f80000      0
  43
  44 active partition: nor0,0 - (kernel) 0x00200000 @ 0x00000000
  45
  46 defaults:
  47 mtdids  : nor0=1fc000000.nor_flash
  48 mtdparts: mtdparts=1fc000000.nor_flash:2m(kernel),256k(dtb),2m(root),27392k(user),512k(env),512k(u-boot)
  49
  50 => ubi part root
  51 Creating 1 MTD partitions on "nor0":
  52 0x000000240000-0x000000440000 : "mtd=2"
  53 UBI: attaching mtd1 to ubi0
  54 UBI: physical eraseblock size:   262144 bytes (256 KiB)
  55 UBI: logical eraseblock size:    262016 bytes
  56 UBI: smallest flash I/O unit:    1
  57 UBI: VID header offset:          64 (aligned 64)
  58 UBI: data offset:                128
  59 UBI: attached mtd1 to ubi0
  60 UBI: MTD device name:            "mtd=2"
  61 UBI: MTD device size:            2 MiB
  62 UBI: number of good PEBs:        8
  63 UBI: number of bad PEBs:         0
  64 UBI: max. allowed volumes:       128
  65 UBI: wear-leveling threshold:    4096
  66 UBI: number of internal volumes: 1
  67 UBI: number of user volumes:     1
  68 UBI: available PEBs:             0
  69 UBI: total number of reserved PEBs: 8
  70 UBI: number of PEBs reserved for bad PEB handling: 0
  71 UBI: max/mean erase counter: 2/1
  72
  73
  74 Now that the UBI device is attached, this device can be modified
  75 using the following commands:
  76
  77 ubi info        Display volume and ubi layout information
  78 ubi createvol   Create UBI volume on UBI device
  79 ubi removevol   Remove UBI volume from UBI device
  80 ubi read        Read data from UBI volume to memory
  81 ubi write       Write data from memory to UBI volume
  82 ubi write.part  Write data from memory to UBI volume, in parts
  83
  84
  85 Here a few examples on the usage:
  86
  87 => ubi create testvol
  88 Creating dynamic volume testvol of size 1048064
  89
  90 => ubi info l
  91 UBI: volume information dump:
  92 UBI: vol_id          0
  93 UBI: reserved_pebs   4
  94 UBI: alignment       1
  95 UBI: data_pad        0
  96 UBI: vol_type        3
  97 UBI: name_len        7
  98 UBI: usable_leb_size 262016
  99 UBI: used_ebs        4
 100 UBI: used_bytes      1048064
 101 UBI: last_eb_bytes   262016
 102 UBI: corrupted       0
 103 UBI: upd_marker      0
 104 UBI: name            testvol
 105
 106 UBI: volume information dump:
 107 UBI: vol_id          2147479551
 108 UBI: reserved_pebs   2
 109 UBI: alignment       1
 110 UBI: data_pad        0
 111 UBI: vol_type        3
 112 UBI: name_len        13
 113 UBI: usable_leb_size 262016
 114 UBI: used_ebs        2
 115 UBI: used_bytes      524032
 116 UBI: last_eb_bytes   2
 117 UBI: corrupted       0
 118 UBI: upd_marker      0
 119 UBI: name            layout volume
 120
 121 => ubi info
 122 UBI: MTD device name:            "mtd=2"
 123 UBI: MTD device size:            2 MiB
 124 UBI: physical eraseblock size:   262144 bytes (256 KiB)
 125 UBI: logical eraseblock size:    262016 bytes
 126 UBI: number of good PEBs:        8
 127 UBI: number of bad PEBs:         0
 128 UBI: smallest flash I/O unit:    1
 129 UBI: VID header offset:          64 (aligned 64)
 130 UBI: data offset:                128
 131 UBI: max. allowed volumes:       128
 132 UBI: wear-leveling threshold:    4096
 133 UBI: number of internal volumes: 1
 134 UBI: number of user volumes:     1
 135 UBI: available PEBs:             0
 136 UBI: total number of reserved PEBs: 8
 137 UBI: number of PEBs reserved for bad PEB handling: 0
 138 UBI: max/mean erase counter: 4/1
 139
 140 => ubi write 800000 testvol 80000
 141 Volume "testvol" found at volume id 0
 142
 143 => ubi read 900000 testvol 80000
 144 Volume testvol found at volume id 0
 145 read 524288 bytes from volume 0 to 900000(buf address)
 146
 147 => cmp.b 800000 900000 80000
 148 Total of 524288 bytes were the same
 149
 150
 151 Next, the ubifsmount command allows you to access filesystems on the
 152 UBI partition which has been attached with the ubi part command:
 153
 154 => help ubifsmount
 155 ubifsmount - mount UBIFS volume
 156
 157 Usage:
 158 ubifsmount <volume-name>
 159     - mount 'volume-name' volume
 160
 161 For example:
 162
 163 => ubifsmount ubi0:recovery
 164 UBIFS: mounted UBI device 0, volume 0, name "recovery"
 165 UBIFS: mounted read-only
 166 UBIFS: file system size:   46473216 bytes (45384 KiB, 44 MiB, 366 LEBs)
 167 UBIFS: journal size:       6348800 bytes (6200 KiB, 6 MiB, 50 LEBs)
 168 UBIFS: media format:       w4/r0 (latest is w4/r0)
 169 UBIFS: default compressor: LZO
 170 UBIFS: reserved for root:  0 bytes (0 KiB)
 171
 172 Note that unlike Linux, U-Boot can only have one active UBI partition
 173 at a time, which can be referred to as ubi0, and must be supplied along
 174 with the name of the filesystem you are mounting.
 175
 176
 177 Once a UBI filesystem has been mounted, the ubifsls command allows you
 178 to list the contents of a directory in the filesystem:
 179
 180
 181 => help ubifsls
 182 ubifsls - list files in a directory
 183
 184 Usage:
 185 ubifsls [directory]
 186     - list files in a 'directory' (default '/')
 187
 188 For example:
 189
 190 => ubifsls
 191             17442  Thu Jan 01 02:57:38 1970  imx28-evk.dtb
 192           2998146  Thu Jan 01 02:57:43 1970  zImage
 193
 194
 195 And the ubifsload command allows you to load a file from a UBI
 196 filesystem:
 197
 198
 199 => help ubifsload
 200 ubifsload - load file from an UBIFS filesystem
 201
 202 Usage:
 203 ubifsload <addr> <filename> [bytes]
 204     - load file 'filename' to address 'addr'
 205
 206 For example:
 207
 208 => ubifsload ${loadaddr} zImage
 209 Loading file 'zImage' to addr 0x42000000 with size 2998146 (0x002dbf82)...
 210 Done
 211
 212
 213 Finally, you can unmount the UBI filesystem with the ubifsumount
 214 command:
 215
 216 => help ubifsumount
 217 ubifsumount - unmount UBIFS volume
 218
 219 Usage:
 220 ubifsumount     - unmount current volume
 221
 222 For example:
 223
 224 => ubifsumount
 225 Unmounting UBIFS volume recovery!
 226
 227
 228 Usage of the UBI CRC skip-check flag of static volumes:
 229 -------------------------------------------------------
 230 Some users of static UBI volumes implement their own integrity check,
 231 thus making the volume CRC check done at open time useless. For
 232 instance, this is the case when one use the ubiblock + dm-verity +
 233 squashfs combination, where dm-verity already checks integrity of the
 234 block device but this time at the block granularity instead of verifying
 235 the whole volume.
 236
 237 Skipping this test drastically improves the boot-time.
 238
 239 U-Boot now supports the "skip_check" flag to optionally skip the CRC
 240 check at open time.
 241
 242 Usage: Case A - Upon UBI volume creation:
 243 You can optionally add "--skipcheck" to the "ubi create" command:
 244
 245 ubi create[vol] volume [size] [type] [id] [--skipcheck]
 246  - create volume name with size ('-' for maximum available size)
 247
 248 Usage: Case B - With an already existing UBI volume:
 249 Use the "ubi skipcheck" command:
 250
 251 ubi skipcheck volume on/off - Set or clear skip_check flag in volume header
 252
 253 Example:
 254 => ubi skipcheck rootfs0 on
 255 Setting skip_check on volume rootfs0
 256
 257 BTW: This saves approx. 10 seconds Linux bootup time on a MT7688 based
 258 target with 128MiB of SPI NAND.