doc/README.gpt

   1 # SPDX-License-Identifier: GPL-2.0+
   2 #
   3 #  Copyright (C) 2012 Samsung Electronics
   4 #
   5 #  Lukasz Majewski <l.majewski@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 doc/arch/index.rst:
 233
 234 =>host bind 0 ./disk.raw
 235 => gpt read host 0
 236 [ . . . ]
 237 => gpt swap host 0 name othername
 238 [ . . . ]
 239
 240 Modifying GPT partition layout from U-Boot:
 241 ===========================================
 242
 243 The entire GPT partition layout can be exported to an environment
 244 variable and then modified enmasse. Users can change the partition
 245 numbers, offsets, names and sizes. The resulting variable can used to
 246 reformat the device. Here is an example of reading the GPT partitions
 247 into a variable and then modifying them:
 248
 249 U-BOOT> gpt read mmc 0 current_partitions
 250 U-BOOT> env edit current_partitions
 251 edit: uuid_disk=[...];name=part1,start=0x4000,size=0x4000,uuid=[...];
 252 name=part2,start=0xc000,size=0xc000,uuid=[...];[ . . . ]
 253
 254 U-BOOT> gpt write mmc 0 $current_partitions
 255 U-BOOT> gpt verify mmc 0 $current_partitions
 256
 257 Partition type GUID:
 258 ====================
 259
 260 For created partition, the used partition type GUID is
 261 PARTITION_BASIC_DATA_GUID (EBD0A0A2-B9E5-4433-87C0-68B6B72699C7).
 262
 263 If you define 'CONFIG_PARTITION_TYPE_GUID', a optionnal parameter 'type'
 264 can specify a other partition type guid:
 265
 266      "uuid_disk=...;name=u-boot,size=60MiB,uuid=...;
 267         name=kernel,size=60MiB,uuid=...,
 268         type=0FC63DAF-8483-4772-8E79-3D69D8477DE4;"
 269
 270 Some strings can be also used at the place of known GUID :
 271         "system"          = PARTITION_SYSTEM_GUID
 272                             (C12A7328-F81F-11D2-BA4B-00A0C93EC93B)
 273         "mbr"             = LEGACY_MBR_PARTITION_GUID
 274                             (024DEE41-33E7-11D3-9D69-0008C781F39F)
 275         "msft"            = PARTITION_MSFT_RESERVED_GUID
 276                             (E3C9E316-0B5C-4DB8-817D-F92DF00215AE)
 277         "data"            = PARTITION_BASIC_DATA_GUID
 278                              (EBD0A0A2-B9E5-4433-87C0-68B6B72699C7)
 279         "linux"           = PARTITION_LINUX_FILE_SYSTEM_DATA_GUID
 280                             (0FC63DAF-8483-4772-8E79-3D69D8477DE4)
 281         "raid"            = PARTITION_LINUX_RAID_GUID
 282                             (A19D880F-05FC-4D3B-A006-743F0F84911E)
 283         "swap"            = PARTITION_LINUX_SWAP_GUID
 284                             (0657FD6D-A4AB-43C4-84E5-0933C84B4F4F)
 285         "lvm"             = PARTITION_LINUX_LVM_GUID
 286                             (E6D6D379-F507-44C2-A23C-238F2A3DF928)
 287         "u-boot-env"      = PARTITION_U_BOOT_ENVIRONMENT
 288                             (3DE21764-95BD-54BD-A5C3-4ABE786F38A8)
 289
 290     "uuid_disk=...;name=u-boot,size=60MiB,uuid=...;
 291         name=kernel,size=60MiB,uuid=...,type=linux;"
 292
 293 They are also used to display the type of partition in "part list" command.
 294
 295
 296 Useful info:
 297 ============
 298
 299 Two programs, namely: 'gdisk' and 'parted' are recommended to work with GPT
 300 recovery. Both are able to handle GUID partitions.
 301 Please, pay attention at -l switch for parted.
 302
 303 "uuid" program is recommended to generate UUID string. Moreover it can decode
 304 (-d switch) passed in UUID string. It can be used to generate partitions UUID
 305 passed to u-boot environment variables.
 306 If optional CONFIG_RANDOM_UUID is defined then for any partition which environment
 307 uuid is unset, uuid is randomly generated and stored in correspond environment
 308 variable.
 309
 310 note:
 311 Each string block of UUID generated by program "uuid" is in big endian and it is
 312 also stored in big endian in disk GPT.
 313 Partitions layout can be printed by typing "mmc part". Note that each partition
 314 GUID has different byte order than UUID generated before, this is because first
 315 three blocks of GUID string are in Little Endian.