[PATCH v6 08/28] mtd: spi-nor: swp: Explain the MEMLOCK ioctl implementation behaviour

[Miquel Raynal]

Add more details about how these requests are actually handled in the
SPI NOR core. Their behaviour was not entirely clear to me at first, and
explaining them in plain English sounds the way to go.

Reviewed-by: Michael Walle <mwalle at kernel.org>
Signed-off-by: Miquel Raynal <miquel.raynal at bootlin.com>
---
// Lock first 8 blocks
$ flash_lock -l /dev/mtd0 $((0 * $ss)) $((8 * $bps)); show_sectors
locked sectors
 region (in hex)   | status   | #sectors
 ------------------+----------+---------
 00000000-01ffffff |   locked | 8
 02000000-0fffffff | unlocked | 56
// Unlock exactly 4 blocks (doable)
$ flash_lock -u /dev/mtd0 $((4 * $ss)) $((10 * $bps)); show_sectors
locked sectors
 region (in hex)   | status   | #sectors
 ------------------+----------+---------
 00000000-00ffffff |   locked | 4
 01000000-0fffffff | unlocked | 60
$ flash_lock -l /dev/mtd0 $((0 * $ss)) $((8 * $bps)); show_sectors
locked sectors
 region (in hex)   | status   | #sectors
 ------------------+----------+---------
 00000000-01ffffff |   locked | 8
 02000000-0fffffff | unlocked | 56
// Unlock only 3 blocks (impossible) -> rounded up to 4 unlocked blocks
$ flash_lock -u /dev/mtd0 $((5 * $ss)) $((10 * $bps)); show_sectors
locked sectors
 region (in hex)   | status   | #sectors
 ------------------+----------+---------
 00000000-00ffffff |   locked | 4
 01000000-0fffffff | unlocked | 60
$ flash_lock -l /dev/mtd0 $((0 * $ss)) $((8 * $bps)); show_sectors
locked sectors
 region (in hex)   | status   | #sectors
 ------------------+----------+---------
 00000000-01ffffff |   locked | 8
 02000000-0fffffff | unlocked | 56
// Unlock 5 blocks (impossible) -> rounded up to 6 unlocked blocks
$ flash_lock -u /dev/mtd0 $((3 * $ss)) $((10 * $bps)); show_sectors
locked sectors
 region (in hex)   | status   | #sectors
 ------------------+----------+---------
 00000000-007fffff |   locked | 2
 00800000-0fffffff | unlocked | 62
---
 drivers/mtd/spi-nor/core.h | 11 ++++++++---
 1 file changed, 8 insertions(+), 3 deletions(-)

diff --git a/drivers/mtd/spi-nor/core.h b/drivers/mtd/spi-nor/core.h
index e838c40a2589..65bb4b5e1e2b 100644
--- a/drivers/mtd/spi-nor/core.h
+++ b/drivers/mtd/spi-nor/core.h
@@ -279,9 +279,14 @@ struct spi_nor_erase_map {
 
 /**
  * struct spi_nor_locking_ops - SPI NOR locking methods
- * @lock:	lock a region of the SPI NOR.
- * @unlock:	unlock a region of the SPI NOR.
- * @is_locked:	check if a region of the SPI NOR is completely locked
+ * @lock:	lock a region of the SPI NOR, never locks more than what is
+ *		requested, ie. may lock less.
+ * @unlock:	unlock a region of the SPI NOR, may unlock more than what is
+ *		requested.
+ * @is_locked:	check if a region of the SPI NOR is completely locked, returns
+ *		false otherwise. This feedback may be misleading because users
+ *		may get an "unlocked" status even though a subpart of the region
+ *		is effectively locked.
  */
 struct spi_nor_locking_ops {
 	int (*lock)(struct spi_nor *nor, loff_t ofs, u64 len);

-- 
2.53.0