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 read[vol] address volume [size] - Read volume to address with size
  18 ubi remove[vol] volume - Remove volume
  19 [Legends]
  20  volume: character name
  21  size: specified in bytes
  22  type: s[tatic] or d[ynamic] (default=dynamic)
  23
  24
  25 The first command that is needed to be issues is "ubi part" to connect
  26 one mtd partition to the UBI subsystem. This command will either create
  27 a new UBI device on the requested MTD partition. Or it will attach a
  28 previously created UBI device. The other UBI commands will only work
  29 when such a UBI device is attached (via "ubi part"). Here an example:
  30
  31 => mtdparts
  32
  33 device nor0 <1fc000000.nor_flash>, # parts = 6
  34  #: name                size            offset          mask_flags
  35  0: kernel              0x00200000      0x00000000      0
  36  1: dtb                 0x00040000      0x00200000      0
  37  2: root                0x00200000      0x00240000      0
  38  3: user                0x01ac0000      0x00440000      0
  39  4: env                 0x00080000      0x01f00000      0
  40  5: u-boot              0x00080000      0x01f80000      0
  41
  42 active partition: nor0,0 - (kernel) 0x00200000 @ 0x00000000
  43
  44 defaults:
  45 mtdids  : nor0=1fc000000.nor_flash
  46 mtdparts: mtdparts=1fc000000.nor_flash:2m(kernel),256k(dtb),2m(root),27392k(user),512k(env),512k(u-boot)
  47
  48 => ubi part root
  49 Creating 1 MTD partitions on "nor0":
  50 0x000000240000-0x000000440000 : "mtd=2"
  51 UBI: attaching mtd1 to ubi0
  52 UBI: physical eraseblock size:   262144 bytes (256 KiB)
  53 UBI: logical eraseblock size:    262016 bytes
  54 UBI: smallest flash I/O unit:    1
  55 UBI: VID header offset:          64 (aligned 64)
  56 UBI: data offset:                128
  57 UBI: attached mtd1 to ubi0
  58 UBI: MTD device name:            "mtd=2"
  59 UBI: MTD device size:            2 MiB
  60 UBI: number of good PEBs:        8
  61 UBI: number of bad PEBs:         0
  62 UBI: max. allowed volumes:       128
  63 UBI: wear-leveling threshold:    4096
  64 UBI: number of internal volumes: 1
  65 UBI: number of user volumes:     1
  66 UBI: available PEBs:             0
  67 UBI: total number of reserved PEBs: 8
  68 UBI: number of PEBs reserved for bad PEB handling: 0
  69 UBI: max/mean erase counter: 2/1
  70
  71
  72 Now that the UBI device is attached, this device can be modified
  73 using the following commands:
  74
  75 ubi info        Display volume and ubi layout information
  76 ubi createvol   Create UBI volume on UBI device
  77 ubi removevol   Remove UBI volume from UBI device
  78 ubi read        Read data from UBI volume to memory
  79 ubi write       Write data from memory to UBI volume
  80
  81
  82 Here a few examples on the usage:
  83
  84 => ubi create testvol
  85 Creating dynamic volume testvol of size 1048064
  86
  87 => ubi info l
  88 UBI: volume information dump:
  89 UBI: vol_id          0
  90 UBI: reserved_pebs   4
  91 UBI: alignment       1
  92 UBI: data_pad        0
  93 UBI: vol_type        3
  94 UBI: name_len        7
  95 UBI: usable_leb_size 262016
  96 UBI: used_ebs        4
  97 UBI: used_bytes      1048064
  98 UBI: last_eb_bytes   262016
  99 UBI: corrupted       0
 100 UBI: upd_marker      0
 101 UBI: name            testvol
 102
 103 UBI: volume information dump:
 104 UBI: vol_id          2147479551
 105 UBI: reserved_pebs   2
 106 UBI: alignment       1
 107 UBI: data_pad        0
 108 UBI: vol_type        3
 109 UBI: name_len        13
 110 UBI: usable_leb_size 262016
 111 UBI: used_ebs        2
 112 UBI: used_bytes      524032
 113 UBI: last_eb_bytes   2
 114 UBI: corrupted       0
 115 UBI: upd_marker      0
 116 UBI: name            layout volume
 117
 118 => ubi info
 119 UBI: MTD device name:            "mtd=2"
 120 UBI: MTD device size:            2 MiB
 121 UBI: physical eraseblock size:   262144 bytes (256 KiB)
 122 UBI: logical eraseblock size:    262016 bytes
 123 UBI: number of good PEBs:        8
 124 UBI: number of bad PEBs:         0
 125 UBI: smallest flash I/O unit:    1
 126 UBI: VID header offset:          64 (aligned 64)
 127 UBI: data offset:                128
 128 UBI: max. allowed volumes:       128
 129 UBI: wear-leveling threshold:    4096
 130 UBI: number of internal volumes: 1
 131 UBI: number of user volumes:     1
 132 UBI: available PEBs:             0
 133 UBI: total number of reserved PEBs: 8
 134 UBI: number of PEBs reserved for bad PEB handling: 0
 135 UBI: max/mean erase counter: 4/1
 136
 137 => ubi write 800000 testvol 80000
 138 Volume "testvol" found at volume id 0
 139
 140 => ubi read 900000 testvol 80000
 141 Volume testvol found at volume id 0
 142 read 524288 bytes from volume 0 to 900000(buf address)
 143
 144 => cmp.b 800000 900000 80000
 145 Total of 524288 bytes were the same
 146
 147
 148 Next, the ubifsmount command allows you to access filesystems on the
 149 UBI partition which has been attached with the ubi part command:
 150
 151 => help ubifsmount
 152 ubifsmount - mount UBIFS volume
 153
 154 Usage:
 155 ubifsmount <volume-name>
 156     - mount 'volume-name' volume
 157
 158 For example:
 159
 160 => ubifsmount ubi0:recovery
 161 UBIFS: mounted UBI device 0, volume 0, name "recovery"
 162 UBIFS: mounted read-only
 163 UBIFS: file system size:   46473216 bytes (45384 KiB, 44 MiB, 366 LEBs)
 164 UBIFS: journal size:       6348800 bytes (6200 KiB, 6 MiB, 50 LEBs)
 165 UBIFS: media format:       w4/r0 (latest is w4/r0)
 166 UBIFS: default compressor: LZO
 167 UBIFS: reserved for root:  0 bytes (0 KiB)
 168
 169 Note that unlike Linux, U-Boot can only have one active UBI partition
 170 at a time, which can be referred to as ubi0, and must be supplied along
 171 with the name of the filesystem you are mounting.
 172
 173
 174 Once a UBI filesystem has been mounted, the ubifsls command allows you
 175 to list the contents of a directory in the filesystem:
 176
 177
 178 => help ubifsls
 179 ubifsls - list files in a directory
 180
 181 Usage:
 182 ubifsls [directory]
 183     - list files in a 'directory' (default '/')
 184
 185 For example:
 186
 187 => ubifsls
 188             17442  Thu Jan 01 02:57:38 1970  imx28-evk.dtb
 189           2998146  Thu Jan 01 02:57:43 1970  zImage
 190
 191
 192 And the ubifsload command allows you to load a file from a UBI
 193 filesystem:
 194
 195
 196 => help ubifsload
 197 ubifsload - load file from an UBIFS filesystem
 198
 199 Usage:
 200 ubifsload <addr> <filename> [bytes]
 201     - load file 'filename' to address 'addr'
 202
 203 For example:
 204
 205 => ubifsload ${loadaddr} zImage
 206 Loading file 'zImage' to addr 0x42000000 with size 2998146 (0x002dbf82)...
 207 Done
 208
 209
 210 Finally, you can unmount the UBI filesystem with the ubifsumount
 211 command:
 212
 213 => help ubifsumount
 214 ubifsumount - unmount UBIFS volume
 215
 216 Usage:
 217 ubifsumount     - unmount current volume
 218
 219 For example:
 220
 221 => ubifsumount
 222 Unmounting UBIFS volume recovery!