Documentation/driver-api/mtd/spi-nor.rst

   1 =================
   2 SPI NOR framework
   3 =================
   4
   5 Part I - Why do we need this framework?
   6 ---------------------------------------
   7
   8 SPI bus controllers (drivers/spi/) only deal with streams of bytes; the bus
   9 controller operates agnostic of the specific device attached. However, some
  10 controllers (such as Freescale's QuadSPI controller) cannot easily handle
  11 arbitrary streams of bytes, but rather are designed specifically for SPI NOR.
  12
  13 In particular, Freescale's QuadSPI controller must know the NOR commands to
  14 find the right LUT sequence. Unfortunately, the SPI subsystem has no notion of
  15 opcodes, addresses, or data payloads; a SPI controller simply knows to send or
  16 receive bytes (Tx and Rx). Therefore, we must define a new layering scheme under
  17 which the controller driver is aware of the opcodes, addressing, and other
  18 details of the SPI NOR protocol.
  19
  20 Part II - How does the framework work?
  21 --------------------------------------
  22
  23 This framework just adds a new layer between the MTD and the SPI bus driver.
  24 With this new layer, the SPI NOR controller driver does not depend on the
  25 m25p80 code anymore.
  26
  27 Before this framework, the layer is like::
  28
  29                    MTD
  30          ------------------------
  31                   m25p80
  32          ------------------------
  33                SPI bus driver
  34          ------------------------
  35                 SPI NOR chip
  36
  37 After this framework, the layer is like::
  38
  39                    MTD
  40          ------------------------
  41               SPI NOR framework
  42          ------------------------
  43                   m25p80
  44          ------------------------
  45                SPI bus driver
  46          ------------------------
  47                SPI NOR chip
  48
  49 With the SPI NOR controller driver (Freescale QuadSPI), it looks like::
  50
  51                    MTD
  52          ------------------------
  53               SPI NOR framework
  54          ------------------------
  55                 fsl-quadSPI
  56          ------------------------
  57                SPI NOR chip
  58
  59 Part III - How can drivers use the framework?
  60 ---------------------------------------------
  61
  62 The main API is spi_nor_scan(). Before you call the hook, a driver should
  63 initialize the necessary fields for spi_nor{}. Please see
  64 drivers/mtd/spi-nor/spi-nor.c for detail. Please also refer to spi-fsl-qspi.c
  65 when you want to write a new driver for a SPI NOR controller.
  66 Another API is spi_nor_restore(), this is used to restore the status of SPI
  67 flash chip such as addressing mode. Call it whenever detach the driver from
  68 device or reboot the system.