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