blob: c0acc8ade5c72afdc0e0ec6936be8b94b093ff69 [file] [log] [blame]
Lukasz Majewski36f2e8e2012-12-11 11:09:44 +01001#
2# Copyright (C) 2012 Samsung Electronics
3#
4# Lukasz Majewski <l.majewski@samsung.com>
5#
6#
Wolfgang Denk1a459662013-07-08 09:37:19 +02007# SPDX-License-Identifier: GPL-2.0+
Lukasz Majewski36f2e8e2012-12-11 11:09:44 +01008
Lukasz Majewski36f2e8e2012-12-11 11:09:44 +01009Glossary:
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
Lukasz Majewski36f2e8e2012-12-11 11:09:44 +010024UUID 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
Patrick Delaunayb38c1082015-10-27 11:00:26 +010034For instance, GUID of Basic data partition: EBD0A0A2-B9E5-4433-87C0-68B6B72699C7
35and GUID of Linux filesystem data: 0FC63DAF-8483-4772-8E79-3D69D8477DE4
Lukasz Majewski36f2e8e2012-12-11 11:09:44 +010036
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 ----------------------------------------------------------
Steve Raeae95fad2014-05-05 13:00:08 -070070 LBA -34 |Entry 1|Entry 2| Entry 3| Entry 4| Backup
71 -------------------------------------------------- GPT
72 LBA -33 |Entries 5 - 128 |
Lukasz Majewski36f2e8e2012-12-11 11:09:44 +010073 | |
74 | |
75 LBA -2 | |
76 --------------------------------------------------
Steve Raeae95fad2014-05-05 13:00:08 -070077 LBA -1 |Backup GPT Header |
Lukasz Majewski36f2e8e2012-12-11 11:09:44 +010078 ----------------------------------------------------------
79
Lukasz Majewski36f2e8e2012-12-11 11:09:44 +010080For 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
Steve Raeae95fad2014-05-05 13:00:08 -070090Primary/Backup GPT header:
Lukasz Majewski36f2e8e2012-12-11 11:09:44 +010091----------------------------
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
Lukasz Majewski36f2e8e2012-12-11 11:09:44 +0100115IMPORTANT:
116
117GPT headers and partition entries are protected by CRC32 (the POSIX CRC32).
118
Steve Raeae95fad2014-05-05 13:00:08 -0700119Primary GPT header and Backup GPT header have swapped values of "Current LBA"
Lukasz Majewski36f2e8e2012-12-11 11:09:44 +0100120and "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
Steve Raeae95fad2014-05-05 13:00:08 -0700129Observe, how Backup GPT is placed in the memory. It is NOT a mirror reflect
Lukasz Majewski36f2e8e2012-12-11 11:09:44 +0100130of the Primary.
131
Lukasz Majewski36f2e8e2012-12-11 11:09:44 +0100132 Partition Entry Format:
133 ----------------------
134 Offset Size Description
135
Przemyslaw Marczak39206382014-04-02 10:20:06 +0200136 0 16 B Partition type GUID (Big Endian)
137 16 16 B Unique partition GUID in (Big Endian)
Lukasz Majewski36f2e8e2012-12-11 11:09:44 +0100138 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
Patrick Delaunaycfdaf4c2015-11-17 11:36:52 +0100145 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 :
Lukasz Majewski36f2e8e2012-12-11 11:09:44 +0100149 Bit 60 - Read-only
150 Bit 62 - Hidden
151 Bit 63 - Not mount
152
Lukasz Majewski36f2e8e2012-12-11 11:09:44 +0100153Creating 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 "partitions=uuid_disk=...;name=u-boot,size=60MiB,uuid=...;
160 name=kernel,size=60MiB,uuid=...;"
161 or
162 "partitions=uuid_disk=${uuid_gpt_disk};name=${uboot_name},
163 size=${uboot_size},uuid=${uboot_uuid};"
164
Rob Herring0c7e8d12015-01-26 09:44:18 -0600165 The fields 'name' and 'size' are mandatory for every partition.
Lukasz Majewski36f2e8e2012-12-11 11:09:44 +0100166 The field 'start' is optional.
167
Robert P. J. Day62a3b7d2016-07-15 13:44:45 -0400168 If field 'size' of the last partition is 0, the partition is extended
Patrick Delaunaycfdaf4c2015-11-17 11:36:52 +0100169 up to the end of the device.
170
Rob Herring0c7e8d12015-01-26 09:44:18 -0600171 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.
Przemyslaw Marczak39206382014-04-02 10:20:06 +0200175
Patrick Delaunaycfdaf4c2015-11-17 11:36:52 +0100176 The field 'bootable' is optional, it is used to mark the GPT partition
177 bootable (set attribute flags "Legacy BIOS bootable").
178 "name=u-boot,size=60MiB;name=boot,size=60Mib,bootable;name=rootfs,size=0"
179 It can be used to locate bootable disks with command
180 "part list <interface> <dev> -bootable <varname>",
181 please check out doc/README.distro for use.
182
Lukasz Majewski36f2e8e2012-12-11 11:09:44 +01001832. Define 'CONFIG_EFI_PARTITION' and 'CONFIG_CMD_GPT'
184
Lukasz Majewskidd445872015-11-20 08:06:14 +01001853. From u-boot prompt type:
Lukasz Majewski36f2e8e2012-12-11 11:09:44 +0100186 gpt write mmc 0 $partitions
187
Lukasz Majewskidd445872015-11-20 08:06:14 +0100188Checking (validating) GPT partitions in U-Boot:
189===============================================
190
191Procedure is the same as above. The only change is at point 3.
192
193At u-boot prompt one needs to write:
194 gpt verify mmc 0 [$partitions]
195
196where [$partitions] is an optional parameter.
197
198When it is not provided, only basic checks based on CRC32 calculation for GPT
199header and PTEs are performed.
200When provided, additionally partition data - name, size and starting
201offset (last two in LBA) - are compared with data defined in '$partitions'
202environment variable.
203
204After running this command, return code is set to 0 if no errors found in
205on non-volatile medium stored GPT.
206
207Following line can be used to assess if GPT verification has succeed:
208
209U-BOOT> gpt verify mmc 0 $partitions
210U-BOOT> if test $? = 0; then echo "GPT OK"; else echo "GPT ERR"; fi
211
212
Alison Chaiken564cf252017-06-04 15:11:21 -0700213The GPT functionality may be tested with the 'sandbox' board by
214creating a disk image as described under 'Block Device Emulation' in
215board/sandbox/README.sandbox:
216
217=>host bind 0 ./disk.raw
218=> gpt read host 0
219[ . . . ]
220=> gpt flip host 0
221[ . . . ]
222
Patrick Delaunay7561b252015-10-27 11:00:27 +0100223Partition type GUID:
224====================
225
226For created partition, the used partition type GUID is
227PARTITION_BASIC_DATA_GUID (EBD0A0A2-B9E5-4433-87C0-68B6B72699C7).
228
229If you define 'CONFIG_PARTITION_TYPE_GUID', a optionnal parameter 'type'
230can specify a other partition type guid:
231
232 "partitions=uuid_disk=...;name=u-boot,size=60MiB,uuid=...;
233 name=kernel,size=60MiB,uuid=...,
234 type=0FC63DAF-8483-4772-8E79-3D69D8477DE4;"
235
Patrick Delaunaybcb41dc2015-10-27 11:00:28 +0100236Some strings can be also used at the place of known GUID :
237 "system" = PARTITION_SYSTEM_GUID
238 (C12A7328-F81F-11D2-BA4B-00A0C93EC93B)
239 "mbr" = LEGACY_MBR_PARTITION_GUID
240 (024DEE41-33E7-11D3-9D69-0008C781F39F)
241 "msft" = PARTITION_MSFT_RESERVED_GUID
242 (E3C9E316-0B5C-4DB8-817D-F92DF00215AE)
243 "data" = PARTITION_BASIC_DATA_GUID
244 (EBD0A0A2-B9E5-4433-87C0-68B6B72699C7)
245 "linux" = PARTITION_LINUX_FILE_SYSTEM_DATA_GUID
246 (0FC63DAF-8483-4772-8E79-3D69D8477DE4)
247 "raid" = PARTITION_LINUX_RAID_GUID
248 (A19D880F-05FC-4D3B-A006-743F0F84911E)
249 "swap" = PARTITION_LINUX_SWAP_GUID
250 (0657FD6D-A4AB-43C4-84E5-0933C84B4F4F)
251 "lvm" = PARTITION_LINUX_LVM_GUID
252 (E6D6D379-F507-44C2-A23C-238F2A3DF928)
253
254 "partitions=uuid_disk=...;name=u-boot,size=60MiB,uuid=...;
255 name=kernel,size=60MiB,uuid=...,type=linux;"
256
257They are also used to display the type of partition in "part list" command.
258
259
Lukasz Majewski36f2e8e2012-12-11 11:09:44 +0100260Useful info:
261============
262
Przemyslaw Marczak39206382014-04-02 10:20:06 +0200263Two programs, namely: 'gdisk' and 'parted' are recommended to work with GPT
264recovery. Both are able to handle GUID partitions.
Lukasz Majewski36f2e8e2012-12-11 11:09:44 +0100265Please, pay attention at -l switch for parted.
266
267"uuid" program is recommended to generate UUID string. Moreover it can decode
268(-d switch) passed in UUID string. It can be used to generate partitions UUID
269passed to u-boot environment variables.
Przemyslaw Marczak39206382014-04-02 10:20:06 +0200270If optional CONFIG_RANDOM_UUID is defined then for any partition which environment
271uuid is unset, uuid is randomly generated and stored in correspond environment
272variable.
273
274note:
275Each string block of UUID generated by program "uuid" is in big endian and it is
276also stored in big endian in disk GPT.
277Partitions layout can be printed by typing "mmc part". Note that each partition
278GUID has different byte order than UUID generated before, this is because first
279three blocks of GUID string are in Little Endian.