Lines Matching +full:spi +full:- +full:slave
2 Overview of Linux kernel SPI support
5 02-Feb-2012
7 What is SPI?
8 ------------
9 The "Serial Peripheral Interface" (SPI) is a synchronous four wire serial
12 standardization body. SPI uses a master/slave configuration.
15 and parallel data lines with "Master Out, Slave In" (MOSI) or "Master In,
16 Slave Out" (MISO) signals. (Other names are also used.) There are four
17 clocking modes through which data is exchanged; mode-0 and mode-3 are most
22 SPI masters use a fourth "chip select" line to activate a given SPI slave
24 in parallel. All SPI slaves support chipselects; they are usually active
25 low signals, labeled nCSx for slave 'x' (e.g. nCS0). Some devices have
29 SPI slave functions are usually not interoperable between vendors
30 (except for commodities like SPI memory chips).
32 - SPI may be used for request/response style device protocols, as with
35 - It may also be used to stream data in either direction (half duplex),
38 - Some devices may use eight bit words. Others may use different word
39 lengths, such as streams of 12-bit or 20-bit digital samples.
41 - Words are usually sent with their most significant bit (MSB) first,
44 - Sometimes SPI is used to daisy-chain devices, like shift registers.
46 In the same way, SPI slaves will only rarely support any kind of automatic
47 discovery/enumeration protocol. The tree of slave devices accessible from
48 a given SPI master will normally be set up manually, with configuration
51 SPI is only one of the names used by such four-wire protocols, and
53 half-duplex SPI, for request/response protocols), SSP ("Synchronous
58 limiting themselves to half-duplex at the hardware level. In fact
59 some SPI chips have this signal mode as a strapping option. These
60 can be accessed using the same programming interface as SPI, but of
65 Microcontrollers often support both master and slave sides of the SPI
66 protocol. This document (and Linux) supports both the master and slave
67 sides of SPI interactions.
71 ---------------------------------------
72 Linux developers using SPI are probably writing device drivers for embedded
73 systems boards. SPI is used to control external chips, and it is also a
76 support only SPI.) Some PC hardware uses SPI flash for BIOS code.
78 SPI slave chips range from digital/analog converters used for analog
82 Most systems using SPI will integrate a few devices on a mainboard.
83 Some provide SPI links on expansion connectors; in cases where no
84 dedicated SPI controller exists, GPIO pins can be used to create a
85 low speed "bitbanging" adapter. Very few systems will "hotplug" an SPI
86 controller; the reasons to use SPI focus on low cost and simple operation,
88 appropriate low-pincount peripheral bus.
91 interfaces with SPI modes. Given SPI support, they could use MMC or SD
95 I'm confused. What are these four SPI "clock modes"?
96 -----------------------------------------------------
100 - CPOL indicates the initial clock polarity. CPOL=0 means the
105 - CPHA indicates the clock phase used to sample data; CPHA=0 says
112 Chip specs won't always say "uses SPI mode X" in as many words,
115 In the SPI mode number, CPOL is the high order bit and CPHA is the
118 trailing clock edge (CPHA=1), that's SPI mode 1.
122 a slave, and the slave can tell the chosen polarity by sampling the
129 ------------------------------------------------
130 The <linux/spi/spi.h> header file includes kerneldoc, as does the
135 SPI requests always go into I/O queues. Requests for a given SPI device
141 There are two types of SPI driver, here called:
144 controllers may be built into System-On-Chip
145 processors, and often support both Master and Slave roles.
151 driver to communicate with a Slave or Master device on the
152 other side of an SPI link.
155 data to filesystems stored on SPI flash like DataFlash; and others might
160 A "struct spi_device" encapsulates the controller-side interface between
163 There is a minimal core of SPI programming interfaces, focussing on
165 device tables provided by board specific initialization code. SPI
168 /sys/devices/.../CTLR ... physical node for a given SPI controller
173 /sys/bus/spi/devices/spiB.C ... symlink to that physical
179 /sys/bus/spi/drivers/D ... driver for one or more spi*.* devices
182 a logical node which could hold class related state for the SPI
184 physical SPI bus segment, with SCLK, MOSI, and MISO.
186 /sys/devices/.../CTLR/slave ... virtual file for (un)registering the
187 slave device for an SPI slave controller.
188 Writing the driver name of an SPI slave handler to this file
189 registers the slave device; writing "(null)" unregisters the slave
191 Reading from this file shows the name of the slave device ("(null)"
195 a logical node which could hold class related state for the SPI
196 slave controller on bus "B". When registered, a single spiB.*
197 device is present here, possible sharing the physical SPI bus
198 segment with other SPI slave devices.
202 the only class-specific state is the bus number ("B" in "spiB"), so
206 How does board-specific init code declare SPI devices?
207 ------------------------------------------------------
208 Linux needs several kinds of information to properly configure SPI devices.
209 That information is normally provided by board-specific code, even for
215 The first kind of information is a list of what SPI controllers exist.
216 For System-on-Chip (SOC) based boards, these will usually be platform
221 Platforms will often abstract the "register SPI controller" operation,
223 the arch/.../mach-*/board-*.c files for several boards can all share the
225 SPI-capable controllers, and only the ones actually usable on a given
228 So for example arch/.../mach-*/board-*.c files might have code like::
230 #include <mach/spi.h> /* for mysoc_spi_data */
232 /* if your mach-* infrastructure doesn't support kernels that can
240 /* this board only uses SPI controller #2 */
245 And SOC-specific utility code might look something like::
247 #include <mach/spi.h>
259 spi2->dev.platform_data = pdata2;
272 same SOC controller is used. For example, on one board SPI might use
273 an external clock, where another derives the SPI clock from current
276 Declare Slave Devices
279 The second kind of information is a list of what SPI slave devices exist
280 on the target board, often with some board-specific data needed for the
283 Normally your arch/.../mach-*/board-*.c files would provide a small table
284 listing the SPI devices on each board. (This would typically be only a
305 Again, notice how board-specific information is provided; each chip may need
306 several types. This example shows generic constraints like the fastest SPI
308 is wired, plus chip-specific constraints like an important delay that's
312 controller driver. An example would be peripheral-specific DMA tuning
321 Then your board initialization code would register that table with the SPI
322 infrastructure, so that it's available later when the SPI master controller
327 Like with other static board-specific setup, you won't unregister those.
331 your ``arch/.../mach-.../board-*.c`` file would primarily provide information
333 certainly includes SPI devices hooked up through the card connectors!
336 Non-static Configurations
340 example is the potential need to hotplug SPI devices and/or controllers.
343 up the spi bus master, and will likely need spi_new_device() to provide the
347 When Linux includes support for MMC/SD/SDIO/DataFlash cards through SPI, those
352 How do I write an "SPI Protocol Driver"?
353 ----------------------------------------
354 Most SPI drivers are currently kernel drivers, but there's also support
357 SPI protocol drivers somewhat resemble platform device drivers::
370 The driver core will automatically attempt to bind this driver to any SPI
377 static int CHIP_probe(struct spi_device *spi)
382 /* assuming the driver requires board-specific data: */
383 pdata = &spi->dev.platform_data;
385 return -ENODEV;
387 /* get memory for driver's per-chip state */
390 return -ENOMEM;
391 spi_set_drvdata(spi, chip);
398 the SPI device using "struct spi_message". When remove() returns,
402 - An spi_message is a sequence of protocol operations, executed
403 as one atomic sequence. SPI driver controls include:
428 - Follow standard kernel rules, and provide DMA-safe buffers in
437 - The basic I/O primitive is spi_async(). Async requests may be
443 - There are also synchronous wrappers like spi_sync(), and wrappers
448 - The spi_write_then_read() call, and convenience wrappers around
451 common RPC-style requests, such as writing an eight bit command
452 and reading a sixteen bit response -- spi_w8r16() being one its
467 of interacting with SPI devices.
469 - I/O buffers use the usual Linux rules, and must be DMA-safe.
473 - The spi_message and spi_transfer metadata used to glue those
476 other allocate-once driver data structures. Zero-init these.
479 routines are available to allocate and zero-initialize an spi_message
483 How do I write an "SPI Master Controller Driver"?
484 -------------------------------------------------
485 An SPI controller will probably be registered on the platform_bus; write
490 to get the driver-private data allocated for that device.
499 return -ENODEV;
505 used to interact with the SPI core and SPI protocol drivers. It will
511 controller and any predeclared spi devices will be made available, and
514 If you need to remove your SPI controller driver, spi_unregister_master()
522 SPI bus (shared SCK, MOSI, MISO). Valid bus numbers start at zero. On
527 If you don't have such hardware-assigned bus number, and for some reason
530 this as a non-static configuration (see above).
533 SPI Master Methods
536 ``master->setup(struct spi_device *spi)``
537 This sets up the device clock rate, SPI mode, and word sizes.
539 call spi_setup(spi) to invoke this routine. It may sleep.
541 Unless each SPI slave has its own configuration registers, don't
543 that's in progress for other SPI devices.
552 ``master->cleanup(struct spi_device *spi)``
557 ``master->prepare_transfer_hardware(struct spi_master *master)``
563 ``master->unprepare_transfer_hardware(struct spi_master *master)``
568 ``master->transfer_one_message(struct spi_master *master, struct spi_message *mesg)``
575 ``master->transfer_one(struct spi_master *master, struct spi_device *spi, struct spi_transfer *tran…
590 ``master->set_cs_timing(struct spi_device *spi, u8 setup_clk_cycles, u8 hold_clk_cycles, u8 inactiv…
591 This method allows SPI client drivers to request SPI master controller
598 ``master->transfer(struct spi_device *spi, struct spi_message *message)``
608 SPI Message Queue
612 SPI subsystem, just implement the queued methods specified above. Using
614 providing pure process-context execution of methods. The message queue
615 can also be elevated to realtime priority on high-priority SPI traffic.
617 Unless the queueing mechanism in the SPI subsystem is selected, the bulk
622 for low-frequency sensor access might be fine using synchronous PIO.
624 But the queue will probably be very real, using message->queue, PIO,
625 often DMA (especially if the root filesystem is in SPI flash), and
634 ---------
635 Contributors to Linux-SPI discussions include (in alphabetical order,
638 - Mark Brown
639 - David Brownell
640 - Russell King
641 - Grant Likely
642 - Dmitry Pervushin
643 - Stephen Street
644 - Mark Underwood
645 - Andrew Victor
646 - Linus Walleij
647 - Vitaly Wool