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 Linux data partition: EBD0A0A2-B9E5-4433-87C0-68B6B72699C7
  35
  36 Historically there are 5 methods to generate this number. The oldest one is
  37 combining machine's MAC address and timer (epoch) value.
  38
  39 Successive versions are using MD5 hash, random numbers and SHA-1 hash. All major
  40 OSes and programming languages are providing libraries to compute UUID (e.g.
  41 uuid command line tool).
  42
  43 GPT 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
  79 For a legacy reasons, GPT's LBA 0 sector has a MBR structure. It is called
  80 "protective MBR".
  81 Its first partition entry ID has 0xEE value, and disk software, which is not
  82 handling the GPT sees it as a storage device without free space.
  83
  84 It 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
  89 Primary/Backup GPT header:
  90 ----------------------------
  91 Offset  Size    Description
  92
  93 0       8 B     Signature ("EFI PART", 45 46 49 20 50 41 52 54)
  94 8       4 B     Revision (For version 1.0, the value is 00 00 01 00)
  95 12      4 B     Header size (in bytes, usually 5C 00 00 00 meaning 92 bytes)
  96 16      4 B     CRC32 of header (0 to header size), with this field zeroed
  97                 during calculation
  98 20      4 B     Reserved (ZERO);
  99 24      8 B     Current LBA (location of this header copy)
 100 32      8 B     Backup LBA (location of the other header copy)
 101 40      8 B     First usable LBA for partitions (primary partition table last
 102                 LBA + 1)
 103 48      8 B     Last usable LBA (secondary partition table first LBA - 1)
 104 56      16 B    Disk GUID (also referred as UUID on UNIXes)
 105 72      8 B     Partition entries starting LBA (always 2 in primary copy)
 106 80      4 B     Number of partition entries
 107 84      4 B     Size of a partition entry (usually 128)
 108 88      4 B     CRC32 of partition array
 109 92      *       Reserved; must be ZERO (420 bytes for a 512-byte LBA)
 110
 111 TOTAL: 512 B
 112
 113
 114 IMPORTANT:
 115
 116 GPT headers and partition entries are protected by CRC32 (the POSIX CRC32).
 117
 118 Primary GPT header and Backup GPT header have swapped values of "Current LBA"
 119 and "Backup LBA" and therefore different CRC32 check-sum.
 120
 121 CRC32 for GPT headers (field "CRC of header") are calculated up till
 122 "Header size" (92), NOT 512 bytes.
 123
 124 CRC32 for partition entries (field "CRC32 of partition array") is calculated for
 125 the whole array entry ( Number_of_partition_entries *
 126 sizeof(partition_entry_size (usually 128)))
 127
 128 Observe, how Backup GPT is placed in the memory. It is NOT a mirror reflect
 129 of 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
 148 Creating GPT partitions in U-Boot:
 149 ==============
 150
 151 To restore GUID partition table one needs to:
 152 1. 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
 168 2. Define 'CONFIG_EFI_PARTITION' and 'CONFIG_CMD_GPT'
 169
 170 2. From u-boot prompt type:
 171    gpt write mmc 0 $partitions
 172
 173 Useful info:
 174 ============
 175
 176 Two programs, namely: 'gdisk' and 'parted' are recommended to work with GPT
 177 recovery. Both are able to handle GUID partitions.
 178 Please, 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
 182 passed to u-boot environment variables.
 183 If optional CONFIG_RANDOM_UUID is defined then for any partition which environment
 184 uuid is unset, uuid is randomly generated and stored in correspond environment
 185 variable.
 186
 187 note:
 188 Each string block of UUID generated by program "uuid" is in big endian and it is
 189 also stored in big endian in disk GPT.
 190 Partitions layout can be printed by typing "mmc part". Note that each partition
 191 GUID has different byte order than UUID generated before, this is because first
 192 three blocks of GUID string are in Little Endian.