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

Joshua Watt
2023-08-25T19:38:57Z

Adds initial documentation for the gpt command

Signed-off-by: Joshua Watt <JPEWhacker@gmail.com>
---
doc/usage/cmd/gpt.rst | 141 ++++++++++++++++++++++++++++++++++++++++++
doc/usage/index.rst | 1 +
2 files changed, 142 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..f6e082fb94
--- /dev/null
+++ b/doc/usage/cmd/gpt.rst
@@ -0,0 +1,141 @@
+.. 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
+the one used by the '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 - Set the partition UUID, optional if CONFIG_RANDOM_UUID=y is enabled
+* type=UUID - Set the 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
+
+
+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.
diff --git a/doc/usage/index.rst b/doc/usage/index.rst
index 3326ec82ff..4bfaabbd16 100644
--- a/doc/usage/index.rst
+++ b/doc/usage/index.rst
@@ -65,6 +65,7 @@ Shell commands
cmd/for
cmd/fwu_mdata
cmd/gpio
+ cmd/gpt
cmd/host
cmd/imxtract
cmd/load
--
2.33.0