Back to home page

OSCL-LXR

 
 

    


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