README.gpt 7.1 KB
Newer Older
1 2 3 4 5 6
#
#  Copyright (C) 2012 Samsung Electronics
#
#  Lukasz Majewski <l.majewski@samsung.com>
#
#
7
# SPDX-License-Identifier:	GPL-2.0+
8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68

Glossary:
========
- UUID -(Universally Unique Identifier)
- GUID - (Globally Unique ID)
- EFI - (Extensible Firmware Interface)
- UEFI - (Unified EFI) - EFI evolution
- GPT (GUID Partition Table) - it is the EFI standard part
- partitions - lists of available partitions (defined at u-boot):
  ./include/configs/{target}.h

Introduction:
=============
This document describes the GPT partition table format and usage of
the gpt command in u-boot.

UUID introduction:
====================

GPT for marking disks/partitions is using the UUID. It is supposed to be a
globally unique value. A UUID is a 16-byte (128-bit) number. The number of
theoretically possible UUIDs is therefore about 3 x 10^38.
More often UUID is displayed as 32 hexadecimal digits, in 5 groups,
separated by hyphens, in the form 8-4-4-4-12 for a total of 36 characters
(32 digits and 4 hyphens)

For instance, GUID of Linux data partition: EBD0A0A2-B9E5-4433-87C0-68B6B72699C7

Historically there are 5 methods to generate this number. The oldest one is
combining machine's MAC address and timer (epoch) value.

Successive versions are using MD5 hash, random numbers and SHA-1 hash. All major
OSes and programming languages are providing libraries to compute UUID (e.g.
uuid command line tool).

GPT brief explanation:
======================

	Layout:
	-------

	--------------------------------------------------
	LBA 0          |Protective MBR                   |
	----------------------------------------------------------
	LBA 1          |Primary GPT Header               | Primary
	-------------------------------------------------- GPT
	LBA 2          |Entry 1|Entry 2| Entry 3| Entry 4|
	--------------------------------------------------
	LBA 3          |Entries 5 - 128                  |
		       |                                 |
		       |                                 |
	----------------------------------------------------------
	LBA 34         |Partition 1                      |
		       |                                 |
		       -----------------------------------
		       |Partition 2                      |
		       |                                 |
		       -----------------------------------
		       |Partition n                      |
		       |                                 |
	----------------------------------------------------------
69 70 71
	LBA -34        |Entry 1|Entry 2| Entry 3| Entry 4| Backup
	-------------------------------------------------- GPT
	LBA -33        |Entries 5 - 128                  |
72 73 74 75
		       |                                 |
		       |                                 |
	LBA -2         |                                 |
	--------------------------------------------------
76
	LBA -1         |Backup GPT Header                |
77 78 79 80 81 82 83 84 85 86 87 88
	----------------------------------------------------------

For a legacy reasons, GPT's LBA 0 sector has a MBR structure. It is called
"protective MBR".
Its first partition entry ID has 0xEE value, and disk software, which is not
handling the GPT sees it as a storage device without free space.

It is possible to define 128 linearly placed partition entries.

"LBA -1" means the last addressable block (in the mmc subsystem:
"dev_desc->lba - 1")

89
Primary/Backup GPT header:
90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117
----------------------------
Offset  Size    Description

0       8 B     Signature ("EFI PART", 45 46 49 20 50 41 52 54)
8       4 B     Revision (For version 1.0, the value is 00 00 01 00)
12      4 B     Header size (in bytes, usually 5C 00 00 00 meaning 92 bytes)
16      4 B     CRC32 of header (0 to header size), with this field zeroed
		during calculation
20      4 B     Reserved (ZERO);
24      8 B     Current LBA (location of this header copy)
32      8 B     Backup LBA (location of the other header copy)
40      8 B     First usable LBA for partitions (primary partition table last
		LBA + 1)
48      8 B     Last usable LBA (secondary partition table first LBA - 1)
56      16 B    Disk GUID (also referred as UUID on UNIXes)
72      8 B     Partition entries starting LBA (always 2 in primary copy)
80      4 B     Number of partition entries
84      4 B     Size of a partition entry (usually 128)
88      4 B     CRC32 of partition array
92      *       Reserved; must be ZERO (420 bytes for a 512-byte LBA)

TOTAL: 512 B


IMPORTANT:

GPT headers and partition entries are protected by CRC32 (the POSIX CRC32).

118
Primary GPT header and Backup GPT header have swapped values of "Current LBA"
119 120 121 122 123 124 125 126 127
and "Backup LBA" and therefore different CRC32 check-sum.

CRC32 for GPT headers (field "CRC of header") are calculated up till
"Header size" (92), NOT 512 bytes.

CRC32 for partition entries (field "CRC32 of partition array") is calculated for
the whole array entry ( Number_of_partition_entries *
sizeof(partition_entry_size (usually 128)))

128
Observe, how Backup GPT is placed in the memory. It is NOT a mirror reflect
129 130 131 132 133 134
of the Primary.

	   Partition Entry Format:
	   ----------------------
	   Offset  Size    Description

135 136
	   0       16 B    Partition type GUID (Big Endian)
	   16      16 B    Unique partition GUID in (Big Endian)
137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159
	   32      8  B    First LBA (Little Endian)
	   40      8  B    Last LBA (inclusive)
	   48      8  B    Attribute flags [+]
	   56      72 B    Partition name (text)

	   Attribute flags:
	   Bit 0  - System partition
	   Bit 60 - Read-only
	   Bit 62 - Hidden
	   Bit 63 - Not mount

Creating GPT partitions in U-Boot:
==============

To restore GUID partition table one needs to:
1. Define partition layout in the environment.
   Format of partitions layout:
     "partitions=uuid_disk=...;name=u-boot,size=60MiB,uuid=...;
	name=kernel,size=60MiB,uuid=...;"
     or
     "partitions=uuid_disk=${uuid_gpt_disk};name=${uboot_name},
	size=${uboot_size},uuid=${uboot_uuid};"

160
   The fields 'name' and 'size' are mandatory for every partition.
161 162
   The field 'start' is optional.

163 164 165 166
   The fields 'uuid' and 'uuid_disk' are optional if CONFIG_RANDOM_UUID is
   enabled. A random uuid will be used if omitted or they point to an empty/
   non-existent environment variable. The environment variable will be set to
   the generated UUID.
167

168 169 170 171 172 173 174 175
2. Define 'CONFIG_EFI_PARTITION' and 'CONFIG_CMD_GPT'

2. From u-boot prompt type:
   gpt write mmc 0 $partitions

Useful info:
============

176 177
Two programs, namely: 'gdisk' and 'parted' are recommended to work with GPT
recovery. Both are able to handle GUID partitions.
178 179 180 181 182
Please, pay attention at -l switch for parted.

"uuid" program is recommended to generate UUID string. Moreover it can decode
(-d switch) passed in UUID string. It can be used to generate partitions UUID
passed to u-boot environment variables.
183 184 185 186 187 188 189 190 191 192
If optional CONFIG_RANDOM_UUID is defined then for any partition which environment
uuid is unset, uuid is randomly generated and stored in correspond environment
variable.

note:
Each string block of UUID generated by program "uuid" is in big endian and it is
also stored in big endian in disk GPT.
Partitions layout can be printed by typing "mmc part". Note that each partition
GUID has different byte order than UUID generated before, this is because first
three blocks of GUID string are in Little Endian.