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