[PATCH v2 9/9] fastboot: Partition specification

Sean Anderson
2021-01-07T15:21:03Z

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@seco.com>
Reviewed-by: Simon Glass <sjg@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