Commit 9cdd273e authored by Mauro Carvalho Chehab's avatar Mauro Carvalho Chehab Committed by Jonathan Corbet
Browse files

spi: docs: convert to ReST and add it to the kABI bookset 



While there's one file there with briefily describes the uAPI,
the documentation was written just like most subsystems: focused
on kernel developers. So, add it together with driver-api books.

Signed-off-by: default avatarMauro Carvalho Chehab <mchehab+samsung@kernel.org>
Acked-by: Jonathan Cameron <Jonathan.Cameron@huawei.com> # for iio
Signed-off-by: default avatarJonathan Corbet <corbet@lwn.net>
parent d2fd3732

Documentation/index.rst

+1 −0
Original line number Diff line number Diff line
@@ -116,6 +116,7 @@ needed). 
   power/index

   target/index

   timers/index

   spi/index

   watchdog/index

   virtual/index

   input/index

Documentation/spi/butterfly→Documentation/spi/butterfly.rst

+25 −19
Original line number Diff line number Diff line 
===================================================

spi_butterfly - parport-to-butterfly adapter driver

===================================================
@@ -27,25 +28,29 @@ need to reflash the firmware, and the pins are the standard Atmel "ISP" 
connector pins (used also on non-Butterfly AVR boards).  On the parport

side this is like "sp12" programming cables.



	======	  =============	  ===================

	Signal	  Butterfly	  Parport (DB-25)

	------	  ---------	  ---------------

	SCK	= J403.PB1/SCK	= pin 2/D0

	RESET	= J403.nRST	= pin 3/D1

	VCC	= J403.VCC_EXT	= pin 8/D6

	MOSI	= J403.PB2/MOSI	= pin 9/D7

	MISO	= J403.PB3/MISO	= pin 11/S7,nBUSY

	GND	= J403.GND	= pin 23/GND

	======	  =============	  ===================

	SCK	  J403.PB1/SCK	  pin 2/D0

	RESET	  J403.nRST	  pin 3/D1

	VCC	  J403.VCC_EXT	  pin 8/D6

	MOSI	  J403.PB2/MOSI	  pin 9/D7

	MISO	  J403.PB3/MISO	  pin 11/S7,nBUSY

	GND	  J403.GND	  pin 23/GND

	======	  =============	  ===================



Then to let Linux master that bus to talk to the DataFlash chip, you must

(a) flash new firmware that disables SPI (set PRR.2, and disable pullups

by clearing PORTB.[0-3]); (b) configure the mtd_dataflash driver; and

(c) cable in the chipselect.



	======	  ============	  ===================

	Signal	  Butterfly	  Parport (DB-25)

	------	  ---------	  ---------------

	VCC	= J400.VCC_EXT	= pin 7/D5

	SELECT	= J400.PB0/nSS	= pin 17/C3,nSELECT

	GND	= J400.GND	= pin 24/GND

	======	  ============	  ===================

	VCC	  J400.VCC_EXT	  pin 7/D5

	SELECT	  J400.PB0/nSS	  pin 17/C3,nSELECT

	GND	  J400.GND	  pin 24/GND

	======	  ============	  ===================



Or you could flash firmware making the AVR into an SPI slave (keeping the

DataFlash in reset) and tweak the spi_butterfly driver to make it bind to
@@ -56,13 +61,14 @@ That would let you talk to the AVR using custom SPI-with-USI firmware, 
while letting either Linux or the AVR use the DataFlash.  There are plenty

of spare parport pins to wire this one up, such as:



	======	  =============	  ===================

	Signal	  Butterfly	  Parport (DB-25)

	------	  ---------	  ---------------

	SCK	= J403.PE4/USCK	= pin 5/D3

	MOSI	= J403.PE5/DI	= pin 6/D4

	MISO	= J403.PE6/DO	= pin 12/S5,nPAPEROUT

	GND	= J403.GND	= pin 22/GND



	IRQ	= J402.PF4	= pin 10/S6,ACK

	GND	= J402.GND(P2)	= pin 25/GND

	======	  =============	  ===================

	SCK	  J403.PE4/USCK	  pin 5/D3

	MOSI	  J403.PE5/DI	  pin 6/D4

	MISO	  J403.PE6/DO	  pin 12/S5,nPAPEROUT

	GND	  J403.GND	  pin 22/GND



	IRQ	  J402.PF4	  pin 10/S6,ACK

	GND	  J402.GND(P2)	  pin 25/GND

	======	  =============	  ===================

Documentation/spi/index.rst

0 → 100644
+22 −0
Original line number Diff line number Diff line 
.. SPDX-License-Identifier: GPL-2.0



=================================

Serial Peripheral Interface (SPI)

=================================



.. toctree::

   :maxdepth: 1



   spi-summary

   spidev

   butterfly

   pxa2xx

   spi-lm70llp

   spi-sc18is602



.. only::  subproject and html



   Indices

   =======



   * :ref:`genindex`

Documentation/spi/pxa2xx→Documentation/spi/pxa2xx.rst

+50 −45
Original line number Diff line number Diff line 
==============================

PXA2xx SPI on SSP driver HOWTO

===================================================

==============================



This a mini howto on the pxa2xx_spi driver.  The driver turns a PXA2xx

synchronous serial port into a SPI master controller

(see Documentation/spi/spi-summary). The driver has the following features

(see Documentation/spi/spi-summary.rst). The driver has the following features



- Support for any PXA2xx SSP

- SSP PIO and SSP DMA data transfers.
@@ -19,7 +21,7 @@ Declaring PXA2xx Master Controllers 
-----------------------------------

Typically a SPI master is defined in the arch/.../mach-*/board-*.c as a

"platform device".  The master configuration is passed to the driver via a table

found in include/linux/spi/pxa2xx_spi.h:

found in include/linux/spi/pxa2xx_spi.h::



  struct pxa2xx_spi_controller {

	u16 num_chipselect;
@@ -36,7 +38,7 @@ See the "PXA2xx Developer Manual" section "DMA Controller". 


NSSP MASTER SAMPLE

------------------

Below is a sample configuration using the PXA255 NSSP.

Below is a sample configuration using the PXA255 NSSP::



  static struct resource pxa_spi_nssp_resources[] = {

	[0] = {
@@ -79,7 +81,7 @@ Declaring Slave Devices 
-----------------------

Typically each SPI slave (chip) is defined in the arch/.../mach-*/board-*.c

using the "spi_board_info" structure found in "linux/spi/spi.h". See

"Documentation/spi/spi-summary" for additional information.

"Documentation/spi/spi-summary.rst" for additional information.



Each slave device attached to the PXA must provide slave specific configuration

information via the structure "pxa2xx_spi_chip" found in
@@ -87,6 +89,8 @@ information via the structure "pxa2xx_spi_chip" found in 
will uses the configuration whenever the driver communicates with the slave

device. All fields are optional.



::



  struct pxa2xx_spi_chip {

	u8 tx_threshold;

	u8 rx_threshold;
@@ -99,7 +103,7 @@ struct pxa2xx_spi_chip { 
The "pxa2xx_spi_chip.tx_threshold" and "pxa2xx_spi_chip.rx_threshold" fields are

used to configure the SSP hardware fifo.  These fields are critical to the

performance of pxa2xx_spi driver and misconfiguration will result in rx

fifo overruns (especially in PIO mode transfers). Good default values are

fifo overruns (especially in PIO mode transfers). Good default values are::



	.tx_threshold = 8,

	.rx_threshold = 8,
@@ -141,6 +145,8 @@ The pxa2xx_spi_chip structure is passed to the pxa2xx_spi driver in the 
"spi_board_info.controller_data" field. Below is a sample configuration using

the PXA255 NSSP.



::



  /* Chip Select control for the CS8415A SPI slave device */

  static void cs8415a_cs_control(u32 command)

  {
@@ -210,7 +216,7 @@ by setting the "enable_dma" flag in the "pxa2xx_spi_controller" structure. The 
mode supports both coherent and stream based DMA mappings.



The following logic is used to determine the type of I/O to be used on

a per "spi_transfer" basis:

a per "spi_transfer" basis::



  if !enable_dma then

	always use PIO transfers
@@ -232,4 +238,3 @@ THANKS TO 
---------



David Brownell and others for mentoring the development of this driver.

Documentation/spi/spi-lm70llp→Documentation/spi/spi-lm70llp.rst

+11 −6
Original line number Diff line number Diff line 
==============================================

spi_lm70llp :  LM70-LLP parport-to-SPI adapter

==============================================



Supported board/chip:



  * National Semiconductor LM70 LLP evaluation board



    Datasheet: http://www.national.com/pf/LM/LM70.html



Author:
@@ -29,9 +32,10 @@ available (on page 4) here: 


The hardware interfacing on the LM70 LLP eval board is as follows:



   ======== == =========   ==========

   Parallel                 LM70 LLP

     Port      Direction   JP2 Header

   ----------- --------- ----------------

     Port   .  Direction   JP2 Header

   ======== == =========   ==========

      D0     2      -         -

      D1     3     -->      V+   5

      D2     4     -->      V+   5
@@ -42,7 +46,7 @@ The hardware interfacing on the LM70 LLP eval board is as follows: 
      D7     9     -->      SI/O 5

     GND    25      -       GND  7

    Select  13     <--      SI/O 1

   ----------- --------- ----------------

   ======== == =========   ==========



Note that since the LM70 uses a "3-wire" variant of SPI, the SI/SO pin

is connected to both pin D7 (as Master Out) and Select (as Master In)
@@ -74,6 +78,7 @@ inverting the value read at pin 13. 


Thanks to

---------

o David Brownell for mentoring the SPI-side driver development.

o Dr.Craig Hollabaugh for the (early) "manual" bitbanging driver version.

o Nadir Billimoria for help interpreting the circuit schematic.
 


- David Brownell for mentoring the SPI-side driver development.

- Dr.Craig Hollabaugh for the (early) "manual" bitbanging driver version.

- Nadir Billimoria for help interpreting the circuit schematic.

CRA Git | Maintained and supported by SUSTech CRA and CCSE