[PATCH 9/9] fastboot: Document alternate partition names

[Sean Anderson]

On 12/31/20 7:36 PM, Heinrich Schuchardt wrote:
> On 12/31/20 11:48 PM, Sean Anderson wrote:
>> This documents the new partition names added in the previous commit.
>>
>> Signed-off-by: Sean Anderson <sean.anderson at seco.com>
>> ---
>>
>>   doc/android/fastboot.rst | 28 ++++++++++++++++++++++++++++
>>   1 file changed, 28 insertions(+)
>>
>> diff --git a/doc/android/fastboot.rst b/doc/android/fastboot.rst
>> index 2877c3cbaa..2ca80ae844 100644
>> --- a/doc/android/fastboot.rst
>> +++ b/doc/android/fastboot.rst
>> @@ -151,6 +151,34 @@ 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.
>>
>> +
>> +Alternate Partition Names
>> +^^^^^^^^^^^^^^^^^^^^^^^^^
>> +
>> +Partitions may also be specified like::
>> +
>> +    devnum.hwpartnum#partname
> 
> Thank you for getting this all documented.
> 
> Don't we need the interface (mmc), too?

No. At the moment only mmc is supported. I suppose I could build in some
forward-compatibility and have something like

     iface,devnum.hwpartnum#partname

It should be relatively easy to extend the MMC code to be block-generic,
but it's out of scope for this series.

> 
>> +
>> +or like::
>> +
>> +    devnum.hwpartnum:partnum
> 
> I think this is the wrong place to document how partitions are addressed
> as it is not Android specific. I would prefer a sub-chapter of doc/usage/.

Sure. Though atm only fastboot and android a/b uses the #partname syntax
as far as I can tell.

--Sean

> 
> Cf.
> https://u-boot.readthedocs.io/en/latest/usage/index.html
> 
> Best regards
> 
> Heinrich
> 
>> +
>> +Where
>> +
>> +  * ``devnum`` is the MMC 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 "partion." Examples of alternate partition names include
>> +``0.1``, ``0#boot``, and ``:3``.
>> +
>>   Writing Partition Table
>>   -----------------------
>>
>>
>