[PATCH 3/4] sf: doc: Add documentation for the 'sf' command

Heinrich Schuchardt xypron.glpk at gmx.de
Tue Apr 6 10:26:38 CEST 2021


On 06.04.21 06:30, Simon Glass wrote:
> This command is fairly complicated so documentation is useful.
> Unfortunately I an not sure how the MTD side of things works and cannot
> find information about that.
>
> Signed-off-by: Simon Glass <sjg at chromium.org>
> ---
>
>  doc/usage/index.rst |   1 +
>  doc/usage/sf.rst    | 238 ++++++++++++++++++++++++++++++++++++++++++++
>  2 files changed, 239 insertions(+)
>  create mode 100644 doc/usage/sf.rst
>
> diff --git a/doc/usage/index.rst b/doc/usage/index.rst
> index 35c515f8b59..a5d31bfae0d 100644
> --- a/doc/usage/index.rst
> +++ b/doc/usage/index.rst
> @@ -34,5 +34,6 @@ Shell commands
>     pstore
>     qfw
>     sbi
> +   sf
>     true
>     scp03
> diff --git a/doc/usage/sf.rst b/doc/usage/sf.rst
> new file mode 100644
> index 00000000000..7ed077b89a7
> --- /dev/null
> +++ b/doc/usage/sf.rst
> @@ -0,0 +1,238 @@
> +.. SPDX-License-Identifier: GPL-2.0+:
> +
> +md command

Thank you for documenting the sf command.

%/md/sf/


> +==========
> +
> +Synopis
> +-------
> +
> +::
> +
> +    sf probe [[[<bus>:]<cs>] [<hz> [<mode>]]]
> +    sf read <addr> <offset>|<partition> <len>
> +    sf write <addr> <offset>|<partition> <len>
> +    sf erase <offset>|<partition> <len>
> +    sf update <addr> <offset>|<partition> <len>
> +    sf protect lock|unlock <sector> <len>
> +    sf test <offset>|<partition> <len>
> +
> +Description
> +-----------
> +
> +The *sf* command is used to access SPI flash, supporting read/write/erase and
> +a few other functions.

For all subcommands except 'sf probe' you have a heading. This somehow
looks inconsistent. Maybe you want to add a heading after all arguments.

> +
> +The flash must first be probed with *sf probe* before any of the other
> +subcommands can be used. All of the parameters are optional:
> +
> +bus
> +	SPI bus number containing the SPI-flash chip, e.g. 0. If you don't know
> +	the number, you can use 'dm uclass' to see all the spi devices,
> +	and check the value for 'seq' for each one (here 0 and 2)::
> +
> +	   uclass 89: spi
> +	   0     spi at 0 @ 05484960, seq 0
> +	   1     spi at 1 @ 05484b40, seq 2
> +
> +cs
> +	SPI chip-select to use for the chip. This is often 0 and can be omitted,
> +	but in some cases multiple slaves are attached to a SPI controller,
> +	selected by a chip-select line for each one.
> +
> +hz
> +	Speed of the SPI bus in hertz. This normally defaults to 100000, i.e.
> +	100KHz, which is very slow. Note that if the device exists in the
> +	device tree, there might be a speed provided there, in which case this
> +	setting is ignored.
> +
> +mode
> +	SPI mode to use:
> +
> +	=====  ================
> +	Mode   Meaning
> +	=====  ================
> +	0      CPOL=0, CPHA=0
> +	1      CPOL=0, CPHA=1
> +	2      CPOL=1, CPHA=0
> +	3      CPOL=1, CPHA=1
> +	=====  ================
> +
> +	CPHA 0 means that data is transferred (sampled) on the first clock

The clock phase (CPHA) ...

> +	edge; 1 means the second.
> +
> +	CPOL 0 controls the idle state of the clock, 0 for low, 1 for high.

The clock polarity (CPOL) controls ...

> +	The active state is the opposite of idle.
> +
> +	You may find this `SPI documentation`_ useful.
> +
> +Once probed, the other subcommands can be used. Parameters are as follows:

This sentence is redundant. You stated already above that probe is the
first subcommand to be executed.

> +
> +addr
> +	Memory address to start transfer
> +
> +offset
> +	Flash offset to start transfer
> +
> +partition
> +	If the parameter is not numeric, it is assumed to be a partition
> +	description in the format <dev_type><dev_num>,<part_num> which is not
> +	covered here. This requires CONFIG_CMD_MTDPARTS.
> +
> +len
> +	Number of bytes to transfer
> +
> +
> +Read
> +----

Please, use a lower heading level than for "Description". Using 'sf
read' as text makes it clear that this is about the sub-command:

sf read
~~~~~~~

> +
> +Use *sf read* to read from SPI flash to memory. The read will fail if an
> +attempt is made to read past the end of the flash.
> +
> +
> +Write
> +-----

sf write
~~~~~~~~

> +
> +Use *sf write* to write from memory to SPI flash. The SPI flash should be
> +erased first, since otherwise the result is undefined.
> +
> +The write will fail if an attempt is made to read past the end of the flash.
> +
> +
> +Erase
> +-----

sf erase
~~~~~~~~

> +
> +Use *sf erase* to erase a region of SPI flash. The erase will fail if any part
> +of the region to be erased is protected or lies past the end of the flash. It
> +may also fail if the start offset or length are not aligned to an erase region
> +(e.g. 256 bytes).
> +
> +
> +Update
> +------

sf update
~~~~~~~~~

> +
> +Use *sf update* to automatically erase and update a region of SPI flash from
> +memory. This works a sector at a time (typical 256 bytes or 4KB). For each
> +sector it first checks if the sector already has the right data. If so it is
> +skipped. If not, the sector is erased and the new data written. Note that if
> +the length is not a multiple of the erase size, the space after the data in
> +the last sector will be erased. If the offset does not start at the beginning
> +of an erase block, the operation will fail.
> +
> +Speed statistics are shown including the number of bytes that were already
> +correct.
> +
> +
> +Protect
> +-------

sf protect
~~~~~~~~~~

> +
> +SPI-flash chips often have a protection feature where the chip is split up into
> +regions which can be locked or unlocked. With *sf protect* it is possible to
> +change these settings, if supported by the driver.
> +
> +lock|unlock
> +	Selects whether to lock or unlock the sectors
> +
> +<sector>
> +	Start sector number to lock/unlock. This may be the byte offset or some
> +	other value, depending on the chip.
> +
> +<len>
> +	Number of bytes to lock/unlock
> +
> +
> +Test
> +----
> +
> +A convenient and fast *sf test* subcommand provides a way to check that SPI
> +flash is working as expected. This works in four stages:
> +
> +   * erase - erases the entire region
> +   * check - checks that the region is erased
> +   * write - writes a test pattern to the region, consisting of the U-Boot code
> +   * read - reads back the test pattern to check that it was written correctly
> +
> +Memory is allocated for two buffers, each <len> bytes in size. At typical
> +size is 64KB to 1MB. The offset and size must be aligned to an erase boundary.
> +
> +Note that this test will fail if any part of the SPI flash is write-protected.
> +
> +
> +Example
> +-------

You have two examples.

Examples
--------

> +
> +::
> +
> +   # This first part uses sandbox

This sentence is not coding. Please, place it above the code block.

This first example uses the sandbox

::

> +   => sf read 1000 1100 80000
> +   device 0 offset 0x1100, size 0x80000
> +   SF: 524288 bytes @ 0x1100 Read: OK
> +   => md 1000
> +   00001000: edfe0dd0 f33a0000 78000000 84250000    ......:....x..%.
> +   00001010: 28000000 11000000 10000000 00000000    ...(............
> +   00001020: 6f050000 0c250000 00000000 00000000    ...o..%.........
> +   00001030: 00000000 00000000 00000000 00000000    ................
> +   00001040: 00000000 00000000 00000000 00000000    ................
> +   00001050: 00000000 00000000 00000000 00000000    ................
> +   00001060: 00000000 00000000 00000000 00000000    ................
> +   00001070: 00000000 00000000 01000000 00000000    ................
> +   00001080: 03000000 04000000 00000000 01000000    ................
> +   00001090: 03000000 04000000 0f000000 01000000    ................
> +   000010a0: 03000000 08000000 1b000000 646e6173    ............sand
> +   000010b0: 00786f62 03000000 08000000 21000000    box............!
> +   000010c0: 646e6173 00786f62 01000000 61696c61    sandbox.....alia
> +   000010d0: 00736573 03000000 07000000 2c000000    ses............,
> +   000010e0: 6332692f 00003040 03000000 07000000    /i2c at 0..........
> +   000010f0: 31000000 6963702f 00003040 03000000    ...1/pci at 0......
> +   => sf erase 0 80000
> +   SF: 524288 bytes @ 0x0 Erased: OK
> +   => sf read 1000 1100 80000
> +   device 0 offset 0x1100, size 0x80000
> +   SF: 524288 bytes @ 0x1100 Read: OK
> +   => md 1000
> +   00001000: ffffffff ffffffff ffffffff ffffffff    ................
> +   00001010: ffffffff ffffffff ffffffff ffffffff    ................
> +   00001020: ffffffff ffffffff ffffffff ffffffff    ................
> +   00001030: ffffffff ffffffff ffffffff ffffffff    ................
> +   00001040: ffffffff ffffffff ffffffff ffffffff    ................
> +   00001050: ffffffff ffffffff ffffffff ffffffff    ................
> +   00001060: ffffffff ffffffff ffffffff ffffffff    ................
> +   00001070: ffffffff ffffffff ffffffff ffffffff    ................
> +   00001080: ffffffff ffffffff ffffffff ffffffff    ................
> +   00001090: ffffffff ffffffff ffffffff ffffffff    ................
> +   000010a0: ffffffff ffffffff ffffffff ffffffff    ................
> +   000010b0: ffffffff ffffffff ffffffff ffffffff    ................
> +   000010c0: ffffffff ffffffff ffffffff ffffffff    ................
> +   000010d0: ffffffff ffffffff ffffffff ffffffff    ................
> +   000010e0: ffffffff ffffffff ffffffff ffffffff    ................
> +   000010f0: ffffffff ffffffff ffffffff ffffffff    ................
> +
> +   # This next part is running on coral, an x86 Chromebook

This is a second independent example. So end the code block here. Put
the description before the next code block:

This second example is running on coral, an x86 Chromebook

::

Best regards

Heinrich

> +   => sf erase 300000 80000
> +   SF: 524288 bytes @ 0x300000 Erased: OK
> +   => sf update 1110000 300000 80000
> +   device 0 offset 0x300000, size 0x80000
> +   524288 bytes written, 0 bytes skipped in 0.457s, speed 1164578 B/s
> +
> +   # This does nothing as the flash is already updated
> +   => sf update 1110000 300000 80000
> +   device 0 offset 0x300000, size 0x80000
> +   0 bytes written, 524288 bytes skipped in 0.196s, speed 2684354 B/s
> +   => sf test 00000 80000   # try a protected region
> +   SPI flash test:
> +   Erase failed (err = -5)
> +   Test failed
> +   => sf test 800000 80000
> +   SPI flash test:
> +   0 erase: 18 ticks, 28444 KiB/s 227.552 Mbps
> +   1 check: 192 ticks, 2666 KiB/s 21.328 Mbps
> +   2 write: 227 ticks, 2255 KiB/s 18.040 Mbps
> +   3 read: 189 ticks, 2708 KiB/s 21.664 Mbps
> +   Test passed
> +   0 erase: 18 ticks, 28444 KiB/s 227.552 Mbps
> +   1 check: 192 ticks, 2666 KiB/s 21.328 Mbps
> +   2 write: 227 ticks, 2255 KiB/s 18.040 Mbps
> +   3 read: 189 ticks, 2708 KiB/s 21.664 Mbps
> +
> +
> +.. _SPI documentation:
> +   https://en.wikipedia.org/wiki/Serial_Peripheral_Interface
>



More information about the U-Boot mailing list