diff options
Diffstat (limited to 'roms/u-boot/doc/README.gpt')
| -rw-r--r-- | roms/u-boot/doc/README.gpt | 315 |
1 files changed, 315 insertions, 0 deletions
diff --git a/roms/u-boot/doc/README.gpt b/roms/u-boot/doc/README.gpt new file mode 100644 index 000000000..91e397d06 --- /dev/null +++ b/roms/u-boot/doc/README.gpt @@ -0,0 +1,315 @@ +# 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/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 + +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', a optionnal 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. |