Tom Rini | 83d290c | 2018-05-06 17:58:06 -0400 | [diff] [blame] | 1 | # SPDX-License-Identifier: GPL-2.0+ |
Lukasz Majewski | 36f2e8e | 2012-12-11 11:09:44 +0100 | [diff] [blame] | 2 | # |
| 3 | # Copyright (C) 2012 Samsung Electronics |
| 4 | # |
| 5 | # Lukasz Majewski <l.majewski@samsung.com> |
Lukasz Majewski | 36f2e8e | 2012-12-11 11:09:44 +0100 | [diff] [blame] | 6 | |
Lukasz Majewski | 36f2e8e | 2012-12-11 11:09:44 +0100 | [diff] [blame] | 7 | Glossary: |
| 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 | |
| 17 | Introduction: |
| 18 | ============= |
| 19 | This document describes the GPT partition table format and usage of |
| 20 | the gpt command in u-boot. |
| 21 | |
Lukasz Majewski | 36f2e8e | 2012-12-11 11:09:44 +0100 | [diff] [blame] | 22 | UUID introduction: |
| 23 | ==================== |
| 24 | |
| 25 | GPT for marking disks/partitions is using the UUID. It is supposed to be a |
| 26 | globally unique value. A UUID is a 16-byte (128-bit) number. The number of |
| 27 | theoretically possible UUIDs is therefore about 3 x 10^38. |
| 28 | More often UUID is displayed as 32 hexadecimal digits, in 5 groups, |
| 29 | separated by hyphens, in the form 8-4-4-4-12 for a total of 36 characters |
| 30 | (32 digits and 4 hyphens) |
| 31 | |
Patrick Delaunay | b38c108 | 2015-10-27 11:00:26 +0100 | [diff] [blame] | 32 | For instance, GUID of Basic data partition: EBD0A0A2-B9E5-4433-87C0-68B6B72699C7 |
| 33 | and GUID of Linux filesystem data: 0FC63DAF-8483-4772-8E79-3D69D8477DE4 |
Lukasz Majewski | 36f2e8e | 2012-12-11 11:09:44 +0100 | [diff] [blame] | 34 | |
| 35 | Historically there are 5 methods to generate this number. The oldest one is |
| 36 | combining machine's MAC address and timer (epoch) value. |
| 37 | |
| 38 | Successive versions are using MD5 hash, random numbers and SHA-1 hash. All major |
| 39 | OSes and programming languages are providing libraries to compute UUID (e.g. |
| 40 | uuid command line tool). |
| 41 | |
| 42 | GPT 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 Rae | ae95fad | 2014-05-05 13:00:08 -0700 | [diff] [blame] | 68 | LBA -34 |Entry 1|Entry 2| Entry 3| Entry 4| Backup |
| 69 | -------------------------------------------------- GPT |
| 70 | LBA -33 |Entries 5 - 128 | |
Lukasz Majewski | 36f2e8e | 2012-12-11 11:09:44 +0100 | [diff] [blame] | 71 | | | |
| 72 | | | |
| 73 | LBA -2 | | |
| 74 | -------------------------------------------------- |
Steve Rae | ae95fad | 2014-05-05 13:00:08 -0700 | [diff] [blame] | 75 | LBA -1 |Backup GPT Header | |
Lukasz Majewski | 36f2e8e | 2012-12-11 11:09:44 +0100 | [diff] [blame] | 76 | ---------------------------------------------------------- |
| 77 | |
Lukasz Majewski | 36f2e8e | 2012-12-11 11:09:44 +0100 | [diff] [blame] | 78 | For a legacy reasons, GPT's LBA 0 sector has a MBR structure. It is called |
| 79 | "protective MBR". |
| 80 | Its first partition entry ID has 0xEE value, and disk software, which is not |
| 81 | handling the GPT sees it as a storage device without free space. |
| 82 | |
| 83 | It 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 Rae | ae95fad | 2014-05-05 13:00:08 -0700 | [diff] [blame] | 88 | Primary/Backup GPT header: |
Lukasz Majewski | 36f2e8e | 2012-12-11 11:09:44 +0100 | [diff] [blame] | 89 | ---------------------------- |
| 90 | Offset Size Description |
| 91 | |
| 92 | 0 8 B Signature ("EFI PART", 45 46 49 20 50 41 52 54) |
| 93 | 8 4 B Revision (For version 1.0, the value is 00 00 01 00) |
| 94 | 12 4 B Header size (in bytes, usually 5C 00 00 00 meaning 92 bytes) |
| 95 | 16 4 B CRC32 of header (0 to header size), with this field zeroed |
| 96 | during calculation |
| 97 | 20 4 B Reserved (ZERO); |
| 98 | 24 8 B Current LBA (location of this header copy) |
| 99 | 32 8 B Backup LBA (location of the other header copy) |
| 100 | 40 8 B First usable LBA for partitions (primary partition table last |
| 101 | LBA + 1) |
| 102 | 48 8 B Last usable LBA (secondary partition table first LBA - 1) |
| 103 | 56 16 B Disk GUID (also referred as UUID on UNIXes) |
| 104 | 72 8 B Partition entries starting LBA (always 2 in primary copy) |
| 105 | 80 4 B Number of partition entries |
| 106 | 84 4 B Size of a partition entry (usually 128) |
| 107 | 88 4 B CRC32 of partition array |
| 108 | 92 * Reserved; must be ZERO (420 bytes for a 512-byte LBA) |
| 109 | |
| 110 | TOTAL: 512 B |
| 111 | |
| 112 | |
Lukasz Majewski | 36f2e8e | 2012-12-11 11:09:44 +0100 | [diff] [blame] | 113 | IMPORTANT: |
| 114 | |
| 115 | GPT headers and partition entries are protected by CRC32 (the POSIX CRC32). |
| 116 | |
Steve Rae | ae95fad | 2014-05-05 13:00:08 -0700 | [diff] [blame] | 117 | Primary GPT header and Backup GPT header have swapped values of "Current LBA" |
Lukasz Majewski | 36f2e8e | 2012-12-11 11:09:44 +0100 | [diff] [blame] | 118 | and "Backup LBA" and therefore different CRC32 check-sum. |
| 119 | |
| 120 | CRC32 for GPT headers (field "CRC of header") are calculated up till |
| 121 | "Header size" (92), NOT 512 bytes. |
| 122 | |
| 123 | CRC32 for partition entries (field "CRC32 of partition array") is calculated for |
| 124 | the whole array entry ( Number_of_partition_entries * |
| 125 | sizeof(partition_entry_size (usually 128))) |
| 126 | |
Steve Rae | ae95fad | 2014-05-05 13:00:08 -0700 | [diff] [blame] | 127 | Observe, how Backup GPT is placed in the memory. It is NOT a mirror reflect |
Lukasz Majewski | 36f2e8e | 2012-12-11 11:09:44 +0100 | [diff] [blame] | 128 | of the Primary. |
| 129 | |
Lukasz Majewski | 36f2e8e | 2012-12-11 11:09:44 +0100 | [diff] [blame] | 130 | Partition Entry Format: |
| 131 | ---------------------- |
| 132 | Offset Size Description |
| 133 | |
Przemyslaw Marczak | 3920638 | 2014-04-02 10:20:06 +0200 | [diff] [blame] | 134 | 0 16 B Partition type GUID (Big Endian) |
| 135 | 16 16 B Unique partition GUID in (Big Endian) |
Lukasz Majewski | 36f2e8e | 2012-12-11 11:09:44 +0100 | [diff] [blame] | 136 | 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 Delaunay | cfdaf4c | 2015-11-17 11:36:52 +0100 | [diff] [blame] | 143 | 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 Majewski | 36f2e8e | 2012-12-11 11:09:44 +0100 | [diff] [blame] | 147 | Bit 60 - Read-only |
| 148 | Bit 62 - Hidden |
| 149 | Bit 63 - Not mount |
| 150 | |
Lukasz Majewski | 36f2e8e | 2012-12-11 11:09:44 +0100 | [diff] [blame] | 151 | Creating GPT partitions in U-Boot: |
| 152 | ============== |
| 153 | |
| 154 | To restore GUID partition table one needs to: |
| 155 | 1. Define partition layout in the environment. |
| 156 | Format of partitions layout: |
Alison Chaiken | 0a24238 | 2017-06-25 16:43:19 -0700 | [diff] [blame] | 157 | "uuid_disk=...;name=u-boot,size=60MiB,uuid=...; |
Lukasz Majewski | 36f2e8e | 2012-12-11 11:09:44 +0100 | [diff] [blame] | 158 | name=kernel,size=60MiB,uuid=...;" |
| 159 | or |
Alison Chaiken | 0a24238 | 2017-06-25 16:43:19 -0700 | [diff] [blame] | 160 | "uuid_disk=${uuid_gpt_disk};name=${uboot_name}, |
Lukasz Majewski | 36f2e8e | 2012-12-11 11:09:44 +0100 | [diff] [blame] | 161 | size=${uboot_size},uuid=${uboot_uuid};" |
| 162 | |
Rob Herring | 0c7e8d1 | 2015-01-26 09:44:18 -0600 | [diff] [blame] | 163 | The fields 'name' and 'size' are mandatory for every partition. |
Lukasz Majewski | 36f2e8e | 2012-12-11 11:09:44 +0100 | [diff] [blame] | 164 | The field 'start' is optional. |
| 165 | |
Robert P. J. Day | 62a3b7d | 2016-07-15 13:44:45 -0400 | [diff] [blame] | 166 | If field 'size' of the last partition is 0, the partition is extended |
Patrick Delaunay | cfdaf4c | 2015-11-17 11:36:52 +0100 | [diff] [blame] | 167 | up to the end of the device. |
| 168 | |
Rob Herring | 0c7e8d1 | 2015-01-26 09:44:18 -0600 | [diff] [blame] | 169 | 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 Chaiken | 73d6d18 | 2017-06-25 16:43:23 -0700 | [diff] [blame] | 172 | the generated UUID. The 'gpt guid' command reads the current value of the |
| 173 | uuid_disk from the GPT. |
Przemyslaw Marczak | 3920638 | 2014-04-02 10:20:06 +0200 | [diff] [blame] | 174 | |
Patrick Delaunay | cfdaf4c | 2015-11-17 11:36:52 +0100 | [diff] [blame] | 175 | 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 Majewski | 36f2e8e | 2012-12-11 11:09:44 +0100 | [diff] [blame] | 182 | 2. Define 'CONFIG_EFI_PARTITION' and 'CONFIG_CMD_GPT' |
| 183 | |
Lukasz Majewski | dd44587 | 2015-11-20 08:06:14 +0100 | [diff] [blame] | 184 | 3. From u-boot prompt type: |
Lukasz Majewski | 36f2e8e | 2012-12-11 11:09:44 +0100 | [diff] [blame] | 185 | gpt write mmc 0 $partitions |
| 186 | |
Lukasz Majewski | dd44587 | 2015-11-20 08:06:14 +0100 | [diff] [blame] | 187 | Checking (validating) GPT partitions in U-Boot: |
| 188 | =============================================== |
| 189 | |
| 190 | Procedure is the same as above. The only change is at point 3. |
| 191 | |
| 192 | At u-boot prompt one needs to write: |
| 193 | gpt verify mmc 0 [$partitions] |
| 194 | |
| 195 | where [$partitions] is an optional parameter. |
| 196 | |
| 197 | When it is not provided, only basic checks based on CRC32 calculation for GPT |
| 198 | header and PTEs are performed. |
| 199 | When provided, additionally partition data - name, size and starting |
| 200 | offset (last two in LBA) - are compared with data defined in '$partitions' |
| 201 | environment variable. |
| 202 | |
| 203 | After running this command, return code is set to 0 if no errors found in |
| 204 | on non-volatile medium stored GPT. |
| 205 | |
| 206 | Following line can be used to assess if GPT verification has succeed: |
| 207 | |
| 208 | U-BOOT> gpt verify mmc 0 $partitions |
| 209 | U-BOOT> if test $? = 0; then echo "GPT OK"; else echo "GPT ERR"; fi |
| 210 | |
Alison Chaiken | 203f9b4 | 2017-07-04 11:19:18 -0700 | [diff] [blame] | 211 | Renaming GPT partitions from U-Boot: |
| 212 | ==================================== |
| 213 | |
| 214 | GPT partition names are a mechanism via which userspace and U-Boot can |
| 215 | communicate about software updates and boot failure. The 'gpt guid', |
| 216 | 'gpt read', 'gpt rename' and 'gpt swap' commands facilitate |
| 217 | programmatic renaming of partitions from bootscripts by generating and |
| 218 | modifying the partitions layout string. Here is an illustration of |
| 219 | employing 'swap' to exchange 'primary' and 'backup' partition names: |
| 220 | |
| 221 | U-BOOT> gpt swap mmc 0 primary backup |
| 222 | |
| 223 | Afterwards, all partitions previously named 'primary' will be named |
| 224 | 'backup', and vice-versa. Alternatively, single partitions may be |
| 225 | renamed. In this example, mmc0's first partition will be renamed |
| 226 | 'primary': |
| 227 | |
| 228 | U-BOOT> gpt rename mmc 0 1 primary |
Lukasz Majewski | dd44587 | 2015-11-20 08:06:14 +0100 | [diff] [blame] | 229 | |
Alison Chaiken | 564cf25 | 2017-06-04 15:11:21 -0700 | [diff] [blame] | 230 | The GPT functionality may be tested with the 'sandbox' board by |
| 231 | creating a disk image as described under 'Block Device Emulation' in |
Keerthy | 5917d0b | 2019-07-29 13:52:04 +0530 | [diff] [blame] | 232 | doc/arch/index.rst: |
Alison Chaiken | 564cf25 | 2017-06-04 15:11:21 -0700 | [diff] [blame] | 233 | |
| 234 | =>host bind 0 ./disk.raw |
| 235 | => gpt read host 0 |
| 236 | [ . . . ] |
Alison Chaiken | 203f9b4 | 2017-07-04 11:19:18 -0700 | [diff] [blame] | 237 | => gpt swap host 0 name othername |
Alison Chaiken | 52791db | 2017-06-25 16:43:21 -0700 | [diff] [blame] | 238 | [ . . . ] |
| 239 | |
Patrick Delaunay | 7561b25 | 2015-10-27 11:00:27 +0100 | [diff] [blame] | 240 | Partition type GUID: |
| 241 | ==================== |
| 242 | |
| 243 | For created partition, the used partition type GUID is |
| 244 | PARTITION_BASIC_DATA_GUID (EBD0A0A2-B9E5-4433-87C0-68B6B72699C7). |
| 245 | |
| 246 | If you define 'CONFIG_PARTITION_TYPE_GUID', a optionnal parameter 'type' |
| 247 | can specify a other partition type guid: |
| 248 | |
Alison Chaiken | 0a24238 | 2017-06-25 16:43:19 -0700 | [diff] [blame] | 249 | "uuid_disk=...;name=u-boot,size=60MiB,uuid=...; |
Patrick Delaunay | 7561b25 | 2015-10-27 11:00:27 +0100 | [diff] [blame] | 250 | name=kernel,size=60MiB,uuid=..., |
| 251 | type=0FC63DAF-8483-4772-8E79-3D69D8477DE4;" |
| 252 | |
Patrick Delaunay | bcb41dc | 2015-10-27 11:00:28 +0100 | [diff] [blame] | 253 | Some strings can be also used at the place of known GUID : |
Rasmus Villemoes | 214cc19 | 2020-11-20 11:45:37 +0100 | [diff] [blame] | 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 Villemoes | c0364ce | 2020-11-20 11:45:36 +0100 | [diff] [blame] | 270 | "u-boot-env" = PARTITION_U_BOOT_ENVIRONMENT |
| 271 | (3DE21764-95BD-54BD-A5C3-4ABE786F38A8) |
Patrick Delaunay | bcb41dc | 2015-10-27 11:00:28 +0100 | [diff] [blame] | 272 | |
Alison Chaiken | 0a24238 | 2017-06-25 16:43:19 -0700 | [diff] [blame] | 273 | "uuid_disk=...;name=u-boot,size=60MiB,uuid=...; |
Patrick Delaunay | bcb41dc | 2015-10-27 11:00:28 +0100 | [diff] [blame] | 274 | name=kernel,size=60MiB,uuid=...,type=linux;" |
| 275 | |
| 276 | They are also used to display the type of partition in "part list" command. |
| 277 | |
| 278 | |
Lukasz Majewski | 36f2e8e | 2012-12-11 11:09:44 +0100 | [diff] [blame] | 279 | Useful info: |
| 280 | ============ |
| 281 | |
Przemyslaw Marczak | 3920638 | 2014-04-02 10:20:06 +0200 | [diff] [blame] | 282 | Two programs, namely: 'gdisk' and 'parted' are recommended to work with GPT |
| 283 | recovery. Both are able to handle GUID partitions. |
Lukasz Majewski | 36f2e8e | 2012-12-11 11:09:44 +0100 | [diff] [blame] | 284 | Please, 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 |
| 288 | passed to u-boot environment variables. |
Przemyslaw Marczak | 3920638 | 2014-04-02 10:20:06 +0200 | [diff] [blame] | 289 | If optional CONFIG_RANDOM_UUID is defined then for any partition which environment |
| 290 | uuid is unset, uuid is randomly generated and stored in correspond environment |
| 291 | variable. |
| 292 | |
| 293 | note: |
| 294 | Each string block of UUID generated by program "uuid" is in big endian and it is |
| 295 | also stored in big endian in disk GPT. |
| 296 | Partitions layout can be printed by typing "mmc part". Note that each partition |
| 297 | GUID has different byte order than UUID generated before, this is because first |
| 298 | three blocks of GUID string are in Little Endian. |