blob: 9e0d2221ef02c5476f84e037078f3577d1a4e536 [file] [log] [blame]
Tom Rini83d290c2018-05-06 17:58:06 -04001# SPDX-License-Identifier: GPL-2.0+
Lukasz Majewski36f2e8e2012-12-11 11:09:44 +01002#
3# Copyright (C) 2012 Samsung Electronics
4#
5# Lukasz Majewski <l.majewski@samsung.com>
Lukasz Majewski36f2e8e2012-12-11 11:09:44 +01006
Lukasz Majewski36f2e8e2012-12-11 11:09:44 +01007Glossary:
8========
9- UUID -(Universally Unique Identifier)
10- GUID - (Globally Unique ID)
11- EFI - (Extensible Firmware Interface)
12- UEFI - (Unified EFI) - EFI evolution
13- GPT (GUID Partition Table) - it is the EFI standard part
14- partitions - lists of available partitions (defined at u-boot):
15 ./include/configs/{target}.h
16
17Introduction:
18=============
19This document describes the GPT partition table format and usage of
20the gpt command in u-boot.
21
Lukasz Majewski36f2e8e2012-12-11 11:09:44 +010022UUID introduction:
23====================
24
25GPT for marking disks/partitions is using the UUID. It is supposed to be a
26globally unique value. A UUID is a 16-byte (128-bit) number. The number of
27theoretically possible UUIDs is therefore about 3 x 10^38.
28More often UUID is displayed as 32 hexadecimal digits, in 5 groups,
29separated by hyphens, in the form 8-4-4-4-12 for a total of 36 characters
30(32 digits and 4 hyphens)
31
Patrick Delaunayb38c1082015-10-27 11:00:26 +010032For instance, GUID of Basic data partition: EBD0A0A2-B9E5-4433-87C0-68B6B72699C7
33and GUID of Linux filesystem data: 0FC63DAF-8483-4772-8E79-3D69D8477DE4
Lukasz Majewski36f2e8e2012-12-11 11:09:44 +010034
35Historically there are 5 methods to generate this number. The oldest one is
36combining machine's MAC address and timer (epoch) value.
37
38Successive versions are using MD5 hash, random numbers and SHA-1 hash. All major
39OSes and programming languages are providing libraries to compute UUID (e.g.
40uuid command line tool).
41
42GPT brief explanation:
43======================
44
45 Layout:
46 -------
47
48 --------------------------------------------------
49 LBA 0 |Protective MBR |
50 ----------------------------------------------------------
51 LBA 1 |Primary GPT Header | Primary
52 -------------------------------------------------- GPT
53 LBA 2 |Entry 1|Entry 2| Entry 3| Entry 4|
54 --------------------------------------------------
55 LBA 3 |Entries 5 - 128 |
56 | |
57 | |
58 ----------------------------------------------------------
59 LBA 34 |Partition 1 |
60 | |
61 -----------------------------------
62 |Partition 2 |
63 | |
64 -----------------------------------
65 |Partition n |
66 | |
67 ----------------------------------------------------------
Steve Raeae95fad2014-05-05 13:00:08 -070068 LBA -34 |Entry 1|Entry 2| Entry 3| Entry 4| Backup
69 -------------------------------------------------- GPT
70 LBA -33 |Entries 5 - 128 |
Lukasz Majewski36f2e8e2012-12-11 11:09:44 +010071 | |
72 | |
73 LBA -2 | |
74 --------------------------------------------------
Steve Raeae95fad2014-05-05 13:00:08 -070075 LBA -1 |Backup GPT Header |
Lukasz Majewski36f2e8e2012-12-11 11:09:44 +010076 ----------------------------------------------------------
77
Lukasz Majewski36f2e8e2012-12-11 11:09:44 +010078For a legacy reasons, GPT's LBA 0 sector has a MBR structure. It is called
79"protective MBR".
80Its first partition entry ID has 0xEE value, and disk software, which is not
81handling the GPT sees it as a storage device without free space.
82
83It is possible to define 128 linearly placed partition entries.
84
85"LBA -1" means the last addressable block (in the mmc subsystem:
86"dev_desc->lba - 1")
87
Steve Raeae95fad2014-05-05 13:00:08 -070088Primary/Backup GPT header:
Lukasz Majewski36f2e8e2012-12-11 11:09:44 +010089----------------------------
90Offset Size Description
91
920 8 B Signature ("EFI PART", 45 46 49 20 50 41 52 54)
938 4 B Revision (For version 1.0, the value is 00 00 01 00)
9412 4 B Header size (in bytes, usually 5C 00 00 00 meaning 92 bytes)
9516 4 B CRC32 of header (0 to header size), with this field zeroed
96 during calculation
9720 4 B Reserved (ZERO);
9824 8 B Current LBA (location of this header copy)
9932 8 B Backup LBA (location of the other header copy)
10040 8 B First usable LBA for partitions (primary partition table last
101 LBA + 1)
10248 8 B Last usable LBA (secondary partition table first LBA - 1)
10356 16 B Disk GUID (also referred as UUID on UNIXes)
10472 8 B Partition entries starting LBA (always 2 in primary copy)
10580 4 B Number of partition entries
10684 4 B Size of a partition entry (usually 128)
10788 4 B CRC32 of partition array
10892 * Reserved; must be ZERO (420 bytes for a 512-byte LBA)
109
110TOTAL: 512 B
111
112
Lukasz Majewski36f2e8e2012-12-11 11:09:44 +0100113IMPORTANT:
114
115GPT headers and partition entries are protected by CRC32 (the POSIX CRC32).
116
Steve Raeae95fad2014-05-05 13:00:08 -0700117Primary GPT header and Backup GPT header have swapped values of "Current LBA"
Lukasz Majewski36f2e8e2012-12-11 11:09:44 +0100118and "Backup LBA" and therefore different CRC32 check-sum.
119
120CRC32 for GPT headers (field "CRC of header") are calculated up till
121"Header size" (92), NOT 512 bytes.
122
123CRC32 for partition entries (field "CRC32 of partition array") is calculated for
124the whole array entry ( Number_of_partition_entries *
125sizeof(partition_entry_size (usually 128)))
126
Steve Raeae95fad2014-05-05 13:00:08 -0700127Observe, how Backup GPT is placed in the memory. It is NOT a mirror reflect
Lukasz Majewski36f2e8e2012-12-11 11:09:44 +0100128of the Primary.
129
Lukasz Majewski36f2e8e2012-12-11 11:09:44 +0100130 Partition Entry Format:
131 ----------------------
132 Offset Size Description
133
Przemyslaw Marczak39206382014-04-02 10:20:06 +0200134 0 16 B Partition type GUID (Big Endian)
135 16 16 B Unique partition GUID in (Big Endian)
Lukasz Majewski36f2e8e2012-12-11 11:09:44 +0100136 32 8 B First LBA (Little Endian)
137 40 8 B Last LBA (inclusive)
138 48 8 B Attribute flags [+]
139 56 72 B Partition name (text)
140
141 Attribute flags:
142 Bit 0 - System partition
Patrick Delaunaycfdaf4c2015-11-17 11:36:52 +0100143 Bit 1 - Hide from EFI
144 Bit 2 - Legacy BIOS bootable
145 Bit 48-63 - Defined and used by the individual partition type
146 For Basic data partition :
Lukasz Majewski36f2e8e2012-12-11 11:09:44 +0100147 Bit 60 - Read-only
148 Bit 62 - Hidden
149 Bit 63 - Not mount
150
Lukasz Majewski36f2e8e2012-12-11 11:09:44 +0100151Creating GPT partitions in U-Boot:
152==============
153
154To restore GUID partition table one needs to:
1551. Define partition layout in the environment.
156 Format of partitions layout:
Alison Chaiken0a242382017-06-25 16:43:19 -0700157 "uuid_disk=...;name=u-boot,size=60MiB,uuid=...;
Lukasz Majewski36f2e8e2012-12-11 11:09:44 +0100158 name=kernel,size=60MiB,uuid=...;"
159 or
Alison Chaiken0a242382017-06-25 16:43:19 -0700160 "uuid_disk=${uuid_gpt_disk};name=${uboot_name},
Lukasz Majewski36f2e8e2012-12-11 11:09:44 +0100161 size=${uboot_size},uuid=${uboot_uuid};"
162
Rob Herring0c7e8d12015-01-26 09:44:18 -0600163 The fields 'name' and 'size' are mandatory for every partition.
Lukasz Majewski36f2e8e2012-12-11 11:09:44 +0100164 The field 'start' is optional.
165
Robert P. J. Day62a3b7d2016-07-15 13:44:45 -0400166 If field 'size' of the last partition is 0, the partition is extended
Patrick Delaunaycfdaf4c2015-11-17 11:36:52 +0100167 up to the end of the device.
168
Rob Herring0c7e8d12015-01-26 09:44:18 -0600169 The fields 'uuid' and 'uuid_disk' are optional if CONFIG_RANDOM_UUID is
170 enabled. A random uuid will be used if omitted or they point to an empty/
171 non-existent environment variable. The environment variable will be set to
Alison Chaiken73d6d182017-06-25 16:43:23 -0700172 the generated UUID. The 'gpt guid' command reads the current value of the
173 uuid_disk from the GPT.
Przemyslaw Marczak39206382014-04-02 10:20:06 +0200174
Patrick Delaunaycfdaf4c2015-11-17 11:36:52 +0100175 The field 'bootable' is optional, it is used to mark the GPT partition
176 bootable (set attribute flags "Legacy BIOS bootable").
177 "name=u-boot,size=60MiB;name=boot,size=60Mib,bootable;name=rootfs,size=0"
178 It can be used to locate bootable disks with command
179 "part list <interface> <dev> -bootable <varname>",
180 please check out doc/README.distro for use.
181
Lukasz Majewski36f2e8e2012-12-11 11:09:44 +01001822. Define 'CONFIG_EFI_PARTITION' and 'CONFIG_CMD_GPT'
183
Lukasz Majewskidd445872015-11-20 08:06:14 +01001843. From u-boot prompt type:
Lukasz Majewski36f2e8e2012-12-11 11:09:44 +0100185 gpt write mmc 0 $partitions
186
Lukasz Majewskidd445872015-11-20 08:06:14 +0100187Checking (validating) GPT partitions in U-Boot:
188===============================================
189
190Procedure is the same as above. The only change is at point 3.
191
192At u-boot prompt one needs to write:
193 gpt verify mmc 0 [$partitions]
194
195where [$partitions] is an optional parameter.
196
197When it is not provided, only basic checks based on CRC32 calculation for GPT
198header and PTEs are performed.
199When provided, additionally partition data - name, size and starting
200offset (last two in LBA) - are compared with data defined in '$partitions'
201environment variable.
202
203After running this command, return code is set to 0 if no errors found in
204on non-volatile medium stored GPT.
205
206Following line can be used to assess if GPT verification has succeed:
207
208U-BOOT> gpt verify mmc 0 $partitions
209U-BOOT> if test $? = 0; then echo "GPT OK"; else echo "GPT ERR"; fi
210
Alison Chaiken203f9b42017-07-04 11:19:18 -0700211Renaming GPT partitions from U-Boot:
212====================================
213
214GPT partition names are a mechanism via which userspace and U-Boot can
215communicate about software updates and boot failure. The 'gpt guid',
216'gpt read', 'gpt rename' and 'gpt swap' commands facilitate
217programmatic renaming of partitions from bootscripts by generating and
218modifying the partitions layout string. Here is an illustration of
219employing 'swap' to exchange 'primary' and 'backup' partition names:
220
221U-BOOT> gpt swap mmc 0 primary backup
222
223Afterwards, all partitions previously named 'primary' will be named
224'backup', and vice-versa. Alternatively, single partitions may be
225renamed. In this example, mmc0's first partition will be renamed
226'primary':
227
228U-BOOT> gpt rename mmc 0 1 primary
Lukasz Majewskidd445872015-11-20 08:06:14 +0100229
Alison Chaiken564cf252017-06-04 15:11:21 -0700230The GPT functionality may be tested with the 'sandbox' board by
231creating a disk image as described under 'Block Device Emulation' in
Keerthy5917d0b2019-07-29 13:52:04 +0530232doc/arch/index.rst:
Alison Chaiken564cf252017-06-04 15:11:21 -0700233
234=>host bind 0 ./disk.raw
235=> gpt read host 0
236[ . . . ]
Alison Chaiken203f9b42017-07-04 11:19:18 -0700237=> gpt swap host 0 name othername
Alison Chaiken52791db2017-06-25 16:43:21 -0700238[ . . . ]
239
Patrick Delaunay7561b252015-10-27 11:00:27 +0100240Partition type GUID:
241====================
242
243For created partition, the used partition type GUID is
244PARTITION_BASIC_DATA_GUID (EBD0A0A2-B9E5-4433-87C0-68B6B72699C7).
245
246If you define 'CONFIG_PARTITION_TYPE_GUID', a optionnal parameter 'type'
247can specify a other partition type guid:
248
Alison Chaiken0a242382017-06-25 16:43:19 -0700249 "uuid_disk=...;name=u-boot,size=60MiB,uuid=...;
Patrick Delaunay7561b252015-10-27 11:00:27 +0100250 name=kernel,size=60MiB,uuid=...,
251 type=0FC63DAF-8483-4772-8E79-3D69D8477DE4;"
252
Patrick Delaunaybcb41dc2015-10-27 11:00:28 +0100253Some strings can be also used at the place of known GUID :
254 "system" = PARTITION_SYSTEM_GUID
255 (C12A7328-F81F-11D2-BA4B-00A0C93EC93B)
256 "mbr" = LEGACY_MBR_PARTITION_GUID
257 (024DEE41-33E7-11D3-9D69-0008C781F39F)
258 "msft" = PARTITION_MSFT_RESERVED_GUID
259 (E3C9E316-0B5C-4DB8-817D-F92DF00215AE)
260 "data" = PARTITION_BASIC_DATA_GUID
261 (EBD0A0A2-B9E5-4433-87C0-68B6B72699C7)
262 "linux" = PARTITION_LINUX_FILE_SYSTEM_DATA_GUID
263 (0FC63DAF-8483-4772-8E79-3D69D8477DE4)
264 "raid" = PARTITION_LINUX_RAID_GUID
265 (A19D880F-05FC-4D3B-A006-743F0F84911E)
266 "swap" = PARTITION_LINUX_SWAP_GUID
267 (0657FD6D-A4AB-43C4-84E5-0933C84B4F4F)
268 "lvm" = PARTITION_LINUX_LVM_GUID
269 (E6D6D379-F507-44C2-A23C-238F2A3DF928)
Rasmus Villemoesc0364ce2020-11-20 11:45:36 +0100270 "u-boot-env" = PARTITION_U_BOOT_ENVIRONMENT
271 (3DE21764-95BD-54BD-A5C3-4ABE786F38A8)
Patrick Delaunaybcb41dc2015-10-27 11:00:28 +0100272
Alison Chaiken0a242382017-06-25 16:43:19 -0700273 "uuid_disk=...;name=u-boot,size=60MiB,uuid=...;
Patrick Delaunaybcb41dc2015-10-27 11:00:28 +0100274 name=kernel,size=60MiB,uuid=...,type=linux;"
275
276They are also used to display the type of partition in "part list" command.
277
278
Lukasz Majewski36f2e8e2012-12-11 11:09:44 +0100279Useful info:
280============
281
Przemyslaw Marczak39206382014-04-02 10:20:06 +0200282Two programs, namely: 'gdisk' and 'parted' are recommended to work with GPT
283recovery. Both are able to handle GUID partitions.
Lukasz Majewski36f2e8e2012-12-11 11:09:44 +0100284Please, 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.
Przemyslaw Marczak39206382014-04-02 10:20:06 +0200289If 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.