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 Linux data partition: EBD0A0A2-B9E5-4433-87C0-68B6B72699C7 35 36Historically there are 5 methods to generate this number. The oldest one is 37combining machine's MAC address and timer (epoch) value. 38 39Successive versions are using MD5 hash, random numbers and SHA-1 hash. All major 40OSes and programming languages are providing libraries to compute UUID (e.g. 41uuid command line tool). 42 43GPT brief explanation: 44====================== 45 46 Layout: 47 ------- 48 49 -------------------------------------------------- 50 LBA 0 |Protective MBR | 51 ---------------------------------------------------------- 52 LBA 1 |Primary GPT Header | Primary 53 -------------------------------------------------- GPT 54 LBA 2 |Entry 1|Entry 2| Entry 3| Entry 4| 55 -------------------------------------------------- 56 LBA 3 |Entries 5 - 128 | 57 | | 58 | | 59 ---------------------------------------------------------- 60 LBA 34 |Partition 1 | 61 | | 62 ----------------------------------- 63 |Partition 2 | 64 | | 65 ----------------------------------- 66 |Partition n | 67 | | 68 ---------------------------------------------------------- 69 LBA -34 |Entry 1|Entry 2| Entry 3| Entry 4| Backup 70 -------------------------------------------------- GPT 71 LBA -33 |Entries 5 - 128 | 72 | | 73 | | 74 LBA -2 | | 75 -------------------------------------------------- 76 LBA -1 |Backup GPT Header | 77 ---------------------------------------------------------- 78 79For a legacy reasons, GPT's LBA 0 sector has a MBR structure. It is called 80"protective MBR". 81Its first partition entry ID has 0xEE value, and disk software, which is not 82handling the GPT sees it as a storage device without free space. 83 84It is possible to define 128 linearly placed partition entries. 85 86"LBA -1" means the last addressable block (in the mmc subsystem: 87"dev_desc->lba - 1") 88 89Primary/Backup GPT header: 90---------------------------- 91Offset Size Description 92 930 8 B Signature ("EFI PART", 45 46 49 20 50 41 52 54) 948 4 B Revision (For version 1.0, the value is 00 00 01 00) 9512 4 B Header size (in bytes, usually 5C 00 00 00 meaning 92 bytes) 9616 4 B CRC32 of header (0 to header size), with this field zeroed 97 during calculation 9820 4 B Reserved (ZERO); 9924 8 B Current LBA (location of this header copy) 10032 8 B Backup LBA (location of the other header copy) 10140 8 B First usable LBA for partitions (primary partition table last 102 LBA + 1) 10348 8 B Last usable LBA (secondary partition table first LBA - 1) 10456 16 B Disk GUID (also referred as UUID on UNIXes) 10572 8 B Partition entries starting LBA (always 2 in primary copy) 10680 4 B Number of partition entries 10784 4 B Size of a partition entry (usually 128) 10888 4 B CRC32 of partition array 10992 * Reserved; must be ZERO (420 bytes for a 512-byte LBA) 110 111TOTAL: 512 B 112 113 114IMPORTANT: 115 116GPT headers and partition entries are protected by CRC32 (the POSIX CRC32). 117 118Primary GPT header and Backup GPT header have swapped values of "Current LBA" 119and "Backup LBA" and therefore different CRC32 check-sum. 120 121CRC32 for GPT headers (field "CRC of header") are calculated up till 122"Header size" (92), NOT 512 bytes. 123 124CRC32 for partition entries (field "CRC32 of partition array") is calculated for 125the whole array entry ( Number_of_partition_entries * 126sizeof(partition_entry_size (usually 128))) 127 128Observe, how Backup GPT is placed in the memory. It is NOT a mirror reflect 129of the Primary. 130 131 Partition Entry Format: 132 ---------------------- 133 Offset Size Description 134 135 0 16 B Partition type GUID (Big Endian) 136 16 16 B Unique partition GUID in (Big Endian) 137 32 8 B First LBA (Little Endian) 138 40 8 B Last LBA (inclusive) 139 48 8 B Attribute flags [+] 140 56 72 B Partition name (text) 141 142 Attribute flags: 143 Bit 0 - System partition 144 Bit 60 - Read-only 145 Bit 62 - Hidden 146 Bit 63 - Not mount 147 148Creating GPT partitions in U-Boot: 149============== 150 151To restore GUID partition table one needs to: 1521. Define partition layout in the environment. 153 Format of partitions layout: 154 "partitions=uuid_disk=...;name=u-boot,size=60MiB,uuid=...; 155 name=kernel,size=60MiB,uuid=...;" 156 or 157 "partitions=uuid_disk=${uuid_gpt_disk};name=${uboot_name}, 158 size=${uboot_size},uuid=${uboot_uuid};" 159 160 The fields 'name' and 'size' are mandatory for every partition. 161 The field 'start' is optional. 162 163 The fields 'uuid' and 'uuid_disk' are optional if CONFIG_RANDOM_UUID is 164 enabled. A random uuid will be used if omitted or they point to an empty/ 165 non-existent environment variable. The environment variable will be set to 166 the generated UUID. 167 1682. Define 'CONFIG_EFI_PARTITION' and 'CONFIG_CMD_GPT' 169 1702. From u-boot prompt type: 171 gpt write mmc 0 $partitions 172 173Useful info: 174============ 175 176Two programs, namely: 'gdisk' and 'parted' are recommended to work with GPT 177recovery. Both are able to handle GUID partitions. 178Please, pay attention at -l switch for parted. 179 180"uuid" program is recommended to generate UUID string. Moreover it can decode 181(-d switch) passed in UUID string. It can be used to generate partitions UUID 182passed to u-boot environment variables. 183If optional CONFIG_RANDOM_UUID is defined then for any partition which environment 184uuid is unset, uuid is randomly generated and stored in correspond environment 185variable. 186 187note: 188Each string block of UUID generated by program "uuid" is in big endian and it is 189also stored in big endian in disk GPT. 190Partitions layout can be printed by typing "mmc part". Note that each partition 191GUID has different byte order than UUID generated before, this is because first 192three blocks of GUID string are in Little Endian. 193