sf: Add documentation and an 'sf mmap' command
v2 cover sf: Add documentation and an 'sf mmap' command
This little series adds documentation and a few other tidy-ups to the 'sf' command.
It also provides a way to access memory-mapped SPI via the command line.
Changes in v2:
- Explain why 'usage' cannot be const
- Many fixes as suggested by Heinrich
Simon Glass (4):
command: Use a constant pointer for the help
sf: Tidy up code to avoid #ifdef
sf: doc: Add documentation for the 'sf' command
sf: Provide a command to access memory-mapped SPI
arch/Kconfig | 2 + cmd/Kconfig | 8 ++ cmd/sf.c | 67 +++++++--- doc/usage/index.rst | 1 + doc/usage/sf.rst | 291 ++++++++++++++++++++++++++++++++++++++++++++ include/command.h | 2 +- 6 files changed, 352 insertions(+), 19 deletions(-) create mode 100644 doc/usage/sf.rst
Signature · 1 line
2.32.0.554.ge1b32706d8-goog
PATCH v2 1/4 command: Use a constant pointer for the help
This text should never change during execution, so it makes sense to use a const char * so that it can be declared as const in the code. Update struct cmd_tbl with a const char * pointer for 'help'.
We cannot make usage const because of the bmode command, used on mx53ppd for example.
---
Changes in v2:
- Explain why 'usage' cannot be const
include/command.h | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
include/command.h +1 -1
@@ -45,7 +45,7 @@ struct cmd_tbl { char *const argv[]);char *usage;/* Usage message (short) */ #ifdef CONFIG_SYS_LONGHELP -char *help;/* Help message (long) */ +const char *help;/* Help message (long) */ #endif #ifdef CONFIG_AUTO_COMPLETE /* do auto completion on the arguments */
Signature · 1 line
2.32.0.554.ge1b32706d8-goog
PATCH v2 2/4 sf: Tidy up code to avoid #ifdef
In reply to Simon GlassUpdate this code to use IS_ENABLED() instead.
---
(no changes since v1)
cmd/sf.c | 32 ++++++++++++++------------------ 1 file changed, 14 insertions(+), 18 deletions(-)
cmd/sf.c +14 -18
@@ -384,7 +384,6 @@ static int do_spi_protect(int argc, char *const argv[])return ret ==0 ?0 :1 ; } -#ifdef CONFIG_CMD_SF_TEST enum {STAGE_ERASE ,STAGE_CHECK ,
@@ -394,7 +393,7 @@ enum { STAGE_COUNT, }; -static char *stage_name[STAGE_COUNT ] = { +static const char *stage_name[STAGE_COUNT ] = {"erase" ,"check" ,"write" ,
@@ -548,7 +547,6 @@ static int do_spi_flash_test(int argc, char *const argv[])return 0 ; } -#endif /* CONFIG_CMD_SF_TEST */ static int do_spi_flash (struct cmd_tbl *cmdtp,int flag,int argc,char *const argv[])
@@ -582,10 +580,8 @@ static int do_spi_flash(struct cmd_tbl *cmdtp, int flag, int argc, ret =do_spi_flash_erase (argc, argv); else if (strcmp(cmd, "protect") == 0) ret =do_spi_protect (argc, argv); -#ifdef CONFIG_CMD_SF_TEST - else if (!strcmp(cmd, "test")) + else if (IS_ENABLED(CONFIG_CMD_SF_TEST) && !strcmp(cmd, "test")) ret =do_spi_flash_test (argc, argv); -#endif else ret =-1 ;
@@ -597,16 +593,8 @@ usage:return CMD_RET_USAGE ; } -#ifdef CONFIG_CMD_SF_TEST -#define SF_TEST_HELP "\nsf test offset len " \ - "- run a very basic destructive test" -#else -#define SF_TEST_HELP -#endif - -U_BOOT_CMD ( - sf,5 ,1 , do_spi_flash, -"SPI flash sub-system" , +#ifdef CONFIG_SYS_LONGHELP +static const char long_help[] ="probe [[bus:]cs] [hz] [mode] - init flash device on given SPI bus\n" " and chip select\n" "sf read addr offset|partition len - read `len' bytes starting at\n"
@@ -622,6 +610,14 @@ U_BOOT_CMD(" at `addr' to flash at `offset'\n" " or to start of mtd `partition'\n" "sf protect lock/unlock sector len - protect/unprotect 'len' bytes starting\n" -" at address 'sector'\n" -SF_TEST_HELP +" at address 'sector'" +#ifdef CONFIG_CMD_SF_TEST + "\nsf test offset len - run a very basic destructive test" +#endif +#endif /* CONFIG_SYS_LONGHELP */ + ; + +U_BOOT_CMD ( + sf,5 ,1 , do_spi_flash, +"SPI flash sub-system" , long_help );
Signature · 1 line
2.32.0.554.ge1b32706d8-goog
PATCH v2 3/4 sf: doc: Add documentation for the 'sf' command
In reply to Simon GlassThis 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.
---
Changes in v2:
- Many fixes as suggested by Heinrich
doc/usage/index.rst | 1 + doc/usage/sf.rst | 241 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 242 insertions(+) create mode 100644 doc/usage/sf.rst
doc/usage/index.rst +1 -0
@@ -42,6 +42,7 @@ Shell commands qfw reset sbi + sf scp03 setexpr size
doc/usage/sf.rst new file +241 -0
241 lines not on this page · raw message
Signature · 1 line
2.32.0.554.ge1b32706d8-goog
Re: [PATCH v2 3/4] sf: doc: Add documentation for the 'sf' command
Quoted 265 lines · Simon Glass
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 <[email protected]>---
Changes in v2:
- Many fixes as suggested by Heinrichdoc/usage/index.rst | 1 + doc/usage/sf.rst | 241 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 242 insertions(+)create mode 100644
doc/usage/sf.rstdoc/usage/index.rst +1
-0@@ -42,6 +42,7 @@ Shell commands qfw reset sbi + sf scp03 setexpr sizedoc/usage/sf.rst new file +231
-0@@ -0,0 +1,241 @@ +.. 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 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 +~~~~~~~ + +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 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 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
doc/usage/sf.rst line 241
Quoted 10 lines
doc/usage/sf.rst new file +10
-0+ 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
For other commands we have mentioned the relvant configuration options. Cf. mmc.rst. Could you, please, add a chapter 'Configuration'.
CONFIG_CMD_SF depends on DM_SPI_FLASH [=y] || SPI_FLASH [=y].
I think there is no SPI driver left that is not migrated to DM. Can't we get rid of either CONFIG_DM_SPI_FLASH or CONFIG_SPI_FLASH?
Best regards
Heinrich
Re: [PATCH v2 3/4] sf: doc: Add documentation for the 'sf' command
Hi Heinrich,
Quoted 19 lines · Heinrich Schuchardt
Quoted 15 lines · Simon Glass
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 <[email protected]>---
Changes in v2:
- Many fixes as suggested by Heinrichdoc/usage/index.rst | 1 + doc/usage/sf.rst | 241 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 242 insertions(+)create mode 100644
doc/usage/sf.rst
[..]
Quoted 4 lines
For other commands we have mentioned the relvant configuration options. Cf.
mmc.rst. Could you, please, add a chapter 'Configuration'.
CONFIG_CMD_SFdepends onDM_SPI_FLASH[=y] ||SPI_FLASH[=y].
OK. Perhaps we need to add some checking to checkpatch?
Quoted 3 lines
I think there is no SPI driver left that is not migrated to DM. Can't we get rid of either
CONFIG_DM_SPI_FLASHorCONFIG_SPI_FLASH?
I hope so. Jagan is the SPI flash maintainer and is on cc.
Regards,
Simon
PATCH v2 4/4 sf: Provide a command to access memory-mapped SPI
In reply to Simon GlassAdd a new 'sf mmap' function to show the address of a SPI offset, if the hardware supports it. This is useful on x86 systems.
---
(no changes since v1)
arch/Kconfig | 2 ++ cmd/Kconfig | 8 ++++++++ cmd/sf.c | 35 +++++++++++++++++++++++++++++++++ doc/usage/sf.rst | 50 ++++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 95 insertions(+)
arch/Kconfig +2 -0
@@ -136,6 +136,7 @@ config SANDBOX imply CMD_LZMADEC imply CMD_SATA imply CMD_SF + imply CMD_SF_MMAP imply CMD_SF_TEST imply CRC32_VERIFY imply FAT_WRITE
@@ -201,6 +202,7 @@ config X86 imply CMD_IRQ imply CMD_PCI imply CMD_SF + imply CMD_SF_MMAP imply CMD_SF_TEST imply CMD_ZBOOT imply DM_ETH
cmd/Kconfig +8 -0
@@ -1273,6 +1273,14 @@ config CMD_SF help SPI Flash support +config CMD_SF_MMAP + bool "sf mmap - Access memory-mapped SPI flash" + depends on CMD_SF + help + On some systems part of the SPI flash is mapped into mmemory. This + command provides a way to map a SPI-flash offset to a memory address, + so that the contents can be browsed using 'md', for example. + config CMD_SF_TEST bool "sf test - Allow testing of SPI flash" depends on CMD_SF
cmd/sf.c +35 -0
@@ -384,6 +384,36 @@ static int do_spi_protect(int argc, char *const argv[])return ret ==0 ?0 :1 ; } +static int do_spi_flash_mmap (int argc,char *const argv[]) +{ +loff_t offset, len, maxsize; +uint map_offset, map_size; +ulong map_base; +int dev =0 ; +int ret; + +if (argc <2 ) +return CMD_RET_USAGE ; + + ret =mtd_arg_off_size (argc -1 , &argv[1 ], &dev, &offset, &len, + &maxsize,MTD_DEV_TYPE_NOR , flash->size); +if (ret) +return ret; + + ret =dm_spi_get_mmap (flash->dev, &map_base, &map_size, &map_offset); +if (ret) { +printf ("Mapping not available (err=%d)\n" , ret); +return CMD_RET_FAILURE ; + } +if (offset <0 || offset + len > map_size) { +printf ("Offset out of range (map size %x)\n" , map_size); +return CMD_RET_FAILURE ; + } +printf ("%lx\n" , map_base + (ulong )offset); + +return 0 ; +} +enum {STAGE_ERASE ,STAGE_CHECK ,
@@ -580,6 +610,8 @@ static int do_spi_flash(struct cmd_tbl *cmdtp, int flag, int argc, ret =do_spi_flash_erase (argc, argv); else if (strcmp(cmd, "protect") == 0) ret =do_spi_protect (argc, argv); + else if (IS_ENABLED(CONFIG_CMD_SF_MMAP) && !strcmp(cmd, "mmap")) + ret =do_spi_flash_mmap (argc, argv); else if (IS_ENABLED(CONFIG_CMD_SF_TEST) && !strcmp(cmd, "test")) ret =do_spi_flash_test (argc, argv); else
@@ -611,6 +643,9 @@ static const char long_help[] = " or to start of mtd `partition'\n" "sf protect lock/unlock sector len - protect/unprotect 'len' bytes starting\n" " at address 'sector'" +#ifdef CONFIG_CMD_SF_MMAP + "\nsf mmap offset len - get memory address of SPI-flash offset\n" +#endif#ifdef CONFIG_CMD_SF_TEST "\nsf test offset len - run a very basic destructive test"#endif
doc/usage/sf.rst +50 -0
68 lines not on this page · raw message
Signature · 1 line
2.32.0.554.ge1b32706d8-goog