[linux-2.6-block.git] / Documentation / mtd / spi-nor.rst

=================
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 fsl-quadspi.c
when you want to write a new driver for a SPI NOR controller.
Another API is spi_nor_restore(), this is used to restore the status of SPI
flash chip such as addressing mode. Call it whenever detach the driver from
device or reboot the system.
Commit	Line	Data
6e58e2d8 MCC	1	=================
	2	SPI NOR framework
	3	=================
1ef39108	4
254592db BN	5	Part I - Why do we need this framework?
254592db BN	6	---------------------------------------
1ef39108	7
254592db BN	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.
1ef39108	12
254592db BN	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.
1ef39108 HS	19
1ef39108 HS	20	Part II - How does the framework work?
254592db	21	--------------------------------------
1ef39108 HS	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
6e58e2d8	27	Before this framework, the layer is like::
1ef39108 HS	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	MTD
	39	------------------------
	40	SPI NOR framework
	41	------------------------
	42	m25p80
	43	------------------------
	44	SPI bus driver
	45	------------------------
	46	SPI NOR chip
	47
254592db	48	With the SPI NOR controller driver (Freescale QuadSPI), it looks like:
1ef39108 HS	49	MTD
	50	------------------------
	51	SPI NOR framework
	52	------------------------
	53	fsl-quadSPI
	54	------------------------
	55	SPI NOR chip
	56
254592db BN	57	Part III - How can drivers use the framework?
254592db BN	58	---------------------------------------------
1ef39108	59
254592db BN	60	The main API is spi_nor_scan(). Before you call the hook, a driver should
	61	initialize the necessary fields for spi_nor{}. Please see
	62	drivers/mtd/spi-nor/spi-nor.c for detail. Please also refer to fsl-quadspi.c
	63	when you want to write a new driver for a SPI NOR controller.
8dee1d97 HZ	64	Another API is spi_nor_restore(), this is used to restore the status of SPI
	65	flash chip such as addressing mode. Call it whenever detach the driver from
	66	device or reboot the system.