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