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
  10 Glossary:
  11 ========
  12 - UUID -(Universally Unique Identifier)
  13 - GUID - (Globally Unique ID)
  14 - EFI - (Extensible Firmware Interface)
  15 - UEFI - (Unified EFI) - EFI evolution
  16 - GPT (GUID Partition Table) - it is the EFI standard part
  17 - partitions - lists of available partitions (defined at u-boot):
  18   ./include/configs/{target}.h
  19
  20 Introduction:
  21 =============
  22 This document describes the GPT partition table format and usage of
  23 the gpt command in u-boot.
  24
  25
  26 UUID introduction:
  27 ====================
  28
  29 GPT for marking disks/partitions is using the UUID. It is supposed to be a
  30 globally unique value. A UUID is a 16-byte (128-bit) number. The number of
  31 theoretically possible UUIDs is therefore about 3 x 10^38.
  32 More often UUID is displayed as 32 hexadecimal digits, in 5 groups,
  33 separated by hyphens, in the form 8-4-4-4-12 for a total of 36 characters
  34 (32 digits and 4 hyphens)
  35
  36 For instance, GUID of Linux data partition: EBD0A0A2-B9E5-4433-87C0-68B6B72699C7
  37
  38 Historically there are 5 methods to generate this number. The oldest one is
  39 combining machine's MAC address and timer (epoch) value.
  40
  41 Successive versions are using MD5 hash, random numbers and SHA-1 hash. All major
  42 OSes and programming languages are providing libraries to compute UUID (e.g.
  43 uuid command line tool).
  44
  45 GPT brief explanation:
  46 ======================
  47
  48         Layout:
  49         -------
  50
  51         --------------------------------------------------
  52         LBA 0          |Protective MBR                   |
  53         ----------------------------------------------------------
  54         LBA 1          |Primary GPT Header               | Primary
  55         -------------------------------------------------- GPT
  56         LBA 2          |Entry 1|Entry 2| Entry 3| Entry 4|
  57         --------------------------------------------------
  58         LBA 3          |Entries 5 - 128                  |
  59                        |                                 |
  60                        |                                 |
  61         ----------------------------------------------------------
  62         LBA 34         |Partition 1                      |
  63                        |                                 |
  64                        -----------------------------------
  65                        |Partition 2                      |
  66                        |                                 |
  67                        -----------------------------------
  68                        |Partition n                      |
  69                        |                                 |
  70         ----------------------------------------------------------
  71         LBA -34        |Entry 1|Entry 2| Entry 3| Entry 4| Secondary
  72         -------------------------------------------------- (bkp)
  73         LBA -33        |Entries 5 - 128                  | GPT
  74                        |                                 |
  75                        |                                 |
  76         LBA -2         |                                 |
  77         --------------------------------------------------
  78         LBA -1         |Secondary GPT Header             |
  79         ----------------------------------------------------------
  80
  81
  82 For a legacy reasons, GPT's LBA 0 sector has a MBR structure. It is called
  83 "protective MBR".
  84 Its first partition entry ID has 0xEE value, and disk software, which is not
  85 handling the GPT sees it as a storage device without free space.
  86
  87 It is possible to define 128 linearly placed partition entries.
  88
  89 "LBA -1" means the last addressable block (in the mmc subsystem:
  90 "dev_desc->lba - 1")
  91
  92 Primary/Secondary GPT header:
  93 ----------------------------
  94 Offset  Size    Description
  95
  96 0       8 B     Signature ("EFI PART", 45 46 49 20 50 41 52 54)
  97 8       4 B     Revision (For version 1.0, the value is 00 00 01 00)
  98 12      4 B     Header size (in bytes, usually 5C 00 00 00 meaning 92 bytes)
  99 16      4 B     CRC32 of header (0 to header size), with this field zeroed
 100                 during calculation
 101 20      4 B     Reserved (ZERO);
 102 24      8 B     Current LBA (location of this header copy)
 103 32      8 B     Backup LBA (location of the other header copy)
 104 40      8 B     First usable LBA for partitions (primary partition table last
 105                 LBA + 1)
 106 48      8 B     Last usable LBA (secondary partition table first LBA - 1)
 107 56      16 B    Disk GUID (also referred as UUID on UNIXes)
 108 72      8 B     Partition entries starting LBA (always 2 in primary copy)
 109 80      4 B     Number of partition entries
 110 84      4 B     Size of a partition entry (usually 128)
 111 88      4 B     CRC32 of partition array
 112 92      *       Reserved; must be ZERO (420 bytes for a 512-byte LBA)
 113
 114 TOTAL: 512 B
 115
 116
 117
 118 IMPORTANT:
 119
 120 GPT headers and partition entries are protected by CRC32 (the POSIX CRC32).
 121
 122 Primary GPT header and Secondary GPT header have swapped values of "Current LBA"
 123 and "Backup LBA" and therefore different CRC32 check-sum.
 124
 125 CRC32 for GPT headers (field "CRC of header") are calculated up till
 126 "Header size" (92), NOT 512 bytes.
 127
 128 CRC32 for partition entries (field "CRC32 of partition array") is calculated for
 129 the whole array entry ( Number_of_partition_entries *
 130 sizeof(partition_entry_size (usually 128)))
 131
 132 Observe, how Secondary GPT is placed in the memory. It is NOT a mirror reflect
 133 of the Primary.
 134
 135
 136            Partition Entry Format:
 137            ----------------------
 138            Offset  Size    Description
 139
 140            0       16 B    Partition type GUID
 141            16      16 B    Unique partition GUID
 142            32      8  B    First LBA (Little Endian)
 143            40      8  B    Last LBA (inclusive)
 144            48      8  B    Attribute flags [+]
 145            56      72 B    Partition name (text)
 146
 147            Attribute flags:
 148            Bit 0  - System partition
 149            Bit 60 - Read-only
 150            Bit 62 - Hidden
 151            Bit 63 - Not mount
 152
 153
 154 Creating GPT partitions in U-Boot:
 155 ==============
 156
 157 To restore GUID partition table one needs to:
 158 1. Define partition layout in the environment.
 159    Format of partitions layout:
 160      "partitions=uuid_disk=...;name=u-boot,size=60MiB,uuid=...;
 161         name=kernel,size=60MiB,uuid=...;"
 162      or
 163      "partitions=uuid_disk=${uuid_gpt_disk};name=${uboot_name},
 164         size=${uboot_size},uuid=${uboot_uuid};"
 165
 166    Fields 'name', 'size' and 'uuid' are mandatory for every partition.
 167    The field 'start' is optional.
 168
 169 2. Define 'CONFIG_EFI_PARTITION' and 'CONFIG_CMD_GPT'
 170
 171 2. From u-boot prompt type:
 172    gpt write mmc 0 $partitions
 173
 174
 175 Useful info:
 176 ============
 177
 178 Two programs, namely: 'fdisk' and 'parted' are recommended to work with GPT
 179 recovery. Parted is able to handle GUID partitions. Unfortunately the 'fdisk'
 180 hasn't got such ability.
 181 Please, pay attention at -l switch for parted.
 182
 183 "uuid" program is recommended to generate UUID string. Moreover it can decode
 184 (-d switch) passed in UUID string. It can be used to generate partitions UUID
 185 passed to u-boot environment variables.