[v2,2/8] doc: Add gpt command documentation

Adds initial documentation for the gpt command

Signed-off-by: Joshua Watt <JPEWhacker@gmail.com>
---
 doc/usage/cmd/gpt.rst | 139 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 139 insertions(+)
 create mode 100644 doc/usage/cmd/gpt.rst

On Wed, Aug 23, 2023 at 10:47:38AM -0600, Joshua Watt wrote:

> Adds initial documentation for the gpt command
> 
> Signed-off-by: Joshua Watt <JPEWhacker@gmail.com>
> ---
>  doc/usage/cmd/gpt.rst | 139 ++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 139 insertions(+)
>  create mode 100644 doc/usage/cmd/gpt.rst

You need to update the index too so it's included (and doesn't trigger
an error about orphan files).  Please do a 'make htmldocs' to make sure
everything else is clean, thanks.

Hi Joshua,

On Wed, 23 Aug 2023 at 10:48, Joshua Watt <jpewhacker@gmail.com> wrote:
>
> Adds initial documentation for the gpt command
>
> Signed-off-by: Joshua Watt <JPEWhacker@gmail.com>
> ---
>  doc/usage/cmd/gpt.rst | 139 ++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 139 insertions(+)
>  create mode 100644 doc/usage/cmd/gpt.rst
>
> diff --git a/doc/usage/cmd/gpt.rst b/doc/usage/cmd/gpt.rst
> new file mode 100644
> index 0000000000..ea2cf73a60
> --- /dev/null
> +++ b/doc/usage/cmd/gpt.rst
> @@ -0,0 +1,139 @@
> +.. SPDX-License-Identifier: GPL-2.0+
> +
> +gpt command
> +===========
> +
> +Synopsis
> +--------
> +
> +::
> +
> +    gpt repair <interface> <device no>
> +    gpt write <interface> <device no> <partition string>
> +    gpt verify <interface> <device no> <partition string>
> +    gpt setenv <interface> <device no> <partition name>
> +    gpt enumerate <interface> <device no>
> +    gpt guid <interface> <device no> [<varname>]
> +    gpt read <interface> <device no> [<varname>]
> +    gpt swap <interface> <dev> <name1> <name2>
> +    gpt rename <interface> <dev> <part> <name>
> +
> +Description
> +-----------
> +
> +The gpt command lets users read, create, modify, or verify the GPT (GUID
> +Partition Table) partition layout.
> +
> +The syntax of the text description of the partition list is similar to

By 'text description' do you mean '<partition string>' ?

> +the one used by the 'mbr' command.

OK, but I think you need to show the string  as a list of
semicolon-separated components (or whatever) and then describe them.
As written, this is quite confusing.

> +
> +The partition list may start with a set of parameters for the whole disk:
> +
> +* uuid_disk (the UUID of the disk)
> +
> +Following the disk parameters, partitions are specified separated by a ';'.
> +Supported partition parameters are:
> +
> +* name (required)
> +* start (required, partition start offset in bytes)
> +* size (in bytes or '-' to expand it to the whole free area)
> +* bootable (boolean flag)
> +* uuid (partition UUID, optional if CONFIG_RANDOM_UUID=y is enabled)
> +* type (partition type GUID, requires CONFIG_PARTITION_TYPE_GUID=y)
> +
> +Here is an example how to create a 6 partitions, some of the predefined sizes:
> +
> +::
> +
> +    => setenv gpt_parts 'uuid_disk=bec9fc2a-86c1-483d-8a0e-0109732277d7;
> +        name=boot,start=4M,size=128M,bootable,type=EBD0A0A2-B9E5-4433-87C0-68B6B72699C7,
> +        name=rootfs,size=3072M,type=0FC63DAF-8483-4772-8E79-3D69D8477DE4;
> +        name=system-data,size=512M,type=0FC63DAF-8483-4772-8E79-3D69D8477DE4;
> +        name=[ext],size=-,type=0FC63DAF-8483-4772-8E79-3D69D8477DE4;
> +        name=user,size=-,type=0FC63DAF-8483-4772-8E79-3D69D8477DE4;
> +        name=modules,size=100M,type=0FC63DAF-8483-4772-8E79-3D69D8477DE4;
> +        name=ramdisk,size=8M,type=0FC63DAF-8483-4772-8E79-3D69D8477DE4
> +    => gpt write mmc 0 $gpt_parts

Please use lower-case hex

> +
> +
> +If 'uuid' is not specified, but CONFIG_RANDOM_UUID is enabled, a random UUID
> +will be generated for the partition
> +
> +The 'gpt verify' command returns 0 if the layout matches the one on the storage
> +device or 1 if not. To check if the layout on the MMC #0 storage device
> +matches the provided text description one has to issue following command:
> +
> +::
> +
> +    => gpt verify mmc 0 $gpt_parts
> +
> +The verify sub-command is especially useful in the system update scripts:
> +
> +::
> +
> +    => if gpt verify mmc 0 $gpt_parts; then
> +         echo GPT layout needs to be updated
> +         ...
> +       fi
> +
> +The 'gpt write' command returns 0 on success write or 1 on failure.
> +
> +The 'gpt setenv' command will set a series of environment variables with
> +information about a particular partition. The variables are:
> +
> +* gpt_partition_addr (the starting offset of the partition, in hexadecimal blocks)
> +* gpt_partition_size (the size of the partition, in hexadecimal blocks)
> +* gpt_partition_name (the name of the partition)
> +* gpt_partition_entry (the partition number in the table, e.g. 1, 2, 3, etc.)
> +
> +To get the information about the partition named 'rootfs', issue the following
> +command:
> +
> +::
> +    => gpt setenv mmc 0 rootfs
> +    => echo ${gpt_partition_addr}
> +    2000
> +    => echo ${gpt_partition_size}
> +    14a000
> +    => echo ${gpt_partition_name}
> +    rootfs
> +    => echo ${gpt_partition_entry}
> +    2
> +
> +The 'gpt enumerate' command will set the variable 'gpt_partition_list' with the
> +list of partition names on the device. For example:
> +
> +::
> +    => gpt enumerate
> +    => echo gpt_partition_list
> +    boot rootfs system-data [ext] user modules ramdisk
> +
> +The 'gpt guid' command will report the GUID of a disk. If 'varname' is
> +specified, the command will set the variable to the GUID, otherwise it will be
> +printed out. For example:
> +
> +::
> +    => gpt guid mmc 0
> +    bec9fc2a-86c1-483d-8a0e-0109732277d7
> +    => gpt guid mmc gpt_disk_uuid
> +    => echo ${gpt_disk_uuid}
> +    bec9fc2a-86c1-483d-8a0e-0109732277d7
> +
> +The 'gpt read' command will print out the current state of the GPT partition
> +table. If 'varname' is specified, the variable will be filled with a partition
> +string as described above that is suitable for passing to other 'gpt' commands.
> +If omitted, a human readable description is printed out.
> +CONFIG_CMD_GPT_RENAME=y is required.
> +
> +The 'gpt swap' command changes the names of all partitions that are named
> +'name1' to be 'name2', and all partitions named 'name2' to be 'name1'.
> +CONFIG_CMD_GPT_RENAME=y is required.
> +
> +The 'gpt rename' command renames all partitions named 'part' to be 'name1'.
> +CONFIG_CMD_GPT_RENAME=y is required.
> +
> +Configuration
> +-------------
> +
> +To use the 'gpt' command you must specify CONFIG_CMD_GPT=y. To enable 'gpt
> +read', 'gpt swap' and 'gpt rename', you must specify CONFIG_CMD_GPT_RENAME=y.
> --
> 2.33.0
>

Great docs thank you!


- Simon