linux/Documentation/spi/spi-summary.rst
<<
>>
Prefs
   1====================================
   2Overview of Linux kernel SPI support
   3====================================
   4
   502-Feb-2012
   6
   7What is SPI?
   8------------
   9The "Serial Peripheral Interface" (SPI) is a synchronous four wire serial
  10link used to connect microcontrollers to sensors, memory, and peripherals.
  11It's a simple "de facto" standard, not complicated enough to acquire a
  12standardization body.  SPI uses a master/slave configuration.
  13
  14The three signal wires hold a clock (SCK, often on the order of 10 MHz),
  15and parallel data lines with "Master Out, Slave In" (MOSI) or "Master In,
  16Slave Out" (MISO) signals.  (Other names are also used.)  There are four
  17clocking modes through which data is exchanged; mode-0 and mode-3 are most
  18commonly used.  Each clock cycle shifts data out and data in; the clock
  19doesn't cycle except when there is a data bit to shift.  Not all data bits
  20are used though; not every protocol uses those full duplex capabilities.
  21
  22SPI masters use a fourth "chip select" line to activate a given SPI slave
  23device, so those three signal wires may be connected to several chips
  24in parallel.  All SPI slaves support chipselects; they are usually active
  25low signals, labeled nCSx for slave 'x' (e.g. nCS0).  Some devices have
  26other signals, often including an interrupt to the master.
  27
  28Unlike serial busses like USB or SMBus, even low level protocols for
  29SPI slave functions are usually not interoperable between vendors
  30(except for commodities like SPI memory chips).
  31
  32  - SPI may be used for request/response style device protocols, as with
  33    touchscreen sensors and memory chips.
  34
  35  - It may also be used to stream data in either direction (half duplex),
  36    or both of them at the same time (full duplex).
  37
  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.
  40
  41  - Words are usually sent with their most significant bit (MSB) first,
  42    but sometimes the least significant bit (LSB) goes first instead.
  43
  44  - Sometimes SPI is used to daisy-chain devices, like shift registers.
  45
  46In the same way, SPI slaves will only rarely support any kind of automatic
  47discovery/enumeration protocol.  The tree of slave devices accessible from
  48a given SPI master will normally be set up manually, with configuration
  49tables.
  50
  51SPI is only one of the names used by such four-wire protocols, and
  52most controllers have no problem handling "MicroWire" (think of it as
  53half-duplex SPI, for request/response protocols), SSP ("Synchronous
  54Serial Protocol"), PSP ("Programmable Serial Protocol"), and other
  55related protocols.
  56
  57Some chips eliminate a signal line by combining MOSI and MISO, and
  58limiting themselves to half-duplex at the hardware level.  In fact
  59some SPI chips have this signal mode as a strapping option.  These
  60can be accessed using the same programming interface as SPI, but of
  61course they won't handle full duplex transfers.  You may find such
  62chips described as using "three wire" signaling: SCK, data, nCSx.
  63(That data line is sometimes called MOMI or SISO.)
  64
  65Microcontrollers often support both master and slave sides of the SPI
  66protocol.  This document (and Linux) supports both the master and slave
  67sides of SPI interactions.
  68
  69
  70Who uses it?  On what kinds of systems?
  71---------------------------------------
  72Linux developers using SPI are probably writing device drivers for embedded
  73systems boards.  SPI is used to control external chips, and it is also a
  74protocol supported by every MMC or SD memory card.  (The older "DataFlash"
  75cards, predating MMC cards but using the same connectors and card shape,
  76support only SPI.)  Some PC hardware uses SPI flash for BIOS code.
  77
  78SPI slave chips range from digital/analog converters used for analog
  79sensors and codecs, to memory, to peripherals like USB controllers
  80or Ethernet adapters; and more.
  81
  82Most systems using SPI will integrate a few devices on a mainboard.
  83Some provide SPI links on expansion connectors; in cases where no
  84dedicated SPI controller exists, GPIO pins can be used to create a
  85low speed "bitbanging" adapter.  Very few systems will "hotplug" an SPI
  86controller; the reasons to use SPI focus on low cost and simple operation,
  87and if dynamic reconfiguration is important, USB will often be a more
  88appropriate low-pincount peripheral bus.
  89
  90Many microcontrollers that can run Linux integrate one or more I/O
  91interfaces with SPI modes.  Given SPI support, they could use MMC or SD
  92cards without needing a special purpose MMC/SD/SDIO controller.
  93
  94
  95I'm confused.  What are these four SPI "clock modes"?
  96-----------------------------------------------------
  97It's easy to be confused here, and the vendor documentation you'll
  98find isn't necessarily helpful.  The four modes combine two mode bits:
  99
 100 - CPOL indicates the initial clock polarity.  CPOL=0 means the
 101   clock starts low, so the first (leading) edge is rising, and
 102   the second (trailing) edge is falling.  CPOL=1 means the clock
 103   starts high, so the first (leading) edge is falling.
 104
 105 - CPHA indicates the clock phase used to sample data; CPHA=0 says
 106   sample on the leading edge, CPHA=1 means the trailing edge.
 107
 108   Since the signal needs to stablize before it's sampled, CPHA=0
 109   implies that its data is written half a clock before the first
 110   clock edge.  The chipselect may have made it become available.
 111
 112Chip specs won't always say "uses SPI mode X" in as many words,
 113but their timing diagrams will make the CPOL and CPHA modes clear.
 114
 115In the SPI mode number, CPOL is the high order bit and CPHA is the
 116low order bit.  So when a chip's timing diagram shows the clock
 117starting low (CPOL=0) and data stabilized for sampling during the
 118trailing clock edge (CPHA=1), that's SPI mode 1.
 119
 120Note that the clock mode is relevant as soon as the chipselect goes
 121active.  So the master must set the clock to inactive before selecting
 122a slave, and the slave can tell the chosen polarity by sampling the
 123clock level when its select line goes active.  That's why many devices
 124support for example both modes 0 and 3:  they don't care about polarity,
 125and always clock data in/out on rising clock edges.
 126
 127
 128How do these driver programming interfaces work?
 129------------------------------------------------
 130The <linux/spi/spi.h> header file includes kerneldoc, as does the
 131main source code, and you should certainly read that chapter of the
 132kernel API document.  This is just an overview, so you get the big
 133picture before those details.
 134
 135SPI requests always go into I/O queues.  Requests for a given SPI device
 136are always executed in FIFO order, and complete asynchronously through
 137completion callbacks.  There are also some simple synchronous wrappers
 138for those calls, including ones for common transaction types like writing
 139a command and then reading its response.
 140
 141There are two types of SPI driver, here called:
 142
 143  Controller drivers ...
 144        controllers may be built into System-On-Chip
 145        processors, and often support both Master and Slave roles.
 146        These drivers touch hardware registers and may use DMA.
 147        Or they can be PIO bitbangers, needing just GPIO pins.
 148
 149  Protocol drivers ...
 150        these pass messages through the controller
 151        driver to communicate with a Slave or Master device on the
 152        other side of an SPI link.
 153
 154So for example one protocol driver might talk to the MTD layer to export
 155data to filesystems stored on SPI flash like DataFlash; and others might
 156control audio interfaces, present touchscreen sensors as input interfaces,
 157or monitor temperature and voltage levels during industrial processing.
 158And those might all be sharing the same controller driver.
 159
 160A "struct spi_device" encapsulates the controller-side interface between
 161those two types of drivers.
 162
 163There is a minimal core of SPI programming interfaces, focussing on
 164using the driver model to connect controller and protocol drivers using
 165device tables provided by board specific initialization code.  SPI
 166shows up in sysfs in several locations::
 167
 168   /sys/devices/.../CTLR ... physical node for a given SPI controller
 169
 170   /sys/devices/.../CTLR/spiB.C ... spi_device on bus "B",
 171        chipselect C, accessed through CTLR.
 172
 173   /sys/bus/spi/devices/spiB.C ... symlink to that physical
 174        .../CTLR/spiB.C device
 175
 176   /sys/devices/.../CTLR/spiB.C/modalias ... identifies the driver
 177        that should be used with this device (for hotplug/coldplug)
 178
 179   /sys/bus/spi/drivers/D ... driver for one or more spi*.* devices
 180
 181   /sys/class/spi_master/spiB ... symlink (or actual device node) to
 182        a logical node which could hold class related state for the SPI
 183        master controller managing bus "B".  All spiB.* devices share one
 184        physical SPI bus segment, with SCLK, MOSI, and MISO.
 185
 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
 190        device.
 191        Reading from this file shows the name of the slave device ("(null)"
 192        if not registered).
 193
 194   /sys/class/spi_slave/spiB ... symlink (or actual device node) to
 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.
 199
 200Note that the actual location of the controller's class state depends
 201on whether you enabled CONFIG_SYSFS_DEPRECATED or not.  At this time,
 202the only class-specific state is the bus number ("B" in "spiB"), so
 203those /sys/class entries are only useful to quickly identify busses.
 204
 205
 206How does board-specific init code declare SPI devices?
 207------------------------------------------------------
 208Linux needs several kinds of information to properly configure SPI devices.
 209That information is normally provided by board-specific code, even for
 210chips that do support some of automated discovery/enumeration.
 211
 212Declare Controllers
 213^^^^^^^^^^^^^^^^^^^
 214
 215The first kind of information is a list of what SPI controllers exist.
 216For System-on-Chip (SOC) based boards, these will usually be platform
 217devices, and the controller may need some platform_data in order to
 218operate properly.  The "struct platform_device" will include resources
 219like the physical address of the controller's first register and its IRQ.
 220
 221Platforms will often abstract the "register SPI controller" operation,
 222maybe coupling it with code to initialize pin configurations, so that
 223the arch/.../mach-*/board-*.c files for several boards can all share the
 224same basic controller setup code.  This is because most SOCs have several
 225SPI-capable controllers, and only the ones actually usable on a given
 226board should normally be set up and registered.
 227
 228So for example arch/.../mach-*/board-*.c files might have code like::
 229
 230        #include <mach/spi.h>   /* for mysoc_spi_data */
 231
 232        /* if your mach-* infrastructure doesn't support kernels that can
 233         * run on multiple boards, pdata wouldn't benefit from "__init".
 234         */
 235        static struct mysoc_spi_data pdata __initdata = { ... };
 236
 237        static __init board_init(void)
 238        {
 239                ...
 240                /* this board only uses SPI controller #2 */
 241                mysoc_register_spi(2, &pdata);
 242                ...
 243        }
 244
 245And SOC-specific utility code might look something like::
 246
 247        #include <mach/spi.h>
 248
 249        static struct platform_device spi2 = { ... };
 250
 251        void mysoc_register_spi(unsigned n, struct mysoc_spi_data *pdata)
 252        {
 253                struct mysoc_spi_data *pdata2;
 254
 255                pdata2 = kmalloc(sizeof *pdata2, GFP_KERNEL);
 256                *pdata2 = pdata;
 257                ...
 258                if (n == 2) {
 259                        spi2->dev.platform_data = pdata2;
 260                        register_platform_device(&spi2);
 261
 262                        /* also: set up pin modes so the spi2 signals are
 263                         * visible on the relevant pins ... bootloaders on
 264                         * production boards may already have done this, but
 265                         * developer boards will often need Linux to do it.
 266                         */
 267                }
 268                ...
 269        }
 270
 271Notice how the platform_data for boards may be different, even if the
 272same SOC controller is used.  For example, on one board SPI might use
 273an external clock, where another derives the SPI clock from current
 274settings of some master clock.
 275
 276Declare Slave Devices
 277^^^^^^^^^^^^^^^^^^^^^
 278
 279The second kind of information is a list of what SPI slave devices exist
 280on the target board, often with some board-specific data needed for the
 281driver to work correctly.
 282
 283Normally your arch/.../mach-*/board-*.c files would provide a small table
 284listing the SPI devices on each board.  (This would typically be only a
 285small handful.)  That might look like::
 286
 287        static struct ads7846_platform_data ads_info = {
 288                .vref_delay_usecs       = 100,
 289                .x_plate_ohms           = 580,
 290                .y_plate_ohms           = 410,
 291        };
 292
 293        static struct spi_board_info spi_board_info[] __initdata = {
 294        {
 295                .modalias       = "ads7846",
 296                .platform_data  = &ads_info,
 297                .mode           = SPI_MODE_0,
 298                .irq            = GPIO_IRQ(31),
 299                .max_speed_hz   = 120000 /* max sample rate at 3V */ * 16,
 300                .bus_num        = 1,
 301                .chip_select    = 0,
 302        },
 303        };
 304
 305Again, notice how board-specific information is provided; each chip may need
 306several types.  This example shows generic constraints like the fastest SPI
 307clock to allow (a function of board voltage in this case) or how an IRQ pin
 308is wired, plus chip-specific constraints like an important delay that's
 309changed by the capacitance at one pin.
 310
 311(There's also "controller_data", information that may be useful to the
 312controller driver.  An example would be peripheral-specific DMA tuning
 313data or chipselect callbacks.  This is stored in spi_device later.)
 314
 315The board_info should provide enough information to let the system work
 316without the chip's driver being loaded.  The most troublesome aspect of
 317that is likely the SPI_CS_HIGH bit in the spi_device.mode field, since
 318sharing a bus with a device that interprets chipselect "backwards" is
 319not possible until the infrastructure knows how to deselect it.
 320
 321Then your board initialization code would register that table with the SPI
 322infrastructure, so that it's available later when the SPI master controller
 323driver is registered::
 324
 325        spi_register_board_info(spi_board_info, ARRAY_SIZE(spi_board_info));
 326
 327Like with other static board-specific setup, you won't unregister those.
 328
 329The widely used "card" style computers bundle memory, cpu, and little else
 330onto a card that's maybe just thirty square centimeters.  On such systems,
 331your ``arch/.../mach-.../board-*.c`` file would primarily provide information
 332about the devices on the mainboard into which such a card is plugged.  That
 333certainly includes SPI devices hooked up through the card connectors!
 334
 335
 336Non-static Configurations
 337^^^^^^^^^^^^^^^^^^^^^^^^^
 338
 339Developer boards often play by different rules than product boards, and one
 340example is the potential need to hotplug SPI devices and/or controllers.
 341
 342For those cases you might need to use spi_busnum_to_master() to look
 343up the spi bus master, and will likely need spi_new_device() to provide the
 344board info based on the board that was hotplugged.  Of course, you'd later
 345call at least spi_unregister_device() when that board is removed.
 346
 347When Linux includes support for MMC/SD/SDIO/DataFlash cards through SPI, those
 348configurations will also be dynamic.  Fortunately, such devices all support
 349basic device identification probes, so they should hotplug normally.
 350
 351
 352How do I write an "SPI Protocol Driver"?
 353----------------------------------------
 354Most SPI drivers are currently kernel drivers, but there's also support
 355for userspace drivers.  Here we talk only about kernel drivers.
 356
 357SPI protocol drivers somewhat resemble platform device drivers::
 358
 359        static struct spi_driver CHIP_driver = {
 360                .driver = {
 361                        .name           = "CHIP",
 362                        .owner          = THIS_MODULE,
 363                        .pm             = &CHIP_pm_ops,
 364                },
 365
 366                .probe          = CHIP_probe,
 367                .remove         = CHIP_remove,
 368        };
 369
 370The driver core will automatically attempt to bind this driver to any SPI
 371device whose board_info gave a modalias of "CHIP".  Your probe() code
 372might look like this unless you're creating a device which is managing
 373a bus (appearing under /sys/class/spi_master).
 374
 375::
 376
 377        static int CHIP_probe(struct spi_device *spi)
 378        {
 379                struct CHIP                     *chip;
 380                struct CHIP_platform_data       *pdata;
 381
 382                /* assuming the driver requires board-specific data: */
 383                pdata = &spi->dev.platform_data;
 384                if (!pdata)
 385                        return -ENODEV;
 386
 387                /* get memory for driver's per-chip state */
 388                chip = kzalloc(sizeof *chip, GFP_KERNEL);
 389                if (!chip)
 390                        return -ENOMEM;
 391                spi_set_drvdata(spi, chip);
 392
 393                ... etc
 394                return 0;
 395        }
 396
 397As soon as it enters probe(), the driver may issue I/O requests to
 398the SPI device using "struct spi_message".  When remove() returns,
 399or after probe() fails, the driver guarantees that it won't submit
 400any more such messages.
 401
 402  - An spi_message is a sequence of protocol operations, executed
 403    as one atomic sequence.  SPI driver controls include:
 404
 405      + when bidirectional reads and writes start ... by how its
 406        sequence of spi_transfer requests is arranged;
 407
 408      + which I/O buffers are used ... each spi_transfer wraps a
 409        buffer for each transfer direction, supporting full duplex
 410        (two pointers, maybe the same one in both cases) and half
 411        duplex (one pointer is NULL) transfers;
 412
 413      + optionally defining short delays after transfers ... using
 414        the spi_transfer.delay.value setting (this delay can be the
 415        only protocol effect, if the buffer length is zero) ...
 416        when specifying this delay the default spi_transfer.delay.unit
 417        is microseconds, however this can be adjusted to clock cycles
 418        or nanoseconds if needed;
 419
 420      + whether the chipselect becomes inactive after a transfer and
 421        any delay ... by using the spi_transfer.cs_change flag;
 422
 423      + hinting whether the next message is likely to go to this same
 424        device ... using the spi_transfer.cs_change flag on the last
 425        transfer in that atomic group, and potentially saving costs
 426        for chip deselect and select operations.
 427
 428  - Follow standard kernel rules, and provide DMA-safe buffers in
 429    your messages.  That way controller drivers using DMA aren't forced
 430    to make extra copies unless the hardware requires it (e.g. working
 431    around hardware errata that force the use of bounce buffering).
 432
 433    If standard dma_map_single() handling of these buffers is inappropriate,
 434    you can use spi_message.is_dma_mapped to tell the controller driver
 435    that you've already provided the relevant DMA addresses.
 436
 437  - The basic I/O primitive is spi_async().  Async requests may be
 438    issued in any context (irq handler, task, etc) and completion
 439    is reported using a callback provided with the message.
 440    After any detected error, the chip is deselected and processing
 441    of that spi_message is aborted.
 442
 443  - There are also synchronous wrappers like spi_sync(), and wrappers
 444    like spi_read(), spi_write(), and spi_write_then_read().  These
 445    may be issued only in contexts that may sleep, and they're all
 446    clean (and small, and "optional") layers over spi_async().
 447
 448  - The spi_write_then_read() call, and convenience wrappers around
 449    it, should only be used with small amounts of data where the
 450    cost of an extra copy may be ignored.  It's designed to support
 451    common RPC-style requests, such as writing an eight bit command
 452    and reading a sixteen bit response -- spi_w8r16() being one its
 453    wrappers, doing exactly that.
 454
 455Some drivers may need to modify spi_device characteristics like the
 456transfer mode, wordsize, or clock rate.  This is done with spi_setup(),
 457which would normally be called from probe() before the first I/O is
 458done to the device.  However, that can also be called at any time
 459that no message is pending for that device.
 460
 461While "spi_device" would be the bottom boundary of the driver, the
 462upper boundaries might include sysfs (especially for sensor readings),
 463the input layer, ALSA, networking, MTD, the character device framework,
 464or other Linux subsystems.
 465
 466Note that there are two types of memory your driver must manage as part
 467of interacting with SPI devices.
 468
 469  - I/O buffers use the usual Linux rules, and must be DMA-safe.
 470    You'd normally allocate them from the heap or free page pool.
 471    Don't use the stack, or anything that's declared "static".
 472
 473  - The spi_message and spi_transfer metadata used to glue those
 474    I/O buffers into a group of protocol transactions.  These can
 475    be allocated anywhere it's convenient, including as part of
 476    other allocate-once driver data structures.  Zero-init these.
 477
 478If you like, spi_message_alloc() and spi_message_free() convenience
 479routines are available to allocate and zero-initialize an spi_message
 480with several transfers.
 481
 482
 483How do I write an "SPI Master Controller Driver"?
 484-------------------------------------------------
 485An SPI controller will probably be registered on the platform_bus; write
 486a driver to bind to the device, whichever bus is involved.
 487
 488The main task of this type of driver is to provide an "spi_master".
 489Use spi_alloc_master() to allocate the master, and spi_master_get_devdata()
 490to get the driver-private data allocated for that device.
 491
 492::
 493
 494        struct spi_master       *master;
 495        struct CONTROLLER       *c;
 496
 497        master = spi_alloc_master(dev, sizeof *c);
 498        if (!master)
 499                return -ENODEV;
 500
 501        c = spi_master_get_devdata(master);
 502
 503The driver will initialize the fields of that spi_master, including the
 504bus number (maybe the same as the platform device ID) and three methods
 505used to interact with the SPI core and SPI protocol drivers.  It will
 506also initialize its own internal state.  (See below about bus numbering
 507and those methods.)
 508
 509After you initialize the spi_master, then use spi_register_master() to
 510publish it to the rest of the system. At that time, device nodes for the
 511controller and any predeclared spi devices will be made available, and
 512the driver model core will take care of binding them to drivers.
 513
 514If you need to remove your SPI controller driver, spi_unregister_master()
 515will reverse the effect of spi_register_master().
 516
 517
 518Bus Numbering
 519^^^^^^^^^^^^^
 520
 521Bus numbering is important, since that's how Linux identifies a given
 522SPI bus (shared SCK, MOSI, MISO).  Valid bus numbers start at zero.  On
 523SOC systems, the bus numbers should match the numbers defined by the chip
 524manufacturer.  For example, hardware controller SPI2 would be bus number 2,
 525and spi_board_info for devices connected to it would use that number.
 526
 527If you don't have such hardware-assigned bus number, and for some reason
 528you can't just assign them, then provide a negative bus number.  That will
 529then be replaced by a dynamically assigned number. You'd then need to treat
 530this as a non-static configuration (see above).
 531
 532
 533SPI Master Methods
 534^^^^^^^^^^^^^^^^^^
 535
 536``master->setup(struct spi_device *spi)``
 537        This sets up the device clock rate, SPI mode, and word sizes.
 538        Drivers may change the defaults provided by board_info, and then
 539        call spi_setup(spi) to invoke this routine.  It may sleep.
 540
 541        Unless each SPI slave has its own configuration registers, don't
 542        change them right away ... otherwise drivers could corrupt I/O
 543        that's in progress for other SPI devices.
 544
 545        .. note::
 546
 547                BUG ALERT:  for some reason the first version of
 548                many spi_master drivers seems to get this wrong.
 549                When you code setup(), ASSUME that the controller
 550                is actively processing transfers for another device.
 551
 552``master->cleanup(struct spi_device *spi)``
 553        Your controller driver may use spi_device.controller_state to hold
 554        state it dynamically associates with that device.  If you do that,
 555        be sure to provide the cleanup() method to free that state.
 556
 557``master->prepare_transfer_hardware(struct spi_master *master)``
 558        This will be called by the queue mechanism to signal to the driver
 559        that a message is coming in soon, so the subsystem requests the
 560        driver to prepare the transfer hardware by issuing this call.
 561        This may sleep.
 562
 563``master->unprepare_transfer_hardware(struct spi_master *master)``
 564        This will be called by the queue mechanism to signal to the driver
 565        that there are no more messages pending in the queue and it may
 566        relax the hardware (e.g. by power management calls). This may sleep.
 567
 568``master->transfer_one_message(struct spi_master *master, struct spi_message *mesg)``
 569        The subsystem calls the driver to transfer a single message while
 570        queuing transfers that arrive in the meantime. When the driver is
 571        finished with this message, it must call
 572        spi_finalize_current_message() so the subsystem can issue the next
 573        message. This may sleep.
 574
 575``master->transfer_one(struct spi_master *master, struct spi_device *spi, struct spi_transfer *transfer)``
 576        The subsystem calls the driver to transfer a single transfer while
 577        queuing transfers that arrive in the meantime. When the driver is
 578        finished with this transfer, it must call
 579        spi_finalize_current_transfer() so the subsystem can issue the next
 580        transfer. This may sleep. Note: transfer_one and transfer_one_message
 581        are mutually exclusive; when both are set, the generic subsystem does
 582        not call your transfer_one callback.
 583
 584        Return values:
 585
 586        * negative errno: error
 587        * 0: transfer is finished
 588        * 1: transfer is still in progress
 589
 590``master->set_cs_timing(struct spi_device *spi, u8 setup_clk_cycles, u8 hold_clk_cycles, u8 inactive_clk_cycles)``
 591        This method allows SPI client drivers to request SPI master controller
 592        for configuring device specific CS setup, hold and inactive timing
 593        requirements.
 594
 595Deprecated Methods
 596^^^^^^^^^^^^^^^^^^
 597
 598``master->transfer(struct spi_device *spi, struct spi_message *message)``
 599        This must not sleep. Its responsibility is to arrange that the
 600        transfer happens and its complete() callback is issued. The two
 601        will normally happen later, after other transfers complete, and
 602        if the controller is idle it will need to be kickstarted. This
 603        method is not used on queued controllers and must be NULL if
 604        transfer_one_message() and (un)prepare_transfer_hardware() are
 605        implemented.
 606
 607
 608SPI Message Queue
 609^^^^^^^^^^^^^^^^^
 610
 611If you are happy with the standard queueing mechanism provided by the
 612SPI subsystem, just implement the queued methods specified above. Using
 613the message queue has the upside of centralizing a lot of code and
 614providing pure process-context execution of methods. The message queue
 615can also be elevated to realtime priority on high-priority SPI traffic.
 616
 617Unless the queueing mechanism in the SPI subsystem is selected, the bulk
 618of the driver will be managing the I/O queue fed by the now deprecated
 619function transfer().
 620
 621That queue could be purely conceptual.  For example, a driver used only
 622for low-frequency sensor access might be fine using synchronous PIO.
 623
 624But the queue will probably be very real, using message->queue, PIO,
 625often DMA (especially if the root filesystem is in SPI flash), and
 626execution contexts like IRQ handlers, tasklets, or workqueues (such
 627as keventd).  Your driver can be as fancy, or as simple, as you need.
 628Such a transfer() method would normally just add the message to a
 629queue, and then start some asynchronous transfer engine (unless it's
 630already running).
 631
 632
 633THANKS TO
 634---------
 635Contributors to Linux-SPI discussions include (in alphabetical order,
 636by last name):
 637
 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
 648