[RFC] doc: mmc man-page

Provide a man-pages for the mmc command.

Signed-off-by: Jaehoon Chung <jh80.chung@samsung.com>
---
 doc/usage/mmc.rst | 149 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 149 insertions(+)
 create mode 100644 doc/usage/mmc.rst

On 2/26/21 11:01 AM, Jaehoon Chung wrote:
> Provide a man-pages for the mmc command.
>
> Signed-off-by: Jaehoon Chung <jh80.chung@samsung.com>
> ---
>   doc/usage/mmc.rst | 149 ++++++++++++++++++++++++++++++++++++++++++++++

Thanks a lot for providing a man-page for the mmc command.

You have to change doc/usage/index.rst too.

>   1 file changed, 149 insertions(+)
>   create mode 100644 doc/usage/mmc.rst
>
> diff --git a/doc/usage/mmc.rst b/doc/usage/mmc.rst
> new file mode 100644
> index 000000000000..30fee447d409
> --- /dev/null
> +++ b/doc/usage/mmc.rst
> @@ -0,0 +1,149 @@
> +.. SPDX-License-Identifier: GPL-2.0+:
> +
> +mmc command
> +============
> +
> +Synopsis
> +--------
> +
> +::
> +
> +    mmc info
> +    mmc read addr blk# cnt
> +    mmc write addr blk# cnt
> +    mmc erase blk# cnt
> +    mmc rescan
> +    mmc part
> +    mmc dev [dev] [part]
> +    mmc list
> +    mmc wp
> +    mmc bootbus <dev> <boot_bus_width> <reset_boot_bus_width> <boot_mode>
> +    mmc bootpart-resize <dev> <dev part size MB> <RPMB part size MB>
> +    mmc partconf <dev> [boot_ack boot_partition partition_access]

This sub-command is missing below.

> +    mmc rst-function <dev> <value>
> +
> +Description
> +-----------
> +
> +The mmc command is used to control MMC(eMMC/SD) device

Please, add missing full stops '.'.

> +
> +The *mmc info* displays information (Manufacturer ID, OEM, Name, Bus Speed, Mode, ...) of MMC device
> +
> +The *mmc read* command reads raw data to memory address from MMC device with block offset and count
> +
> +The *mmc write* write raw data to MMC device from memory address with block offset and count
> +    addr - memory address

Please format arguments like this:

addr
	memory address

You can check the formatting using 'make htmldocs'.

> +
> +    blk# - start block offset
> +
> +    cnt - block count
> +
> +The *mmc erase* erases MMC device from block offset until count
> +    blk# - start block offset
> +
> +    cnt - block count
> +
> +The *mmc rescan* scans the available MMC device
> +
> +The *mmc part* displays the list available partition on current mmc device
> +
> +The *mmc dev* show or set current mmc device
> +    [dev]

Please, remove the brackets.

> +        device number to change
> +    [part]
> +        partition number to change
> +
> +The *mmc list* displays the list avaiable devices

The *mmc list* command ...

> +
> +The *mmc wp* enables "power on write protect" function about boot partitions

The *mmc wp* command ...

%s/about/for/

Please, mention that power cycling is needed to lift the write protection.

> +
> +The *mmc bootbus* sets the BOOT_BUS_WIDTH feild

The *mmc bootbus* command ...

%s/feild/field/

> +    BOOTU_BUS_WIDTH[177] is one of EXT_CSD register. (*Refer to eMMC specification*)
> +
> +The *mmc-bootpart-resize* changes sizes of boot and RPMB partition

partitions.

> +    dev - device number
> +
> +    boot part size MB - Size to change boot partition

How about:

target size of boot partition

> +
> +    RPMB part size MB - Size to chagne RPMB partition

%s/chagne/change/

target size of RPMB partition

> +
> +The *mmc rst-function* change the RST_n_FUNCTION filed

field?

I think we should describe what a RST_n_FUNCTION is.

We should enumerate the allowable values. The eMMC specification (JEDEC
Standard No. 84-B51, 2014) has:

0x0: RST_n signal is temporarily disabled (default)
0x1: RST_n signal is permanently enabled
0x2: RST_n signal is permanently disabled

> +    **WARNING**: This is a write-once filed. (*Refer to eMMC specification*)

%s/filed/field/

> +
> +Example
> +-------
> +
> +The *mmc info* command displays device's capabilities:
> +::
> +
> +    => mmc info
> +    Device: EXYNOS DWMMC
> +    Manufacturer ID: 45
> +    OEM: 100
> +    Name: SDW16
> +    Bus Speed: 52000000
> +    Mode: MMC DDR52 (52MHz)
> +    Rd Block Len: 512
> +    MMC version 5.0
> +    High Capacity: Yes
> +    Capacity: 14.7 GiB
> +    Bus Width: 8-bit DDR
> +    Erase Group Size: 512 KiB
> +    HC WP Group Size: 8 MiB
> +    User Capacity: 14.7 GiB WRREL
> +    Boot Capacity: 4 MiB ENH
> +    RPMB Capacity: 4 MiB ENH
> +    Boot area 0 is not write protected
> +    Boot area 1 is not write protected
> +
> +The raw data can be read/written via *mmc read/write* command:
> +::
> +
> +    => mmc read 0x40000000 0x5000 0x100
> +    MMC read: dev # 0, block # 20480, count 256 ... 256 blocks read: OK
> +
> +    => mmc write 0x40000000 0x5000 0x10
> +    MMC write: dev # 0, block # 20480, count 256 ... 256 blocks written: OK
> +
> +The partition list can be shown via *mmc part* command:
> +::
> +
> +    => mmc part
> +    Partition Map for MMC device 0  --   Partition Type: DOS
> +
> +    Part    Start Sector    Num Sectors     UUID            Type
> +      1     8192            131072          dff8751a-01     0e Boot
> +      2     139264          6291456         dff8751a-02     83
> +      3     6430720         1048576         dff8751a-03     83
> +      4     7479296         23298048        dff8751a-04     05 Extd
> +      5     7481344         307200          dff8751a-05     83
> +      6     7790592         65536           dff8751a-06     83
> +      7     7858176         16384           dff8751a-07     83
> +      8     7876608         22900736        dff8751a-08     83
> +
> +The current device can be shown or set via *mmc dev* command:
> +::
> +
> +    => mmc dev
> +    switch to partitions #0, OK
> +    mmc0(part0) is current device
> +    => mmc dev 2 0
> +    switch to partitions #0, OK
> +    mmc2 is current device
> +
> +The list of available devices can be shown via *mmc list* command:
> +::
> +
> +    => mmc list
> +    mmc list
> +    EXYNOS DWMMC: 0 (eMMC)
> +    EXYNOS DWMMC: 2 (SD)
> +
> +Configuration
> +-------------
> +
> +The mmc command is only avaialble if CONFIG_CMD_MMC=y.
> +Some commands need to enable more configuration.

Some sub-command need require further configuration:

> +
> +* write / erase - CONFIG_MMC_WRITE

write, erase
	CONFIG_MMC_WRITE=y

> +* bootbus - CONFIG_SUPPORT_EMMC_BOOT=y
>

Best regards

Heinrich

Hi Heinrich,

On 2/26/21 7:32 PM, Heinrich Schuchardt wrote:
> On 2/26/21 11:01 AM, Jaehoon Chung wrote:
>> Provide a man-pages for the mmc command.
>>
>> Signed-off-by: Jaehoon Chung <jh80.chung@samsung.com>
>> ---
>>   doc/usage/mmc.rst | 149 ++++++++++++++++++++++++++++++++++++++++++++++
> 
> Thanks a lot for providing a man-page for the mmc command.
> 
> You have to change doc/usage/index.rst too.

Thanks for reviewing.

> 
>>   1 file changed, 149 insertions(+)
>>   create mode 100644 doc/usage/mmc.rst
>>
>> diff --git a/doc/usage/mmc.rst b/doc/usage/mmc.rst
>> new file mode 100644
>> index 000000000000..30fee447d409
>> --- /dev/null
>> +++ b/doc/usage/mmc.rst
>> @@ -0,0 +1,149 @@
>> +.. SPDX-License-Identifier: GPL-2.0+:
>> +
>> +mmc command
>> +============
>> +
>> +Synopsis
>> +--------
>> +
>> +::
>> +
>> +    mmc info
>> +    mmc read addr blk# cnt
>> +    mmc write addr blk# cnt
>> +    mmc erase blk# cnt
>> +    mmc rescan
>> +    mmc part
>> +    mmc dev [dev] [part]
>> +    mmc list
>> +    mmc wp
>> +    mmc bootbus <dev> <boot_bus_width> <reset_boot_bus_width> <boot_mode>
>> +    mmc bootpart-resize <dev> <dev part size MB> <RPMB part size MB>
>> +    mmc partconf <dev> [boot_ack boot_partition partition_access]
> 
> This sub-command is missing below.
> 
>> +    mmc rst-function <dev> <value>
>> +
>> +Description
>> +-----------
>> +
>> +The mmc command is used to control MMC(eMMC/SD) device
> 
> Please, add missing full stops '.'.

Okay.

> 
>> +
>> +The *mmc info* displays information (Manufacturer ID, OEM, Name, Bus Speed, Mode, ...) of MMC device
>> +
>> +The *mmc read* command reads raw data to memory address from MMC device with block offset and count
>> +
>> +The *mmc write* write raw data to MMC device from memory address with block offset and count
>> +    addr - memory address
> 
> Please format arguments like this:
> 
> addr
>     memory address
> 
> You can check the formatting using 'make htmldocs'.

Okay. I will check with 'make htmldocs'

> 
>> +
>> +    blk# - start block offset
>> +
>> +    cnt - block count
>> +
>> +The *mmc erase* erases MMC device from block offset until count
>> +    blk# - start block offset
>> +
>> +    cnt - block count
>> +
>> +The *mmc rescan* scans the available MMC device
>> +
>> +The *mmc part* displays the list available partition on current mmc device
>> +
>> +The *mmc dev* show or set current mmc device
>> +    [dev]
> 
> Please, remove the brackets.

Will remove.

> 
>> +        device number to change
>> +    [part]
>> +        partition number to change
>> +
>> +The *mmc list* displays the list avaiable devices
> 
> The *mmc list* command ...
> 
>> +
>> +The *mmc wp* enables "power on write protect" function about boot partitions
> 
> The *mmc wp* command ...
> 
> %s/about/for/

I will update other things according to your comments.

> 
> Please, mention that power cycling is needed to lift the write protection.
> 
>> +
>> +The *mmc bootbus* sets the BOOT_BUS_WIDTH feild
> 
> The *mmc bootbus* command ...
> 
> %s/feild/field/
> 
>> +    BOOTU_BUS_WIDTH[177] is one of EXT_CSD register. (*Refer to eMMC specification*)
>> +
>> +The *mmc-bootpart-resize* changes sizes of boot and RPMB partition
> 
> partitions.
> 
>> +    dev - device number
>> +
>> +    boot part size MB - Size to change boot partition
> 
> How about:
> 
> target size of boot partition
> 
>> +
>> +    RPMB part size MB - Size to chagne RPMB partition
> 
> %s/chagne/change/
> 
> target size of RPMB partition
> 
>> +
>> +The *mmc rst-function* change the RST_n_FUNCTION filed
> 
> field?
> 
> I think we should describe what a RST_n_FUNCTION is.
> 
> We should enumerate the allowable values. The eMMC specification (JEDEC
> Standard No. 84-B51, 2014) has:
> 
> 0x0: RST_n signal is temporarily disabled (default)
> 0x1: RST_n signal is permanently enabled
> 0x2: RST_n signal is permanently disabled

I thought  that we don't need to describe in more detail and 
user has to read eMMC Specification to understand what a RST_n_FUCTION is.

Because it's dangerous to use without exact understanding.

But I agreed yours..I will add description in more detail.

> 
>> +    **WARNING**: This is a write-once filed. (*Refer to eMMC specification*)
> 
> %s/filed/field/
> 
>> +
>> +Example
>> +-------
>> +
>> +The *mmc info* command displays device's capabilities:
>> +::
>> +
>> +    => mmc info
>> +    Device: EXYNOS DWMMC
>> +    Manufacturer ID: 45
>> +    OEM: 100
>> +    Name: SDW16
>> +    Bus Speed: 52000000
>> +    Mode: MMC DDR52 (52MHz)
>> +    Rd Block Len: 512
>> +    MMC version 5.0
>> +    High Capacity: Yes
>> +    Capacity: 14.7 GiB
>> +    Bus Width: 8-bit DDR
>> +    Erase Group Size: 512 KiB
>> +    HC WP Group Size: 8 MiB
>> +    User Capacity: 14.7 GiB WRREL
>> +    Boot Capacity: 4 MiB ENH
>> +    RPMB Capacity: 4 MiB ENH
>> +    Boot area 0 is not write protected
>> +    Boot area 1 is not write protected
>> +
>> +The raw data can be read/written via *mmc read/write* command:
>> +::
>> +
>> +    => mmc read 0x40000000 0x5000 0x100
>> +    MMC read: dev # 0, block # 20480, count 256 ... 256 blocks read: OK
>> +
>> +    => mmc write 0x40000000 0x5000 0x10
>> +    MMC write: dev # 0, block # 20480, count 256 ... 256 blocks written: OK
>> +
>> +The partition list can be shown via *mmc part* command:
>> +::
>> +
>> +    => mmc part
>> +    Partition Map for MMC device 0  --   Partition Type: DOS
>> +
>> +    Part    Start Sector    Num Sectors     UUID            Type
>> +      1     8192            131072          dff8751a-01     0e Boot
>> +      2     139264          6291456         dff8751a-02     83
>> +      3     6430720         1048576         dff8751a-03     83
>> +      4     7479296         23298048        dff8751a-04     05 Extd
>> +      5     7481344         307200          dff8751a-05     83
>> +      6     7790592         65536           dff8751a-06     83
>> +      7     7858176         16384           dff8751a-07     83
>> +      8     7876608         22900736        dff8751a-08     83
>> +
>> +The current device can be shown or set via *mmc dev* command:
>> +::
>> +
>> +    => mmc dev
>> +    switch to partitions #0, OK
>> +    mmc0(part0) is current device
>> +    => mmc dev 2 0
>> +    switch to partitions #0, OK
>> +    mmc2 is current device
>> +
>> +The list of available devices can be shown via *mmc list* command:
>> +::
>> +
>> +    => mmc list
>> +    mmc list
>> +    EXYNOS DWMMC: 0 (eMMC)
>> +    EXYNOS DWMMC: 2 (SD)
>> +
>> +Configuration
>> +-------------
>> +
>> +The mmc command is only avaialble if CONFIG_CMD_MMC=y.
>> +Some commands need to enable more configuration.
> 
> Some sub-command need require further configuration:

Right. I have been checking other sub-command.
There are too many commands, so i wonder that it needs to add the example of all command.
Because some commands have one-time programmable, it's difficult to change my eMMC's register.

Best Regards,
Jaehoon Chung

> 
>> +
>> +* write / erase - CONFIG_MMC_WRITE
> 
> write, erase
>     CONFIG_MMC_WRITE=y
> 
>> +* bootbus - CONFIG_SUPPORT_EMMC_BOOT=y
>>
> 
> Best regards
> 
> Heinrich
>