mirror of
https://github.com/AsahiLinux/u-boot
synced 2024-12-15 15:53:02 +00:00
5ef229a007
Commit 37c5195dfc ("doc: Move distro boot doc to rST") renamed
doc/README.distro to doc/develop/distro.rst.
Signed-off-by: Dario Binacchi <dario.binacchi@amarulasolutions.com>
Reviewed-by: Patrice Chotard <patrice.chotard@foss.st.com>
Reviewed-by: Soeren Moch <smoch@web.de>
Reviewed-by: Patrick Delaunay <patrick.delaunay@foss.st.com>
315 lines
12 KiB
Text
315 lines
12 KiB
Text
# SPDX-License-Identifier: GPL-2.0+
|
|
#
|
|
# Copyright (C) 2012 Samsung Electronics
|
|
#
|
|
# Lukasz Majewski <l.majewski@samsung.com>
|
|
|
|
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:
|
|
"uuid_disk=...;name=u-boot,size=60MiB,uuid=...;
|
|
name=kernel,size=60MiB,uuid=...;"
|
|
or
|
|
"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 'gpt guid' command reads the current value of the
|
|
uuid_disk from the GPT.
|
|
|
|
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/develop/distro.rst 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
|
|
|
|
Renaming GPT partitions from U-Boot:
|
|
====================================
|
|
|
|
GPT partition names are a mechanism via which userspace and U-Boot can
|
|
communicate about software updates and boot failure. The 'gpt guid',
|
|
'gpt read', 'gpt rename' and 'gpt swap' commands facilitate
|
|
programmatic renaming of partitions from bootscripts by generating and
|
|
modifying the partitions layout string. Here is an illustration of
|
|
employing 'swap' to exchange 'primary' and 'backup' partition names:
|
|
|
|
U-BOOT> gpt swap mmc 0 primary backup
|
|
|
|
Afterwards, all partitions previously named 'primary' will be named
|
|
'backup', and vice-versa. Alternatively, single partitions may be
|
|
renamed. In this example, mmc0's first partition will be renamed
|
|
'primary':
|
|
|
|
U-BOOT> gpt rename mmc 0 1 primary
|
|
|
|
The GPT functionality may be tested with the 'sandbox' board by
|
|
creating a disk image as described under 'Block Device Emulation' in
|
|
doc/arch/index.rst:
|
|
|
|
=>host bind 0 ./disk.raw
|
|
=> gpt read host 0
|
|
[ . . . ]
|
|
=> gpt swap host 0 name othername
|
|
[ . . . ]
|
|
|
|
Modifying GPT partition layout from U-Boot:
|
|
===========================================
|
|
|
|
The entire GPT partition layout can be exported to an environment
|
|
variable and then modified enmasse. Users can change the partition
|
|
numbers, offsets, names and sizes. The resulting variable can used to
|
|
reformat the device. Here is an example of reading the GPT partitions
|
|
into a variable and then modifying them:
|
|
|
|
U-BOOT> gpt read mmc 0 current_partitions
|
|
U-BOOT> env edit current_partitions
|
|
edit: uuid_disk=[...];name=part1,start=0x4000,size=0x4000,uuid=[...];
|
|
name=part2,start=0xc000,size=0xc000,uuid=[...];[ . . . ]
|
|
|
|
U-BOOT> gpt write mmc 0 $current_partitions
|
|
U-BOOT> gpt verify mmc 0 $current_partitions
|
|
|
|
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', an optional parameter 'type'
|
|
can specify a other partition type guid:
|
|
|
|
"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)
|
|
"u-boot-env" = PARTITION_U_BOOT_ENVIRONMENT
|
|
(3DE21764-95BD-54BD-A5C3-4ABE786F38A8)
|
|
|
|
"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.
|