mirror of
https://github.com/torvalds/linux.git
synced 2024-11-21 19:41:42 +00:00
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: Mauro Carvalho Chehab <mchehab+samsung@kernel.org> Acked-by: Jonathan Cameron <Jonathan.Cameron@huawei.com> # for iio Signed-off-by: Jonathan Corbet <corbet@lwn.net>
This commit is contained in:
Mauro Carvalho Chehab
Jonathan Corbet
parent
d2fd3732e4
commit
9cdd273e29
@ -116,6 +116,7 @@ needed).
|
||||
power/index
|
||||
target/index
|
||||
timers/index
|
||||
spi/index
|
||||
watchdog/index
|
||||
virtual/index
|
||||
input/index
|
||||
|
||||
@ -1,3 +1,4 @@
|
||||
===================================================
|
||||
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
|
||||
====== ============= ===================
|
||||
22
Documentation/spi/index.rst
Normal file
22
Documentation/spi/index.rst
Normal file
@ -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`
|
||||
@ -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.
|
||||
@ -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.
|
||||
@ -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 */
|
||||
@ -49,14 +51,14 @@ 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,
|
||||
@ -64,22 +66,22 @@ static struct platform_device pxa_spi_nssp = {
|
||||
.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
|
||||
@ -87,19 +89,21 @@ 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 {
|
||||
::
|
||||
|
||||
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,
|
||||
@ -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 */
|
||||
@ -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
|
||||
@ -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.
|
||||
|
||||
@ -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:
|
||||
@ -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.
|
||||
@ -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:
|
||||
@ -1,3 +1,4 @@
|
||||
====================================
|
||||
Overview of Linux kernel SPI support
|
||||
====================================
|
||||
|
||||
@ -139,12 +140,14 @@ a command and then reading its response.
|
||||
|
||||
There are two types of SPI driver, here called:
|
||||
|
||||
Controller drivers ... controllers may be built into System-On-Chip
|
||||
Controller drivers ...
|
||||
controllers may be built into System-On-Chip
|
||||
processors, and often support both Master and Slave roles.
|
||||
These drivers touch hardware registers and may use DMA.
|
||||
Or they can be PIO bitbangers, needing just GPIO pins.
|
||||
|
||||
Protocol drivers ... these pass messages through the controller
|
||||
Protocol drivers ...
|
||||
these pass messages through the controller
|
||||
driver to communicate with a Slave or Master device on the
|
||||
other side of an SPI link.
|
||||
|
||||
@ -160,7 +163,7 @@ those two types of drivers.
|
||||
There is a minimal core of SPI programming interfaces, focussing on
|
||||
using the driver model to connect controller and protocol drivers using
|
||||
device tables provided by board specific initialization code. SPI
|
||||
shows up in sysfs in several locations:
|
||||
shows up in sysfs in several locations::
|
||||
|
||||
/sys/devices/.../CTLR ... physical node for a given SPI controller
|
||||
|
||||
@ -168,7 +171,7 @@ shows up in sysfs in several locations:
|
||||
chipselect C, accessed through CTLR.
|
||||
|
||||
/sys/bus/spi/devices/spiB.C ... symlink to that physical
|
||||
.../CTLR/spiB.C device
|
||||
.../CTLR/spiB.C device
|
||||
|
||||
/sys/devices/.../CTLR/spiB.C/modalias ... identifies the driver
|
||||
that should be used with this device (for hotplug/coldplug)
|
||||
@ -206,7 +209,8 @@ Linux needs several kinds of information to properly configure SPI devices.
|
||||
That information is normally provided by board-specific code, even for
|
||||
chips that do support some of automated discovery/enumeration.
|
||||
|
||||
DECLARE CONTROLLERS
|
||||
Declare Controllers
|
||||
^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The first kind of information is a list of what SPI controllers exist.
|
||||
For System-on-Chip (SOC) based boards, these will usually be platform
|
||||
@ -221,7 +225,7 @@ same basic controller setup code. This is because most SOCs have several
|
||||
SPI-capable controllers, and only the ones actually usable on a given
|
||||
board should normally be set up and registered.
|
||||
|
||||
So for example arch/.../mach-*/board-*.c files might have code like:
|
||||
So for example arch/.../mach-*/board-*.c files might have code like::
|
||||
|
||||
#include <mach/spi.h> /* for mysoc_spi_data */
|
||||
|
||||
@ -238,7 +242,7 @@ So for example arch/.../mach-*/board-*.c files might have code like:
|
||||
...
|
||||
}
|
||||
|
||||
And SOC-specific utility code might look something like:
|
||||
And SOC-specific utility code might look something like::
|
||||
|
||||
#include <mach/spi.h>
|
||||
|
||||
@ -269,8 +273,8 @@ same SOC controller is used. For example, on one board SPI might use
|
||||
an external clock, where another derives the SPI clock from current
|
||||
settings of some master clock.
|
||||
|
||||
|
||||
DECLARE SLAVE DEVICES
|
||||
Declare Slave Devices
|
||||
^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The second kind of information is a list of what SPI slave devices exist
|
||||
on the target board, often with some board-specific data needed for the
|
||||
@ -278,7 +282,7 @@ driver to work correctly.
|
||||
|
||||
Normally your arch/.../mach-*/board-*.c files would provide a small table
|
||||
listing the SPI devices on each board. (This would typically be only a
|
||||
small handful.) That might look like:
|
||||
small handful.) That might look like::
|
||||
|
||||
static struct ads7846_platform_data ads_info = {
|
||||
.vref_delay_usecs = 100,
|
||||
@ -316,7 +320,7 @@ not possible until the infrastructure knows how to deselect it.
|
||||
|
||||
Then your board initialization code would register that table with the SPI
|
||||
infrastructure, so that it's available later when the SPI master controller
|
||||
driver is registered:
|
||||
driver is registered::
|
||||
|
||||
spi_register_board_info(spi_board_info, ARRAY_SIZE(spi_board_info));
|
||||
|
||||
@ -324,12 +328,13 @@ Like with other static board-specific setup, you won't unregister those.
|
||||
|
||||
The widely used "card" style computers bundle memory, cpu, and little else
|
||||
onto a card that's maybe just thirty square centimeters. On such systems,
|
||||
your arch/.../mach-.../board-*.c file would primarily provide information
|
||||
your ``arch/.../mach-.../board-*.c`` file would primarily provide information
|
||||
about the devices on the mainboard into which such a card is plugged. That
|
||||
certainly includes SPI devices hooked up through the card connectors!
|
||||
|
||||
|
||||
NON-STATIC CONFIGURATIONS
|
||||
Non-static Configurations
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Developer boards often play by different rules than product boards, and one
|
||||
example is the potential need to hotplug SPI devices and/or controllers.
|
||||
@ -349,7 +354,7 @@ How do I write an "SPI Protocol Driver"?
|
||||
Most SPI drivers are currently kernel drivers, but there's also support
|
||||
for userspace drivers. Here we talk only about kernel drivers.
|
||||
|
||||
SPI protocol drivers somewhat resemble platform device drivers:
|
||||
SPI protocol drivers somewhat resemble platform device drivers::
|
||||
|
||||
static struct spi_driver CHIP_driver = {
|
||||
.driver = {
|
||||
@ -367,6 +372,8 @@ device whose board_info gave a modalias of "CHIP". Your probe() code
|
||||
might look like this unless you're creating a device which is managing
|
||||
a bus (appearing under /sys/class/spi_master).
|
||||
|
||||
::
|
||||
|
||||
static int CHIP_probe(struct spi_device *spi)
|
||||
{
|
||||
struct CHIP *chip;
|
||||
@ -479,6 +486,8 @@ The main task of this type of driver is to provide an "spi_master".
|
||||
Use spi_alloc_master() to allocate the master, and spi_master_get_devdata()
|
||||
to get the driver-private data allocated for that device.
|
||||
|
||||
::
|
||||
|
||||
struct spi_master *master;
|
||||
struct CONTROLLER *c;
|
||||
|
||||
@ -503,7 +512,8 @@ If you need to remove your SPI controller driver, spi_unregister_master()
|
||||
will reverse the effect of spi_register_master().
|
||||
|
||||
|
||||
BUS NUMBERING
|
||||
Bus Numbering
|
||||
^^^^^^^^^^^^^
|
||||
|
||||
Bus numbering is important, since that's how Linux identifies a given
|
||||
SPI bus (shared SCK, MOSI, MISO). Valid bus numbers start at zero. On
|
||||
@ -517,9 +527,10 @@ then be replaced by a dynamically assigned number. You'd then need to treat
|
||||
this as a non-static configuration (see above).
|
||||
|
||||
|
||||
SPI MASTER METHODS
|
||||
SPI Master Methods
|
||||
^^^^^^^^^^^^^^^^^^
|
||||
|
||||
master->setup(struct spi_device *spi)
|
||||
``master->setup(struct spi_device *spi)``
|
||||
This sets up the device clock rate, SPI mode, and word sizes.
|
||||
Drivers may change the defaults provided by board_info, and then
|
||||
call spi_setup(spi) to invoke this routine. It may sleep.
|
||||
@ -528,37 +539,37 @@ SPI MASTER METHODS
|
||||
change them right away ... otherwise drivers could corrupt I/O
|
||||
that's in progress for other SPI devices.
|
||||
|
||||
** BUG ALERT: for some reason the first version of
|
||||
** many spi_master drivers seems to get this wrong.
|
||||
** When you code setup(), ASSUME that the controller
|
||||
** is actively processing transfers for another device.
|
||||
.. note::
|
||||
|
||||
master->cleanup(struct spi_device *spi)
|
||||
BUG ALERT: for some reason the first version of
|
||||
many spi_master drivers seems to get this wrong.
|
||||
When you code setup(), ASSUME that the controller
|
||||
is actively processing transfers for another device.
|
||||
|
||||
``master->cleanup(struct spi_device *spi)``
|
||||
Your controller driver may use spi_device.controller_state to hold
|
||||
state it dynamically associates with that device. If you do that,
|
||||
be sure to provide the cleanup() method to free that state.
|
||||
|
||||
master->prepare_transfer_hardware(struct spi_master *master)
|
||||
``master->prepare_transfer_hardware(struct spi_master *master)``
|
||||
This will be called by the queue mechanism to signal to the driver
|
||||
that a message is coming in soon, so the subsystem requests the
|
||||
driver to prepare the transfer hardware by issuing this call.
|
||||
This may sleep.
|
||||
|
||||
master->unprepare_transfer_hardware(struct spi_master *master)
|
||||
``master->unprepare_transfer_hardware(struct spi_master *master)``
|
||||
This will be called by the queue mechanism to signal to the driver
|
||||
that there are no more messages pending in the queue and it may
|
||||
relax the hardware (e.g. by power management calls). This may sleep.
|
||||
|
||||
master->transfer_one_message(struct spi_master *master,
|
||||
struct spi_message *mesg)
|
||||
``master->transfer_one_message(struct spi_master *master, struct spi_message *mesg)``
|
||||
The subsystem calls the driver to transfer a single message while
|
||||
queuing transfers that arrive in the meantime. When the driver is
|
||||
finished with this message, it must call
|
||||
spi_finalize_current_message() so the subsystem can issue the next
|
||||
message. This may sleep.
|
||||
|
||||
master->transfer_one(struct spi_master *master, struct spi_device *spi,
|
||||
struct spi_transfer *transfer)
|
||||
``master->transfer_one(struct spi_master *master, struct spi_device *spi, struct spi_transfer *transfer)``
|
||||
The subsystem calls the driver to transfer a single transfer while
|
||||
queuing transfers that arrive in the meantime. When the driver is
|
||||
finished with this transfer, it must call
|
||||
@ -568,19 +579,20 @@ SPI MASTER METHODS
|
||||
not call your transfer_one callback.
|
||||
|
||||
Return values:
|
||||
negative errno: error
|
||||
0: transfer is finished
|
||||
1: transfer is still in progress
|
||||
|
||||
master->set_cs_timing(struct spi_device *spi, u8 setup_clk_cycles,
|
||||
u8 hold_clk_cycles, u8 inactive_clk_cycles)
|
||||
* negative errno: error
|
||||
* 0: transfer is finished
|
||||
* 1: transfer is still in progress
|
||||
|
||||
``master->set_cs_timing(struct spi_device *spi, u8 setup_clk_cycles, u8 hold_clk_cycles, u8 inactive_clk_cycles)``
|
||||
This method allows SPI client drivers to request SPI master controller
|
||||
for configuring device specific CS setup, hold and inactive timing
|
||||
requirements.
|
||||
|
||||
DEPRECATED METHODS
|
||||
Deprecated Methods
|
||||
^^^^^^^^^^^^^^^^^^
|
||||
|
||||
master->transfer(struct spi_device *spi, struct spi_message *message)
|
||||
``master->transfer(struct spi_device *spi, struct spi_message *message)``
|
||||
This must not sleep. Its responsibility is to arrange that the
|
||||
transfer happens and its complete() callback is issued. The two
|
||||
will normally happen later, after other transfers complete, and
|
||||
@ -590,7 +602,8 @@ SPI MASTER METHODS
|
||||
implemented.
|
||||
|
||||
|
||||
SPI MESSAGE QUEUE
|
||||
SPI Message Queue
|
||||
^^^^^^^^^^^^^^^^^
|
||||
|
||||
If you are happy with the standard queueing mechanism provided by the
|
||||
SPI subsystem, just implement the queued methods specified above. Using
|
||||
@ -619,13 +632,13 @@ THANKS TO
|
||||
Contributors to Linux-SPI discussions include (in alphabetical order,
|
||||
by last name):
|
||||
|
||||
Mark Brown
|
||||
David Brownell
|
||||
Russell King
|
||||
Grant Likely
|
||||
Dmitry Pervushin
|
||||
Stephen Street
|
||||
Mark Underwood
|
||||
Andrew Victor
|
||||
Linus Walleij
|
||||
Vitaly Wool
|
||||
- Mark Brown
|
||||
- David Brownell
|
||||
- Russell King
|
||||
- Grant Likely
|
||||
- Dmitry Pervushin
|
||||
- Stephen Street
|
||||
- Mark Underwood
|
||||
- Andrew Victor
|
||||
- Linus Walleij
|
||||
- Vitaly Wool
|
||||
@ -1,7 +1,13 @@
|
||||
=================
|
||||
SPI userspace API
|
||||
=================
|
||||
|
||||
SPI devices have a limited userspace API, supporting basic half-duplex
|
||||
read() and write() access to SPI slave devices. Using ioctl() requests,
|
||||
full duplex transfers and device I/O configuration are also available.
|
||||
|
||||
::
|
||||
|
||||
#include <fcntl.h>
|
||||
#include <unistd.h>
|
||||
#include <sys/ioctl.h>
|
||||
@ -39,14 +45,17 @@ device node with a "dev" attribute that will be understood by udev or mdev.
|
||||
busybox; it's less featureful, but often enough.) For a SPI device with
|
||||
chipselect C on bus B, you should see:
|
||||
|
||||
/dev/spidevB.C ... character special device, major number 153 with
|
||||
/dev/spidevB.C ...
|
||||
character special device, major number 153 with
|
||||
a dynamically chosen minor device number. This is the node
|
||||
that userspace programs will open, created by "udev" or "mdev".
|
||||
|
||||
/sys/devices/.../spiB.C ... as usual, the SPI device node will
|
||||
/sys/devices/.../spiB.C ...
|
||||
as usual, the SPI device node will
|
||||
be a child of its SPI master controller.
|
||||
|
||||
/sys/class/spidev/spidevB.C ... created when the "spidev" driver
|
||||
/sys/class/spidev/spidevB.C ...
|
||||
created when the "spidev" driver
|
||||
binds to that device. (Directory or symlink, based on whether
|
||||
or not you enabled the "deprecated sysfs files" Kconfig option.)
|
||||
|
||||
@ -80,7 +89,8 @@ the SPI_IOC_MESSAGE(N) request.
|
||||
Several ioctl() requests let your driver read or override the device's current
|
||||
settings for data transfer parameters:
|
||||
|
||||
SPI_IOC_RD_MODE, SPI_IOC_WR_MODE ... pass a pointer to a byte which will
|
||||
SPI_IOC_RD_MODE, SPI_IOC_WR_MODE ...
|
||||
pass a pointer to a byte which will
|
||||
return (RD) or assign (WR) the SPI transfer mode. Use the constants
|
||||
SPI_MODE_0..SPI_MODE_3; or if you prefer you can combine SPI_CPOL
|
||||
(clock polarity, idle high iff this is set) or SPI_CPHA (clock phase,
|
||||
@ -88,22 +98,26 @@ settings for data transfer parameters:
|
||||
Note that this request is limited to SPI mode flags that fit in a
|
||||
single byte.
|
||||
|
||||
SPI_IOC_RD_MODE32, SPI_IOC_WR_MODE32 ... pass a pointer to a uin32_t
|
||||
SPI_IOC_RD_MODE32, SPI_IOC_WR_MODE32 ...
|
||||
pass a pointer to a uin32_t
|
||||
which will return (RD) or assign (WR) the full SPI transfer mode,
|
||||
not limited to the bits that fit in one byte.
|
||||
|
||||
SPI_IOC_RD_LSB_FIRST, SPI_IOC_WR_LSB_FIRST ... pass a pointer to a byte
|
||||
SPI_IOC_RD_LSB_FIRST, SPI_IOC_WR_LSB_FIRST ...
|
||||
pass a pointer to a byte
|
||||
which will return (RD) or assign (WR) the bit justification used to
|
||||
transfer SPI words. Zero indicates MSB-first; other values indicate
|
||||
the less common LSB-first encoding. In both cases the specified value
|
||||
is right-justified in each word, so that unused (TX) or undefined (RX)
|
||||
bits are in the MSBs.
|
||||
|
||||
SPI_IOC_RD_BITS_PER_WORD, SPI_IOC_WR_BITS_PER_WORD ... pass a pointer to
|
||||
SPI_IOC_RD_BITS_PER_WORD, SPI_IOC_WR_BITS_PER_WORD ...
|
||||
pass a pointer to
|
||||
a byte which will return (RD) or assign (WR) the number of bits in
|
||||
each SPI transfer word. The value zero signifies eight bits.
|
||||
|
||||
SPI_IOC_RD_MAX_SPEED_HZ, SPI_IOC_WR_MAX_SPEED_HZ ... pass a pointer to a
|
||||
SPI_IOC_RD_MAX_SPEED_HZ, SPI_IOC_WR_MAX_SPEED_HZ ...
|
||||
pass a pointer to a
|
||||
u32 which will return (RD) or assign (WR) the maximum SPI transfer
|
||||
speed, in Hz. The controller can't necessarily assign that specific
|
||||
clock speed.
|
||||
@ -695,7 +695,7 @@ static int iio_dummy_remove(struct iio_sw_device *swd)
|
||||
* i2c:
|
||||
* Documentation/i2c/writing-clients.rst
|
||||
* spi:
|
||||
* Documentation/spi/spi-summary
|
||||
* Documentation/spi/spi-summary.rst
|
||||
*/
|
||||
static const struct iio_sw_device_ops iio_dummy_device_ops = {
|
||||
.probe = iio_dummy_probe,
|
||||
|
||||
@ -543,7 +543,7 @@ config SPI_PXA2XX
|
||||
help
|
||||
This enables using a PXA2xx or Sodaville SSP port as a SPI master
|
||||
controller. The driver can be configured to use any SSP port and
|
||||
additional documentation can be found a Documentation/spi/pxa2xx.
|
||||
additional documentation can be found a Documentation/spi/pxa2xx.rst.
|
||||
|
||||
config SPI_PXA2XX_PCI
|
||||
def_tristate SPI_PXA2XX && PCI && COMMON_CLK
|
||||
|
||||
@ -23,7 +23,7 @@
|
||||
* with a battery powered AVR microcontroller and lots of goodies. You
|
||||
* can use GCC to develop firmware for this.
|
||||
*
|
||||
* See Documentation/spi/butterfly for information about how to build
|
||||
* See Documentation/spi/butterfly.rst for information about how to build
|
||||
* and use this custom parallel port cable.
|
||||
*/
|
||||
|
||||
|
||||
@ -34,7 +34,7 @@
|
||||
* available (on page 4) here:
|
||||
* http://www.national.com/appinfo/tempsensors/files/LM70LLPEVALmanual.pdf
|
||||
*
|
||||
* Also see Documentation/spi/spi-lm70llp. The SPI<->parport code here is
|
||||
* Also see Documentation/spi/spi-lm70llp.rst. The SPI<->parport code here is
|
||||
* (heavily) based on spi-butterfly by David Brownell.
|
||||
*
|
||||
* The LM70 LLP connects to the PC parallel port in the following manner:
|
||||
|
||||
@ -4,7 +4,7 @@
|
||||
*
|
||||
* Copyright (C) 2012 Guenter Roeck <linux@roeck-us.net>
|
||||
*
|
||||
* For further information, see the Documentation/spi/spi-sc18is602 file.
|
||||
* For further information, see the Documentation/spi/spi-sc18is602.rst file.
|
||||
*/
|
||||
|
||||
/**
|
||||
|
||||
Loading…
Reference in New Issue
Block a user