diff options
Diffstat (limited to 'doc/README.ubi')
| -rw-r--r-- | doc/README.ubi | 258 |
1 files changed, 258 insertions, 0 deletions
diff --git a/doc/README.ubi b/doc/README.ubi new file mode 100644 index 00000000000..c78a81795b9 --- /dev/null +++ b/doc/README.ubi @@ -0,0 +1,258 @@ +------------------- +UBI usage in U-Boot +------------------- + +UBI support in U-Boot is broken down into five separate commands. +The first is the ubi command, which has six subcommands: + +=> help ubi +ubi - ubi commands + +Usage: +ubi part [part] [offset] + - Show or set current partition (with optional VID header offset) +ubi info [l[ayout]] - Display volume and ubi layout information +ubi create[vol] volume [size] [type] - create volume name with size +ubi write[vol] address volume size - Write volume from address with size +ubi write.part address volume size [fullsize] + - Write part of a volume from address +ubi read[vol] address volume [size] - Read volume to address with size +ubi remove[vol] volume - Remove volume +[Legends] + volume: character name + size: specified in bytes + type: s[tatic] or d[ynamic] (default=dynamic) + + +The first command that is needed to be issues is "ubi part" to connect +one mtd partition to the UBI subsystem. This command will either create +a new UBI device on the requested MTD partition. Or it will attach a +previously created UBI device. The other UBI commands will only work +when such a UBI device is attached (via "ubi part"). Here an example: + +=> mtdparts + +device nor0 <1fc000000.nor_flash>, # parts = 6 + #: name size offset mask_flags + 0: kernel 0x00200000 0x00000000 0 + 1: dtb 0x00040000 0x00200000 0 + 2: root 0x00200000 0x00240000 0 + 3: user 0x01ac0000 0x00440000 0 + 4: env 0x00080000 0x01f00000 0 + 5: u-boot 0x00080000 0x01f80000 0 + +active partition: nor0,0 - (kernel) 0x00200000 @ 0x00000000 + +defaults: +mtdids : nor0=1fc000000.nor_flash +mtdparts: mtdparts=1fc000000.nor_flash:2m(kernel),256k(dtb),2m(root),27392k(user),512k(env),512k(u-boot) + +=> ubi part root +Creating 1 MTD partitions on "nor0": +0x000000240000-0x000000440000 : "mtd=2" +UBI: attaching mtd1 to ubi0 +UBI: physical eraseblock size: 262144 bytes (256 KiB) +UBI: logical eraseblock size: 262016 bytes +UBI: smallest flash I/O unit: 1 +UBI: VID header offset: 64 (aligned 64) +UBI: data offset: 128 +UBI: attached mtd1 to ubi0 +UBI: MTD device name: "mtd=2" +UBI: MTD device size: 2 MiB +UBI: number of good PEBs: 8 +UBI: number of bad PEBs: 0 +UBI: max. allowed volumes: 128 +UBI: wear-leveling threshold: 4096 +UBI: number of internal volumes: 1 +UBI: number of user volumes: 1 +UBI: available PEBs: 0 +UBI: total number of reserved PEBs: 8 +UBI: number of PEBs reserved for bad PEB handling: 0 +UBI: max/mean erase counter: 2/1 + + +Now that the UBI device is attached, this device can be modified +using the following commands: + +ubi info Display volume and ubi layout information +ubi createvol Create UBI volume on UBI device +ubi removevol Remove UBI volume from UBI device +ubi read Read data from UBI volume to memory +ubi write Write data from memory to UBI volume +ubi write.part Write data from memory to UBI volume, in parts + + +Here a few examples on the usage: + +=> ubi create testvol +Creating dynamic volume testvol of size 1048064 + +=> ubi info l +UBI: volume information dump: +UBI: vol_id 0 +UBI: reserved_pebs 4 +UBI: alignment 1 +UBI: data_pad 0 +UBI: vol_type 3 +UBI: name_len 7 +UBI: usable_leb_size 262016 +UBI: used_ebs 4 +UBI: used_bytes 1048064 +UBI: last_eb_bytes 262016 +UBI: corrupted 0 +UBI: upd_marker 0 +UBI: name testvol + +UBI: volume information dump: +UBI: vol_id 2147479551 +UBI: reserved_pebs 2 +UBI: alignment 1 +UBI: data_pad 0 +UBI: vol_type 3 +UBI: name_len 13 +UBI: usable_leb_size 262016 +UBI: used_ebs 2 +UBI: used_bytes 524032 +UBI: last_eb_bytes 2 +UBI: corrupted 0 +UBI: upd_marker 0 +UBI: name layout volume + +=> ubi info +UBI: MTD device name: "mtd=2" +UBI: MTD device size: 2 MiB +UBI: physical eraseblock size: 262144 bytes (256 KiB) +UBI: logical eraseblock size: 262016 bytes +UBI: number of good PEBs: 8 +UBI: number of bad PEBs: 0 +UBI: smallest flash I/O unit: 1 +UBI: VID header offset: 64 (aligned 64) +UBI: data offset: 128 +UBI: max. allowed volumes: 128 +UBI: wear-leveling threshold: 4096 +UBI: number of internal volumes: 1 +UBI: number of user volumes: 1 +UBI: available PEBs: 0 +UBI: total number of reserved PEBs: 8 +UBI: number of PEBs reserved for bad PEB handling: 0 +UBI: max/mean erase counter: 4/1 + +=> ubi write 800000 testvol 80000 +Volume "testvol" found at volume id 0 + +=> ubi read 900000 testvol 80000 +Volume testvol found at volume id 0 +read 524288 bytes from volume 0 to 900000(buf address) + +=> cmp.b 800000 900000 80000 +Total of 524288 bytes were the same + + +Next, the ubifsmount command allows you to access filesystems on the +UBI partition which has been attached with the ubi part command: + +=> help ubifsmount +ubifsmount - mount UBIFS volume + +Usage: +ubifsmount <volume-name> + - mount 'volume-name' volume + +For example: + +=> ubifsmount ubi0:recovery +UBIFS: mounted UBI device 0, volume 0, name "recovery" +UBIFS: mounted read-only +UBIFS: file system size: 46473216 bytes (45384 KiB, 44 MiB, 366 LEBs) +UBIFS: journal size: 6348800 bytes (6200 KiB, 6 MiB, 50 LEBs) +UBIFS: media format: w4/r0 (latest is w4/r0) +UBIFS: default compressor: LZO +UBIFS: reserved for root: 0 bytes (0 KiB) + +Note that unlike Linux, U-Boot can only have one active UBI partition +at a time, which can be referred to as ubi0, and must be supplied along +with the name of the filesystem you are mounting. + + +Once a UBI filesystem has been mounted, the ubifsls command allows you +to list the contents of a directory in the filesystem: + + +=> help ubifsls +ubifsls - list files in a directory + +Usage: +ubifsls [directory] + - list files in a 'directory' (default '/') + +For example: + +=> ubifsls + 17442 Thu Jan 01 02:57:38 1970 imx28-evk.dtb + 2998146 Thu Jan 01 02:57:43 1970 zImage + + +And the ubifsload command allows you to load a file from a UBI +filesystem: + + +=> help ubifsload +ubifsload - load file from an UBIFS filesystem + +Usage: +ubifsload <addr> <filename> [bytes] + - load file 'filename' to address 'addr' + +For example: + +=> ubifsload ${loadaddr} zImage +Loading file 'zImage' to addr 0x42000000 with size 2998146 (0x002dbf82)... +Done + + +Finally, you can unmount the UBI filesystem with the ubifsumount +command: + +=> help ubifsumount +ubifsumount - unmount UBIFS volume + +Usage: +ubifsumount - unmount current volume + +For example: + +=> ubifsumount +Unmounting UBIFS volume recovery! + + +Usage of the UBI CRC skip-check flag of static volumes: +------------------------------------------------------- +Some users of static UBI volumes implement their own integrity check, +thus making the volume CRC check done at open time useless. For +instance, this is the case when one use the ubiblock + dm-verity + +squashfs combination, where dm-verity already checks integrity of the +block device but this time at the block granularity instead of verifying +the whole volume. + +Skipping this test drastically improves the boot-time. + +U-Boot now supports the "skip_check" flag to optionally skip the CRC +check at open time. + +Usage: Case A - Upon UBI volume creation: +You can optionally add "--skipcheck" to the "ubi create" command: + +ubi create[vol] volume [size] [type] [id] [--skipcheck] + - create volume name with size ('-' for maximum available size) + +Usage: Case B - With an already existing UBI volume: +Use the "ubi skipcheck" command: + +ubi skipcheck volume on/off - Set or clear skip_check flag in volume header + +Example: +=> ubi skipcheck rootfs0 on +Setting skip_check on volume rootfs0 + +BTW: This saves approx. 10 seconds Linux bootup time on a MT7688 based +target with 128MiB of SPI NAND. |