[PATCH v2 3/5] doc: document read/write commands

[Simon Glass]

Hi Rasmus,

On Wed, 1 Mar 2023 at 14:13, Rasmus Villemoes
<rasmus.villemoes at prevas.dk> wrote:
>
> Signed-off-by: Rasmus Villemoes <rasmus.villemoes at prevas.dk>
> ---
>  doc/usage/cmd/read.rst | 40 ++++++++++++++++++++++++++++++++++++++++
>  doc/usage/index.rst    |  1 +
>  2 files changed, 41 insertions(+)
>  create mode 100644 doc/usage/cmd/read.rst
>

Reviewed-by: Simon Glass <sjg at chromium.org>

Please add a commit msg

> diff --git a/doc/usage/cmd/read.rst b/doc/usage/cmd/read.rst
> new file mode 100644
> index 0000000000..705d5a3e0c
> --- /dev/null
> +++ b/doc/usage/cmd/read.rst
> @@ -0,0 +1,40 @@
> +.. SPDX-License-Identifier: GPL-2.0+:
> +
> +read/write commands
> +===================
> +
> +Synopsis
> +--------
> +
> +::
> +
> +    read <interface> <dev[:part|#partname]> <addr> <blk#> <cnt>
> +    write <interface> <dev[:part|#partname]> <addr> <blk#> <cnt>
> +
> +The read and write commands can be used for raw access to data in
> +block devices (or partitions therein), i.e. without going through a
> +file system.
> +
> +read
> +----
> +
> +The block device is specified using the <interface> (e.g. "mmc") and
> +<dev> parameters. If the block device has a partition table, one can
> +optionally specify a partition number (using the :part syntax) or
> +partition name (using the #partname syntax). The command then reads
> +the <cnt> blocks of data starting at block number <blk#> of the given
> +device/partition to the memory address <addr>.
> +
> +Examples:

For other commands the examples go at the bottom.

> +
> +    # Read 2 MiB from partition 3 of mmc device 2 to $loadaddr
> +    read mmc 2.3 $loadaddr 0 0x1000
> +
> +    # Read 16 MiB from the partition named 'kernel' of mmc device 1 to $loadaddr
> +    read mmc 1#kernel $loadaddr 0 0x8000
> +
> +write
> +-----

I think this needs its own file, with the material basically repeated
(perhaps even use an example which includes a read and a write?)

> +
> +The write command is completely equivalent to the read command, except
> +of course that the transer direction is reversed.

transfer

> diff --git a/doc/usage/index.rst b/doc/usage/index.rst
> index 840c20c934..d6365cf8a4 100644
> --- a/doc/usage/index.rst
> +++ b/doc/usage/index.rst
> @@ -71,6 +71,7 @@ Shell commands
>     cmd/printenv
>     cmd/pstore
>     cmd/qfw
> +   cmd/read
>     cmd/reset
>     cmd/rng
>     cmd/sbi
> --
> 2.37.2
>

Regards,
Simon