[U-Boot] [PATCH 1/6] gpt:doc: GPT (GUID Partition Table) documentation

[Stephen Warren <swarren@wwwdotorg.org>]

On 08/24/2012 02:13 AM, Lukasz Majewski wrote:
> Documentation of the GPT table format.

> +++ b/doc/README.gpt

> +Glossary:
> +========
> +- UUID -(Universally Unique Identifier)
> +- GUID - (Globally Unique ID)
> +- EFI - (Extensible Firmware Interface)
> +- UEFI - (Unified EFI) - EFI evolution
> +- GPT (GUID Page Table) - it is the EFI standard part

GUID Partition Table, not Page.

> +- partitions - lists of availavle partitions (defined at u-boot):
> +  ./include/configs/{target}.h
> +
> +Introduction:
> +=============
> +This document describes the GPT partition table format when used with u-boot.
> +
> +
> +UUID introduction[5]:
> +====================

What is "[5]"?

> +For instance, GUID of Linux data partition: EBD0A0A2-B9E5-4433-87C0-68B6B72699C7
> +For u-boot GPT hyphens are omitted.

I don't think U-Boot should omit any of the hyphens; it makes the UUIDs
far more readable, and the strings can then be cut/paste to/from other
applications that use/print UUIDs, without any manual conversion.

> +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.
> +
> +However it costs in terms of the computational power and memory footprint.
> +Therefore u-boot uses the crc32 with reading random block (512B) from MMC
> +storage device to generate UUID/GUID.

That doesn't seem particularly relevant to general documentation about
GPT; it's an implementation detail of the GPT creation command in a
later patch, and could easily be changed.

In fact, I wonder why not require the user to concoct UUIDs and pass
them to your GPT creation command, rather than forming them using some
non-standard process.

> +GUID brief explanation:

Not "GUID", but "GPT".

> +======================
> +
> +	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                      |

The indentation looks inconsistent in this diagram

> +		       |                                 |
> +		       -----------------------------------
> +		       |Partition 2                      |
> +		       |                                 |
> +		       -----------------------------------
> +		       |Partition n                      |
> +		       |                                 |

> +       -----------------------------------------------------------
> +       LBA -34         |Entry 1|Entry 2| Entry 3| Entry 4| Secondary
> +       --------------------------------------------------- (bkp)
> +       LBA 34          |Partition 1                      |
> +		       |                                 |
> +		       -----------------------------------
> +		       |Partition 2                      |
> +		       |                                 |
> +		       -----------------------------------
> +		       |Partition n                      |
> +		       |                                 |

That part of the diagram appears duplicated.

> +       -----------------------------------------------------------
> +       LBA -34         |Entry 1|Entry 2| Entry 3| Entry 4| Secondary
> +       --------------------------------------------------- (bkp)
> +       LBA -33         |Entries 5 - 128                  | GPT
> +		       |                                 |
> +		       |                                 |
> +       LBA -2          |                                 |
> +       ---------------------------------------------------
> +       LBA -1          |Secondary GPT Header             |
> +       -----------------------------------------------------------
> +

> +	   Attribute flags (Don't used at u-boot):

I wouldn't write "Don't used at u-boot" since that's potentially subject
to change. For example, I'm expecting to send a patch to use the "Legacy
BIOS bootable" attribute soon.