[PATCH 16/19] mtd: spi-nor: Add steps for testing locking support

[Michael Walle]

On Fri Nov 14, 2025 at 6:53 PM CET, Miquel Raynal wrote:
> As recently raised on the mailing list, it may be useful to propose a
> list of steps to go through in order to proove the devices have been
> described correctly, especially since all the block protection
> information is not stored in any kind of table and is instead filled
> manually by developpers.
>
> Use the debugfs output to ease the comparison between expectations and
> reality.
>
> Signed-off-by: Miquel Raynal <miquel.raynal at bootlin.com>
> ---
>  Documentation/driver-api/mtd/spi-nor.rst | 118 +++++++++++++++++++++++++++++++
>  1 file changed, 118 insertions(+)
>
> diff --git a/Documentation/driver-api/mtd/spi-nor.rst b/Documentation/driver-api/mtd/spi-nor.rst
> index 148fa4288760b6ba47d530ed72c5ef81397d598f..d56ff5c42a98af23a65097c9b77cd20ef2504a49 100644
> --- a/Documentation/driver-api/mtd/spi-nor.rst
> +++ b/Documentation/driver-api/mtd/spi-nor.rst
> @@ -203,3 +203,121 @@ section, after the ``---`` marker.
>      mtd.writesize = 1
>      mtd.oobsize = 0
>      regions = 0
> +
> +5) If your flash supports locking, also follow the following test
> +   procedure to make sure it correctly behaves. These tests must be
> +   conducted with #WP high (no hardware protection) or the `no-wp`
> +   property in the DT node.

Or? If WPn is low, the no-wp property doesn't matter. It's hardware
write protected. Also there is that corner case, where you can
actually fully lock your flash: WPn hard tied to low. Be aware, that
you can enable locking even if WPn is tied low. That has the use
case to initially program the flash and then lock it forever. So we
might add a warning note, that WPn should somehow be controllable
(or be sure that is tied high) before conducting the locking tests.

> +
> +   Test full chip locking and make sure expectations, the MEMISLOCKED
> +   ioctl output, the debugfs output and experimental results are all
> +   aligned::
> +
> +    root at 1:~# alias show_sectors='grep -A4 "locked sectors" /sys/kernel/debug/spi-nor/spi0.0/params'
> +    root at 1:~# flash_lock -u /dev/mtd0
> +    root at 1:~# flash_lock -i /dev/mtd0
> +    Device: /dev/mtd0
> +    Start: 0
> +    Len: 0x4000000
> +    Lock status: unlocked
> +    Return code: 0
> +    root at 1:~# mtd_debug erase /dev/mtd0 0 2097152
> +    Erased 2097152 bytes from address 0x00000000 in flash
> +    root at 1:~# mtd_debug write /dev/mtd0 0 2097152 spi_test
> +    Copied 2097152 bytes from spi_test to address 0x00000000 in flash
> +    root at 1:~# mtd_debug read /dev/mtd0 0 2097152 spi_read
> +    Copied 2097152 bytes from address 0x00000000 in flash to spi_read
> +    root at 1:~# sha256sum spi*
> +    c444216a6ba2a4a66cccd60a0dd062bce4b865dd52b200ef5e21838c4b899ac8  spi_read
> +    c444216a6ba2a4a66cccd60a0dd062bce4b865dd52b200ef5e21838c4b899ac8  spi_test
> +    root at 1:~# show_sectors
> +    software locked sectors
> +     region (in hex)   | status   | #blocks
> +     ------------------+----------+--------
> +     00000000-03ffffff | unlocked | 1024
> +
> +    root at 1:~# flash_lock -l /dev/mtd0
> +    root at 1:~# flash_lock -i /dev/mtd0
> +    Device: /dev/mtd0
> +    Start: 0
> +    Len: 0x4000000
> +    Lock status: locked
> +    Return code: 1
> +    root at 1:~# mtd_debug erase /dev/mtd0 0 2097152
> +    Erased 2097152 bytes from address 0x00000000 in flash
> +    root at 1:~# mtd_debug read /dev/mtd0 0 2097152 spi_read
> +    Copied 2097152 bytes from address 0x00000000 in flash to spi_read
> +    root at 1:~# sha256sum spi*
> +    c444216a6ba2a4a66cccd60a0dd062bce4b865dd52b200ef5e21838c4b899ac8  spi_read
> +    c444216a6ba2a4a66cccd60a0dd062bce4b865dd52b200ef5e21838c4b899ac8  spi_test
> +    root at 1:~# dd if=/dev/urandom of=./spi_test2 bs=1M count=2
> +    2+0 records in
> +    2+0 records out
> +    root at 1:~# mtd_debug write /dev/mtd0 0 2097152 spi_test2
> +    Copied 2097152 bytes from spi_test to address 0x00000000 in flash
> +    root at 1:~# mtd_debug read /dev/mtd0 0 2097152 spi_read2
> +    Copied 2097152 bytes from address 0x00000000 in flash to spi_read
> +    root at 1:~# sha256sum spi*
> +    c444216a6ba2a4a66cccd60a0dd062bce4b865dd52b200ef5e21838c4b899ac8  spi_read
> +    c444216a6ba2a4a66cccd60a0dd062bce4b865dd52b200ef5e21838c4b899ac8  spi_read2
> +    c444216a6ba2a4a66cccd60a0dd062bce4b865dd52b200ef5e21838c4b899ac8  spi_test
> +    bea9334df51c620440f86751cba0799214a016329f1736f9456d40cf40efdc88  spi_test2
> +    root at 1:~# show_sectors
> +    software locked sectors
> +     region (in hex)   | status   | #blocks
> +     ------------------+----------+--------
> +     00000000-03ffffff |   locked | 1024
> +
> +   Once we trust the debugfs output we can use it to test various
> +   situations. Check top locking/unlocking (end of the device)::
> +
> +    root at 1:~# bs=$(cat /sys/class/mtd/mtd0/erasesize)
> +    root at 1:~# size=$(cat /sys/class/mtd/mtd0/size)
> +
> +    root at 1:~# flash_lock -u /dev/mtd0
> +    root at 1:~# flash_lock -l /dev/mtd0 $(($size - (2 * $bs))) 2 # last two
> +    root at 1:~# show_sectors
> +    software locked sectors
> +     region (in hex)   | status   | #blocks
> +     ------------------+----------+--------
> +     00000000-03fdffff | unlocked | 1022
> +     03fe0000-03ffffff |   locked | 2
> +    root at 1:~# flash_lock -u /dev/mtd0 $(($size - (2 * $bs))) 1 # last one

huh? shouldn't that be 1 * $bs?

-michael

> +    root at 1:~# show_sectors
> +    software locked sectors
> +     region (in hex)   | status   | #blocks
> +     ------------------+----------+--------
> +     00000000-03feffff | unlocked | 1023
> +     03ff0000-03ffffff |   locked | 1
> +
> +   If the flash features 4 block protection bits (BP), we can protect
> +   more than 4MB (typically 128 64kiB-blocks or more), with a finer
> +   grain than locking the entire device::
> +
> +    root at 1:~# flash_lock -u /dev/mtd0
> +    root at 1:~# flash_lock -l /dev/mtd0 $(($size - (2**7 * $bs))) $((2**7))
> +    root at 1:~# show_sectors
> +    software locked sectors
> +     region (in hex)   | status   | #blocks
> +     ------------------+----------+--------
> +     00000000-037fffff | unlocked | 896
> +     03800000-03ffffff |   locked | 128
> +
> +   If the flash features a Top/Bottom (TB) bit, we can protect the
> +   beginning of the flash::
> +
> +    root at 1:~# flash_lock -u /dev/mtd0
> +    root at 1:~# flash_lock -l /dev/mtd0 0 2 # first two
> +    root at 1:~# show_sectors
> +    software locked sectors
> +     region (in hex)   | status   | #blocks
> +     ------------------+----------+--------
> +     00000000-0001ffff |   locked | 2
> +     00020000-03ffffff | unlocked | 1022
> +    root at 1:~# flash_lock -u /dev/mtd0 $bs 1 # first one
> +    root at 1:~# show_sectors
> +    software locked sectors
> +     region (in hex)   | status   | #blocks
> +     ------------------+----------+--------
> +     00000000-0000ffff |   locked | 1
> +     00010000-03ffffff | unlocked | 1023

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 297 bytes
Desc: not available
URL: <http://lists.infradead.org/pipermail/linux-mtd/attachments/20251118/3aebbf52/attachment-0001.sig>