doc/README.gpt

   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
   9 Glossary:
  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
  19 Introduction:
  20 =============
  21 This document describes the GPT partition table format and usage of
  22 the gpt command in u-boot.
  23
  24 UUID introduction:
  25 ====================
  26
  27 GPT for marking disks/partitions is using the UUID. It is supposed to be a
  28 globally unique value. A UUID is a 16-byte (128-bit) number. The number of
  29 theoretically possible UUIDs is therefore about 3 x 10^38.
  30 More often UUID is displayed as 32 hexadecimal digits, in 5 groups,
  31 separated by hyphens, in the form 8-4-4-4-12 for a total of 36 characters
  32 (32 digits and 4 hyphens)
  33
  34 For instance, GUID of Basic data partition: EBD0A0A2-B9E5-4433-87C0-68B6B72699C7
  35 and GUID of Linux filesystem data: 0FC63DAF-8483-4772-8E79-3D69D8477DE4
  36
  37 Historically there are 5 methods to generate this number. The oldest one is
  38 combining machine's MAC address and timer (epoch) value.
  39
  40 Successive versions are using MD5 hash, random numbers and SHA-1 hash. All major
  41 OSes and programming languages are providing libraries to compute UUID (e.g.
  42 uuid command line tool).
  43
  44 GPT 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         ----------------------------------------------------------
  70         LBA -34        |Entry 1|Entry 2| Entry 3| Entry 4| Backup
  71         -------------------------------------------------- GPT
  72         LBA -33        |Entries 5 - 128                  |
  73                        |                                 |
  74                        |                                 |
  75         LBA -2         |                                 |
  76         --------------------------------------------------
  77         LBA -1         |Backup GPT Header                |
  78         ----------------------------------------------------------
  79
  80 For a legacy reasons, GPT's LBA 0 sector has a MBR structure. It is called
  81 "protective MBR".
  82 Its first partition entry ID has 0xEE value, and disk software, which is not
  83 handling the GPT sees it as a storage device without free space.
  84
  85 It 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
  90 Primary/Backup GPT header:
  91 ----------------------------
  92 Offset  Size    Description
  93
  94 0       8 B     Signature ("EFI PART", 45 46 49 20 50 41 52 54)
  95 8       4 B     Revision (For version 1.0, the value is 00 00 01 00)
  96 12      4 B     Header size (in bytes, usually 5C 00 00 00 meaning 92 bytes)
  97 16      4 B     CRC32 of header (0 to header size), with this field zeroed
  98                 during calculation
  99 20      4 B     Reserved (ZERO);
 100 24      8 B     Current LBA (location of this header copy)
 101 32      8 B     Backup LBA (location of the other header copy)
 102 40      8 B     First usable LBA for partitions (primary partition table last
 103                 LBA + 1)
 104 48      8 B     Last usable LBA (secondary partition table first LBA - 1)
 105 56      16 B    Disk GUID (also referred as UUID on UNIXes)
 106 72      8 B     Partition entries starting LBA (always 2 in primary copy)
 107 80      4 B     Number of partition entries
 108 84      4 B     Size of a partition entry (usually 128)
 109 88      4 B     CRC32 of partition array
 110 92      *       Reserved; must be ZERO (420 bytes for a 512-byte LBA)
 111
 112 TOTAL: 512 B
 113
 114
 115 IMPORTANT:
 116
 117 GPT headers and partition entries are protected by CRC32 (the POSIX CRC32).
 118
 119 Primary GPT header and Backup GPT header have swapped values of "Current LBA"
 120 and "Backup LBA" and therefore different CRC32 check-sum.
 121
 122 CRC32 for GPT headers (field "CRC of header") are calculated up till
 123 "Header size" (92), NOT 512 bytes.
 124
 125 CRC32 for partition entries (field "CRC32 of partition array") is calculated for
 126 the whole array entry ( Number_of_partition_entries *
 127 sizeof(partition_entry_size (usually 128)))
 128
 129 Observe, how Backup GPT is placed in the memory. It is NOT a mirror reflect
 130 of the Primary.
 131
 132            Partition Entry Format:
 133            ----------------------
 134            Offset  Size    Description
 135
 136            0       16 B    Partition type GUID (Big Endian)
 137            16      16 B    Unique partition GUID in (Big Endian)
 138            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
 145            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 :
 149            Bit 60 - Read-only
 150            Bit 62 - Hidden
 151            Bit 63 - Not mount
 152
 153 Creating GPT partitions in U-Boot:
 154 ==============
 155
 156 To restore GUID partition table one needs to:
 157 1. Define partition layout in the environment.
 158    Format of partitions layout:
 159      "uuid_disk=...;name=u-boot,size=60MiB,uuid=...;
 160         name=kernel,size=60MiB,uuid=...;"
 161      or
 162      "uuid_disk=${uuid_gpt_disk};name=${uboot_name},
 163         size=${uboot_size},uuid=${uboot_uuid};"
 164
 165    The fields 'name' and 'size' are mandatory for every partition.
 166    The field 'start' is optional.
 167
 168    If field 'size' of the last partition is 0, the partition is extended
 169    up to the end of the device.
 170
 171    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.  The 'gpt guid' command reads the current value of the
 175    uuid_disk from the GPT.
 176
 177    The field 'bootable' is optional, it is used to mark the GPT partition
 178    bootable (set attribute flags "Legacy BIOS bootable").
 179      "name=u-boot,size=60MiB;name=boot,size=60Mib,bootable;name=rootfs,size=0"
 180    It can be used to locate bootable disks with command
 181    "part list <interface> <dev> -bootable <varname>",
 182    please check out doc/README.distro for use.
 183
 184 2. Define 'CONFIG_EFI_PARTITION' and 'CONFIG_CMD_GPT'
 185
 186 3. From u-boot prompt type:
 187    gpt write mmc 0 $partitions
 188
 189 Checking (validating) GPT partitions in U-Boot:
 190 ===============================================
 191
 192 Procedure is the same as above. The only change is at point 3.
 193
 194 At u-boot prompt one needs to write:
 195    gpt verify mmc 0 [$partitions]
 196
 197 where [$partitions] is an optional parameter.
 198
 199 When it is not provided, only basic checks based on CRC32 calculation for GPT
 200 header and PTEs are performed.
 201 When provided, additionally partition data - name, size and starting
 202 offset (last two in LBA) - are compared with data defined in '$partitions'
 203 environment variable.
 204
 205 After running this command, return code is set to 0 if no errors found in
 206 on non-volatile medium stored GPT.
 207
 208 Following line can be used to assess if GPT verification has succeed:
 209
 210 U-BOOT> gpt verify mmc 0 $partitions
 211 U-BOOT> if test $? = 0; then echo "GPT OK"; else echo "GPT ERR"; fi
 212
 213 Renaming GPT partitions from U-Boot:
 214 ====================================
 215
 216 GPT partition names are a mechanism via which userspace and U-Boot can
 217 communicate about software updates and boot failure.  The 'gpt guid',
 218 'gpt read', 'gpt rename' and 'gpt swap' commands facilitate
 219 programmatic renaming of partitions from bootscripts by generating and
 220 modifying the partitions layout string.  Here is an illustration of
 221 employing 'swap' to exchange 'primary' and 'backup' partition names:
 222
 223 U-BOOT> gpt swap mmc 0 primary backup
 224
 225 Afterwards, all partitions previously named 'primary' will be named
 226 'backup', and vice-versa.  Alternatively, single partitions may be
 227 renamed.  In this example, mmc0's first partition will be renamed
 228 'primary':
 229
 230 U-BOOT> gpt rename mmc 0 1 primary
 231
 232 The GPT functionality may be tested with the 'sandbox' board by
 233 creating a disk image as described under 'Block Device Emulation' in
 234 board/sandbox/README.sandbox:
 235
 236 =>host bind 0 ./disk.raw
 237 => gpt read host 0
 238 [ . . . ]
 239 => gpt flip host 0
 240 [ . . . ]
 241
 242 The GPT functionality may be tested with the 'sandbox' board by
 243 creating a disk image as described under 'Block Device Emulation' in
 244 board/sandbox/README.sandbox:
 245
 246 =>host bind 0 ./disk.raw
 247 => gpt read host 0
 248 [ . . . ]
 249 => gpt swap host 0 name othername
 250 [ . . . ]
 251
 252 Partition type GUID:
 253 ====================
 254
 255 For created partition, the used partition type GUID is
 256 PARTITION_BASIC_DATA_GUID (EBD0A0A2-B9E5-4433-87C0-68B6B72699C7).
 257
 258 If you define 'CONFIG_PARTITION_TYPE_GUID', a optionnal parameter 'type'
 259 can specify a other partition type guid:
 260
 261      "uuid_disk=...;name=u-boot,size=60MiB,uuid=...;
 262         name=kernel,size=60MiB,uuid=...,
 263         type=0FC63DAF-8483-4772-8E79-3D69D8477DE4;"
 264
 265 Some strings can be also used at the place of known GUID :
 266         "system" = PARTITION_SYSTEM_GUID
 267                    (C12A7328-F81F-11D2-BA4B-00A0C93EC93B)
 268         "mbr"    = LEGACY_MBR_PARTITION_GUID
 269                    (024DEE41-33E7-11D3-9D69-0008C781F39F)
 270         "msft"   = PARTITION_MSFT_RESERVED_GUID
 271                    (E3C9E316-0B5C-4DB8-817D-F92DF00215AE)
 272         "data"   = PARTITION_BASIC_DATA_GUID
 273                     (EBD0A0A2-B9E5-4433-87C0-68B6B72699C7)
 274         "linux"  = PARTITION_LINUX_FILE_SYSTEM_DATA_GUID
 275                    (0FC63DAF-8483-4772-8E79-3D69D8477DE4)
 276         "raid"   = PARTITION_LINUX_RAID_GUID
 277                    (A19D880F-05FC-4D3B-A006-743F0F84911E)
 278         "swap"   = PARTITION_LINUX_SWAP_GUID
 279                    (0657FD6D-A4AB-43C4-84E5-0933C84B4F4F)
 280         "lvm"    = PARTITION_LINUX_LVM_GUID
 281                    (E6D6D379-F507-44C2-A23C-238F2A3DF928)
 282
 283     "uuid_disk=...;name=u-boot,size=60MiB,uuid=...;
 284         name=kernel,size=60MiB,uuid=...,type=linux;"
 285
 286 They are also used to display the type of partition in "part list" command.
 287
 288
 289 Useful info:
 290 ============
 291
 292 Two programs, namely: 'gdisk' and 'parted' are recommended to work with GPT
 293 recovery. Both are able to handle GUID partitions.
 294 Please, pay attention at -l switch for parted.
 295
 296 "uuid" program is recommended to generate UUID string. Moreover it can decode
 297 (-d switch) passed in UUID string. It can be used to generate partitions UUID
 298 passed to u-boot environment variables.
 299 If optional CONFIG_RANDOM_UUID is defined then for any partition which environment
 300 uuid is unset, uuid is randomly generated and stored in correspond environment
 301 variable.
 302
 303 note:
 304 Each string block of UUID generated by program "uuid" is in big endian and it is
 305 also stored in big endian in disk GPT.
 306 Partitions layout can be printed by typing "mmc part". Note that each partition
 307 GUID has different byte order than UUID generated before, this is because first
 308 three blocks of GUID string are in Little Endian.