forked from u-boot/u-boot
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathREADME.gpt
315 lines (250 loc) · 11.9 KB
/
README.gpt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
# SPDX-License-Identifier: GPL-2.0+
#
# Copyright (C) 2012 Samsung Electronics
#
# Lukasz Majewski <[email protected]>
Glossary:
========
- UUID -(Universally Unique Identifier)
- GUID - (Globally Unique ID)
- EFI - (Extensible Firmware Interface)
- UEFI - (Unified EFI) - EFI evolution
- GPT (GUID Partition Table) - it is the EFI standard part
- partitions - lists of available partitions (defined at u-boot):
./include/configs/{target}.h
Introduction:
=============
This document describes the GPT partition table format and usage of
the gpt command in u-boot.
UUID introduction:
====================
GPT for marking disks/partitions is using the UUID. It is supposed to be a
globally unique value. A UUID is a 16-byte (128-bit) number. The number of
theoretically possible UUIDs is therefore about 3 x 10^38.
More often UUID is displayed as 32 hexadecimal digits, in 5 groups,
separated by hyphens, in the form 8-4-4-4-12 for a total of 36 characters
(32 digits and 4 hyphens)
For instance, GUID of Basic data partition: EBD0A0A2-B9E5-4433-87C0-68B6B72699C7
and GUID of Linux filesystem data: 0FC63DAF-8483-4772-8E79-3D69D8477DE4
Historically there are 5 methods to generate this number. The oldest one is
combining machine's MAC address and timer (epoch) value.
Successive versions are using MD5 hash, random numbers and SHA-1 hash. All major
OSes and programming languages are providing libraries to compute UUID (e.g.
uuid command line tool).
GPT brief explanation:
======================
Layout:
-------
--------------------------------------------------
LBA 0 |Protective MBR |
----------------------------------------------------------
LBA 1 |Primary GPT Header | Primary
-------------------------------------------------- GPT
LBA 2 |Entry 1|Entry 2| Entry 3| Entry 4|
--------------------------------------------------
LBA 3 |Entries 5 - 128 |
| |
| |
----------------------------------------------------------
LBA 34 |Partition 1 |
| |
-----------------------------------
|Partition 2 |
| |
-----------------------------------
|Partition n |
| |
----------------------------------------------------------
LBA -34 |Entry 1|Entry 2| Entry 3| Entry 4| Backup
-------------------------------------------------- GPT
LBA -33 |Entries 5 - 128 |
| |
| |
LBA -2 | |
--------------------------------------------------
LBA -1 |Backup GPT Header |
----------------------------------------------------------
For a legacy reasons, GPT's LBA 0 sector has a MBR structure. It is called
"protective MBR".
Its first partition entry ID has 0xEE value, and disk software, which is not
handling the GPT sees it as a storage device without free space.
It is possible to define 128 linearly placed partition entries.
"LBA -1" means the last addressable block (in the mmc subsystem:
"dev_desc->lba - 1")
Primary/Backup GPT header:
----------------------------
Offset Size Description
0 8 B Signature ("EFI PART", 45 46 49 20 50 41 52 54)
8 4 B Revision (For version 1.0, the value is 00 00 01 00)
12 4 B Header size (in bytes, usually 5C 00 00 00 meaning 92 bytes)
16 4 B CRC32 of header (0 to header size), with this field zeroed
during calculation
20 4 B Reserved (ZERO);
24 8 B Current LBA (location of this header copy)
32 8 B Backup LBA (location of the other header copy)
40 8 B First usable LBA for partitions (primary partition table last
LBA + 1)
48 8 B Last usable LBA (secondary partition table first LBA - 1)
56 16 B Disk GUID (also referred as UUID on UNIXes)
72 8 B Partition entries starting LBA (always 2 in primary copy)
80 4 B Number of partition entries
84 4 B Size of a partition entry (usually 128)
88 4 B CRC32 of partition array
92 * Reserved; must be ZERO (420 bytes for a 512-byte LBA)
TOTAL: 512 B
IMPORTANT:
GPT headers and partition entries are protected by CRC32 (the POSIX CRC32).
Primary GPT header and Backup GPT header have swapped values of "Current LBA"
and "Backup LBA" and therefore different CRC32 check-sum.
CRC32 for GPT headers (field "CRC of header") are calculated up till
"Header size" (92), NOT 512 bytes.
CRC32 for partition entries (field "CRC32 of partition array") is calculated for
the whole array entry ( Number_of_partition_entries *
sizeof(partition_entry_size (usually 128)))
Observe, how Backup GPT is placed in the memory. It is NOT a mirror reflect
of the Primary.
Partition Entry Format:
----------------------
Offset Size Description
0 16 B Partition type GUID (Big Endian)
16 16 B Unique partition GUID in (Big Endian)
32 8 B First LBA (Little Endian)
40 8 B Last LBA (inclusive)
48 8 B Attribute flags [+]
56 72 B Partition name (text)
Attribute flags:
Bit 0 - System partition
Bit 1 - Hide from EFI
Bit 2 - Legacy BIOS bootable
Bit 48-63 - Defined and used by the individual partition type
For Basic data partition :
Bit 60 - Read-only
Bit 62 - Hidden
Bit 63 - Not mount
Creating GPT partitions in U-Boot:
==============
To restore GUID partition table one needs to:
1. Define partition layout in the environment.
Format of partitions layout:
"uuid_disk=...;name=u-boot,size=60MiB,uuid=...;
name=kernel,size=60MiB,uuid=...;"
or
"uuid_disk=${uuid_gpt_disk};name=${uboot_name},
size=${uboot_size},uuid=${uboot_uuid};"
The fields 'name' and 'size' are mandatory for every partition.
The field 'start' is optional.
If field 'size' of the last partition is 0, the partition is extended
up to the end of the device.
The fields 'uuid' and 'uuid_disk' are optional if CONFIG_RANDOM_UUID is
enabled. A random uuid will be used if omitted or they point to an empty/
non-existent environment variable. The environment variable will be set to
the generated UUID. The 'gpt guid' command reads the current value of the
uuid_disk from the GPT.
The field 'bootable' is optional, it is used to mark the GPT partition
bootable (set attribute flags "Legacy BIOS bootable").
"name=u-boot,size=60MiB;name=boot,size=60Mib,bootable;name=rootfs,size=0"
It can be used to locate bootable disks with command
"part list <interface> <dev> -bootable <varname>",
please check out doc/README.distro for use.
2. Define 'CONFIG_EFI_PARTITION' and 'CONFIG_CMD_GPT'
3. From u-boot prompt type:
gpt write mmc 0 $partitions
Checking (validating) GPT partitions in U-Boot:
===============================================
Procedure is the same as above. The only change is at point 3.
At u-boot prompt one needs to write:
gpt verify mmc 0 [$partitions]
where [$partitions] is an optional parameter.
When it is not provided, only basic checks based on CRC32 calculation for GPT
header and PTEs are performed.
When provided, additionally partition data - name, size and starting
offset (last two in LBA) - are compared with data defined in '$partitions'
environment variable.
After running this command, return code is set to 0 if no errors found in
on non-volatile medium stored GPT.
Following line can be used to assess if GPT verification has succeed:
U-BOOT> gpt verify mmc 0 $partitions
U-BOOT> if test $? = 0; then echo "GPT OK"; else echo "GPT ERR"; fi
Renaming GPT partitions from U-Boot:
====================================
GPT partition names are a mechanism via which userspace and U-Boot can
communicate about software updates and boot failure. The 'gpt guid',
'gpt read', 'gpt rename' and 'gpt swap' commands facilitate
programmatic renaming of partitions from bootscripts by generating and
modifying the partitions layout string. Here is an illustration of
employing 'swap' to exchange 'primary' and 'backup' partition names:
U-BOOT> gpt swap mmc 0 primary backup
Afterwards, all partitions previously named 'primary' will be named
'backup', and vice-versa. Alternatively, single partitions may be
renamed. In this example, mmc0's first partition will be renamed
'primary':
U-BOOT> gpt rename mmc 0 1 primary
The GPT functionality may be tested with the 'sandbox' board by
creating a disk image as described under 'Block Device Emulation' in
doc/arch/index.rst:
=>host bind 0 ./disk.raw
=> gpt read host 0
[ . . . ]
=> gpt swap host 0 name othername
[ . . . ]
Modifying GPT partition layout from U-Boot:
===========================================
The entire GPT partition layout can be exported to an environment
variable and then modified enmasse. Users can change the partition
numbers, offsets, names and sizes. The resulting variable can used to
reformat the device. Here is an example of reading the GPT partitions
into a variable and then modifying them:
U-BOOT> gpt read mmc 0 current_partitions
U-BOOT> env edit current_partitions
edit: uuid_disk=[...];name=part1,start=0x4000,size=0x4000,uuid=[...];
name=part2,start=0xc000,size=0xc000,uuid=[...];[ . . . ]
U-BOOT> gpt write mmc 0 $current_partitions
U-BOOT> gpt verify mmc 0 $current_partitions
Partition type GUID:
====================
For created partition, the used partition type GUID is
PARTITION_BASIC_DATA_GUID (EBD0A0A2-B9E5-4433-87C0-68B6B72699C7).
If you define 'CONFIG_PARTITION_TYPE_GUID', a optionnal parameter 'type'
can specify a other partition type guid:
"uuid_disk=...;name=u-boot,size=60MiB,uuid=...;
name=kernel,size=60MiB,uuid=...,
type=0FC63DAF-8483-4772-8E79-3D69D8477DE4;"
Some strings can be also used at the place of known GUID :
"system" = PARTITION_SYSTEM_GUID
(C12A7328-F81F-11D2-BA4B-00A0C93EC93B)
"mbr" = LEGACY_MBR_PARTITION_GUID
(024DEE41-33E7-11D3-9D69-0008C781F39F)
"msft" = PARTITION_MSFT_RESERVED_GUID
(E3C9E316-0B5C-4DB8-817D-F92DF00215AE)
"data" = PARTITION_BASIC_DATA_GUID
(EBD0A0A2-B9E5-4433-87C0-68B6B72699C7)
"linux" = PARTITION_LINUX_FILE_SYSTEM_DATA_GUID
(0FC63DAF-8483-4772-8E79-3D69D8477DE4)
"raid" = PARTITION_LINUX_RAID_GUID
(A19D880F-05FC-4D3B-A006-743F0F84911E)
"swap" = PARTITION_LINUX_SWAP_GUID
(0657FD6D-A4AB-43C4-84E5-0933C84B4F4F)
"lvm" = PARTITION_LINUX_LVM_GUID
(E6D6D379-F507-44C2-A23C-238F2A3DF928)
"u-boot-env" = PARTITION_U_BOOT_ENVIRONMENT
(3DE21764-95BD-54BD-A5C3-4ABE786F38A8)
"uuid_disk=...;name=u-boot,size=60MiB,uuid=...;
name=kernel,size=60MiB,uuid=...,type=linux;"
They are also used to display the type of partition in "part list" command.
Useful info:
============
Two programs, namely: 'gdisk' and 'parted' are recommended to work with GPT
recovery. Both are able to handle GUID partitions.
Please, pay attention at -l switch for parted.
"uuid" program is recommended to generate UUID string. Moreover it can decode
(-d switch) passed in UUID string. It can be used to generate partitions UUID
passed to u-boot environment variables.
If optional CONFIG_RANDOM_UUID is defined then for any partition which environment
uuid is unset, uuid is randomly generated and stored in correspond environment
variable.
note:
Each string block of UUID generated by program "uuid" is in big endian and it is
also stored in big endian in disk GPT.
Partitions layout can be printed by typing "mmc part". Note that each partition
GUID has different byte order than UUID generated before, this is because first
three blocks of GUID string are in Little Endian.