| .. SPDX-License-Identifier: GPL-2.0+: |
| |
| .. index:: |
| single: sf (command) |
| |
| sf command |
| ========== |
| |
| Synopsis |
| -------- |
| |
| :: |
| |
| 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 |