Skip to content

Commit

Permalink
spi: docs: convert to ReST and add it to the kABI bookset
Browse files Browse the repository at this point in the history 
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: Mauro Carvalho Chehab <[email protected]>
Acked-by: Jonathan Cameron <[email protected]> # for iio
Signed-off-by: Jonathan Corbet <[email protected]>
  • Loading branch information
@mchehab
mchehab authored and Jonathan Corbet committed Jul 31, 2019
1 parent d2fd373 commit 9cdd273
Show file tree
Hide file tree
Showing 13 changed files with 198 additions and 129 deletions.
1 change: 1 addition & 0 deletions Documentation/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -116,6 +116,7 @@ needed).
power/index
target/index
timers/index
spi/index
watchdog/index
virtual/index
input/index
Expand Down
44 changes: 25 additions & 19 deletions Documentation/spi/butterfly → Documentation/spi/butterfly.rst
View file
Original file line number Diff line number Diff line change
@@ -1,3 +1,4 @@
===================================================
spi_butterfly - parport-to-butterfly adapter driver
===================================================

Expand Down Expand Up @@ -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
Expand All @@ -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
====== ============= ===================
22 changes: 22 additions & 0 deletions Documentation/spi/index.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
.. 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`
95 changes: 50 additions & 45 deletions Documentation/spi/pxa2xx → Documentation/spi/pxa2xx.rst
View file
Original file line number Diff line number Diff line change
@@ -1,8 +1,10 @@
==============================
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.
Expand All @@ -19,12 +21,12 @@ 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 {
struct pxa2xx_spi_controller {
u16 num_chipselect;
u8 enable_dma;
};
};

The "pxa2xx_spi_controller.num_chipselect" field is used to determine the number of
slave device (chips) attached to this SPI master.
Expand All @@ -36,9 +38,9 @@ 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[] = {
static struct resource pxa_spi_nssp_resources[] = {
[0] = {
.start = __PREG(SSCR0_P(2)), /* Start address of NSSP */
.end = __PREG(SSCR0_P(2)) + 0x2c, /* Range of registers */
Expand All @@ -49,57 +51,59 @@ static struct resource pxa_spi_nssp_resources[] = {
.end = IRQ_NSSP,
.flags = IORESOURCE_IRQ,
},
};
};

static struct pxa2xx_spi_controller pxa_nssp_master_info = {
static struct pxa2xx_spi_controller pxa_nssp_master_info = {
.num_chipselect = 1, /* Matches the number of chips attached to NSSP */
.enable_dma = 1, /* Enables NSSP DMA */
};
};

static struct platform_device pxa_spi_nssp = {
static struct platform_device pxa_spi_nssp = {
.name = "pxa2xx-spi", /* MUST BE THIS VALUE, so device match driver */
.id = 2, /* Bus number, MUST MATCH SSP number 1..n */
.resource = pxa_spi_nssp_resources,
.num_resources = ARRAY_SIZE(pxa_spi_nssp_resources),
.dev = {
.platform_data = &pxa_nssp_master_info, /* Passed to driver */
},
};
};

static struct platform_device *devices[] __initdata = {
static struct platform_device *devices[] __initdata = {
&pxa_spi_nssp,
};
};

static void __init board_init(void)
{
static void __init board_init(void)
{
(void)platform_add_device(devices, ARRAY_SIZE(devices));
}
}

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
"include/linux/spi/pxa2xx_spi.h". The pxa2xx_spi master controller driver
will uses the configuration whenever the driver communicates with the slave
device. All fields are optional.

struct pxa2xx_spi_chip {
::

struct pxa2xx_spi_chip {
u8 tx_threshold;
u8 rx_threshold;
u8 dma_burst_size;
u32 timeout;
u8 enable_loopback;
void (*cs_control)(u32 command);
};
};

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,
Expand Down Expand Up @@ -141,41 +145,43 @@ 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)
{
::

/* Chip Select control for the CS8415A SPI slave device */
static void cs8415a_cs_control(u32 command)
{
if (command & PXA2XX_CS_ASSERT)
GPCR(2) = GPIO_bit(2);
else
GPSR(2) = GPIO_bit(2);
}
}

/* Chip Select control for the CS8405A SPI slave device */
static void cs8405a_cs_control(u32 command)
{
/* Chip Select control for the CS8405A SPI slave device */
static void cs8405a_cs_control(u32 command)
{
if (command & PXA2XX_CS_ASSERT)
GPCR(3) = GPIO_bit(3);
else
GPSR(3) = GPIO_bit(3);
}
}

static struct pxa2xx_spi_chip cs8415a_chip_info = {
static struct pxa2xx_spi_chip cs8415a_chip_info = {
.tx_threshold = 8, /* SSP hardward FIFO threshold */
.rx_threshold = 8, /* SSP hardward FIFO threshold */
.dma_burst_size = 8, /* Byte wide transfers used so 8 byte bursts */
.timeout = 235, /* See Intel documentation */
.cs_control = cs8415a_cs_control, /* Use external chip select */
};
};

static struct pxa2xx_spi_chip cs8405a_chip_info = {
static struct pxa2xx_spi_chip cs8405a_chip_info = {
.tx_threshold = 8, /* SSP hardward FIFO threshold */
.rx_threshold = 8, /* SSP hardward FIFO threshold */
.dma_burst_size = 8, /* Byte wide transfers used so 8 byte bursts */
.timeout = 235, /* See Intel documentation */
.cs_control = cs8405a_cs_control, /* Use external chip select */
};
};

static struct spi_board_info streetracer_spi_board_info[] __initdata = {
static struct spi_board_info streetracer_spi_board_info[] __initdata = {
{
.modalias = "cs8415a", /* Name of spi_driver for this device */
.max_speed_hz = 3686400, /* Run SSP as fast a possbile */
Expand All @@ -193,13 +199,13 @@ static struct spi_board_info streetracer_spi_board_info[] __initdata = {
.controller_data = &cs8405a_chip_info, /* Master chip config */
.irq = STREETRACER_APCI_IRQ, /* Slave device interrupt */
},
};
};

static void __init streetracer_init(void)
{
static void __init streetracer_init(void)
{
spi_register_board_info(streetracer_spi_board_info,
ARRAY_SIZE(streetracer_spi_board_info));
}
}


DMA and PIO I/O Support
Expand All @@ -210,26 +216,25 @@ 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
if !enable_dma then
always use PIO transfers

if spi_message.len > 8191 then
if spi_message.len > 8191 then
print "rate limited" warning
use PIO transfers

if spi_message.is_dma_mapped and rx_dma_buf != 0 and tx_dma_buf != 0 then
if spi_message.is_dma_mapped and rx_dma_buf != 0 and tx_dma_buf != 0 then
use coherent DMA mode

if rx_buf and tx_buf are aligned on 8 byte boundary then
if rx_buf and tx_buf are aligned on 8 byte boundary then
use streaming DMA mode

otherwise
otherwise
use PIO transfer

THANKS TO
---------

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

17 changes: 11 additions & 6 deletions Documentation/spi/spi-lm70llp → Documentation/spi/spi-lm70llp.rst
View file
Original file line number Diff line number Diff line change
@@ -1,8 +1,11 @@
==============================================
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:
Expand All @@ -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
Expand All @@ -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)
Expand Down Expand Up @@ -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.
3 changes: 3 additions & 0 deletions Documentation/spi/spi-sc18is602 → Documentation/spi/spi-sc18is602.rst
View file
Original file line number Diff line number Diff line change
@@ -1,8 +1,11 @@
===========================
Kernel driver spi-sc18is602
===========================

Supported chips:

* NXP SI18IS602/602B/603

Datasheet: http://www.nxp.com/documents/data_sheet/SC18IS602_602B_603.pdf

Author:
Expand Down
Loading

0 comments on commit 9cdd273

Please sign in to comment.