mirror of
https://github.com/AsahiLinux/u-boot
synced 2024-11-14 00:47:26 +00:00
sf: doc: Add documentation for the 'sf' command
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@chromium.org> Acked-by: Pratyush Yadav <p.yadav@ti.com> Reviewed-by: Jagan Teki <jagan@amarulasolutions.com> Acked-by: Heinrich Schuchardt <xypron.glpk@gmx.de>
This commit is contained in:
Simon Glass
parent
3512e1570d
commit
1fb115e4d2
2 changed files with 246 additions and 0 deletions
|
|
@ -45,6 +45,7 @@ Shell commands
|
||||||
qfw
|
qfw
|
||||||
reset
|
reset
|
||||||
sbi
|
sbi
|
||||||
|
sf
|
||||||
scp03
|
scp03
|
||||||
setexpr
|
setexpr
|
||||||
size
|
size
|
||||||
|
|
|
||||||
245
doc/usage/sf.rst
Normal file
245
doc/usage/sf.rst
Normal file
|
|
@ -0,0 +1,245 @@
|
||||||
|
.. SPDX-License-Identifier: GPL-2.0+:
|
||||||
|
|
||||||
|
sf command
|
||||||
|
==========
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
Probe
|
||||||
|
-----
|
||||||
|
|
||||||
|
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@0 @ 05484960, seq 0
|
||||||
|
1 spi@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
|
||||||
|
===== ================
|
||||||
|
|
||||||
|
Clock phase (CPHA) 0 means that data is transferred (sampled) on the
|
||||||
|
first clock edge; 1 means the second.
|
||||||
|
|
||||||
|
Clock polarity (CPOL) controls the idle state of the clock, 0 for low,
|
||||||
|
1 for high.
|
||||||
|
The active state is the opposite of idle.
|
||||||
|
|
||||||
|
You may find this `SPI documentation`_ useful.
|
||||||
|
|
||||||
|
Parameters for other subcommands (described below) are as follows:
|
||||||
|
|
||||||
|
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
|
||||||
|
~~~~
|
||||||
|
|
||||||
|
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
|
||||||
|
~~~~~
|
||||||
|
|
||||||
|
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
|
||||||
|
~~~~~
|
||||||
|
|
||||||
|
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
|
||||||
|
~~~~~~
|
||||||
|
|
||||||
|
Use *sf update* to automatically erase and update a region of SPI flash from
|
||||||
|
memory. This works a sector at a time (typical 4KB or 64KB). 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
|
||||||
|
~~~~~~~
|
||||||
|
|
||||||
|
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.
|
||||||
|
|
||||||
|
|
||||||
|
Examples
|
||||||
|
--------
|
||||||
|
|
||||||
|
This first example uses sandbox::
|
||||||
|
|
||||||
|
=> sf probe
|
||||||
|
SF: Detected m25p16 with page size 256 Bytes, erase size 64 KiB, total 2 MiB
|
||||||
|
=> 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@0..........
|
||||||
|
000010f0: 31000000 6963702f 00003040 03000000 ...1/pci@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 second example is running on coral, an x86 Chromebook::
|
||||||
|
|
||||||
|
=> sf probe
|
||||||
|
SF: Detected w25q128fw with page size 256 Bytes, erase size 4 KiB, total 16 MiB
|
||||||
|
=> 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
|
||||||
Loading…
Reference in a new issue