[1/1] doc: man-page for cp

Add a man-page for the cp command.

Signed-off-by: Heinrich Schuchardt <heinrich.schuchardt@canonical.com>
---
 doc/usage/cmd/cp.rst | 83 ++++++++++++++++++++++++++++++++++++++++++++
 doc/usage/index.rst  |  1 +
 2 files changed, 84 insertions(+)
 create mode 100644 doc/usage/cmd/cp.rst

Hi Heinrich,

On Fri, 28 Apr 2023 at 01:41, Heinrich Schuchardt
<heinrich.schuchardt@canonical.com> wrote:
>
> Add a man-page for the cp command.
>
> Signed-off-by: Heinrich Schuchardt <heinrich.schuchardt@canonical.com>
> ---
>  doc/usage/cmd/cp.rst | 83 ++++++++++++++++++++++++++++++++++++++++++++
>  doc/usage/index.rst  |  1 +
>  2 files changed, 84 insertions(+)
>  create mode 100644 doc/usage/cmd/cp.rst
>
> diff --git a/doc/usage/cmd/cp.rst b/doc/usage/cmd/cp.rst
> new file mode 100644
> index 0000000000..897c0bb7df
> --- /dev/null
> +++ b/doc/usage/cmd/cp.rst
> @@ -0,0 +1,83 @@
> +.. SPDX-License-Identifier: GPL-2.0+:
> +
> +cp command
> +==========
> +
> +Synopsis
> +--------
> +
> +::
> +
> +    mm source target count
> +    mm.b source target count
> +    mm.w source target count
> +    mm.l source target count
> +    mm.q source target count

Is this the cp or the mm command?

I think it is better to do:

mm.<size>

or something like that, to avoid repetition

> +
> +Description
> +-----------
> +
> +The cp command is used to copy *count* words of memory from the *source*

To me it is confusing to use the term 'words' here. A word typically
means a machine word in a computer, e.g. 32- or 64-bits.

How about just referring to 'transfer size' or 'access size'?

> +address to the *target* address. If the *target* address points to NOR flash,
> +the flash is programmed.
> +
> +The word size is defined by the suffix defaulting to 32 bits:
> +
> +====== ============
> +suffix word size
> +====== ============
> +.b      8 bit words
> +.w     16 bit words
> +.l     32 bit words
> +.q     64 bit words
> +<none> 32 bit words
> +====== ============
> +
> +source
> +        source address, hexadecimal
> +
> +target
> +        target address, hexadecimal
> +
> +count
> +        number of words to be copied, hexadecimal
> +
> +Examples
> +--------
> +
> +The example device has a NOR flash where the lower part of the flash is
> +protected. We first copy to RAM, then to unprotected flash. Last we try to
> +write to protectd flash.
> +
> +::
> +
> +    => mtd list
> +    List of MTD devices:
> +    * nor0
> +      - device: flash@0
> +      - parent: root_driver
> +      - driver: cfi_flash
> +      - path: /flash@0
> +      - type: NOR flash
> +      - block size: 0x20000 bytes
> +      - min I/O: 0x1 bytes
> +      - 0x000000000000-0x000002000000 : "nor0"
> +    => cp.b 4020000 5000000 200000
> +    => cp.b 4020000 1e00000 20000
> +    Copy to Flash... done
> +    => cp.b 4020000 0 20000
> +    Copy to Flash... Can't write to protected Flash sectors
> +    =>
> +
> +Configuration
> +-------------
> +
> +The cp command is available if CONFIG_CMD_MEMORY=y. Support for 64 bit words
> +(cp.q) depends on CONFIG_MEM_SUPPORT_64BIT_DATA=y. Copying to flash depends on
> +CONFIG_MTD_NOR_FLASH=y.
> +
> +Return value
> +------------
> +
> +The return value $? is set to 0 (true) if the command was successfully,
> +1 (false) otherwise.
> diff --git a/doc/usage/index.rst b/doc/usage/index.rst
> index cdf710919a..0fde130a54 100644
> --- a/doc/usage/index.rst
> +++ b/doc/usage/index.rst
> @@ -41,6 +41,7 @@ Shell commands
>     cmd/cmp
>     cmd/coninfo
>     cmd/conitrace
> +   cmd/cp
>     cmd/cyclic
>     cmd/dm
>     cmd/ebtupdate
> --
> 2.39.2
>

Regards,
Simon

On 4/28/23 21:21, Simon Glass wrote:
> Hi Heinrich,
> 
> On Fri, 28 Apr 2023 at 01:41, Heinrich Schuchardt
> <heinrich.schuchardt@canonical.com> wrote:
>>
>> Add a man-page for the cp command.
>>
>> Signed-off-by: Heinrich Schuchardt <heinrich.schuchardt@canonical.com>
>> ---
>>   doc/usage/cmd/cp.rst | 83 ++++++++++++++++++++++++++++++++++++++++++++
>>   doc/usage/index.rst  |  1 +
>>   2 files changed, 84 insertions(+)
>>   create mode 100644 doc/usage/cmd/cp.rst
>>
>> diff --git a/doc/usage/cmd/cp.rst b/doc/usage/cmd/cp.rst
>> new file mode 100644
>> index 0000000000..897c0bb7df
>> --- /dev/null
>> +++ b/doc/usage/cmd/cp.rst
>> @@ -0,0 +1,83 @@
>> +.. SPDX-License-Identifier: GPL-2.0+:
>> +
>> +cp command
>> +==========
>> +
>> +Synopsis
>> +--------
>> +
>> +::
>> +
>> +    mm source target count
>> +    mm.b source target count
>> +    mm.w source target count
>> +    mm.l source target count
>> +    mm.q source target count
> 
> Is this the cp or the mm command?

Thanks for reviewing. It must be cp.

> 
> I think it is better to do:
> 
> mm.<size>
> 
> or something like that, to avoid repetition

We cannot completely avoid repetition as 'cp' without postfix exists.
With size I would associate a number.
Having to look into multiple places to find out that there is a cp.q 
form is not helpful.

I think the current format is the easiest way to see at a glance how to 
use the command.

> 
>> +
>> +Description
>> +-----------
>> +
>> +The cp command is used to copy *count* words of memory from the *source*
> 
> To me it is confusing to use the term 'words' here. A word typically
> means a machine word in a computer, e.g. 32- or 64-bits.
> 
> How about just referring to 'transfer size' or 'access size'?

When hearing 'transfer size' I would think of the total number of bytes 
being transferred. How about 'chunk'?

Best regards

Heinrich

> 
>> +address to the *target* address. If the *target* address points to NOR flash,
>> +the flash is programmed.
>> +
>> +The word size is defined by the suffix defaulting to 32 bits:
>> +
>> +====== ============
>> +suffix word size
>> +====== ============
>> +.b      8 bit words
>> +.w     16 bit words
>> +.l     32 bit words
>> +.q     64 bit words
>> +<none> 32 bit words
>> +====== ============
>> +
>> +source
>> +        source address, hexadecimal
>> +
>> +target
>> +        target address, hexadecimal
>> +
>> +count
>> +        number of words to be copied, hexadecimal
>> +
>> +Examples
>> +--------
>> +
>> +The example device has a NOR flash where the lower part of the flash is
>> +protected. We first copy to RAM, then to unprotected flash. Last we try to
>> +write to protectd flash.
>> +
>> +::
>> +
>> +    => mtd list
>> +    List of MTD devices:
>> +    * nor0
>> +      - device: flash@0
>> +      - parent: root_driver
>> +      - driver: cfi_flash
>> +      - path: /flash@0
>> +      - type: NOR flash
>> +      - block size: 0x20000 bytes
>> +      - min I/O: 0x1 bytes
>> +      - 0x000000000000-0x000002000000 : "nor0"
>> +    => cp.b 4020000 5000000 200000
>> +    => cp.b 4020000 1e00000 20000
>> +    Copy to Flash... done
>> +    => cp.b 4020000 0 20000
>> +    Copy to Flash... Can't write to protected Flash sectors
>> +    =>
>> +
>> +Configuration
>> +-------------
>> +
>> +The cp command is available if CONFIG_CMD_MEMORY=y. Support for 64 bit words
>> +(cp.q) depends on CONFIG_MEM_SUPPORT_64BIT_DATA=y. Copying to flash depends on
>> +CONFIG_MTD_NOR_FLASH=y.
>> +
>> +Return value
>> +------------
>> +
>> +The return value $? is set to 0 (true) if the command was successfully,
>> +1 (false) otherwise.
>> diff --git a/doc/usage/index.rst b/doc/usage/index.rst
>> index cdf710919a..0fde130a54 100644
>> --- a/doc/usage/index.rst
>> +++ b/doc/usage/index.rst
>> @@ -41,6 +41,7 @@ Shell commands
>>      cmd/cmp
>>      cmd/coninfo
>>      cmd/conitrace
>> +   cmd/cp
>>      cmd/cyclic
>>      cmd/dm
>>      cmd/ebtupdate
>> --
>> 2.39.2
>>
> 
> Regards,
> Simon

Hi Heinrich,

On Fri, 28 Apr 2023 at 13:43, Heinrich Schuchardt
<heinrich.schuchardt@canonical.com> wrote:
>
>
>
> On 4/28/23 21:21, Simon Glass wrote:
> > Hi Heinrich,
> >
> > On Fri, 28 Apr 2023 at 01:41, Heinrich Schuchardt
> > <heinrich.schuchardt@canonical.com> wrote:
> >>
> >> Add a man-page for the cp command.
> >>
> >> Signed-off-by: Heinrich Schuchardt <heinrich.schuchardt@canonical.com>
> >> ---
> >>   doc/usage/cmd/cp.rst | 83 ++++++++++++++++++++++++++++++++++++++++++++
> >>   doc/usage/index.rst  |  1 +
> >>   2 files changed, 84 insertions(+)
> >>   create mode 100644 doc/usage/cmd/cp.rst
> >>
> >> diff --git a/doc/usage/cmd/cp.rst b/doc/usage/cmd/cp.rst
> >> new file mode 100644
> >> index 0000000000..897c0bb7df
> >> --- /dev/null
> >> +++ b/doc/usage/cmd/cp.rst
> >> @@ -0,0 +1,83 @@
> >> +.. SPDX-License-Identifier: GPL-2.0+:
> >> +
> >> +cp command
> >> +==========
> >> +
> >> +Synopsis
> >> +--------
> >> +
> >> +::
> >> +
> >> +    mm source target count
> >> +    mm.b source target count
> >> +    mm.w source target count
> >> +    mm.l source target count
> >> +    mm.q source target count
> >
> > Is this the cp or the mm command?
>
> Thanks for reviewing. It must be cp.
>
> >
> > I think it is better to do:
> >
> > mm.<size>
> >
> > or something like that, to avoid repetition
>
> We cannot completely avoid repetition as 'cp' without postfix exists.
> With size I would associate a number.
> Having to look into multiple places to find out that there is a cp.q
> form is not helpful.

You could do:

  cp[.b | w | l | q]

I suppose

But I agree it is a bit painful

   cp[.<size>]

might be better

>
> I think the current format is the easiest way to see at a glance how to
> use the command.
>
> >
> >> +
> >> +Description
> >> +-----------
> >> +
> >> +The cp command is used to copy *count* words of memory from the *source*
> >
> > To me it is confusing to use the term 'words' here. A word typically
> > means a machine word in a computer, e.g. 32- or 64-bits.
> >
> > How about just referring to 'transfer size' or 'access size'?
>
> When hearing 'transfer size' I would think of the total number of bytes
> being transferred. How about 'chunk'?

It is better than word or transfer size, yes. But chunk seems like a
group of things and isn't quite right, I think.

Do you not like 'access size'? If not, then chunk is OK I suppose.

Regards,
Simon