[PATCH v2 9/9] fastboot: Partition specification

[Sean Anderson]

This documents the way U-Boot understands partitions specifications.
This also updates the fastboot documentation for the changes in the
previous commit.

Signed-off-by: Sean Anderson <sean.anderson at seco.com>
Reviewed-by: Simon Glass <sjg at chromium.org>
---

Changes in v2:
- Move partition documentation under doc/usage

 doc/android/fastboot.rst |  4 ++++
 doc/usage/index.rst      |  1 +
 doc/usage/part.rst       | 33 +++++++++++++++++++++++++++++++++
 3 files changed, 38 insertions(+)
 create mode 100644 doc/usage/part.rst

diff --git a/doc/android/fastboot.rst b/doc/android/fastboot.rst
index 2877c3cbaa..7b6eff82b4 100644
--- a/doc/android/fastboot.rst
+++ b/doc/android/fastboot.rst
@@ -151,6 +151,10 @@ The device index starts from ``a`` and refers to the interface (e.g. USB
 controller, SD/MMC controller) or disk index. The partition index starts
 from ``1`` and describes the partition number on the particular device.
 
+Alternatively, partition types may be specified using :ref:`U-Boot's partition
+syntax <partitions>`. This allows specifying partitions like ``0.1``,
+``0#boot``, or ``:3``. The interface is always ``mmc``.
+
 Writing Partition Table
 -----------------------
 
diff --git a/doc/usage/index.rst b/doc/usage/index.rst
index fbb2c0481c..a22ace03e8 100644
--- a/doc/usage/index.rst
+++ b/doc/usage/index.rst
@@ -4,6 +4,7 @@ Use U-Boot
 .. toctree::
 
    netconsole
+   part
 
 Shell commands
 --------------
diff --git a/doc/usage/part.rst b/doc/usage/part.rst
new file mode 100644
index 0000000000..e58b529147
--- /dev/null
+++ b/doc/usage/part.rst
@@ -0,0 +1,33 @@
+.. SPDX-License-Identifier: GPL-2.0+
+.. _partitions:
+
+Partitions
+==========
+
+Many U-Boot commands allow specifying partitions like::
+
+    some_command <interface> <devnum.hwpartnum:partnum>
+
+or like::
+
+    some_command <interface> <devnum.hwpartnum#partname
+
+Where
+
+  * ``interface`` is the device interface, like ``mmc`` or ``scsi``. For a full
+    list of supported interfaces, consult the ``if_typename_str`` array in
+    ``drivers/block/blk-uclass.c``
+  * ``devnum`` is the device number. This defaults to 0.
+  * ``hwpartnum`` is the hardware partition number. This defaults to 0 (the user
+    partition on eMMC devices).
+  * ``partname`` is the partition name on GPT devices. Partitions do not have
+    names on MBR devices.
+  * ``partnum`` is the partition number, starting from 1. The partition number 0
+    is special, and specifies that the whole device is to be used as one
+    "partition."
+
+If neither ``partname`` nor ``partnum`` is specified and there is a partition
+table, then partition 1 is used. If there is no partition table, then the whole
+device is used as one "partition." If none of ``devnum``, ``hwpartnum``,
+``partnum``, or ``partname`` is specified, then ``devnum`` defaults to the value
+of the ``bootdevice`` environmental variable.
-- 
2.25.1