[PATCH v3 9/9] fastboot: Partition specification

[Heinrich Schuchardt]

On 01.02.21 17:43, Sean Anderson wrote:
> 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 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

There is a part command. That command should be in doc/usage/part.rst.

How about doc/usage/partitions.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

From the above it is not clear what is optional and what can go together.

Is this what you meant:

::

   <command> <interface> <devnum>[.<hwpartnum>][:<partnum>|#<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

Could you, please, use a text form like:

interface
    the device interface like mmc or scsi ...

devnum
    the device number ...

to match our existing man-pages.

Here interface and devnum will automatically be rendered in bold without
adding disturbing mark-up. Cf.
https://u-boot.readthedocs.io/en/latest/usage/for.html


> (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.

Please, add examples with their interpretation.

A reference to the part command might be of interest.

Best regards

Heinrich