[PATCH v3 9/9] fastboot: Partition specification

[Sean Anderson <seanga2@gmail.com>]

On 2/1/21 5:30 PM, Heinrich Schuchardt wrote:
> 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@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
> 
> There is a part command. That command should be in doc/usage/part.rst.
> 
> How about doc/usage/partitions.rst?

Ok. Perhaps commands should be in a subdirectory of doc/usage then? This
will help separate general usage documentation from man pages.

> 
> 
>> 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>]

Yes. This will work.

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

Ok.

--Sean

> 
> A reference to the part command might be of interest.
> 
> Best regards
> 
> Heinrich
>