0001 ====================================
0002 Overview of Linux kernel SPI support
0003 ====================================
0004
0005 02-Feb-2012
0006
0007 What is SPI?
0008 ------------
0009 The "Serial Peripheral Interface" (SPI) is a synchronous four wire serial
0010 link used to connect microcontrollers to sensors, memory, and peripherals.
0011 It's a simple "de facto" standard, not complicated enough to acquire a
0012 standardization body. SPI uses a master/slave configuration.
0013
0014 The three signal wires hold a clock (SCK, often on the order of 10 MHz),
0015 and parallel data lines with "Master Out, Slave In" (MOSI) or "Master In,
0016 Slave Out" (MISO) signals. (Other names are also used.) There are four
0017 clocking modes through which data is exchanged; mode-0 and mode-3 are most
0018 commonly used. Each clock cycle shifts data out and data in; the clock
0019 doesn't cycle except when there is a data bit to shift. Not all data bits
0020 are used though; not every protocol uses those full duplex capabilities.
0021
0022 SPI masters use a fourth "chip select" line to activate a given SPI slave
0023 device, so those three signal wires may be connected to several chips
0024 in parallel. All SPI slaves support chipselects; they are usually active
0025 low signals, labeled nCSx for slave 'x' (e.g. nCS0). Some devices have
0026 other signals, often including an interrupt to the master.
0027
0028 Unlike serial busses like USB or SMBus, even low level protocols for
0029 SPI slave functions are usually not interoperable between vendors
0030 (except for commodities like SPI memory chips).
0031
0032 - SPI may be used for request/response style device protocols, as with
0033 touchscreen sensors and memory chips.
0034
0035 - It may also be used to stream data in either direction (half duplex),
0036 or both of them at the same time (full duplex).
0037
0038 - Some devices may use eight bit words. Others may use different word
0039 lengths, such as streams of 12-bit or 20-bit digital samples.
0040
0041 - Words are usually sent with their most significant bit (MSB) first,
0042 but sometimes the least significant bit (LSB) goes first instead.
0043
0044 - Sometimes SPI is used to daisy-chain devices, like shift registers.
0045
0046 In the same way, SPI slaves will only rarely support any kind of automatic
0047 discovery/enumeration protocol. The tree of slave devices accessible from
0048 a given SPI master will normally be set up manually, with configuration
0049 tables.
0050
0051 SPI is only one of the names used by such four-wire protocols, and
0052 most controllers have no problem handling "MicroWire" (think of it as
0053 half-duplex SPI, for request/response protocols), SSP ("Synchronous
0054 Serial Protocol"), PSP ("Programmable Serial Protocol"), and other
0055 related protocols.
0056
0057 Some chips eliminate a signal line by combining MOSI and MISO, and
0058 limiting themselves to half-duplex at the hardware level. In fact
0059 some SPI chips have this signal mode as a strapping option. These
0060 can be accessed using the same programming interface as SPI, but of
0061 course they won't handle full duplex transfers. You may find such
0062 chips described as using "three wire" signaling: SCK, data, nCSx.
0063 (That data line is sometimes called MOMI or SISO.)
0064
0065 Microcontrollers often support both master and slave sides of the SPI
0066 protocol. This document (and Linux) supports both the master and slave
0067 sides of SPI interactions.
0068
0069
0070 Who uses it? On what kinds of systems?
0071 ---------------------------------------
0072 Linux developers using SPI are probably writing device drivers for embedded
0073 systems boards. SPI is used to control external chips, and it is also a
0074 protocol supported by every MMC or SD memory card. (The older "DataFlash"
0075 cards, predating MMC cards but using the same connectors and card shape,
0076 support only SPI.) Some PC hardware uses SPI flash for BIOS code.
0077
0078 SPI slave chips range from digital/analog converters used for analog
0079 sensors and codecs, to memory, to peripherals like USB controllers
0080 or Ethernet adapters; and more.
0081
0082 Most systems using SPI will integrate a few devices on a mainboard.
0083 Some provide SPI links on expansion connectors; in cases where no
0084 dedicated SPI controller exists, GPIO pins can be used to create a
0085 low speed "bitbanging" adapter. Very few systems will "hotplug" an SPI
0086 controller; the reasons to use SPI focus on low cost and simple operation,
0087 and if dynamic reconfiguration is important, USB will often be a more
0088 appropriate low-pincount peripheral bus.
0089
0090 Many microcontrollers that can run Linux integrate one or more I/O
0091 interfaces with SPI modes. Given SPI support, they could use MMC or SD
0092 cards without needing a special purpose MMC/SD/SDIO controller.
0093
0094
0095 I'm confused. What are these four SPI "clock modes"?
0096 -----------------------------------------------------
0097 It's easy to be confused here, and the vendor documentation you'll
0098 find isn't necessarily helpful. The four modes combine two mode bits:
0099
0100 - CPOL indicates the initial clock polarity. CPOL=0 means the
0101 clock starts low, so the first (leading) edge is rising, and
0102 the second (trailing) edge is falling. CPOL=1 means the clock
0103 starts high, so the first (leading) edge is falling.
0104
0105 - CPHA indicates the clock phase used to sample data; CPHA=0 says
0106 sample on the leading edge, CPHA=1 means the trailing edge.
0107
0108 Since the signal needs to stablize before it's sampled, CPHA=0
0109 implies that its data is written half a clock before the first
0110 clock edge. The chipselect may have made it become available.
0111
0112 Chip specs won't always say "uses SPI mode X" in as many words,
0113 but their timing diagrams will make the CPOL and CPHA modes clear.
0114
0115 In the SPI mode number, CPOL is the high order bit and CPHA is the
0116 low order bit. So when a chip's timing diagram shows the clock
0117 starting low (CPOL=0) and data stabilized for sampling during the
0118 trailing clock edge (CPHA=1), that's SPI mode 1.
0119
0120 Note that the clock mode is relevant as soon as the chipselect goes
0121 active. So the master must set the clock to inactive before selecting
0122 a slave, and the slave can tell the chosen polarity by sampling the
0123 clock level when its select line goes active. That's why many devices
0124 support for example both modes 0 and 3: they don't care about polarity,
0125 and always clock data in/out on rising clock edges.
0126
0127
0128 How do these driver programming interfaces work?
0129 ------------------------------------------------
0130 The <linux/spi/spi.h> header file includes kerneldoc, as does the
0131 main source code, and you should certainly read that chapter of the
0132 kernel API document. This is just an overview, so you get the big
0133 picture before those details.
0134
0135 SPI requests always go into I/O queues. Requests for a given SPI device
0136 are always executed in FIFO order, and complete asynchronously through
0137 completion callbacks. There are also some simple synchronous wrappers
0138 for those calls, including ones for common transaction types like writing
0139 a command and then reading its response.
0140
0141 There are two types of SPI driver, here called:
0142
0143 Controller drivers ...
0144 controllers may be built into System-On-Chip
0145 processors, and often support both Master and Slave roles.
0146 These drivers touch hardware registers and may use DMA.
0147 Or they can be PIO bitbangers, needing just GPIO pins.
0148
0149 Protocol drivers ...
0150 these pass messages through the controller
0151 driver to communicate with a Slave or Master device on the
0152 other side of an SPI link.
0153
0154 So for example one protocol driver might talk to the MTD layer to export
0155 data to filesystems stored on SPI flash like DataFlash; and others might
0156 control audio interfaces, present touchscreen sensors as input interfaces,
0157 or monitor temperature and voltage levels during industrial processing.
0158 And those might all be sharing the same controller driver.
0159
0160 A "struct spi_device" encapsulates the controller-side interface between
0161 those two types of drivers.
0162
0163 There is a minimal core of SPI programming interfaces, focussing on
0164 using the driver model to connect controller and protocol drivers using
0165 device tables provided by board specific initialization code. SPI
0166 shows up in sysfs in several locations::
0167
0168 /sys/devices/.../CTLR ... physical node for a given SPI controller
0169
0170 /sys/devices/.../CTLR/spiB.C ... spi_device on bus "B",
0171 chipselect C, accessed through CTLR.
0172
0173 /sys/bus/spi/devices/spiB.C ... symlink to that physical
0174 .../CTLR/spiB.C device
0175
0176 /sys/devices/.../CTLR/spiB.C/modalias ... identifies the driver
0177 that should be used with this device (for hotplug/coldplug)
0178
0179 /sys/bus/spi/drivers/D ... driver for one or more spi*.* devices
0180
0181 /sys/class/spi_master/spiB ... symlink (or actual device node) to
0182 a logical node which could hold class related state for the SPI
0183 master controller managing bus "B". All spiB.* devices share one
0184 physical SPI bus segment, with SCLK, MOSI, and MISO.
0185
0186 /sys/devices/.../CTLR/slave ... virtual file for (un)registering the
0187 slave device for an SPI slave controller.
0188 Writing the driver name of an SPI slave handler to this file
0189 registers the slave device; writing "(null)" unregisters the slave
0190 device.
0191 Reading from this file shows the name of the slave device ("(null)"
0192 if not registered).
0193
0194 /sys/class/spi_slave/spiB ... symlink (or actual device node) to
0195 a logical node which could hold class related state for the SPI
0196 slave controller on bus "B". When registered, a single spiB.*
0197 device is present here, possible sharing the physical SPI bus
0198 segment with other SPI slave devices.
0199
0200 Note that the actual location of the controller's class state depends
0201 on whether you enabled CONFIG_SYSFS_DEPRECATED or not. At this time,
0202 the only class-specific state is the bus number ("B" in "spiB"), so
0203 those /sys/class entries are only useful to quickly identify busses.
0204
0205
0206 How does board-specific init code declare SPI devices?
0207 ------------------------------------------------------
0208 Linux needs several kinds of information to properly configure SPI devices.
0209 That information is normally provided by board-specific code, even for
0210 chips that do support some of automated discovery/enumeration.
0211
0212 Declare Controllers
0213 ^^^^^^^^^^^^^^^^^^^
0214
0215 The first kind of information is a list of what SPI controllers exist.
0216 For System-on-Chip (SOC) based boards, these will usually be platform
0217 devices, and the controller may need some platform_data in order to
0218 operate properly. The "struct platform_device" will include resources
0219 like the physical address of the controller's first register and its IRQ.
0220
0221 Platforms will often abstract the "register SPI controller" operation,
0222 maybe coupling it with code to initialize pin configurations, so that
0223 the arch/.../mach-*/board-*.c files for several boards can all share the
0224 same basic controller setup code. This is because most SOCs have several
0225 SPI-capable controllers, and only the ones actually usable on a given
0226 board should normally be set up and registered.
0227
0228 So for example arch/.../mach-*/board-*.c files might have code like::
0229
0230 #include <mach/spi.h> /* for mysoc_spi_data */
0231
0232 /* if your mach-* infrastructure doesn't support kernels that can
0233 * run on multiple boards, pdata wouldn't benefit from "__init".
0234 */
0235 static struct mysoc_spi_data pdata __initdata = { ... };
0236
0237 static __init board_init(void)
0238 {
0239 ...
0240 /* this board only uses SPI controller #2 */
0241 mysoc_register_spi(2, &pdata);
0242 ...
0243 }
0244
0245 And SOC-specific utility code might look something like::
0246
0247 #include <mach/spi.h>
0248
0249 static struct platform_device spi2 = { ... };
0250
0251 void mysoc_register_spi(unsigned n, struct mysoc_spi_data *pdata)
0252 {
0253 struct mysoc_spi_data *pdata2;
0254
0255 pdata2 = kmalloc(sizeof *pdata2, GFP_KERNEL);
0256 *pdata2 = pdata;
0257 ...
0258 if (n == 2) {
0259 spi2->dev.platform_data = pdata2;
0260 register_platform_device(&spi2);
0261
0262 /* also: set up pin modes so the spi2 signals are
0263 * visible on the relevant pins ... bootloaders on
0264 * production boards may already have done this, but
0265 * developer boards will often need Linux to do it.
0266 */
0267 }
0268 ...
0269 }
0270
0271 Notice how the platform_data for boards may be different, even if the
0272 same SOC controller is used. For example, on one board SPI might use
0273 an external clock, where another derives the SPI clock from current
0274 settings of some master clock.
0275
0276 Declare Slave Devices
0277 ^^^^^^^^^^^^^^^^^^^^^
0278
0279 The second kind of information is a list of what SPI slave devices exist
0280 on the target board, often with some board-specific data needed for the
0281 driver to work correctly.
0282
0283 Normally your arch/.../mach-*/board-*.c files would provide a small table
0284 listing the SPI devices on each board. (This would typically be only a
0285 small handful.) That might look like::
0286
0287 static struct ads7846_platform_data ads_info = {
0288 .vref_delay_usecs = 100,
0289 .x_plate_ohms = 580,
0290 .y_plate_ohms = 410,
0291 };
0292
0293 static struct spi_board_info spi_board_info[] __initdata = {
0294 {
0295 .modalias = "ads7846",
0296 .platform_data = &ads_info,
0297 .mode = SPI_MODE_0,
0298 .irq = GPIO_IRQ(31),
0299 .max_speed_hz = 120000 /* max sample rate at 3V */ * 16,
0300 .bus_num = 1,
0301 .chip_select = 0,
0302 },
0303 };
0304
0305 Again, notice how board-specific information is provided; each chip may need
0306 several types. This example shows generic constraints like the fastest SPI
0307 clock to allow (a function of board voltage in this case) or how an IRQ pin
0308 is wired, plus chip-specific constraints like an important delay that's
0309 changed by the capacitance at one pin.
0310
0311 (There's also "controller_data", information that may be useful to the
0312 controller driver. An example would be peripheral-specific DMA tuning
0313 data or chipselect callbacks. This is stored in spi_device later.)
0314
0315 The board_info should provide enough information to let the system work
0316 without the chip's driver being loaded. The most troublesome aspect of
0317 that is likely the SPI_CS_HIGH bit in the spi_device.mode field, since
0318 sharing a bus with a device that interprets chipselect "backwards" is
0319 not possible until the infrastructure knows how to deselect it.
0320
0321 Then your board initialization code would register that table with the SPI
0322 infrastructure, so that it's available later when the SPI master controller
0323 driver is registered::
0324
0325 spi_register_board_info(spi_board_info, ARRAY_SIZE(spi_board_info));
0326
0327 Like with other static board-specific setup, you won't unregister those.
0328
0329 The widely used "card" style computers bundle memory, cpu, and little else
0330 onto a card that's maybe just thirty square centimeters. On such systems,
0331 your ``arch/.../mach-.../board-*.c`` file would primarily provide information
0332 about the devices on the mainboard into which such a card is plugged. That
0333 certainly includes SPI devices hooked up through the card connectors!
0334
0335
0336 Non-static Configurations
0337 ^^^^^^^^^^^^^^^^^^^^^^^^^
0338
0339 When Linux includes support for MMC/SD/SDIO/DataFlash cards through SPI, those
0340 configurations will also be dynamic. Fortunately, such devices all support
0341 basic device identification probes, so they should hotplug normally.
0342
0343
0344 How do I write an "SPI Protocol Driver"?
0345 ----------------------------------------
0346 Most SPI drivers are currently kernel drivers, but there's also support
0347 for userspace drivers. Here we talk only about kernel drivers.
0348
0349 SPI protocol drivers somewhat resemble platform device drivers::
0350
0351 static struct spi_driver CHIP_driver = {
0352 .driver = {
0353 .name = "CHIP",
0354 .owner = THIS_MODULE,
0355 .pm = &CHIP_pm_ops,
0356 },
0357
0358 .probe = CHIP_probe,
0359 .remove = CHIP_remove,
0360 };
0361
0362 The driver core will automatically attempt to bind this driver to any SPI
0363 device whose board_info gave a modalias of "CHIP". Your probe() code
0364 might look like this unless you're creating a device which is managing
0365 a bus (appearing under /sys/class/spi_master).
0366
0367 ::
0368
0369 static int CHIP_probe(struct spi_device *spi)
0370 {
0371 struct CHIP *chip;
0372 struct CHIP_platform_data *pdata;
0373
0374 /* assuming the driver requires board-specific data: */
0375 pdata = &spi->dev.platform_data;
0376 if (!pdata)
0377 return -ENODEV;
0378
0379 /* get memory for driver's per-chip state */
0380 chip = kzalloc(sizeof *chip, GFP_KERNEL);
0381 if (!chip)
0382 return -ENOMEM;
0383 spi_set_drvdata(spi, chip);
0384
0385 ... etc
0386 return 0;
0387 }
0388
0389 As soon as it enters probe(), the driver may issue I/O requests to
0390 the SPI device using "struct spi_message". When remove() returns,
0391 or after probe() fails, the driver guarantees that it won't submit
0392 any more such messages.
0393
0394 - An spi_message is a sequence of protocol operations, executed
0395 as one atomic sequence. SPI driver controls include:
0396
0397 + when bidirectional reads and writes start ... by how its
0398 sequence of spi_transfer requests is arranged;
0399
0400 + which I/O buffers are used ... each spi_transfer wraps a
0401 buffer for each transfer direction, supporting full duplex
0402 (two pointers, maybe the same one in both cases) and half
0403 duplex (one pointer is NULL) transfers;
0404
0405 + optionally defining short delays after transfers ... using
0406 the spi_transfer.delay.value setting (this delay can be the
0407 only protocol effect, if the buffer length is zero) ...
0408 when specifying this delay the default spi_transfer.delay.unit
0409 is microseconds, however this can be adjusted to clock cycles
0410 or nanoseconds if needed;
0411
0412 + whether the chipselect becomes inactive after a transfer and
0413 any delay ... by using the spi_transfer.cs_change flag;
0414
0415 + hinting whether the next message is likely to go to this same
0416 device ... using the spi_transfer.cs_change flag on the last
0417 transfer in that atomic group, and potentially saving costs
0418 for chip deselect and select operations.
0419
0420 - Follow standard kernel rules, and provide DMA-safe buffers in
0421 your messages. That way controller drivers using DMA aren't forced
0422 to make extra copies unless the hardware requires it (e.g. working
0423 around hardware errata that force the use of bounce buffering).
0424
0425 If standard dma_map_single() handling of these buffers is inappropriate,
0426 you can use spi_message.is_dma_mapped to tell the controller driver
0427 that you've already provided the relevant DMA addresses.
0428
0429 - The basic I/O primitive is spi_async(). Async requests may be
0430 issued in any context (irq handler, task, etc) and completion
0431 is reported using a callback provided with the message.
0432 After any detected error, the chip is deselected and processing
0433 of that spi_message is aborted.
0434
0435 - There are also synchronous wrappers like spi_sync(), and wrappers
0436 like spi_read(), spi_write(), and spi_write_then_read(). These
0437 may be issued only in contexts that may sleep, and they're all
0438 clean (and small, and "optional") layers over spi_async().
0439
0440 - The spi_write_then_read() call, and convenience wrappers around
0441 it, should only be used with small amounts of data where the
0442 cost of an extra copy may be ignored. It's designed to support
0443 common RPC-style requests, such as writing an eight bit command
0444 and reading a sixteen bit response -- spi_w8r16() being one its
0445 wrappers, doing exactly that.
0446
0447 Some drivers may need to modify spi_device characteristics like the
0448 transfer mode, wordsize, or clock rate. This is done with spi_setup(),
0449 which would normally be called from probe() before the first I/O is
0450 done to the device. However, that can also be called at any time
0451 that no message is pending for that device.
0452
0453 While "spi_device" would be the bottom boundary of the driver, the
0454 upper boundaries might include sysfs (especially for sensor readings),
0455 the input layer, ALSA, networking, MTD, the character device framework,
0456 or other Linux subsystems.
0457
0458 Note that there are two types of memory your driver must manage as part
0459 of interacting with SPI devices.
0460
0461 - I/O buffers use the usual Linux rules, and must be DMA-safe.
0462 You'd normally allocate them from the heap or free page pool.
0463 Don't use the stack, or anything that's declared "static".
0464
0465 - The spi_message and spi_transfer metadata used to glue those
0466 I/O buffers into a group of protocol transactions. These can
0467 be allocated anywhere it's convenient, including as part of
0468 other allocate-once driver data structures. Zero-init these.
0469
0470 If you like, spi_message_alloc() and spi_message_free() convenience
0471 routines are available to allocate and zero-initialize an spi_message
0472 with several transfers.
0473
0474
0475 How do I write an "SPI Master Controller Driver"?
0476 -------------------------------------------------
0477 An SPI controller will probably be registered on the platform_bus; write
0478 a driver to bind to the device, whichever bus is involved.
0479
0480 The main task of this type of driver is to provide an "spi_master".
0481 Use spi_alloc_master() to allocate the master, and spi_master_get_devdata()
0482 to get the driver-private data allocated for that device.
0483
0484 ::
0485
0486 struct spi_master *master;
0487 struct CONTROLLER *c;
0488
0489 master = spi_alloc_master(dev, sizeof *c);
0490 if (!master)
0491 return -ENODEV;
0492
0493 c = spi_master_get_devdata(master);
0494
0495 The driver will initialize the fields of that spi_master, including the
0496 bus number (maybe the same as the platform device ID) and three methods
0497 used to interact with the SPI core and SPI protocol drivers. It will
0498 also initialize its own internal state. (See below about bus numbering
0499 and those methods.)
0500
0501 After you initialize the spi_master, then use spi_register_master() to
0502 publish it to the rest of the system. At that time, device nodes for the
0503 controller and any predeclared spi devices will be made available, and
0504 the driver model core will take care of binding them to drivers.
0505
0506 If you need to remove your SPI controller driver, spi_unregister_master()
0507 will reverse the effect of spi_register_master().
0508
0509
0510 Bus Numbering
0511 ^^^^^^^^^^^^^
0512
0513 Bus numbering is important, since that's how Linux identifies a given
0514 SPI bus (shared SCK, MOSI, MISO). Valid bus numbers start at zero. On
0515 SOC systems, the bus numbers should match the numbers defined by the chip
0516 manufacturer. For example, hardware controller SPI2 would be bus number 2,
0517 and spi_board_info for devices connected to it would use that number.
0518
0519 If you don't have such hardware-assigned bus number, and for some reason
0520 you can't just assign them, then provide a negative bus number. That will
0521 then be replaced by a dynamically assigned number. You'd then need to treat
0522 this as a non-static configuration (see above).
0523
0524
0525 SPI Master Methods
0526 ^^^^^^^^^^^^^^^^^^
0527
0528 ``master->setup(struct spi_device *spi)``
0529 This sets up the device clock rate, SPI mode, and word sizes.
0530 Drivers may change the defaults provided by board_info, and then
0531 call spi_setup(spi) to invoke this routine. It may sleep.
0532
0533 Unless each SPI slave has its own configuration registers, don't
0534 change them right away ... otherwise drivers could corrupt I/O
0535 that's in progress for other SPI devices.
0536
0537 .. note::
0538
0539 BUG ALERT: for some reason the first version of
0540 many spi_master drivers seems to get this wrong.
0541 When you code setup(), ASSUME that the controller
0542 is actively processing transfers for another device.
0543
0544 ``master->cleanup(struct spi_device *spi)``
0545 Your controller driver may use spi_device.controller_state to hold
0546 state it dynamically associates with that device. If you do that,
0547 be sure to provide the cleanup() method to free that state.
0548
0549 ``master->prepare_transfer_hardware(struct spi_master *master)``
0550 This will be called by the queue mechanism to signal to the driver
0551 that a message is coming in soon, so the subsystem requests the
0552 driver to prepare the transfer hardware by issuing this call.
0553 This may sleep.
0554
0555 ``master->unprepare_transfer_hardware(struct spi_master *master)``
0556 This will be called by the queue mechanism to signal to the driver
0557 that there are no more messages pending in the queue and it may
0558 relax the hardware (e.g. by power management calls). This may sleep.
0559
0560 ``master->transfer_one_message(struct spi_master *master, struct spi_message *mesg)``
0561 The subsystem calls the driver to transfer a single message while
0562 queuing transfers that arrive in the meantime. When the driver is
0563 finished with this message, it must call
0564 spi_finalize_current_message() so the subsystem can issue the next
0565 message. This may sleep.
0566
0567 ``master->transfer_one(struct spi_master *master, struct spi_device *spi, struct spi_transfer *transfer)``
0568 The subsystem calls the driver to transfer a single transfer while
0569 queuing transfers that arrive in the meantime. When the driver is
0570 finished with this transfer, it must call
0571 spi_finalize_current_transfer() so the subsystem can issue the next
0572 transfer. This may sleep. Note: transfer_one and transfer_one_message
0573 are mutually exclusive; when both are set, the generic subsystem does
0574 not call your transfer_one callback.
0575
0576 Return values:
0577
0578 * negative errno: error
0579 * 0: transfer is finished
0580 * 1: transfer is still in progress
0581
0582 ``master->set_cs_timing(struct spi_device *spi, u8 setup_clk_cycles, u8 hold_clk_cycles, u8 inactive_clk_cycles)``
0583 This method allows SPI client drivers to request SPI master controller
0584 for configuring device specific CS setup, hold and inactive timing
0585 requirements.
0586
0587 Deprecated Methods
0588 ^^^^^^^^^^^^^^^^^^
0589
0590 ``master->transfer(struct spi_device *spi, struct spi_message *message)``
0591 This must not sleep. Its responsibility is to arrange that the
0592 transfer happens and its complete() callback is issued. The two
0593 will normally happen later, after other transfers complete, and
0594 if the controller is idle it will need to be kickstarted. This
0595 method is not used on queued controllers and must be NULL if
0596 transfer_one_message() and (un)prepare_transfer_hardware() are
0597 implemented.
0598
0599
0600 SPI Message Queue
0601 ^^^^^^^^^^^^^^^^^
0602
0603 If you are happy with the standard queueing mechanism provided by the
0604 SPI subsystem, just implement the queued methods specified above. Using
0605 the message queue has the upside of centralizing a lot of code and
0606 providing pure process-context execution of methods. The message queue
0607 can also be elevated to realtime priority on high-priority SPI traffic.
0608
0609 Unless the queueing mechanism in the SPI subsystem is selected, the bulk
0610 of the driver will be managing the I/O queue fed by the now deprecated
0611 function transfer().
0612
0613 That queue could be purely conceptual. For example, a driver used only
0614 for low-frequency sensor access might be fine using synchronous PIO.
0615
0616 But the queue will probably be very real, using message->queue, PIO,
0617 often DMA (especially if the root filesystem is in SPI flash), and
0618 execution contexts like IRQ handlers, tasklets, or workqueues (such
0619 as keventd). Your driver can be as fancy, or as simple, as you need.
0620 Such a transfer() method would normally just add the message to a
0621 queue, and then start some asynchronous transfer engine (unless it's
0622 already running).
0623
0624
0625 THANKS TO
0626 ---------
0627 Contributors to Linux-SPI discussions include (in alphabetical order,
0628 by last name):
0629
0630 - Mark Brown
0631 - David Brownell
0632 - Russell King
0633 - Grant Likely
0634 - Dmitry Pervushin
0635 - Stephen Street
0636 - Mark Underwood
0637 - Andrew Victor
0638 - Linus Walleij
0639 - Vitaly Wool