[J-u-boot.git] / doc / README.gpt

#
#  Copyright (C) 2012 Samsung Electronics
#
#  Lukasz Majewski <[email protected]>
#
#
# SPDX-License-Identifier:	GPL-2.0+

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 Basic data partition: EBD0A0A2-B9E5-4433-87C0-68B6B72699C7
and GUID of Linux filesystem data: 0FC63DAF-8483-4772-8E79-3D69D8477DE4

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                      |
		       |                                 |
	----------------------------------------------------------
	LBA -34        |Entry 1|Entry 2| Entry 3| Entry 4| Backup
	-------------------------------------------------- GPT
	LBA -33        |Entries 5 - 128                  |
		       |                                 |
		       |                                 |
	LBA -2         |                                 |
	--------------------------------------------------
	LBA -1         |Backup GPT Header                |
	----------------------------------------------------------

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")

Primary/Backup GPT header:
----------------------------
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).

Primary GPT header and Backup GPT header have swapped values of "Current LBA"
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)))

Observe, how Backup GPT is placed in the memory. It is NOT a mirror reflect
of the Primary.

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

	   0       16 B    Partition type GUID (Big Endian)
	   16      16 B    Unique partition GUID in (Big Endian)
	   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 1  - Hide from EFI
	   Bit 2  - Legacy BIOS bootable
	   Bit 48-63 - Defined and used by the individual partition type
	   For Basic data 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};"

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

   If field 'size' of the last partition is 0, the partition is extended
   up to the end of the device.

   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.

   The field 'bootable' is optional, it is used to mark the GPT partition
   bootable (set attribute flags "Legacy BIOS bootable").
     "name=u-boot,size=60MiB;name=boot,size=60Mib,bootable;name=rootfs,size=0"
   It can be used to locate bootable disks with command
   "part list <interface> <dev> -bootable <varname>",
   please check out doc/README.distro for use.

2. Define 'CONFIG_EFI_PARTITION' and 'CONFIG_CMD_GPT'

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

Checking (validating) GPT partitions in U-Boot:
===============================================

Procedure is the same as above. The only change is at point 3.

At u-boot prompt one needs to write:
   gpt verify mmc 0 [$partitions]

where [$partitions] is an optional parameter.

When it is not provided, only basic checks based on CRC32 calculation for GPT
header and PTEs are performed.
When provided, additionally partition data - name, size and starting
offset (last two in LBA) - are compared with data defined in '$partitions'
environment variable.

After running this command, return code is set to 0 if no errors found in
on non-volatile medium stored GPT.

Following line can be used to assess if GPT verification has succeed:

U-BOOT> gpt verify mmc 0 $partitions
U-BOOT> if test $? = 0; then echo "GPT OK"; else echo "GPT ERR"; fi


Partition type GUID:
====================

For created partition, the used partition type GUID is
PARTITION_BASIC_DATA_GUID (EBD0A0A2-B9E5-4433-87C0-68B6B72699C7).

If you define 'CONFIG_PARTITION_TYPE_GUID', a optionnal parameter 'type'
can specify a other partition type guid:

     "partitions=uuid_disk=...;name=u-boot,size=60MiB,uuid=...;
	name=kernel,size=60MiB,uuid=...,
	type=0FC63DAF-8483-4772-8E79-3D69D8477DE4;"

Some strings can be also used at the place of known GUID :
	"system" = PARTITION_SYSTEM_GUID
	           (C12A7328-F81F-11D2-BA4B-00A0C93EC93B)
	"mbr"    = LEGACY_MBR_PARTITION_GUID
	           (024DEE41-33E7-11D3-9D69-0008C781F39F)
	"msft"   = PARTITION_MSFT_RESERVED_GUID
	           (E3C9E316-0B5C-4DB8-817D-F92DF00215AE)
	"data"   = PARTITION_BASIC_DATA_GUID
	            (EBD0A0A2-B9E5-4433-87C0-68B6B72699C7)
	"linux"  = PARTITION_LINUX_FILE_SYSTEM_DATA_GUID
	           (0FC63DAF-8483-4772-8E79-3D69D8477DE4)
	"raid"   = PARTITION_LINUX_RAID_GUID
	           (A19D880F-05FC-4D3B-A006-743F0F84911E)
	"swap"   = PARTITION_LINUX_SWAP_GUID
	           (0657FD6D-A4AB-43C4-84E5-0933C84B4F4F)
	"lvm"    = PARTITION_LINUX_LVM_GUID
	           (E6D6D379-F507-44C2-A23C-238F2A3DF928)

    "partitions=uuid_disk=...;name=u-boot,size=60MiB,uuid=...;
	name=kernel,size=60MiB,uuid=...,type=linux;"

They are also used to display the type of partition in "part list" command.


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

Two programs, namely: 'gdisk' and 'parted' are recommended to work with GPT
recovery. Both are able to handle GUID partitions.
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.
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.
Commit	Line	Data
36f2e8e0 ŁM	1	#
	2	# Copyright (C) 2012 Samsung Electronics
	3	#
	4	# Lukasz Majewski <[email protected]>
	5	#
	6	#
1a459660	7	# SPDX-License-Identifier: GPL-2.0+
36f2e8e0	8
36f2e8e0 ŁM	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
36f2e8e0 ŁM	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
b38c108a PD	34	For instance, GUID of Basic data partition: EBD0A0A2-B9E5-4433-87C0-68B6B72699C7
b38c108a PD	35	and GUID of Linux filesystem data: 0FC63DAF-8483-4772-8E79-3D69D8477DE4
36f2e8e0 ŁM	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	----------------------------------------------------------
ae95fad5 SR	70	LBA -34 \|Entry 1\|Entry 2\| Entry 3\| Entry 4\| Backup
	71	-------------------------------------------------- GPT
	72	LBA -33 \|Entries 5 - 128 \|
36f2e8e0 ŁM	73	\| \|
	74	\| \|
	75	LBA -2 \| \|
	76	--------------------------------------------------
ae95fad5	77	LBA -1 \|Backup GPT Header \|
36f2e8e0 ŁM	78	----------------------------------------------------------
36f2e8e0 ŁM	79
36f2e8e0 ŁM	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
ae95fad5	90	Primary/Backup GPT header:
36f2e8e0 ŁM	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
36f2e8e0 ŁM	115	IMPORTANT:
	116
	117	GPT headers and partition entries are protected by CRC32 (the POSIX CRC32).
	118
ae95fad5	119	Primary GPT header and Backup GPT header have swapped values of "Current LBA"
36f2e8e0 ŁM	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
ae95fad5	129	Observe, how Backup GPT is placed in the memory. It is NOT a mirror reflect
36f2e8e0 ŁM	130	of the Primary.
36f2e8e0 ŁM	131
36f2e8e0 ŁM	132	Partition Entry Format:
	133	----------------------
	134	Offset Size Description
	135
39206382 PM	136	0 16 B Partition type GUID (Big Endian)
39206382 PM	137	16 16 B Unique partition GUID in (Big Endian)
36f2e8e0 ŁM	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
cfdaf4ca PD	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 :
36f2e8e0 ŁM	149	Bit 60 - Read-only
	150	Bit 62 - Hidden
	151	Bit 63 - Not mount
	152
36f2e8e0 ŁM	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	"partitions=uuid_disk=...;name=u-boot,size=60MiB,uuid=...;
	160	name=kernel,size=60MiB,uuid=...;"
	161	or
	162	"partitions=uuid_disk=${uuid_gpt_disk};name=${uboot_name},
	163	size=${uboot_size},uuid=${uboot_uuid};"
	164
0c7e8d13	165	The fields 'name' and 'size' are mandatory for every partition.
36f2e8e0 ŁM	166	The field 'start' is optional.
36f2e8e0 ŁM	167
62a3b7dd	168	If field 'size' of the last partition is 0, the partition is extended
cfdaf4ca PD	169	up to the end of the device.
cfdaf4ca PD	170
0c7e8d13 RH	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.
39206382	175
cfdaf4ca PD	176	The field 'bootable' is optional, it is used to mark the GPT partition
	177	bootable (set attribute flags "Legacy BIOS bootable").
	178	"name=u-boot,size=60MiB;name=boot,size=60Mib,bootable;name=rootfs,size=0"
	179	It can be used to locate bootable disks with command
	180	"part list <interface> <dev> -bootable <varname>",
	181	please check out doc/README.distro for use.
	182
36f2e8e0 ŁM	183	2. Define 'CONFIG_EFI_PARTITION' and 'CONFIG_CMD_GPT'
36f2e8e0 ŁM	184
dd445879	185	3. From u-boot prompt type:
36f2e8e0 ŁM	186	gpt write mmc 0 $partitions
36f2e8e0 ŁM	187
dd445879 LM	188	Checking (validating) GPT partitions in U-Boot:
	189	===============================================
	190
	191	Procedure is the same as above. The only change is at point 3.
	192
	193	At u-boot prompt one needs to write:
	194	gpt verify mmc 0 [$partitions]
	195
	196	where [$partitions] is an optional parameter.
	197
	198	When it is not provided, only basic checks based on CRC32 calculation for GPT
	199	header and PTEs are performed.
	200	When provided, additionally partition data - name, size and starting
	201	offset (last two in LBA) - are compared with data defined in '$partitions'
	202	environment variable.
	203
	204	After running this command, return code is set to 0 if no errors found in
	205	on non-volatile medium stored GPT.
	206
	207	Following line can be used to assess if GPT verification has succeed:
	208
	209	U-BOOT> gpt verify mmc 0 $partitions
	210	U-BOOT> if test $? = 0; then echo "GPT OK"; else echo "GPT ERR"; fi
	211
	212
7561b258 PD	213	Partition type GUID:
	214	====================
	215
	216	For created partition, the used partition type GUID is
	217	PARTITION_BASIC_DATA_GUID (EBD0A0A2-B9E5-4433-87C0-68B6B72699C7).
	218
	219	If you define 'CONFIG_PARTITION_TYPE_GUID', a optionnal parameter 'type'
	220	can specify a other partition type guid:
	221
	222	"partitions=uuid_disk=...;name=u-boot,size=60MiB,uuid=...;
	223	name=kernel,size=60MiB,uuid=...,
	224	type=0FC63DAF-8483-4772-8E79-3D69D8477DE4;"
	225
bcb41dca PD	226	Some strings can be also used at the place of known GUID :
	227	"system" = PARTITION_SYSTEM_GUID
	228	(C12A7328-F81F-11D2-BA4B-00A0C93EC93B)
	229	"mbr" = LEGACY_MBR_PARTITION_GUID
	230	(024DEE41-33E7-11D3-9D69-0008C781F39F)
	231	"msft" = PARTITION_MSFT_RESERVED_GUID
	232	(E3C9E316-0B5C-4DB8-817D-F92DF00215AE)
	233	"data" = PARTITION_BASIC_DATA_GUID
	234	(EBD0A0A2-B9E5-4433-87C0-68B6B72699C7)
	235	"linux" = PARTITION_LINUX_FILE_SYSTEM_DATA_GUID
	236	(0FC63DAF-8483-4772-8E79-3D69D8477DE4)
	237	"raid" = PARTITION_LINUX_RAID_GUID
	238	(A19D880F-05FC-4D3B-A006-743F0F84911E)
	239	"swap" = PARTITION_LINUX_SWAP_GUID
	240	(0657FD6D-A4AB-43C4-84E5-0933C84B4F4F)
	241	"lvm" = PARTITION_LINUX_LVM_GUID
	242	(E6D6D379-F507-44C2-A23C-238F2A3DF928)
	243
	244	"partitions=uuid_disk=...;name=u-boot,size=60MiB,uuid=...;
	245	name=kernel,size=60MiB,uuid=...,type=linux;"
	246
	247	They are also used to display the type of partition in "part list" command.
	248
	249
36f2e8e0 ŁM	250	Useful info:
	251	============
	252
39206382 PM	253	Two programs, namely: 'gdisk' and 'parted' are recommended to work with GPT
39206382 PM	254	recovery. Both are able to handle GUID partitions.
36f2e8e0 ŁM	255	Please, pay attention at -l switch for parted.
	256
	257	"uuid" program is recommended to generate UUID string. Moreover it can decode
	258	(-d switch) passed in UUID string. It can be used to generate partitions UUID
	259	passed to u-boot environment variables.
39206382 PM	260	If optional CONFIG_RANDOM_UUID is defined then for any partition which environment
	261	uuid is unset, uuid is randomly generated and stored in correspond environment
	262	variable.
	263
	264	note:
	265	Each string block of UUID generated by program "uuid" is in big endian and it is
	266	also stored in big endian in disk GPT.
	267	Partitions layout can be printed by typing "mmc part". Note that each partition
	268	GUID has different byte order than UUID generated before, this is because first
	269	three blocks of GUID string are in Little Endian.