README.gpt 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296
  1. # SPDX-License-Identifier: GPL-2.0+
  2. #
  3. # Copyright (C) 2012 Samsung Electronics
  4. #
  5. # Lukasz Majewski <l.majewski@samsung.com>
  6. Glossary:
  7. ========
  8. - UUID -(Universally Unique Identifier)
  9. - GUID - (Globally Unique ID)
  10. - EFI - (Extensible Firmware Interface)
  11. - UEFI - (Unified EFI) - EFI evolution
  12. - GPT (GUID Partition Table) - it is the EFI standard part
  13. - partitions - lists of available partitions (defined at u-boot):
  14. ./include/configs/{target}.h
  15. Introduction:
  16. =============
  17. This document describes the GPT partition table format and usage of
  18. the gpt command in u-boot.
  19. UUID introduction:
  20. ====================
  21. GPT for marking disks/partitions is using the UUID. It is supposed to be a
  22. globally unique value. A UUID is a 16-byte (128-bit) number. The number of
  23. theoretically possible UUIDs is therefore about 3 x 10^38.
  24. More often UUID is displayed as 32 hexadecimal digits, in 5 groups,
  25. separated by hyphens, in the form 8-4-4-4-12 for a total of 36 characters
  26. (32 digits and 4 hyphens)
  27. For instance, GUID of Basic data partition: EBD0A0A2-B9E5-4433-87C0-68B6B72699C7
  28. and GUID of Linux filesystem data: 0FC63DAF-8483-4772-8E79-3D69D8477DE4
  29. Historically there are 5 methods to generate this number. The oldest one is
  30. combining machine's MAC address and timer (epoch) value.
  31. Successive versions are using MD5 hash, random numbers and SHA-1 hash. All major
  32. OSes and programming languages are providing libraries to compute UUID (e.g.
  33. uuid command line tool).
  34. GPT brief explanation:
  35. ======================
  36. Layout:
  37. -------
  38. --------------------------------------------------
  39. LBA 0 |Protective MBR |
  40. ----------------------------------------------------------
  41. LBA 1 |Primary GPT Header | Primary
  42. -------------------------------------------------- GPT
  43. LBA 2 |Entry 1|Entry 2| Entry 3| Entry 4|
  44. --------------------------------------------------
  45. LBA 3 |Entries 5 - 128 |
  46. | |
  47. | |
  48. ----------------------------------------------------------
  49. LBA 34 |Partition 1 |
  50. | |
  51. -----------------------------------
  52. |Partition 2 |
  53. | |
  54. -----------------------------------
  55. |Partition n |
  56. | |
  57. ----------------------------------------------------------
  58. LBA -34 |Entry 1|Entry 2| Entry 3| Entry 4| Backup
  59. -------------------------------------------------- GPT
  60. LBA -33 |Entries 5 - 128 |
  61. | |
  62. | |
  63. LBA -2 | |
  64. --------------------------------------------------
  65. LBA -1 |Backup GPT Header |
  66. ----------------------------------------------------------
  67. For a legacy reasons, GPT's LBA 0 sector has a MBR structure. It is called
  68. "protective MBR".
  69. Its first partition entry ID has 0xEE value, and disk software, which is not
  70. handling the GPT sees it as a storage device without free space.
  71. It is possible to define 128 linearly placed partition entries.
  72. "LBA -1" means the last addressable block (in the mmc subsystem:
  73. "dev_desc->lba - 1")
  74. Primary/Backup GPT header:
  75. ----------------------------
  76. Offset Size Description
  77. 0 8 B Signature ("EFI PART", 45 46 49 20 50 41 52 54)
  78. 8 4 B Revision (For version 1.0, the value is 00 00 01 00)
  79. 12 4 B Header size (in bytes, usually 5C 00 00 00 meaning 92 bytes)
  80. 16 4 B CRC32 of header (0 to header size), with this field zeroed
  81. during calculation
  82. 20 4 B Reserved (ZERO);
  83. 24 8 B Current LBA (location of this header copy)
  84. 32 8 B Backup LBA (location of the other header copy)
  85. 40 8 B First usable LBA for partitions (primary partition table last
  86. LBA + 1)
  87. 48 8 B Last usable LBA (secondary partition table first LBA - 1)
  88. 56 16 B Disk GUID (also referred as UUID on UNIXes)
  89. 72 8 B Partition entries starting LBA (always 2 in primary copy)
  90. 80 4 B Number of partition entries
  91. 84 4 B Size of a partition entry (usually 128)
  92. 88 4 B CRC32 of partition array
  93. 92 * Reserved; must be ZERO (420 bytes for a 512-byte LBA)
  94. TOTAL: 512 B
  95. IMPORTANT:
  96. GPT headers and partition entries are protected by CRC32 (the POSIX CRC32).
  97. Primary GPT header and Backup GPT header have swapped values of "Current LBA"
  98. and "Backup LBA" and therefore different CRC32 check-sum.
  99. CRC32 for GPT headers (field "CRC of header") are calculated up till
  100. "Header size" (92), NOT 512 bytes.
  101. CRC32 for partition entries (field "CRC32 of partition array") is calculated for
  102. the whole array entry ( Number_of_partition_entries *
  103. sizeof(partition_entry_size (usually 128)))
  104. Observe, how Backup GPT is placed in the memory. It is NOT a mirror reflect
  105. of the Primary.
  106. Partition Entry Format:
  107. ----------------------
  108. Offset Size Description
  109. 0 16 B Partition type GUID (Big Endian)
  110. 16 16 B Unique partition GUID in (Big Endian)
  111. 32 8 B First LBA (Little Endian)
  112. 40 8 B Last LBA (inclusive)
  113. 48 8 B Attribute flags [+]
  114. 56 72 B Partition name (text)
  115. Attribute flags:
  116. Bit 0 - System partition
  117. Bit 1 - Hide from EFI
  118. Bit 2 - Legacy BIOS bootable
  119. Bit 48-63 - Defined and used by the individual partition type
  120. For Basic data partition :
  121. Bit 60 - Read-only
  122. Bit 62 - Hidden
  123. Bit 63 - Not mount
  124. Creating GPT partitions in U-Boot:
  125. ==============
  126. To restore GUID partition table one needs to:
  127. 1. Define partition layout in the environment.
  128. Format of partitions layout:
  129. "uuid_disk=...;name=u-boot,size=60MiB,uuid=...;
  130. name=kernel,size=60MiB,uuid=...;"
  131. or
  132. "uuid_disk=${uuid_gpt_disk};name=${uboot_name},
  133. size=${uboot_size},uuid=${uboot_uuid};"
  134. The fields 'name' and 'size' are mandatory for every partition.
  135. The field 'start' is optional.
  136. If field 'size' of the last partition is 0, the partition is extended
  137. up to the end of the device.
  138. The fields 'uuid' and 'uuid_disk' are optional if CONFIG_RANDOM_UUID is
  139. enabled. A random uuid will be used if omitted or they point to an empty/
  140. non-existent environment variable. The environment variable will be set to
  141. the generated UUID. The 'gpt guid' command reads the current value of the
  142. uuid_disk from the GPT.
  143. The field 'bootable' is optional, it is used to mark the GPT partition
  144. bootable (set attribute flags "Legacy BIOS bootable").
  145. "name=u-boot,size=60MiB;name=boot,size=60Mib,bootable;name=rootfs,size=0"
  146. It can be used to locate bootable disks with command
  147. "part list <interface> <dev> -bootable <varname>",
  148. please check out doc/README.distro for use.
  149. 2. Define 'CONFIG_EFI_PARTITION' and 'CONFIG_CMD_GPT'
  150. 3. From u-boot prompt type:
  151. gpt write mmc 0 $partitions
  152. Checking (validating) GPT partitions in U-Boot:
  153. ===============================================
  154. Procedure is the same as above. The only change is at point 3.
  155. At u-boot prompt one needs to write:
  156. gpt verify mmc 0 [$partitions]
  157. where [$partitions] is an optional parameter.
  158. When it is not provided, only basic checks based on CRC32 calculation for GPT
  159. header and PTEs are performed.
  160. When provided, additionally partition data - name, size and starting
  161. offset (last two in LBA) - are compared with data defined in '$partitions'
  162. environment variable.
  163. After running this command, return code is set to 0 if no errors found in
  164. on non-volatile medium stored GPT.
  165. Following line can be used to assess if GPT verification has succeed:
  166. U-BOOT> gpt verify mmc 0 $partitions
  167. U-BOOT> if test $? = 0; then echo "GPT OK"; else echo "GPT ERR"; fi
  168. Renaming GPT partitions from U-Boot:
  169. ====================================
  170. GPT partition names are a mechanism via which userspace and U-Boot can
  171. communicate about software updates and boot failure. The 'gpt guid',
  172. 'gpt read', 'gpt rename' and 'gpt swap' commands facilitate
  173. programmatic renaming of partitions from bootscripts by generating and
  174. modifying the partitions layout string. Here is an illustration of
  175. employing 'swap' to exchange 'primary' and 'backup' partition names:
  176. U-BOOT> gpt swap mmc 0 primary backup
  177. Afterwards, all partitions previously named 'primary' will be named
  178. 'backup', and vice-versa. Alternatively, single partitions may be
  179. renamed. In this example, mmc0's first partition will be renamed
  180. 'primary':
  181. U-BOOT> gpt rename mmc 0 1 primary
  182. The GPT functionality may be tested with the 'sandbox' board by
  183. creating a disk image as described under 'Block Device Emulation' in
  184. doc/arch/index.rst:
  185. =>host bind 0 ./disk.raw
  186. => gpt read host 0
  187. [ . . . ]
  188. => gpt swap host 0 name othername
  189. [ . . . ]
  190. Partition type GUID:
  191. ====================
  192. For created partition, the used partition type GUID is
  193. PARTITION_BASIC_DATA_GUID (EBD0A0A2-B9E5-4433-87C0-68B6B72699C7).
  194. If you define 'CONFIG_PARTITION_TYPE_GUID', a optionnal parameter 'type'
  195. can specify a other partition type guid:
  196. "uuid_disk=...;name=u-boot,size=60MiB,uuid=...;
  197. name=kernel,size=60MiB,uuid=...,
  198. type=0FC63DAF-8483-4772-8E79-3D69D8477DE4;"
  199. Some strings can be also used at the place of known GUID :
  200. "system" = PARTITION_SYSTEM_GUID
  201. (C12A7328-F81F-11D2-BA4B-00A0C93EC93B)
  202. "mbr" = LEGACY_MBR_PARTITION_GUID
  203. (024DEE41-33E7-11D3-9D69-0008C781F39F)
  204. "msft" = PARTITION_MSFT_RESERVED_GUID
  205. (E3C9E316-0B5C-4DB8-817D-F92DF00215AE)
  206. "data" = PARTITION_BASIC_DATA_GUID
  207. (EBD0A0A2-B9E5-4433-87C0-68B6B72699C7)
  208. "linux" = PARTITION_LINUX_FILE_SYSTEM_DATA_GUID
  209. (0FC63DAF-8483-4772-8E79-3D69D8477DE4)
  210. "raid" = PARTITION_LINUX_RAID_GUID
  211. (A19D880F-05FC-4D3B-A006-743F0F84911E)
  212. "swap" = PARTITION_LINUX_SWAP_GUID
  213. (0657FD6D-A4AB-43C4-84E5-0933C84B4F4F)
  214. "lvm" = PARTITION_LINUX_LVM_GUID
  215. (E6D6D379-F507-44C2-A23C-238F2A3DF928)
  216. "uuid_disk=...;name=u-boot,size=60MiB,uuid=...;
  217. name=kernel,size=60MiB,uuid=...,type=linux;"
  218. They are also used to display the type of partition in "part list" command.
  219. Useful info:
  220. ============
  221. Two programs, namely: 'gdisk' and 'parted' are recommended to work with GPT
  222. recovery. Both are able to handle GUID partitions.
  223. Please, pay attention at -l switch for parted.
  224. "uuid" program is recommended to generate UUID string. Moreover it can decode
  225. (-d switch) passed in UUID string. It can be used to generate partitions UUID
  226. passed to u-boot environment variables.
  227. If optional CONFIG_RANDOM_UUID is defined then for any partition which environment
  228. uuid is unset, uuid is randomly generated and stored in correspond environment
  229. variable.
  230. note:
  231. Each string block of UUID generated by program "uuid" is in big endian and it is
  232. also stored in big endian in disk GPT.
  233. Partitions layout can be printed by typing "mmc part". Note that each partition
  234. GUID has different byte order than UUID generated before, this is because first
  235. three blocks of GUID string are in Little Endian.