kernel/git/next/linux-next.git/Documentation/driver-api/mtd, branch master

mtd: spi-nor: Refactor Read Status/Write Status support

2026-09-07T07:45:20+00:00

SPI NOR has a lot of history. Additions over additions, the subtleties of the JESD216 specification, their implementations by the manufacturers and the hardware mistakes have generated a gigantic maze, let's try to understand what is really needed. The specification explains the QE (Quad Enable) bitfield as describing where the bit to enable the Quad capability is, but also how to set it. Unfortunately, the specification is not precise about what opcodes are supported exactly in all the cases. There is an introduction that basically states: - Opcode 0x05 reads SR1 - Opcode 0x35 reads SR2 - Opcode 0x01 writes SR1, and then SR2 if another byte is written Then the bitfield, among indicating the location of the QE bit, may indicate: - Reading SR1 and SR2 in one operation is not possible (loops over the content of SR1) - Reading SR2 directly is possible - Only writing SR1 zeroes SR2. One problem with the current implementation, is that it only focuses on the QE bit. A quad_enable function was created for each case, even though in practice, the logic was always the same: read, modify, write, read back and verify. One problem comes when other features need to play with the status registers, like software block protection or OTP: you never know how to properly handle the QE bit, nor where it is, nor how to read/write the Status registers. This lead to approximations/guessing (in swp.c, otp.c and obviously in legacy controller drivers like atmel.c) but also to the implementation of a gazillon of helpers for reading/writing/checking the status registers. In addition, I believe some design decisions had a negative impact over the years. - All possible situations had to be flagged by the core. This is likely wrong, because we no longer know why we need specific quirks. It was ineherent to the state of the SPI NOR core before the great cleanup that had happened the past few years. I believe this creates confusion in the core today, and we should push this to vendor fixups instead. As an example, in 2023 Hsin-Yi was facing an issue because his chip was setting the wrong QER value, leading to RDCR being prevented, thus falling into a condition blindly setting a random QE bit (I strongy believe it is done like that for wrong reasons). His chip actually had RDCR support! The correct fix should have been to mark the capability in a device fixup instead of handling this in the core. Link: https://lore.kernel.org/lkml/CAJMQK-hR0eaO0b4Vd0U8_KAndLyZapqdHjVLAoe42rWi9rdLkA@mail.gmail.com/ - SFDP parsing is over cautious. I believe BFPT_DWORD15_QER_SR2_BIT1_NO_RD is abusive (nothing states that RDCR is not supported), and BFPT_DWORD15_QER_SR2_BIT1 is also out of specification when forcing 16-bit Status writes. - SNOR_F_HAS_16BIT_SR is only imposing 16bit Status writes, whereas reads can still be 8-bit wide. - The usage of helpers verifying the writes was also spread for IMHO no really good reason. Why shouldn't we trust spi operations when it comes to Status Registers? We do not read back our page reads, so why status registers should be treated with so much care, if it's not because we are unsure of what is being done? My proposal includes a check when it comes to the QE bit (done once) but we don't need these checks otherwise. If the QE bit was written properly, there are high chances that the other register accesses will just be fine, no? Asde from my main quest, I also observed no good reason to ask the read/write status register callers to use nor->bouncebuf while the low-level helpers could do it themselves (we are talking about one or two bytes being copied). So after these observations, my proposal is the following: - Create private low level helpers that just read or write a status register. They are flexible, we can give the opcode (which varies based on the SFDP QER field) and the length (1 or 2). - Create public generic accessors which will be used to read/write sr1 and/or sr2. This is where all the cleverness shall be. The helpers use the available opcodes for a given chip in order to fullfill the request. - Provide a single generic ->quad_enable() hook which generically does all the steps mentioned above (read, modify, write, read back and verify). - Create a list of opcodes for all 6 possible situations: {read, write} {sr1, sr2, sr1 and sr2}. These opcodes are filled/cleared based on the QER field. An opcode set to 0 indicates the absence of support (there is no 0x00 opcode in SPI NOR). I tried my best to analyze the current behavior and to mimic it as much as possible, but this is a risky cleanup. However, if we go for this, it will be *much* easier in the future to handle all kind of chip variations. We won't be limited to a couple of flags anymore, but rather we'll be able to just disable a read or write capability using a single line. Known deviations: - The Atmel manufacturer driver drives non SFDP chips which by default were receiving the HAS_16B_WR flag, forcing SR2 writes all the times, but it was deliberately making single bytes writes to SR1 for its locking operations. The flag is likely wrong for them, so I removed it. - I am proposing on purpose a single quad_enable helper. It should match all the cases, with 1 identified difference which I believe is harmless: in the SR2_BIT7 case, the helper would make an extra SR1 read/write which was not done before. This entry explicitly supports reading and writing the two registers. Note: no manufacturer has been identified to actually use that entry yet. Signed-off-by: Miquel Raynal Signed-off-by: Michael Walle

mtd: spi-nor: Add steps for testing locking with CMP

2026-05-27T12:36:02+00:00

Extend the test coverage by giving guidelines to verify the CMP bit acts according to our expectations. Signed-off-by: Miquel Raynal Signed-off-by: Pratyush Yadav

mtd: spi-nor: Add steps for testing locking support

2026-05-27T12:36:02+00:00

As recently raised on the mailing list, it may be useful to propose a list of steps to go through in order to prove 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 developers. Use the debugfs output to ease the comparison between expectations and reality. [rdunlap@infradead.org: fix build warning] Link: https://lore.kernel.org/linux-mtd/20260526172341.773398-1-rdunlap@infradead.org/ Signed-off-by: Miquel Raynal Signed-off-by: Randy Dunlap Signed-off-by: Pratyush Yadav

Docs: typos/spelling

2024-05-02T16:02:29+00:00

Fix spelling and grammar in Docs descriptions Signed-off-by: Remington Brasga Reviewed-by: Randy Dunlap Signed-off-by: Jonathan Corbet Link: https://lore.kernel.org/r/20240429225527.2329-1-rbrasga@uci.edu

docs: mtd: spi-nor: drop obsolete info

2023-11-24T20:11:19+00:00

The architecture description is obsolete, it no longer applies to the current SPI NOR framework state, remove it. Reviewed-by: Michael Walle Reviewed-by: Pratyush Yadav Link: https://lore.kernel.org/r/20231124184902.1194235-3-tudor.ambarus@linaro.org Signed-off-by: Tudor Ambarus

docs: mtd: spi-nor: add sections about flash additions and testing

2023-11-24T20:11:13+00:00

Add sections about how to propose a new flash addition and about the minimum testing requirements. Reviewed-by: Michael Walle Reviewed-by: Pratyush Yadav Link: https://lore.kernel.org/r/20231124184902.1194235-2-tudor.ambarus@linaro.org Signed-off-by: Tudor Ambarus

mtd: spi-nor: Stop exporting spi_nor_restore()

2023-04-04T06:43:50+00:00

Some SPI NOR controllers that used this method were moved to drivers/spi/. We don't accept new support for the existing SPI NOR controllers drivers under drivers/mtd/spi-nor/controllers/ and we encourage their owners to move the drivers under drivers/spi/. Make spi_nor_restore() private as we're going to use it just in core.c. Link: https://lore.kernel.org/r/20230331074606.3559258-8-tudor.ambarus@linaro.org Signed-off-by: Tudor Ambarus

Documentation / MTD: Rename the intel-spi driver

2022-02-14T12:53:10+00:00

Since the driver is renamed (and moved) update the BIOS upgrade guide accordingly from intel-spi to spi-intel. Keep the guide under MTD documentation because this is pretty much still about MTD and SPI-NOR. Signed-off-by: Mika Westerberg Reviewed-by: Andy Shevchenko Reviewed-by: Mauro Lima Reviewed-by: Tudor Ambarus Link: https://lore.kernel.org/r/20220209122706.42439-4-mika.westerberg@linux.intel.com Signed-off-by: Mark Brown

Merge tag 'mtd/for-5.11' of git://git.kernel.org/pub/scm/linux/kernel/git/mtd/linux

2020-12-16T22:58:35+00:00

Pull MTD updates from Miquel Raynal: "MTD core: - Fix refcounting for unpartitioned MTDs - Fix misspelled function parameter 'section' - Remove unneeded break - cmdline parser: Fix parsing of part-names with colons - mtdpart: Fix misdocumented function parameter 'mtd' MTD devices: - phram: - Allow the user to set the erase page size - File headers are not good candidates for kernel-doc - physmap-bt1-rom: Fix __iomem addrspace removal warning - plat-ram: correctly free memory on error path in platram_probe() - powernv_flash: Add function names to headers and fix 'dev' - docg3: Fix kernel-doc 'bad line' and 'excessive doc' issues UBI cleanup fixes: - gluebi: Fix misnamed function parameter documentation - wl: Fix a couple of kernel-doc issues - eba: Fix a couple of misdocumentation issues - kapi: Correct documentation for 'ubi_leb_read_sg's 'sgl' parameter - Document 'ubi_num' in struct mtd_dev_param Generic NAND core ECC management: - Add an I/O request tweaking mechanism - Entire rework of the software BCH ECC driver, creation of a real ECC engine, getting rid of raw NAND structures, migration to more generic prototypes, misc fixes and style cleanup. Moved now to the Generic NAND layer. - Entire rework of the software Hamming ECC driver, creation of a real ECC engine, getting rid of raw NAND structures, misc renames, comment updates, cleanup, and style fixes. Moved now to the generic NAND layer. - Necessary plumbing at the NAND level to retrieve generic NAND ECC engines (softwares and on-die). - Update of the bindings. Raw NAND core: - Geting rid of the chip->ecc.priv entry. - Fix miscellaneous typos in kernel-doc Raw NAND controller drivers: - Arasan: Document 'anfc_op's 'buf' member - AU1550: Ensure the presence of the right includes - Brcmnand: Demote non-conformant kernel-doc headers - Cafe: Remove superfluous param doc and add another - Davinci: Do not use extra dereferencing - Diskonchip: Marking unused variables as __always_unused - GPMI: - Fix the driver only sense CS0 R/B issue - Fix the random DMA timeout issue - Use a single line for of_device_id - Use of_device_get_match_data() - Fix reference count leak in gpmi ops - Cleanup makefile - Fix binding matching of clocks on different SoCs - Ingenic: remove redundant get_device() in ingenic_ecc_get() - Intel LGM: New NAND controller driver - Marvell: Drop useless line - Meson: - Fix a resource leak in init - Fix meson_nfc_dma_buffer_release() arguments - mxc: - Use device_get_match_data() - Use a single line for of_device_id - Remove platform data support - Omap: - Fix a bunch of kernel-doc misdemeanours - Finish ELM half populated function header, demote empty ones - s3c2410: Add documentation for 2 missing struct members - Sunxi: Document 'sunxi_nfc's 'caps' member - Qcom: - Add support for SDX55 - Support for IPQ6018 QPIC NAND controller - Fix DMA sync on FLASH_STATUS register read - Rockchip: New NAND controller driver for RK3308, RK2928 and others - Sunxi: Add MDMA support ONENAND: - bbt: Fix expected kernel-doc formatting - Fix some kernel-doc misdemeanours - Fix expected kernel-doc formatting - Use mtd->oops_panic_write as condition SPI-NAND core: - Creation of a SPI-NAND on-die ECC engine - Move ECC related definitions earlier in the driver - Fix typo in comment - Fill a default ECC provider/algorithm - Remove outdated comment - Fix OOB read - Allow the case where there is no ECC engine - Use the external ECC engine logic SPI-NAND chip drivers: - Micron: - Add support for MT29F2G01AAAED - Use more specific names - Macronix: - Add support for MX35LFxG24AD - Add support for MX35LFxGE4AD - Toshiba: Demote non-conformant kernel-doc header SPI-NOR core: - Initial support for stateful Octal DTR mode using volatile settings - Preliminary support for JEDEC 251 (xSPI) and JEDEC 216D standards - Support for Cypress Semper flash - Support to specify ECC block size of SPI NOR flashes - Fixes to avoid clearing of non-volatile Block Protection bits at probe - hisi-sfc: Demote non-conformant kernel-doc" * tag 'mtd/for-5.11' of git://git.kernel.org/pub/scm/linux/kernel/git/mtd/linux: (120 commits) mtd: spinand: macronix: Add support for MX35LFxG24AD mtd: rawnand: rockchip: NFC driver for RK3308, RK2928 and others dt-bindings: mtd: Describe Rockchip RK3xxx NAND flash controller mtd: rawnand: gpmi: Use a single line for of_device_id mtd: rawnand: gpmi: Fix the random DMA timeout issue mtd: rawnand: gpmi: Fix the driver only sense CS0 R/B issue mtd: rawnand: qcom: Add NAND controller support for SDX55 dt-bindings: qcom_nandc: Add SDX55 QPIC NAND documentation mtd: rawnand: mxc: Use a single line for of_device_id mtd: rawnand: mxc: Use device_get_match_data() mtd: rawnand: meson: Fix a resource leak in init mtd: rawnand: gpmi: Use of_device_get_match_data() mtd: rawnand: Add NAND controller support on Intel LGM SoC dt-bindings: mtd: Add Nand Flash Controller support for Intel LGM SoC mtd: spinand: micron: Add support for MT29F2G01AAAED mtd: spinand: micron: Use more specific names mtd: rawnand: gpmi: fix reference count leak in gpmi ops dt-bindings: mtd: gpmi-nand: Fix matching of clocks on different SoCs mtd: spinand: macronix: Add support for MX35LFxGE4AD mtd: plat-ram: correctly free memory on error path in platram_probe() ...

docs: mtd: Avoid htmldocs warnings

2020-12-10T21:37:32+00:00

Moving files around produced the following warnings: Error: Cannot open file drivers/mtd/nand/raw/nand_ecc.c Error: Cannot open file drivers/mtd/nand/raw/nand_ecc.c Fix one by just dropping the reference because it is not relevant, the other by using a better noun instead of a file name. Signed-off-by: Miquel Raynal Link: https://lore.kernel.org/linux-mtd/20201113123831.32429-1-miquel.raynal@bootlin.com