From mboxrd@z Thu Jan  1 00:00:00 1970
From: Sean Anderson <sean.anderson@seco.com>
Date: Mon, 1 Feb 2021 11:43:40 -0500
Subject: [PATCH v3 9/9] fastboot: Partition specification
In-Reply-To: <2660a65f-8783-06ed-fe93-2d638ce3a842@seco.com>
References: <2660a65f-8783-06ed-fe93-2d638ce3a842@seco.com>
Message-ID: <0a8c9702-786e-1166-f5b0-d20677647619@seco.com>
List-Id: <u-boot.lists.denx.de>
MIME-Version: 1.0
Content-Type: text/plain; charset="us-ascii"
Content-Transfer-Encoding: 7bit
To: u-boot@lists.denx.de

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 v3:
- Rebase onto dfu/master

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 16b11399b3..ce513a2a0f 100644
--- a/doc/android/fastboot.rst
+++ b/doc/android/fastboot.rst
@@ -154,6 +154,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 83cfbafd90..9b64434cb2 100644
--- a/doc/usage/index.rst
+++ b/doc/usage/index.rst
@@ -6,6 +6,7 @@ Use U-Boot
  
     fdt_overlays
     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.29.2