[PATCH 0/2] docs: mtd: spi-nor: add sections about flash additions and testing

[PATCH 0/2] docs: mtd: spi-nor: add sections about flash additions and testing

[Tudor Ambarus]

Introduce guide about when to propose a new flash addition and what are
the minimum test requirements. Dropped the old documentation as it no
longer applies to the current SPI NOR framework state.

Generate the htmldoc by using ``make htmldocs`` and then find the
SPI NOR documentation at
``Documentation/output/driver-api/mtd/spi-nor.html``

Tudor Ambarus (2):
  docs: mtd: spi-nor: add sections about flash additions and testing
  docs: mtd: spi-nor: drop obsolete info

 Documentation/driver-api/mtd/spi-nor.rst | 249 +++++++++++++++++------
 1 file changed, 188 insertions(+), 61 deletions(-)

-- 
2.34.1

[PATCH 1/2] docs: mtd: spi-nor: add sections about flash additions and testing

[Tudor Ambarus]

Add sections about how to propose a new flash addition and about the
minimum testing requirements.

Signed-off-by: Tudor Ambarus <tudor.ambarus@linaro.org>
---
 Documentation/driver-api/mtd/spi-nor.rst | 189 +++++++++++++++++++++++
 1 file changed, 189 insertions(+)

diff --git a/Documentation/driver-api/mtd/spi-nor.rst b/Documentation/driver-api/mtd/spi-nor.rst
index c22f8c0f7950..cc8e81e09544 100644
--- a/Documentation/driver-api/mtd/spi-nor.rst
+++ b/Documentation/driver-api/mtd/spi-nor.rst
@@ -63,3 +63,192 @@ The main API is spi_nor_scan(). Before you call the hook, a driver should
 initialize the necessary fields for spi_nor{}. Please see
 drivers/mtd/spi-nor/spi-nor.c for detail. Please also refer to spi-fsl-qspi.c
 when you want to write a new driver for a SPI NOR controller.
+
+How to propose a new flash addition
+-----------------------------------
+
+Most SPI NOR flashes comply with the JEDEC JESD216
+Serial Flash Discoverable Parameter (SFDP) standard. SFDP describes
+the functional and feature capabilities of serial flash devices in a
+standard set of internal read-only parameter tables.
+
+The SPI NOR driver queries the SFDP tables in order to determine the
+flash's parameters and settings. If the flash defines the SFDP tables
+it's likely that you won't need a flash entry at all, and instead
+rely on the generic flash driver which probes the flash solely based
+on its SFDP data. All one has to do is to specify the "jedec,spi-nor"
+compatible in the device tree.
+
+There are cases however where you need to define an explicit flash
+entry. This typically happens when the flash has settings or support
+that is not covered by the SFDP tables (e.g. Block Protection), or
+when the flash contains mangled SFDP data. If the later, one needs
+to implement the ``spi_nor_fixups`` hooks in order to amend the SFDP
+parameters with the correct values.
+
+Minimum testing requirements
+-----------------------------
+
+Do all the tests from below and paste them in the commit's comments
+section, after the ``---`` marker.
+
+1/ Specify the controller that you used to test the flash and specify
+the frequency at which the flash was operated::
+
+    E.g. This flash is populated on the X board and was tested at Y
+    frequency using the Z (put compatible) SPI controller.
+
+2/ Dump the sysfs entries and print the md5/sha1/sha256 SFDP checksum::
+
+    root@1:~#  cat /sys/bus/spi/devices/spi1.0/spi-nor/partname
+    sst26vf064b
+    root@1:~#  cat /sys/bus/spi/devices/spi1.0/spi-nor/jedec_id
+    bf2643
+    root@1:~#  cat /sys/bus/spi/devices/spi1.0/spi-nor/manufacturer
+    sst
+    root@1:~# hexdump -C  /sys/bus/spi/devices/spi1.0/spi-nor/sfdp
+    00000000  53 46 44 50 06 01 02 ff  00 06 01 10 30 00 00 ff  |SFDP........0...|
+    00000010  81 00 01 06 00 01 00 ff  bf 00 01 18 00 02 00 01  |................|
+    00000020  ff ff ff ff ff ff ff ff  ff ff ff ff ff ff ff ff  |................|
+    00000030  fd 20 f1 ff ff ff ff 03  44 eb 08 6b 08 3b 80 bb  |. ......D..k.;..|
+    00000040  fe ff ff ff ff ff 00 ff  ff ff 44 0b 0c 20 0d d8  |..........D.. ..|
+    00000050  0f d8 10 d8 20 91 48 24  80 6f 1d 81 ed 0f 77 38  |.... .H$.o....w8|
+    00000060  30 b0 30 b0 f7 ff ff ff  29 c2 5c ff f0 30 c0 80  |0.0.....).\..0..|
+    00000070  ff ff ff ff ff ff ff ff  ff ff ff ff ff ff ff ff  |................|
+    *
+    00000100  ff 00 04 ff f3 7f 00 00  f5 7f 00 00 f9 ff 7d 00  |..............}.|
+    00000110  f5 7f 00 00 f3 7f 00 00  ff ff ff ff ff ff ff ff  |................|
+    00000120  ff ff ff ff ff ff ff ff  ff ff ff ff ff ff ff ff  |................|
+    *
+    00000200  bf 26 43 ff b9 5f fd ff  30 f2 60 f3 32 ff 0a 12  |.&C.._..0.`.2...|
+    00000210  23 46 ff 0f 19 32 0f 19  19 ff ff ff ff ff ff ff  |#F...2..........|
+    00000220  00 66 99 38 ff 05 01 35  06 04 02 32 b0 30 72 42  |.f.8...5...2.0rB|
+    00000230  8d e8 98 88 a5 85 c0 9f  af 5a ff ff 06 ec 06 0c  |.........Z......|
+    00000240  00 03 08 0b ff ff ff ff  ff 07 ff ff 02 02 ff 06  |................|
+    00000250  03 00 fd fd 04 07 00 fc  03 00 fe fe 02 02 07 0e  |................|
+    00000260
+    root@1:~# sha256sum /sys/bus/spi/devices/spi1.0/spi-nor/sfdp
+    428f34d0461876f189ac97f93e68a05fa6428c6650b3b7baf736a921e5898ed1  /sys/bus/spi/devices/spi1.0/spi-nor/sfdp
+
+3/ Dump debugfs data::
+
+    root@1:~# cat /sys/kernel/debug/spi-nor/spi1.0/capabilities
+    Supported read modes by the flash
+     1S-1S-1S
+      opcode		0x03
+      mode cycles	0
+      dummy cycles	0
+     1S-1S-1S (fast read)
+      opcode		0x0b
+      mode cycles	0
+      dummy cycles	8
+     1S-1S-2S
+      opcode		0x3b
+      mode cycles	0
+      dummy cycles	8
+     1S-2S-2S
+      opcode		0xbb
+      mode cycles	4
+      dummy cycles	0
+     1S-1S-4S
+      opcode		0x6b
+      mode cycles	0
+      dummy cycles	8
+     1S-4S-4S
+      opcode		0xeb
+      mode cycles	2
+      dummy cycles	4
+     4S-4S-4S
+      opcode		0x0b
+      mode cycles	2
+      dummy cycles	4
+    
+    Supported page program modes by the flash
+     1S-1S-1S
+      opcode	0x02
+    
+    root@1:~# cat /sys/kernel/debug/spi-nor/spi1.0/params
+    name		sst26vf064b
+    id			bf 26 43 bf 26 43
+    size		8.00 MiB
+    write size		1
+    page size		256
+    address nbytes	3
+    flags		HAS_LOCK | HAS_16BIT_SR | SOFT_RESET | SWP_IS_VOLATILE
+    
+    opcodes
+     read		0xeb
+      dummy cycles	6
+     erase		0x20
+     program		0x02
+     8D extension	none
+    
+    protocols
+     read		1S-4S-4S
+     write		1S-1S-1S
+     register		1S-1S-1S
+    
+    erase commands
+     20 (4.00 KiB) [0]
+     d8 (8.00 KiB) [1]
+     d8 (32.0 KiB) [2]
+     d8 (64.0 KiB) [3]
+     c7 (8.00 MiB)
+    
+    sector map
+     region (in hex)   | erase mask | flags
+     ------------------+------------+----------
+     00000000-00007fff |     [01  ] |
+     00008000-0000ffff |     [0 2 ] |
+     00010000-007effff |     [0  3] |
+     007f0000-007f7fff |     [0 2 ] |
+     007f8000-007fffff |     [01  ] |
+
+4/ Use `mtd-utils <https://git.infradead.org/mtd-utils.git>`__
+and verify that erase, read and page program operations work fine.
+
+a/ Generate a 2 MB file::
+
+    root@1:~# dd if=/dev/urandom of=./spi_test bs=1M count=2
+    2+0 records in
+    2+0 records out
+    2097152 bytes (2.1 MB, 2.0 MiB) copied, 0.848566 s, 2.5 MB/s
+
+b/ Verify erase::
+
+    root@1:~# mtd_debug write /dev/mtd1 0 2097152 spi_test
+    Copied 2097152 bytes from spi_test to address 0x00000000 in flash
+
+    root@1:~# mtd_debug erase /dev/mtd1 0 2097152
+    Erased 2097152 bytes from address 0x00000000 in flash
+
+    root@1:~# mtd_debug read /dev/mtd1 0 2097152 spi_read
+    Copied 2097152 bytes from address 0x00000000 in flash to spi_read
+
+    root@1:~# hexdump -C spi_read
+    00000000  ff ff ff ff ff ff ff ff  ff ff ff ff ff ff ff ff  |................|
+    *
+    00200000
+
+c/ Write, read back and compare::
+
+    root@1:~# mtd_debug write /dev/mtd1 0 2097152 spi_test
+    Copied 2097152 bytes from spi_test to address 0x00000000 in flash
+
+    root@1:~# mtd_debug read /dev/mtd1 0 2097152 spi_read
+    Copied 2097152 bytes from address 0x00000000 in flash to spi_read
+
+    root@1:~# sha1sum spi_*
+    51eeddc316a4121cf96e76e526d94d638283ec22  spi_read
+    51eeddc316a4121cf96e76e526d94d638283ec22  spi_test
+
+d/ Dump mtd_info data::
+
+    root@1:~# mtd_debug info /dev/mtd1
+    mtd.type = MTD_NORFLASH
+    mtd.flags = MTD_CAP_NORFLASH
+    mtd.size = 8388608 (8M)
+    mtd.erasesize = 4096 (4K)
+    mtd.writesize = 1
+    mtd.oobsize = 0
+    regions = 0
-- 
2.34.1

[PATCH 2/2] docs: mtd: spi-nor: drop obsolete info

[Tudor Ambarus]

The architecture description is obsolete, it no longer applies to
the current SPI NOR framework state, remove it.

Signed-off-by: Tudor Ambarus <tudor.ambarus@linaro.org>
---
 Documentation/driver-api/mtd/spi-nor.rst | 62 ------------------------
 1 file changed, 62 deletions(-)

diff --git a/Documentation/driver-api/mtd/spi-nor.rst b/Documentation/driver-api/mtd/spi-nor.rst
index cc8e81e09544..7a8737fe181d 100644
--- a/Documentation/driver-api/mtd/spi-nor.rst
+++ b/Documentation/driver-api/mtd/spi-nor.rst
@@ -2,68 +2,6 @@
 SPI NOR framework
 =================
 
-Part I - Why do we need this framework?
----------------------------------------
-
-SPI bus controllers (drivers/spi/) only deal with streams of bytes; the bus
-controller operates agnostic of the specific device attached. However, some
-controllers (such as Freescale's QuadSPI controller) cannot easily handle
-arbitrary streams of bytes, but rather are designed specifically for SPI NOR.
-
-In particular, Freescale's QuadSPI controller must know the NOR commands to
-find the right LUT sequence. Unfortunately, the SPI subsystem has no notion of
-opcodes, addresses, or data payloads; a SPI controller simply knows to send or
-receive bytes (Tx and Rx). Therefore, we must define a new layering scheme under
-which the controller driver is aware of the opcodes, addressing, and other
-details of the SPI NOR protocol.
-
-Part II - How does the framework work?
---------------------------------------
-
-This framework just adds a new layer between the MTD and the SPI bus driver.
-With this new layer, the SPI NOR controller driver does not depend on the
-m25p80 code anymore.
-
-Before this framework, the layer is like::
-
-                   MTD
-         ------------------------
-                  m25p80
-         ------------------------
-	       SPI bus driver
-         ------------------------
-	        SPI NOR chip
-
-After this framework, the layer is like::
-
-                   MTD
-         ------------------------
-              SPI NOR framework
-         ------------------------
-                  m25p80
-         ------------------------
-	       SPI bus driver
-         ------------------------
-	       SPI NOR chip
-
-With the SPI NOR controller driver (Freescale QuadSPI), it looks like::
-
-                   MTD
-         ------------------------
-              SPI NOR framework
-         ------------------------
-                fsl-quadSPI
-         ------------------------
-	       SPI NOR chip
-
-Part III - How can drivers use the framework?
----------------------------------------------
-
-The main API is spi_nor_scan(). Before you call the hook, a driver should
-initialize the necessary fields for spi_nor{}. Please see
-drivers/mtd/spi-nor/spi-nor.c for detail. Please also refer to spi-fsl-qspi.c
-when you want to write a new driver for a SPI NOR controller.
-
 How to propose a new flash addition
 -----------------------------------
 
-- 
2.34.1

Re: [PATCH 1/2] docs: mtd: spi-nor: add sections about flash additions and testing

[Michael Walle]

Hi Tudor,

> Add sections about how to propose a new flash addition and about the
> minimum testing requirements.

Thanks for doing this :)

> Signed-off-by: Tudor Ambarus <tudor.ambarus@linaro.org>
> ---
>  Documentation/driver-api/mtd/spi-nor.rst | 189 +++++++++++++++++++++++
>  1 file changed, 189 insertions(+)
> 
> diff --git a/Documentation/driver-api/mtd/spi-nor.rst 
> b/Documentation/driver-api/mtd/spi-nor.rst
> index c22f8c0f7950..cc8e81e09544 100644
> --- a/Documentation/driver-api/mtd/spi-nor.rst
> +++ b/Documentation/driver-api/mtd/spi-nor.rst
> @@ -63,3 +63,192 @@ The main API is spi_nor_scan(). Before you call the 
> hook, a driver should
>  initialize the necessary fields for spi_nor{}. Please see
>  drivers/mtd/spi-nor/spi-nor.c for detail. Please also refer to 
> spi-fsl-qspi.c
>  when you want to write a new driver for a SPI NOR controller.
> +
> +How to propose a new flash addition
> +-----------------------------------
> +
> +Most SPI NOR flashes comply with the JEDEC JESD216
> +Serial Flash Discoverable Parameter (SFDP) standard. SFDP describes
> +the functional and feature capabilities of serial flash devices in a
> +standard set of internal read-only parameter tables.
> +
> +The SPI NOR driver queries the SFDP tables in order to determine the
> +flash's parameters and settings. If the flash defines the SFDP tables
> +it's likely that you won't need a flash entry at all, and instead
> +rely on the generic flash driver which probes the flash solely based
> +on its SFDP data. All one has to do is to specify the "jedec,spi-nor"
> +compatible in the device tree.
> +
> +There are cases however where you need to define an explicit flash
> +entry. This typically happens when the flash has settings or support
> +that is not covered by the SFDP tables (e.g. Block Protection), or
> +when the flash contains mangled SFDP data. If the later, one needs
> +to implement the ``spi_nor_fixups`` hooks in order to amend the SFDP
> +parameters with the correct values.
> +
> +Minimum testing requirements
> +-----------------------------
> +
> +Do all the tests from below and paste them in the commit's comments
> +section, after the ``---`` marker.
> +
> +1/ Specify the controller that you used to test the flash and specify
> +the frequency at which the flash was operated::
> +
> +    E.g. This flash is populated on the X board and was tested at Y
> +    frequency using the Z (put compatible) SPI controller.
> +
> +2/ Dump the sysfs entries and print the md5/sha1/sha256 SFDP 
> checksum::
> +
> +    root@1:~#  cat /sys/bus/spi/devices/spi1.0/spi-nor/partname
> +    sst26vf064b
> +    root@1:~#  cat /sys/bus/spi/devices/spi1.0/spi-nor/jedec_id
> +    bf2643
> +    root@1:~#  cat /sys/bus/spi/devices/spi1.0/spi-nor/manufacturer
> +    sst
> +    root@1:~# hexdump -C  /sys/bus/spi/devices/spi1.0/spi-nor/sfdp

Please use "xxd -p" (and maybe mention that if xxd is not available,
"hexdump -Cv" could be used instead). With xxd one can just use "xxd 
-rp"
to generate a binary again.

Otherwise looks good. So with the above fixed:

Reviewed-by: Michael Walle <michael@walle.cc>

> +    00000000  53 46 44 50 06 01 02 ff  00 06 01 10 30 00 00 ff  
> |SFDP........0...|
> +    00000010  81 00 01 06 00 01 00 ff  bf 00 01 18 00 02 00 01  
> |................|
> +    00000020  ff ff ff ff ff ff ff ff  ff ff ff ff ff ff ff ff  
> |................|
> +    00000030  fd 20 f1 ff ff ff ff 03  44 eb 08 6b 08 3b 80 bb  |. 
> ......D..k.;..|
> +    00000040  fe ff ff ff ff ff 00 ff  ff ff 44 0b 0c 20 0d d8  
> |..........D.. ..|
> +    00000050  0f d8 10 d8 20 91 48 24  80 6f 1d 81 ed 0f 77 38  |.... 
> .H$.o....w8|
> +    00000060  30 b0 30 b0 f7 ff ff ff  29 c2 5c ff f0 30 c0 80  
> |0.0.....).\..0..|
> +    00000070  ff ff ff ff ff ff ff ff  ff ff ff ff ff ff ff ff  
> |................|
> +    *
> +    00000100  ff 00 04 ff f3 7f 00 00  f5 7f 00 00 f9 ff 7d 00  
> |..............}.|
> +    00000110  f5 7f 00 00 f3 7f 00 00  ff ff ff ff ff ff ff ff  
> |................|
> +    00000120  ff ff ff ff ff ff ff ff  ff ff ff ff ff ff ff ff  
> |................|
> +    *
> +    00000200  bf 26 43 ff b9 5f fd ff  30 f2 60 f3 32 ff 0a 12  
> |.&C.._..0.`.2...|
> +    00000210  23 46 ff 0f 19 32 0f 19  19 ff ff ff ff ff ff ff  
> |#F...2..........|
> +    00000220  00 66 99 38 ff 05 01 35  06 04 02 32 b0 30 72 42  
> |.f.8...5...2.0rB|
> +    00000230  8d e8 98 88 a5 85 c0 9f  af 5a ff ff 06 ec 06 0c  
> |.........Z......|
> +    00000240  00 03 08 0b ff ff ff ff  ff 07 ff ff 02 02 ff 06  
> |................|
> +    00000250  03 00 fd fd 04 07 00 fc  03 00 fe fe 02 02 07 0e  
> |................|
> +    00000260
> +    root@1:~# sha256sum /sys/bus/spi/devices/spi1.0/spi-nor/sfdp
> +    428f34d0461876f189ac97f93e68a05fa6428c6650b3b7baf736a921e5898ed1  
> /sys/bus/spi/devices/spi1.0/spi-nor/sfdp
> +
> +3/ Dump debugfs data::
> +
> +    root@1:~# cat /sys/kernel/debug/spi-nor/spi1.0/capabilities
> +    Supported read modes by the flash
> +     1S-1S-1S
> +      opcode		0x03
> +      mode cycles	0
> +      dummy cycles	0
> +     1S-1S-1S (fast read)
> +      opcode		0x0b
> +      mode cycles	0
> +      dummy cycles	8
> +     1S-1S-2S
> +      opcode		0x3b
> +      mode cycles	0
> +      dummy cycles	8
> +     1S-2S-2S
> +      opcode		0xbb
> +      mode cycles	4
> +      dummy cycles	0
> +     1S-1S-4S
> +      opcode		0x6b
> +      mode cycles	0
> +      dummy cycles	8
> +     1S-4S-4S
> +      opcode		0xeb
> +      mode cycles	2
> +      dummy cycles	4
> +     4S-4S-4S
> +      opcode		0x0b
> +      mode cycles	2
> +      dummy cycles	4
> +
> +    Supported page program modes by the flash
> +     1S-1S-1S
> +      opcode	0x02
> +
> +    root@1:~# cat /sys/kernel/debug/spi-nor/spi1.0/params
> +    name		sst26vf064b
> +    id			bf 26 43 bf 26 43
> +    size		8.00 MiB
> +    write size		1
> +    page size		256
> +    address nbytes	3
> +    flags		HAS_LOCK | HAS_16BIT_SR | SOFT_RESET | SWP_IS_VOLATILE
> +
> +    opcodes
> +     read		0xeb
> +      dummy cycles	6
> +     erase		0x20
> +     program		0x02
> +     8D extension	none
> +
> +    protocols
> +     read		1S-4S-4S
> +     write		1S-1S-1S
> +     register		1S-1S-1S
> +
> +    erase commands
> +     20 (4.00 KiB) [0]
> +     d8 (8.00 KiB) [1]
> +     d8 (32.0 KiB) [2]
> +     d8 (64.0 KiB) [3]
> +     c7 (8.00 MiB)
> +
> +    sector map
> +     region (in hex)   | erase mask | flags
> +     ------------------+------------+----------
> +     00000000-00007fff |     [01  ] |
> +     00008000-0000ffff |     [0 2 ] |
> +     00010000-007effff |     [0  3] |
> +     007f0000-007f7fff |     [0 2 ] |
> +     007f8000-007fffff |     [01  ] |
> +
> +4/ Use `mtd-utils <https://git.infradead.org/mtd-utils.git>`__
> +and verify that erase, read and page program operations work fine.
> +
> +a/ Generate a 2 MB file::
> +
> +    root@1:~# dd if=/dev/urandom of=./spi_test bs=1M count=2
> +    2+0 records in
> +    2+0 records out
> +    2097152 bytes (2.1 MB, 2.0 MiB) copied, 0.848566 s, 2.5 MB/s
> +
> +b/ Verify erase::
> +
> +    root@1:~# mtd_debug write /dev/mtd1 0 2097152 spi_test
> +    Copied 2097152 bytes from spi_test to address 0x00000000 in flash
> +
> +    root@1:~# mtd_debug erase /dev/mtd1 0 2097152
> +    Erased 2097152 bytes from address 0x00000000 in flash
> +
> +    root@1:~# mtd_debug read /dev/mtd1 0 2097152 spi_read
> +    Copied 2097152 bytes from address 0x00000000 in flash to spi_read
> +
> +    root@1:~# hexdump -C spi_read
> +    00000000  ff ff ff ff ff ff ff ff  ff ff ff ff ff ff ff ff  
> |................|
> +    *
> +    00200000
> +
> +c/ Write, read back and compare::
> +
> +    root@1:~# mtd_debug write /dev/mtd1 0 2097152 spi_test
> +    Copied 2097152 bytes from spi_test to address 0x00000000 in flash
> +
> +    root@1:~# mtd_debug read /dev/mtd1 0 2097152 spi_read
> +    Copied 2097152 bytes from address 0x00000000 in flash to spi_read
> +
> +    root@1:~# sha1sum spi_*
> +    51eeddc316a4121cf96e76e526d94d638283ec22  spi_read
> +    51eeddc316a4121cf96e76e526d94d638283ec22  spi_test
> +
> +d/ Dump mtd_info data::
> +
> +    root@1:~# mtd_debug info /dev/mtd1
> +    mtd.type = MTD_NORFLASH
> +    mtd.flags = MTD_CAP_NORFLASH
> +    mtd.size = 8388608 (8M)
> +    mtd.erasesize = 4096 (4K)
> +    mtd.writesize = 1
> +    mtd.oobsize = 0
> +    regions = 0

Re: [PATCH 2/2] docs: mtd: spi-nor: drop obsolete info

[Michael Walle]

> The architecture description is obsolete, it no longer applies to
> the current SPI NOR framework state, remove it.
> 
> Signed-off-by: Tudor Ambarus <tudor.ambarus@linaro.org>

Reviewed-by: Michael Walle <michael@walle.cc>

Re: [PATCH 1/2] docs: mtd: spi-nor: add sections about flash additions and testing

[Bagas Sanjaya]

[-- Attachment #1: Type: text/plain, Size: 11382 bytes --]

On Thu, Nov 23, 2023 at 06:07:20PM +0200, Tudor Ambarus wrote:
> +Minimum testing requirements
> +-----------------------------
> +
> +Do all the tests from below and paste them in the commit's comments
> +section, after the ``---`` marker.
> +
> +1/ Specify the controller that you used to test the flash and specify
> +the frequency at which the flash was operated::
> +
> +    E.g. This flash is populated on the X board and was tested at Y
> +    frequency using the Z (put compatible) SPI controller.
> +
> +2/ Dump the sysfs entries and print the md5/sha1/sha256 SFDP checksum::
> +
> +    root@1:~#  cat /sys/bus/spi/devices/spi1.0/spi-nor/partname
> +    sst26vf064b
> +    root@1:~#  cat /sys/bus/spi/devices/spi1.0/spi-nor/jedec_id
> +    bf2643
> +    root@1:~#  cat /sys/bus/spi/devices/spi1.0/spi-nor/manufacturer
> +    sst
> +    root@1:~# hexdump -C  /sys/bus/spi/devices/spi1.0/spi-nor/sfdp
> +    00000000  53 46 44 50 06 01 02 ff  00 06 01 10 30 00 00 ff  |SFDP........0...|
> +    00000010  81 00 01 06 00 01 00 ff  bf 00 01 18 00 02 00 01  |................|
> +    00000020  ff ff ff ff ff ff ff ff  ff ff ff ff ff ff ff ff  |................|
> +    00000030  fd 20 f1 ff ff ff ff 03  44 eb 08 6b 08 3b 80 bb  |. ......D..k.;..|
> +    00000040  fe ff ff ff ff ff 00 ff  ff ff 44 0b 0c 20 0d d8  |..........D.. ..|
> +    00000050  0f d8 10 d8 20 91 48 24  80 6f 1d 81 ed 0f 77 38  |.... .H$.o....w8|
> +    00000060  30 b0 30 b0 f7 ff ff ff  29 c2 5c ff f0 30 c0 80  |0.0.....).\..0..|
> +    00000070  ff ff ff ff ff ff ff ff  ff ff ff ff ff ff ff ff  |................|
> +    *
> +    00000100  ff 00 04 ff f3 7f 00 00  f5 7f 00 00 f9 ff 7d 00  |..............}.|
> +    00000110  f5 7f 00 00 f3 7f 00 00  ff ff ff ff ff ff ff ff  |................|
> +    00000120  ff ff ff ff ff ff ff ff  ff ff ff ff ff ff ff ff  |................|
> +    *
> +    00000200  bf 26 43 ff b9 5f fd ff  30 f2 60 f3 32 ff 0a 12  |.&C.._..0.`.2...|
> +    00000210  23 46 ff 0f 19 32 0f 19  19 ff ff ff ff ff ff ff  |#F...2..........|
> +    00000220  00 66 99 38 ff 05 01 35  06 04 02 32 b0 30 72 42  |.f.8...5...2.0rB|
> +    00000230  8d e8 98 88 a5 85 c0 9f  af 5a ff ff 06 ec 06 0c  |.........Z......|
> +    00000240  00 03 08 0b ff ff ff ff  ff 07 ff ff 02 02 ff 06  |................|
> +    00000250  03 00 fd fd 04 07 00 fc  03 00 fe fe 02 02 07 0e  |................|
> +    00000260
> +    root@1:~# sha256sum /sys/bus/spi/devices/spi1.0/spi-nor/sfdp
> +    428f34d0461876f189ac97f93e68a05fa6428c6650b3b7baf736a921e5898ed1  /sys/bus/spi/devices/spi1.0/spi-nor/sfdp
> +
> +3/ Dump debugfs data::
> +
> +    root@1:~# cat /sys/kernel/debug/spi-nor/spi1.0/capabilities
> +    Supported read modes by the flash
> +     1S-1S-1S
> +      opcode		0x03
> +      mode cycles	0
> +      dummy cycles	0
> +     1S-1S-1S (fast read)
> +      opcode		0x0b
> +      mode cycles	0
> +      dummy cycles	8
> +     1S-1S-2S
> +      opcode		0x3b
> +      mode cycles	0
> +      dummy cycles	8
> +     1S-2S-2S
> +      opcode		0xbb
> +      mode cycles	4
> +      dummy cycles	0
> +     1S-1S-4S
> +      opcode		0x6b
> +      mode cycles	0
> +      dummy cycles	8
> +     1S-4S-4S
> +      opcode		0xeb
> +      mode cycles	2
> +      dummy cycles	4
> +     4S-4S-4S
> +      opcode		0x0b
> +      mode cycles	2
> +      dummy cycles	4
> +    
> +    Supported page program modes by the flash
> +     1S-1S-1S
> +      opcode	0x02
> +    
> +    root@1:~# cat /sys/kernel/debug/spi-nor/spi1.0/params
> +    name		sst26vf064b
> +    id			bf 26 43 bf 26 43
> +    size		8.00 MiB
> +    write size		1
> +    page size		256
> +    address nbytes	3
> +    flags		HAS_LOCK | HAS_16BIT_SR | SOFT_RESET | SWP_IS_VOLATILE
> +    
> +    opcodes
> +     read		0xeb
> +      dummy cycles	6
> +     erase		0x20
> +     program		0x02
> +     8D extension	none
> +    
> +    protocols
> +     read		1S-4S-4S
> +     write		1S-1S-1S
> +     register		1S-1S-1S
> +    
> +    erase commands
> +     20 (4.00 KiB) [0]
> +     d8 (8.00 KiB) [1]
> +     d8 (32.0 KiB) [2]
> +     d8 (64.0 KiB) [3]
> +     c7 (8.00 MiB)
> +    
> +    sector map
> +     region (in hex)   | erase mask | flags
> +     ------------------+------------+----------
> +     00000000-00007fff |     [01  ] |
> +     00008000-0000ffff |     [0 2 ] |
> +     00010000-007effff |     [0  3] |
> +     007f0000-007f7fff |     [0 2 ] |
> +     007f8000-007fffff |     [01  ] |
> +
> +4/ Use `mtd-utils <https://git.infradead.org/mtd-utils.git>`__
> +and verify that erase, read and page program operations work fine.
> +
> +a/ Generate a 2 MB file::
> +
> +    root@1:~# dd if=/dev/urandom of=./spi_test bs=1M count=2
> +    2+0 records in
> +    2+0 records out
> +    2097152 bytes (2.1 MB, 2.0 MiB) copied, 0.848566 s, 2.5 MB/s
> +
> +b/ Verify erase::
> +
> +    root@1:~# mtd_debug write /dev/mtd1 0 2097152 spi_test
> +    Copied 2097152 bytes from spi_test to address 0x00000000 in flash
> +
> +    root@1:~# mtd_debug erase /dev/mtd1 0 2097152
> +    Erased 2097152 bytes from address 0x00000000 in flash
> +
> +    root@1:~# mtd_debug read /dev/mtd1 0 2097152 spi_read
> +    Copied 2097152 bytes from address 0x00000000 in flash to spi_read
> +
> +    root@1:~# hexdump -C spi_read
> +    00000000  ff ff ff ff ff ff ff ff  ff ff ff ff ff ff ff ff  |................|
> +    *
> +    00200000
> +
> +c/ Write, read back and compare::
> +
> +    root@1:~# mtd_debug write /dev/mtd1 0 2097152 spi_test
> +    Copied 2097152 bytes from spi_test to address 0x00000000 in flash
> +
> +    root@1:~# mtd_debug read /dev/mtd1 0 2097152 spi_read
> +    Copied 2097152 bytes from address 0x00000000 in flash to spi_read
> +
> +    root@1:~# sha1sum spi_*
> +    51eeddc316a4121cf96e76e526d94d638283ec22  spi_read
> +    51eeddc316a4121cf96e76e526d94d638283ec22  spi_test
> +
> +d/ Dump mtd_info data::
> +
> +    root@1:~# mtd_debug info /dev/mtd1
> +    mtd.type = MTD_NORFLASH
> +    mtd.flags = MTD_CAP_NORFLASH
> +    mtd.size = 8388608 (8M)
> +    mtd.erasesize = 4096 (4K)
> +    mtd.writesize = 1
> +    mtd.oobsize = 0
> +    regions = 0

The numbered lists don't properly rendered, so I have to fix it up:

---- >8 ----
diff --git a/Documentation/driver-api/mtd/spi-nor.rst b/Documentation/driver-api/mtd/spi-nor.rst
index 7a8737fe181de5..d482658628b3c0 100644
--- a/Documentation/driver-api/mtd/spi-nor.rst
+++ b/Documentation/driver-api/mtd/spi-nor.rst
@@ -30,13 +30,13 @@ Minimum testing requirements
 Do all the tests from below and paste them in the commit's comments
 section, after the ``---`` marker.
 
-1/ Specify the controller that you used to test the flash and specify
-the frequency at which the flash was operated::
+1) Specify the controller that you used to test the flash and specify
+   the frequency at which the flash was operated, e.g.::
 
-    E.g. This flash is populated on the X board and was tested at Y
+    This flash is populated on the X board and was tested at Y
     frequency using the Z (put compatible) SPI controller.
 
-2/ Dump the sysfs entries and print the md5/sha1/sha256 SFDP checksum::
+2) Dump the sysfs entries and print the md5/sha1/sha256 SFDP checksum::
 
     root@1:~#  cat /sys/bus/spi/devices/spi1.0/spi-nor/partname
     sst26vf064b
@@ -68,7 +68,7 @@ the frequency at which the flash was operated::
     root@1:~# sha256sum /sys/bus/spi/devices/spi1.0/spi-nor/sfdp
     428f34d0461876f189ac97f93e68a05fa6428c6650b3b7baf736a921e5898ed1  /sys/bus/spi/devices/spi1.0/spi-nor/sfdp
 
-3/ Dump debugfs data::
+3) Dump debugfs data::
 
     root@1:~# cat /sys/kernel/debug/spi-nor/spi1.0/capabilities
     Supported read modes by the flash
@@ -142,51 +142,51 @@ the frequency at which the flash was operated::
      007f0000-007f7fff |     [0 2 ] |
      007f8000-007fffff |     [01  ] |
 
-4/ Use `mtd-utils <https://git.infradead.org/mtd-utils.git>`__
-and verify that erase, read and page program operations work fine.
+4) Use `mtd-utils <https://git.infradead.org/mtd-utils.git>`__
+and verify that erase, read and page program operations work fine:
 
-a/ Generate a 2 MB file::
+   a) Generate a 2 MB file::
 
-    root@1:~# dd if=/dev/urandom of=./spi_test bs=1M count=2
-    2+0 records in
-    2+0 records out
-    2097152 bytes (2.1 MB, 2.0 MiB) copied, 0.848566 s, 2.5 MB/s
+       root@1:~# dd if=/dev/urandom of=./spi_test bs=1M count=2
+       2+0 records in
+       2+0 records out
+       2097152 bytes (2.1 MB, 2.0 MiB) copied, 0.848566 s, 2.5 MB/s
 
-b/ Verify erase::
+   b) Verify erase::
 
-    root@1:~# mtd_debug write /dev/mtd1 0 2097152 spi_test
-    Copied 2097152 bytes from spi_test to address 0x00000000 in flash
+       root@1:~# mtd_debug write /dev/mtd1 0 2097152 spi_test
+       Copied 2097152 bytes from spi_test to address 0x00000000 in flash
 
-    root@1:~# mtd_debug erase /dev/mtd1 0 2097152
-    Erased 2097152 bytes from address 0x00000000 in flash
+       root@1:~# mtd_debug erase /dev/mtd1 0 2097152
+       Erased 2097152 bytes from address 0x00000000 in flash
 
-    root@1:~# mtd_debug read /dev/mtd1 0 2097152 spi_read
-    Copied 2097152 bytes from address 0x00000000 in flash to spi_read
+       root@1:~# mtd_debug read /dev/mtd1 0 2097152 spi_read
+       Copied 2097152 bytes from address 0x00000000 in flash to spi_read
 
-    root@1:~# hexdump -C spi_read
-    00000000  ff ff ff ff ff ff ff ff  ff ff ff ff ff ff ff ff  |................|
-    *
-    00200000
+       root@1:~# hexdump -C spi_read
+       00000000  ff ff ff ff ff ff ff ff  ff ff ff ff ff ff ff ff  |................|
+       *
+       00200000
 
-c/ Write, read back and compare::
+   c) Write, read back and compare::
 
-    root@1:~# mtd_debug write /dev/mtd1 0 2097152 spi_test
-    Copied 2097152 bytes from spi_test to address 0x00000000 in flash
+       root@1:~# mtd_debug write /dev/mtd1 0 2097152 spi_test
+       Copied 2097152 bytes from spi_test to address 0x00000000 in flash
 
-    root@1:~# mtd_debug read /dev/mtd1 0 2097152 spi_read
-    Copied 2097152 bytes from address 0x00000000 in flash to spi_read
+       root@1:~# mtd_debug read /dev/mtd1 0 2097152 spi_read
+       Copied 2097152 bytes from address 0x00000000 in flash to spi_read
 
-    root@1:~# sha1sum spi_*
-    51eeddc316a4121cf96e76e526d94d638283ec22  spi_read
-    51eeddc316a4121cf96e76e526d94d638283ec22  spi_test
+       root@1:~# sha1sum spi_*
+       51eeddc316a4121cf96e76e526d94d638283ec22  spi_read
+       51eeddc316a4121cf96e76e526d94d638283ec22  spi_test
 
-d/ Dump mtd_info data::
+   d) Dump mtd_info data::
 
-    root@1:~# mtd_debug info /dev/mtd1
-    mtd.type = MTD_NORFLASH
-    mtd.flags = MTD_CAP_NORFLASH
-    mtd.size = 8388608 (8M)
-    mtd.erasesize = 4096 (4K)
-    mtd.writesize = 1
-    mtd.oobsize = 0
-    regions = 0
+       root@1:~# mtd_debug info /dev/mtd1
+       mtd.type = MTD_NORFLASH
+       mtd.flags = MTD_CAP_NORFLASH
+       mtd.size = 8388608 (8M)
+       mtd.erasesize = 4096 (4K)
+       mtd.writesize = 1
+       mtd.oobsize = 0
+       regions = 0

Thanks.

-- 
An old man doll... just what I always wanted! - Clara

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 228 bytes --]

Re: [PATCH 1/2] docs: mtd: spi-nor: add sections about flash additions and testing

[Pratyush Yadav]

Hi,


On Thu, Nov 23 2023, Tudor Ambarus wrote:

> Add sections about how to propose a new flash addition and about the
> minimum testing requirements.
>
> Signed-off-by: Tudor Ambarus <tudor.ambarus@linaro.org>
> ---
>  Documentation/driver-api/mtd/spi-nor.rst | 189 +++++++++++++++++++++++
>  1 file changed, 189 insertions(+)
>
> diff --git a/Documentation/driver-api/mtd/spi-nor.rst b/Documentation/driver-api/mtd/spi-nor.rst
> index c22f8c0f7950..cc8e81e09544 100644
> --- a/Documentation/driver-api/mtd/spi-nor.rst
> +++ b/Documentation/driver-api/mtd/spi-nor.rst
> @@ -63,3 +63,192 @@ The main API is spi_nor_scan(). Before you call the hook, a driver should
>  initialize the necessary fields for spi_nor{}. Please see
>  drivers/mtd/spi-nor/spi-nor.c for detail. Please also refer to spi-fsl-qspi.c
>  when you want to write a new driver for a SPI NOR controller.
[...]
> +4/ Use `mtd-utils <https://git.infradead.org/mtd-utils.git>`__
> +and verify that erase, read and page program operations work fine.
> +
> +a/ Generate a 2 MB file::
> +
> +    root@1:~# dd if=/dev/urandom of=./spi_test bs=1M count=2
> +    2+0 records in
> +    2+0 records out
> +    2097152 bytes (2.1 MB, 2.0 MiB) copied, 0.848566 s, 2.5 MB/s
> +
> +b/ Verify erase::
> +
> +    root@1:~# mtd_debug write /dev/mtd1 0 2097152 spi_test
> +    Copied 2097152 bytes from spi_test to address 0x00000000 in flash

Perhaps mention that the 2 MiB region should already be erased.
Otherwise some flashes might refuse the writes (like the ones with ECC
-- Cypress S28 family comes to mind). Experienced engineers should know
this already but it might trip up some beginners.

Looks good otherwise. Thanks for working on this.

Reviewed-by: Pratyush Yadav <pratyush@kernel.org>

> +
> +    root@1:~# mtd_debug erase /dev/mtd1 0 2097152
> +    Erased 2097152 bytes from address 0x00000000 in flash
> +
> +    root@1:~# mtd_debug read /dev/mtd1 0 2097152 spi_read
> +    Copied 2097152 bytes from address 0x00000000 in flash to spi_read
> +
> +    root@1:~# hexdump -C spi_read
> +    00000000  ff ff ff ff ff ff ff ff  ff ff ff ff ff ff ff ff  |................|
> +    *
> +    00200000
> +
[...]

-- 
Regards,
Pratyush Yadav

Re: [PATCH 2/2] docs: mtd: spi-nor: drop obsolete info

[Pratyush Yadav]

On Thu, Nov 23 2023, Tudor Ambarus wrote:

> The architecture description is obsolete, it no longer applies to
> the current SPI NOR framework state, remove it.
>
> Signed-off-by: Tudor Ambarus <tudor.ambarus@linaro.org>

Reviewed-by: Pratyush Yadav <pratyush@kernel.org>

-- 
Regards,
Pratyush Yadav

Re: [PATCH 1/2] docs: mtd: spi-nor: add sections about flash additions and testing

[Tudor Ambarus]

On 11/24/23 14:36, Pratyush Yadav wrote:
> Hi,
> 
> 
> On Thu, Nov 23 2023, Tudor Ambarus wrote:
> 
>> Add sections about how to propose a new flash addition and about the
>> minimum testing requirements.
>>
>> Signed-off-by: Tudor Ambarus <tudor.ambarus@linaro.org>
>> ---
>>  Documentation/driver-api/mtd/spi-nor.rst | 189 +++++++++++++++++++++++
>>  1 file changed, 189 insertions(+)
>>
>> diff --git a/Documentation/driver-api/mtd/spi-nor.rst b/Documentation/driver-api/mtd/spi-nor.rst
>> index c22f8c0f7950..cc8e81e09544 100644
>> --- a/Documentation/driver-api/mtd/spi-nor.rst
>> +++ b/Documentation/driver-api/mtd/spi-nor.rst
>> @@ -63,3 +63,192 @@ The main API is spi_nor_scan(). Before you call the hook, a driver should
>>  initialize the necessary fields for spi_nor{}. Please see
>>  drivers/mtd/spi-nor/spi-nor.c for detail. Please also refer to spi-fsl-qspi.c
>>  when you want to write a new driver for a SPI NOR controller.
> [...]
>> +4/ Use `mtd-utils <https://git.infradead.org/mtd-utils.git>`__
>> +and verify that erase, read and page program operations work fine.
>> +
>> +a/ Generate a 2 MB file::
>> +
>> +    root@1:~# dd if=/dev/urandom of=./spi_test bs=1M count=2
>> +    2+0 records in
>> +    2+0 records out
>> +    2097152 bytes (2.1 MB, 2.0 MiB) copied, 0.848566 s, 2.5 MB/s
>> +
>> +b/ Verify erase::
>> +
>> +    root@1:~# mtd_debug write /dev/mtd1 0 2097152 spi_test
>> +    Copied 2097152 bytes from spi_test to address 0x00000000 in flash
> 
> Perhaps mention that the 2 MiB region should already be erased.
> Otherwise some flashes might refuse the writes (like the ones with ECC

right, then maybe we could do a

/erase
/read
/dump and see 0xff
/sha1sum to have the 0xff checksum
/write
/read what was written
/sha1sum on the read to make it's different that the 0xff checksum and
that the write worked

> -- Cypress S28 family comes to mind). Experienced engineers should know
> this already but it might trip up some beginners.
> 
> Looks good otherwise. Thanks for working on this.
> 
> Reviewed-by: Pratyush Yadav <pratyush@kernel.org>
> 
>> +
>> +    root@1:~# mtd_debug erase /dev/mtd1 0 2097152
>> +    Erased 2097152 bytes from address 0x00000000 in flash
>> +
>> +    root@1:~# mtd_debug read /dev/mtd1 0 2097152 spi_read
>> +    Copied 2097152 bytes from address 0x00000000 in flash to spi_read
>> +
>> +    root@1:~# hexdump -C spi_read
>> +    00000000  ff ff ff ff ff ff ff ff  ff ff ff ff ff ff ff ff  |................|
>> +    *
>> +    00200000
>> +
> [...]
> 

Re: [PATCH 1/2] docs: mtd: spi-nor: add sections about flash additions and testing

[Tudor Ambarus]

On 24.11.2023 09:12, Bagas Sanjaya wrote:
> The numbered lists don't properly rendered, so I have to fix it up:

Thanks, Bagas! It looks better, indeed. I'll include the diff in the
next version.

Cheers,
ta