1 # SPDX-License-Identifier: GPL-2.0+ 2 # 3 # Copyright (C) 2012 Samsung Electronics 4 # 5 # Lukasz Majewski <l.majewski (a] samsung.com> 6 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 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 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 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 ---------------------------------------------------------- 68 LBA -34 |Entry 1|Entry 2| Entry 3| Entry 4| Backup 69 -------------------------------------------------- GPT 70 LBA -33 |Entries 5 - 128 | 71 | | 72 | | 73 LBA -2 | | 74 -------------------------------------------------- 75 LBA -1 |Backup GPT Header | 76 ---------------------------------------------------------- 77 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 88 Primary/Backup GPT header: 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 113 IMPORTANT: 114 115 GPT headers and partition entries are protected by CRC32 (the POSIX CRC32). 116 117 Primary GPT header and Backup GPT header have swapped values of "Current LBA" 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 127 Observe, how Backup GPT is placed in the memory. It is NOT a mirror reflect 128 of the Primary. 129 130 Partition Entry Format: 131 ---------------------- 132 Offset Size Description 133 134 0 16 B Partition type GUID (Big Endian) 135 16 16 B Unique partition GUID in (Big Endian) 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 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 : 147 Bit 60 - Read-only 148 Bit 62 - Hidden 149 Bit 63 - Not mount 150 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: 157 "uuid_disk=...;name=u-boot,size=60MiB,uuid=...; 158 name=kernel,size=60MiB,uuid=...;" 159 or 160 "uuid_disk=${uuid_gpt_disk};name=${uboot_name}, 161 size=${uboot_size},uuid=${uboot_uuid};" 162 163 The fields 'name' and 'size' are mandatory for every partition. 164 The field 'start' is optional. 165 166 If field 'size' of the last partition is 0, the partition is extended 167 up to the end of the device. 168 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 172 the generated UUID. The 'gpt guid' command reads the current value of the 173 uuid_disk from the GPT. 174 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 182 2. Define 'CONFIG_EFI_PARTITION' and 'CONFIG_CMD_GPT' 183 184 3. From u-boot prompt type: 185 gpt write mmc 0 $partitions 186 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 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 229 230 The GPT functionality may be tested with the 'sandbox' board by 231 creating a disk image as described under 'Block Device Emulation' in 232 board/sandbox/README.sandbox: 233 234 =>host bind 0 ./disk.raw 235 => gpt read host 0 236 [ . . . ] 237 => gpt swap host 0 name othername 238 [ . . . ] 239 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 249 "uuid_disk=...;name=u-boot,size=60MiB,uuid=...; 250 name=kernel,size=60MiB,uuid=..., 251 type=0FC63DAF-8483-4772-8E79-3D69D8477DE4;" 252 253 Some 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) 270 271 "uuid_disk=...;name=u-boot,size=60MiB,uuid=...; 272 name=kernel,size=60MiB,uuid=...,type=linux;" 273 274 They are also used to display the type of partition in "part list" command. 275 276 277 Useful info: 278 ============ 279 280 Two programs, namely: 'gdisk' and 'parted' are recommended to work with GPT 281 recovery. Both are able to handle GUID partitions. 282 Please, pay attention at -l switch for parted. 283 284 "uuid" program is recommended to generate UUID string. Moreover it can decode 285 (-d switch) passed in UUID string. It can be used to generate partitions UUID 286 passed to u-boot environment variables. 287 If optional CONFIG_RANDOM_UUID is defined then for any partition which environment 288 uuid is unset, uuid is randomly generated and stored in correspond environment 289 variable. 290 291 note: 292 Each string block of UUID generated by program "uuid" is in big endian and it is 293 also stored in big endian in disk GPT. 294 Partitions layout can be printed by typing "mmc part". Note that each partition 295 GUID has different byte order than UUID generated before, this is because first 296 three blocks of GUID string are in Little Endian. 297
