[PATCH v5 2/8] doc: Add gpt command documentation

[Joshua Watt <jpewhacker@gmail.com>]

Adds initial documentation for the gpt command

Signed-off-by: Joshua Watt <JPEWhacker@gmail.com>
---
 doc/usage/cmd/gpt.rst | 184 ++++++++++++++++++++++++++++++++++++++++++
 doc/usage/index.rst   |   1 +
 2 files changed, 185 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..6387c8116f
--- /dev/null
+++ b/doc/usage/cmd/gpt.rst
@@ -0,0 +1,184 @@
+.. SPDX-License-Identifier: GPL-2.0+
+
+gpt command
+===========
+
+Synopsis
+--------
+
+::
+
+    gpt enumerate <interface> <dev>
+    gpt guid <interface> <dev> [<varname>]
+    gpt read <interface> <dev> [<varname>]
+    gpt rename <interface> <dev> <part> <name>
+    gpt repair <interface> <dev>
+    gpt setenv <interface> <dev> <partition name>
+    gpt swap <interface> <dev> <name1> <name2>
+    gpt verify <interface> <dev> [<partition string>]
+    gpt write <interface> <dev> <partition string>
+
+Description
+-----------
+
+The gpt command lets users read, create, modify, or verify the GPT (GUID
+Partition Table) partition layout.
+
+Common arguments:
+
+interface
+    interface for accessing the block device (mmc, sata, scsi, usb, ....)
+
+dev
+    device number
+
+partition string
+    Describes the GPT partition layout for a disk.  The syntax is similar to
+    the one used by the :doc:`mbr command <mbr>` command. The string contains
+    one or more partition descriptors, each separated by a ";". Each descriptor
+    contains one or more fields, with each field separated by a ",". Fields are
+    either of the form "key=value" to set a specific value, or simple "flag" to
+    set a boolean flag
+
+    The first descriptor can optionally be used to describe parameters for the
+    whole disk with the following fields:
+
+    * uuid_disk=UUID - Set the UUID for the disk
+
+    Partition descriptors can have the following fields:
+
+    * name=<NAME> - The partition name, required
+    * start=<BYTES> - The partition start offset in bytes, required
+    * size=<BYTES> - The partition size in bytes or "-" to expand it to the whole free area
+    * bootable - Set the legacy bootable flag
+    * uuid=<UUID> - The partition UUID, optional if CONFIG_RANDOM_UUID=y is enabled
+    * type=<UUID> - The partition type GUID, requires CONFIG_PARTITION_TYPE_GUID=y
+
+
+    If 'uuid' is not specified, but CONFIG_RANDOM_UUID is enabled, a random UUID
+    will be generated for the partition
+
+gpt enumerate
+~~~~~~~~~~~~~
+
+Sets the variable 'gpt_partition_list' to be a list of all the partition names
+on the device.
+
+gpt guid
+~~~~~~~~
+
+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.
+
+gpt read
+~~~~~~~~
+
+Prints the current state of the GPT partition table. If 'varname' is specified,
+the variable will be filled with a partition string in the same format as a
+'<partition string>', suitable for passing to other 'gpt' commands.  If the
+argument is omitted, a human readable description is printed out.
+CONFIG_CMD_GPT_RENAME=y is required.
+
+gpt rename
+~~~~~~~~~~
+
+Renames all partitions named 'part' to be 'name'. CONFIG_CMD_GPT_RENAME=y is
+required.
+
+gpt repair
+~~~~~~~~~~
+
+Repairs the GPT partition tables if it they become corrupted.
+
+gpt setenv
+~~~~~~~~~~
+
+The 'gpt setenv' command will set a series of environment variables with
+information about the partition named '<partition name>'. The variables are:
+
+gpt_partition_addr
+    the starting offset of the partition in blocks as a hexadecimal number
+
+gpt_partition_size
+    the size of the partition in blocks as a hexadecimal number
+
+gpt_partition_name
+    the name of the partition
+
+gpt_partition_entry
+    the partition number in the table, e.g. 1, 2, 3, etc.
+
+gpt swap
+~~~~~~~~
+
+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.
+
+gpt verify
+~~~~~~~~~~
+
+Sets return value $? to 0 (true) if the partition layout on the
+specified disk matches the one in the provided partition string, and 1 (false)
+if it does not match. If no partition string is specified, the command will
+check if the disk is partitioned or not.
+
+gpt write
+~~~~~~~~~
+
+(Re)writes the partition table on the disk to match the provided
+partition string. It returns 0 on success or 1 on failure.
+
+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.
+
+Examples
+~~~~~~~~
+Create 6 partitions on a disk::
+
+    => 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
+
+
+Verify that the device matches the partition layout described in the variable
+$gpt_parts::
+
+    => gpt verify mmc 0 $gpt_parts
+
+
+Get the information about the partition named 'rootfs'::
+
+    => 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
+
+Get the list of partition names on the disk::
+
+    => gpt enumerate
+    => echo gpt_partition_list
+    boot rootfs system-data [ext] user modules ramdisk
+
+
+Get the GUID for a disk::
+
+    => gpt guid mmc 0
+    bec9fc2a-86c1-483d-8a0e-0109732277d7
+    => gpt guid mmc gpt_disk_uuid
+    => echo ${gpt_disk_uuid}
+    bec9fc2a-86c1-483d-8a0e-0109732277d7
diff --git a/doc/usage/index.rst b/doc/usage/index.rst
index f45a7f5502..fa702920fa 100644
--- a/doc/usage/index.rst
+++ b/doc/usage/index.rst
@@ -66,6 +66,7 @@ Shell commands
    cmd/for
    cmd/fwu_mdata
    cmd/gpio
+   cmd/gpt
    cmd/host
    cmd/imxtract
    cmd/load
-- 
2.34.1