Lines Matching +full:spi +full:- +full:controller
1 Overview of Linux kernel SPI support
4 02-Feb-2012
6 What is SPI?
7 ------------
8 The "Serial Peripheral Interface" (SPI) is a synchronous four wire serial
11 standardization body. SPI uses a master/slave configuration.
16 clocking modes through which data is exchanged; mode-0 and mode-3 are most
21 SPI masters use a fourth "chip select" line to activate a given SPI slave
23 in parallel. All SPI slaves support chipselects; they are usually active
28 SPI slave functions are usually not interoperable between vendors
29 (except for commodities like SPI memory chips).
31 - SPI may be used for request/response style device protocols, as with
34 - It may also be used to stream data in either direction (half duplex),
37 - Some devices may use eight bit words. Others may use different word
38 lengths, such as streams of 12-bit or 20-bit digital samples.
40 - Words are usually sent with their most significant bit (MSB) first,
43 - Sometimes SPI is used to daisy-chain devices, like shift registers.
45 In the same way, SPI slaves will only rarely support any kind of automatic
47 a given SPI master will normally be set up manually, with configuration
50 SPI is only one of the names used by such four-wire protocols, and
52 half-duplex SPI, for request/response protocols), SSP ("Synchronous
57 limiting themselves to half-duplex at the hardware level. In fact
58 some SPI chips have this signal mode as a strapping option. These
59 can be accessed using the same programming interface as SPI, but of
64 Microcontrollers often support both master and slave sides of the SPI
66 sides of SPI interactions.
70 ---------------------------------------
71 Linux developers using SPI are probably writing device drivers for embedded
72 systems boards. SPI is used to control external chips, and it is also a
75 support only SPI.) Some PC hardware uses SPI flash for BIOS code.
77 SPI slave chips range from digital/analog converters used for analog
81 Most systems using SPI will integrate a few devices on a mainboard.
82 Some provide SPI links on expansion connectors; in cases where no
83 dedicated SPI controller exists, GPIO pins can be used to create a
84 low speed "bitbanging" adapter. Very few systems will "hotplug" an SPI
85 controller; the reasons to use SPI focus on low cost and simple operation,
87 appropriate low-pincount peripheral bus.
90 interfaces with SPI modes. Given SPI support, they could use MMC or SD
91 cards without needing a special purpose MMC/SD/SDIO controller.
94 I'm confused. What are these four SPI "clock modes"?
95 -----------------------------------------------------
99 - CPOL indicates the initial clock polarity. CPOL=0 means the
104 - CPHA indicates the clock phase used to sample data; CPHA=0 says
111 Chip specs won't always say "uses SPI mode X" in as many words,
114 In the SPI mode number, CPOL is the high order bit and CPHA is the
117 trailing clock edge (CPHA=1), that's SPI mode 1.
128 ------------------------------------------------
129 The <linux/spi/spi.h> header file includes kerneldoc, as does the
134 SPI requests always go into I/O queues. Requests for a given SPI device
140 There are two types of SPI driver, here called:
142 Controller drivers ... controllers may be built into System-On-Chip
147 Protocol drivers ... these pass messages through the controller
149 other side of an SPI link.
152 data to filesystems stored on SPI flash like DataFlash; and others might
155 And those might all be sharing the same controller driver.
157 A "struct spi_device" encapsulates the controller-side interface between
160 There is a minimal core of SPI programming interfaces, focussing on
161 using the driver model to connect controller and protocol drivers using
162 device tables provided by board specific initialization code. SPI
165 /sys/devices/.../CTLR ... physical node for a given SPI controller
170 /sys/bus/spi/devices/spiB.C ... symlink to that physical
176 /sys/bus/spi/drivers/D ... driver for one or more spi*.* devices
179 a logical node which could hold class related state for the SPI
180 master controller managing bus "B". All spiB.* devices share one
181 physical SPI bus segment, with SCLK, MOSI, and MISO.
184 slave device for an SPI slave controller.
185 Writing the driver name of an SPI slave handler to this file
192 a logical node which could hold class related state for the SPI
193 slave controller on bus "B". When registered, a single spiB.*
194 device is present here, possible sharing the physical SPI bus
195 segment with other SPI slave devices.
197 Note that the actual location of the controller's class state depends
199 the only class-specific state is the bus number ("B" in "spiB"), so
203 How does board-specific init code declare SPI devices?
204 ------------------------------------------------------
205 Linux needs several kinds of information to properly configure SPI devices.
206 That information is normally provided by board-specific code, even for
211 The first kind of information is a list of what SPI controllers exist.
212 For System-on-Chip (SOC) based boards, these will usually be platform
213 devices, and the controller may need some platform_data in order to
215 like the physical address of the controller's first register and its IRQ.
217 Platforms will often abstract the "register SPI controller" operation,
219 the arch/.../mach-*/board-*.c files for several boards can all share the
220 same basic controller setup code. This is because most SOCs have several
221 SPI-capable controllers, and only the ones actually usable on a given
224 So for example arch/.../mach-*/board-*.c files might have code like:
226 #include <mach/spi.h> /* for mysoc_spi_data */
228 /* if your mach-* infrastructure doesn't support kernels that can
236 /* this board only uses SPI controller #2 */
241 And SOC-specific utility code might look something like:
243 #include <mach/spi.h>
255 spi2->dev.platform_data = pdata2;
268 same SOC controller is used. For example, on one board SPI might use
269 an external clock, where another derives the SPI clock from current
275 The second kind of information is a list of what SPI slave devices exist
276 on the target board, often with some board-specific data needed for the
279 Normally your arch/.../mach-*/board-*.c files would provide a small table
280 listing the SPI devices on each board. (This would typically be only a
301 Again, notice how board-specific information is provided; each chip may need
302 several types. This example shows generic constraints like the fastest SPI
304 is wired, plus chip-specific constraints like an important delay that's
308 controller driver. An example would be peripheral-specific DMA tuning
317 Then your board initialization code would register that table with the SPI
318 infrastructure, so that it's available later when the SPI master controller
323 Like with other static board-specific setup, you won't unregister those.
327 your arch/.../mach-.../board-*.c file would primarily provide information
329 certainly includes SPI devices hooked up through the card connectors!
332 NON-STATIC CONFIGURATIONS
335 example is the potential need to hotplug SPI devices and/or controllers.
338 up the spi bus master, and will likely need spi_new_device() to provide the
342 When Linux includes support for MMC/SD/SDIO/DataFlash cards through SPI, those
347 How do I write an "SPI Protocol Driver"?
348 ----------------------------------------
349 Most SPI drivers are currently kernel drivers, but there's also support
352 SPI protocol drivers somewhat resemble platform device drivers:
365 The driver core will automatically attempt to bind this driver to any SPI
370 static int CHIP_probe(struct spi_device *spi)
375 /* assuming the driver requires board-specific data: */
376 pdata = &spi->dev.platform_data;
378 return -ENODEV;
380 /* get memory for driver's per-chip state */
383 return -ENOMEM;
384 spi_set_drvdata(spi, chip);
391 the SPI device using "struct spi_message". When remove() returns,
395 - An spi_message is a sequence of protocol operations, executed
396 as one atomic sequence. SPI driver controls include:
418 - Follow standard kernel rules, and provide DMA-safe buffers in
419 your messages. That way controller drivers using DMA aren't forced
424 you can use spi_message.is_dma_mapped to tell the controller driver
427 - The basic I/O primitive is spi_async(). Async requests may be
433 - There are also synchronous wrappers like spi_sync(), and wrappers
438 - The spi_write_then_read() call, and convenience wrappers around
441 common RPC-style requests, such as writing an eight bit command
442 and reading a sixteen bit response -- spi_w8r16() being one its
457 of interacting with SPI devices.
459 - I/O buffers use the usual Linux rules, and must be DMA-safe.
463 - The spi_message and spi_transfer metadata used to glue those
466 other allocate-once driver data structures. Zero-init these.
469 routines are available to allocate and zero-initialize an spi_message
473 How do I write an "SPI Master Controller Driver"?
474 -------------------------------------------------
475 An SPI controller will probably be registered on the platform_bus; write
480 to get the driver-private data allocated for that device.
483 struct CONTROLLER *c;
487 return -ENODEV;
493 used to interact with the SPI core and SPI protocol drivers. It will
499 controller and any predeclared spi devices will be made available, and
502 If you need to remove your SPI controller driver, spi_unregister_master()
509 SPI bus (shared SCK, MOSI, MISO). Valid bus numbers start at zero. On
511 manufacturer. For example, hardware controller SPI2 would be bus number 2,
514 If you don't have such hardware-assigned bus number, and for some reason
517 this as a non-static configuration (see above).
520 SPI MASTER METHODS
522 master->setup(struct spi_device *spi)
523 This sets up the device clock rate, SPI mode, and word sizes.
525 call spi_setup(spi) to invoke this routine. It may sleep.
527 Unless each SPI slave has its own configuration registers, don't
529 that's in progress for other SPI devices.
533 ** When you code setup(), ASSUME that the controller
536 master->cleanup(struct spi_device *spi)
537 Your controller driver may use spi_device.controller_state to hold
541 master->prepare_transfer_hardware(struct spi_master *master)
547 master->unprepare_transfer_hardware(struct spi_master *master)
552 master->transfer_one_message(struct spi_master *master,
560 master->transfer_one(struct spi_master *master, struct spi_device *spi,
577 master->transfer(struct spi_device *spi, struct spi_message *message)
581 if the controller is idle it will need to be kickstarted. This
587 SPI MESSAGE QUEUE
590 SPI subsystem, just implement the queued methods specified above. Using
592 providing pure process-context execution of methods. The message queue
593 can also be elevated to realtime priority on high-priority SPI traffic.
595 Unless the queueing mechanism in the SPI subsystem is selected, the bulk
600 for low-frequency sensor access might be fine using synchronous PIO.
602 But the queue will probably be very real, using message->queue, PIO,
603 often DMA (especially if the root filesystem is in SPI flash), and
612 ---------
613 Contributors to Linux-SPI discussions include (in alphabetical order,