doc/README.gpt

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