715 lines · plain
1====================================2Overview of Linux kernel SPI support3====================================4 502-Feb-20126 7What is SPI?8------------9The "Serial Peripheral Interface" (SPI) is a synchronous four wire serial10link used to connect microcontrollers to sensors, memory, and peripherals.11It's a simple "de facto" standard, not complicated enough to acquire a12standardization body. SPI uses a host/target 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 four17clocking modes through which data is exchanged; mode-0 and mode-3 are most18commonly used. Each clock cycle shifts data out and data in; the clock19doesn't cycle except when there is a data bit to shift. Not all data bits20are used though; not every protocol uses those full duplex capabilities.21 22SPI hosts use a fourth "chip select" line to activate a given SPI target23device, so those three signal wires may be connected to several chips24in parallel. All SPI targets support chipselects; they are usually active25low signals, labeled nCSx for target 'x' (e.g. nCS0). Some devices have26other signals, often including an interrupt to the host.27 28Unlike serial busses like USB or SMBus, even low level protocols for29SPI target functions are usually not interoperable between vendors30(except for commodities like SPI memory chips).31 32 - SPI may be used for request/response style device protocols, as with33 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 word39 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 targets will only rarely support any kind of automatic47discovery/enumeration protocol. The tree of target devices accessible from48a given SPI host controller will normally be set up manually, with49configuration tables.50 51SPI is only one of the names used by such four-wire protocols, and52most controllers have no problem handling "MicroWire" (think of it as53half-duplex SPI, for request/response protocols), SSP ("Synchronous54Serial Protocol"), PSP ("Programmable Serial Protocol"), and other55related protocols.56 57Some chips eliminate a signal line by combining MOSI and MISO, and58limiting themselves to half-duplex at the hardware level. In fact59some SPI chips have this signal mode as a strapping option. These60can be accessed using the same programming interface as SPI, but of61course they won't handle full duplex transfers. You may find such62chips described as using "three wire" signaling: SCK, data, nCSx.63(That data line is sometimes called MOMI or SISO.)64 65Microcontrollers often support both host and target sides of the SPI66protocol. This document (and Linux) supports both the host and target67sides of SPI interactions.68 69 70Who uses it? On what kinds of systems?71---------------------------------------72Linux developers using SPI are probably writing device drivers for embedded73systems boards. SPI is used to control external chips, and it is also a74protocol 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 target chips range from digital/analog converters used for analog79sensors and codecs, to memory, to peripherals like USB controllers80or 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 no84dedicated SPI controller exists, GPIO pins can be used to create a85low speed "bitbanging" adapter. Very few systems will "hotplug" an SPI86controller; the reasons to use SPI focus on low cost and simple operation,87and if dynamic reconfiguration is important, USB will often be a more88appropriate low-pincount peripheral bus.89 90Many microcontrollers that can run Linux integrate one or more I/O91interfaces with SPI modes. Given SPI support, they could use MMC or SD92cards 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'll98find isn't necessarily helpful. The four modes combine two mode bits:99 100 - CPOL indicates the initial clock polarity. CPOL=0 means the101 clock starts low, so the first (leading) edge is rising, and102 the second (trailing) edge is falling. CPOL=1 means the clock103 starts high, so the first (leading) edge is falling.104 105 - CPHA indicates the clock phase used to sample data; CPHA=0 says106 sample on the leading edge, CPHA=1 means the trailing edge.107 108 Since the signal needs to stabilize before it's sampled, CPHA=0109 implies that its data is written half a clock before the first110 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 the116low order bit. So when a chip's timing diagram shows the clock117starting low (CPOL=0) and data stabilized for sampling during the118trailing clock edge (CPHA=1), that's SPI mode 1.119 120Note that the clock mode is relevant as soon as the chipselect goes121active. So the host must set the clock to inactive before selecting122a target, and the target can tell the chosen polarity by sampling the123clock level when its select line goes active. That's why many devices124support 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 the131main source code, and you should certainly read that chapter of the132kernel API document. This is just an overview, so you get the big133picture before those details.134 135SPI requests always go into I/O queues. Requests for a given SPI device136are always executed in FIFO order, and complete asynchronously through137completion callbacks. There are also some simple synchronous wrappers138for those calls, including ones for common transaction types like writing139a 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-Chip145 processors, and often support both Controller and target 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 controller151 driver to communicate with a target or Controller device on the152 other side of an SPI link.153 154So for example one protocol driver might talk to the MTD layer to export155data to filesystems stored on SPI flash like DataFlash; and others might156control 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 between161those two types of drivers.162 163There is a minimal core of SPI programming interfaces, focussing on164using the driver model to connect controller and protocol drivers using165device tables provided by board specific initialization code. SPI166shows up in sysfs in several locations::167 168 /sys/devices/.../CTLR ... physical node for a given SPI controller169 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 physical174 .../CTLR/spiB.C device175 176 /sys/devices/.../CTLR/spiB.C/modalias ... identifies the driver177 that should be used with this device (for hotplug/coldplug)178 179 /sys/bus/spi/drivers/D ... driver for one or more spi*.* devices180 181 /sys/class/spi_master/spiB ... symlink to a logical node which could hold182 class related state for the SPI host controller managing bus "B".183 All spiB.* devices share one physical SPI bus segment, with SCLK,184 MOSI, and MISO.185 186 /sys/devices/.../CTLR/slave ... virtual file for (un)registering the187 target device for an SPI target controller.188 Writing the driver name of an SPI target handler to this file189 registers the target device; writing "(null)" unregisters the target190 device.191 Reading from this file shows the name of the target device ("(null)"192 if not registered).193 194 /sys/class/spi_slave/spiB ... symlink to a logical node which could hold195 class related state for the SPI target controller on bus "B". When196 registered, a single spiB.* device is present here, possible sharing197 the physical SPI bus segment with other SPI target devices.198 199At this time, the only class-specific state is the bus number ("B" in "spiB"),200so those /sys/class entries are only useful to quickly identify busses.201 202 203How does board-specific init code declare SPI devices?204------------------------------------------------------205Linux needs several kinds of information to properly configure SPI devices.206That information is normally provided by board-specific code, even for207chips that do support some of automated discovery/enumeration.208 209Declare Controllers210^^^^^^^^^^^^^^^^^^^211 212The first kind of information is a list of what SPI controllers exist.213For System-on-Chip (SOC) based boards, these will usually be platform214devices, and the controller may need some platform_data in order to215operate properly. The "struct platform_device" will include resources216like the physical address of the controller's first register and its IRQ.217 218Platforms will often abstract the "register SPI controller" operation,219maybe coupling it with code to initialize pin configurations, so that220the arch/.../mach-*/board-*.c files for several boards can all share the221same basic controller setup code. This is because most SOCs have several222SPI-capable controllers, and only the ones actually usable on a given223board should normally be set up and registered.224 225So for example arch/.../mach-*/board-*.c files might have code like::226 227 #include <mach/spi.h> /* for mysoc_spi_data */228 229 /* if your mach-* infrastructure doesn't support kernels that can230 * run on multiple boards, pdata wouldn't benefit from "__init".231 */232 static struct mysoc_spi_data pdata __initdata = { ... };233 234 static __init board_init(void)235 {236 ...237 /* this board only uses SPI controller #2 */238 mysoc_register_spi(2, &pdata);239 ...240 }241 242And SOC-specific utility code might look something like::243 244 #include <mach/spi.h>245 246 static struct platform_device spi2 = { ... };247 248 void mysoc_register_spi(unsigned n, struct mysoc_spi_data *pdata)249 {250 struct mysoc_spi_data *pdata2;251 252 pdata2 = kmalloc(sizeof *pdata2, GFP_KERNEL);253 *pdata2 = pdata;254 ...255 if (n == 2) {256 spi2->dev.platform_data = pdata2;257 register_platform_device(&spi2);258 259 /* also: set up pin modes so the spi2 signals are260 * visible on the relevant pins ... bootloaders on261 * production boards may already have done this, but262 * developer boards will often need Linux to do it.263 */264 }265 ...266 }267 268Notice how the platform_data for boards may be different, even if the269same SOC controller is used. For example, on one board SPI might use270an external clock, where another derives the SPI clock from current271settings of some master clock.272 273Declare target Devices274^^^^^^^^^^^^^^^^^^^^^^275 276The second kind of information is a list of what SPI target devices exist277on the target board, often with some board-specific data needed for the278driver to work correctly.279 280Normally your arch/.../mach-*/board-*.c files would provide a small table281listing the SPI devices on each board. (This would typically be only a282small handful.) That might look like::283 284 static struct ads7846_platform_data ads_info = {285 .vref_delay_usecs = 100,286 .x_plate_ohms = 580,287 .y_plate_ohms = 410,288 };289 290 static struct spi_board_info spi_board_info[] __initdata = {291 {292 .modalias = "ads7846",293 .platform_data = &ads_info,294 .mode = SPI_MODE_0,295 .irq = GPIO_IRQ(31),296 .max_speed_hz = 120000 /* max sample rate at 3V */ * 16,297 .bus_num = 1,298 .chip_select = 0,299 },300 };301 302Again, notice how board-specific information is provided; each chip may need303several types. This example shows generic constraints like the fastest SPI304clock to allow (a function of board voltage in this case) or how an IRQ pin305is wired, plus chip-specific constraints like an important delay that's306changed by the capacitance at one pin.307 308(There's also "controller_data", information that may be useful to the309controller driver. An example would be peripheral-specific DMA tuning310data or chipselect callbacks. This is stored in spi_device later.)311 312The board_info should provide enough information to let the system work313without the chip's driver being loaded. The most troublesome aspect of314that is likely the SPI_CS_HIGH bit in the spi_device.mode field, since315sharing a bus with a device that interprets chipselect "backwards" is316not possible until the infrastructure knows how to deselect it.317 318Then your board initialization code would register that table with the SPI319infrastructure, so that it's available later when the SPI host controller320driver is registered::321 322 spi_register_board_info(spi_board_info, ARRAY_SIZE(spi_board_info));323 324Like with other static board-specific setup, you won't unregister those.325 326The widely used "card" style computers bundle memory, cpu, and little else327onto a card that's maybe just thirty square centimeters. On such systems,328your ``arch/.../mach-.../board-*.c`` file would primarily provide information329about the devices on the mainboard into which such a card is plugged. That330certainly includes SPI devices hooked up through the card connectors!331 332 333Non-static Configurations334^^^^^^^^^^^^^^^^^^^^^^^^^335 336When Linux includes support for MMC/SD/SDIO/DataFlash cards through SPI, those337configurations will also be dynamic. Fortunately, such devices all support338basic device identification probes, so they should hotplug normally.339 340 341How do I write an "SPI Protocol Driver"?342----------------------------------------343Most SPI drivers are currently kernel drivers, but there's also support344for userspace drivers. Here we talk only about kernel drivers.345 346SPI protocol drivers somewhat resemble platform device drivers::347 348 static struct spi_driver CHIP_driver = {349 .driver = {350 .name = "CHIP",351 .pm = &CHIP_pm_ops,352 },353 354 .probe = CHIP_probe,355 .remove = CHIP_remove,356 };357 358The driver core will automatically attempt to bind this driver to any SPI359device whose board_info gave a modalias of "CHIP". Your probe() code360might look like this unless you're creating a device which is managing361a bus (appearing under /sys/class/spi_master).362 363::364 365 static int CHIP_probe(struct spi_device *spi)366 {367 struct CHIP *chip;368 struct CHIP_platform_data *pdata;369 370 /* assuming the driver requires board-specific data: */371 pdata = &spi->dev.platform_data;372 if (!pdata)373 return -ENODEV;374 375 /* get memory for driver's per-chip state */376 chip = kzalloc(sizeof *chip, GFP_KERNEL);377 if (!chip)378 return -ENOMEM;379 spi_set_drvdata(spi, chip);380 381 ... etc382 return 0;383 }384 385As soon as it enters probe(), the driver may issue I/O requests to386the SPI device using "struct spi_message". When remove() returns,387or after probe() fails, the driver guarantees that it won't submit388any more such messages.389 390 - An spi_message is a sequence of protocol operations, executed391 as one atomic sequence. SPI driver controls include:392 393 + when bidirectional reads and writes start ... by how its394 sequence of spi_transfer requests is arranged;395 396 + which I/O buffers are used ... each spi_transfer wraps a397 buffer for each transfer direction, supporting full duplex398 (two pointers, maybe the same one in both cases) and half399 duplex (one pointer is NULL) transfers;400 401 + optionally defining short delays after transfers ... using402 the spi_transfer.delay.value setting (this delay can be the403 only protocol effect, if the buffer length is zero) ...404 when specifying this delay the default spi_transfer.delay.unit405 is microseconds, however this can be adjusted to clock cycles406 or nanoseconds if needed;407 408 + whether the chipselect becomes inactive after a transfer and409 any delay ... by using the spi_transfer.cs_change flag;410 411 + hinting whether the next message is likely to go to this same412 device ... using the spi_transfer.cs_change flag on the last413 transfer in that atomic group, and potentially saving costs414 for chip deselect and select operations.415 416 - Follow standard kernel rules, and provide DMA-safe buffers in417 your messages. That way controller drivers using DMA aren't forced418 to make extra copies unless the hardware requires it (e.g. working419 around hardware errata that force the use of bounce buffering).420 421 - The basic I/O primitive is spi_async(). Async requests may be422 issued in any context (irq handler, task, etc) and completion423 is reported using a callback provided with the message.424 After any detected error, the chip is deselected and processing425 of that spi_message is aborted.426 427 - There are also synchronous wrappers like spi_sync(), and wrappers428 like spi_read(), spi_write(), and spi_write_then_read(). These429 may be issued only in contexts that may sleep, and they're all430 clean (and small, and "optional") layers over spi_async().431 432 - The spi_write_then_read() call, and convenience wrappers around433 it, should only be used with small amounts of data where the434 cost of an extra copy may be ignored. It's designed to support435 common RPC-style requests, such as writing an eight bit command436 and reading a sixteen bit response -- spi_w8r16() being one its437 wrappers, doing exactly that.438 439Some drivers may need to modify spi_device characteristics like the440transfer mode, wordsize, or clock rate. This is done with spi_setup(),441which would normally be called from probe() before the first I/O is442done to the device. However, that can also be called at any time443that no message is pending for that device.444 445While "spi_device" would be the bottom boundary of the driver, the446upper boundaries might include sysfs (especially for sensor readings),447the input layer, ALSA, networking, MTD, the character device framework,448or other Linux subsystems.449 450Note that there are two types of memory your driver must manage as part451of interacting with SPI devices.452 453 - I/O buffers use the usual Linux rules, and must be DMA-safe.454 You'd normally allocate them from the heap or free page pool.455 Don't use the stack, or anything that's declared "static".456 457 - The spi_message and spi_transfer metadata used to glue those458 I/O buffers into a group of protocol transactions. These can459 be allocated anywhere it's convenient, including as part of460 other allocate-once driver data structures. Zero-init these.461 462If you like, spi_message_alloc() and spi_message_free() convenience463routines are available to allocate and zero-initialize an spi_message464with several transfers.465 466 467How do I write an "SPI Controller Driver"?468-------------------------------------------------469An SPI controller will probably be registered on the platform_bus; write470a driver to bind to the device, whichever bus is involved.471 472The main task of this type of driver is to provide an "spi_controller".473Use spi_alloc_host() to allocate the host controller, and474spi_controller_get_devdata() to get the driver-private data allocated for that475device.476 477::478 479 struct spi_controller *ctlr;480 struct CONTROLLER *c;481 482 ctlr = spi_alloc_host(dev, sizeof *c);483 if (!ctlr)484 return -ENODEV;485 486 c = spi_controller_get_devdata(ctlr);487 488The driver will initialize the fields of that spi_controller, including the bus489number (maybe the same as the platform device ID) and three methods used to490interact with the SPI core and SPI protocol drivers. It will also initialize491its own internal state. (See below about bus numbering and those methods.)492 493After you initialize the spi_controller, then use spi_register_controller() to494publish it to the rest of the system. At that time, device nodes for the495controller and any predeclared spi devices will be made available, and496the driver model core will take care of binding them to drivers.497 498If you need to remove your SPI controller driver, spi_unregister_controller()499will reverse the effect of spi_register_controller().500 501 502Bus Numbering503^^^^^^^^^^^^^504 505Bus numbering is important, since that's how Linux identifies a given506SPI bus (shared SCK, MOSI, MISO). Valid bus numbers start at zero. On507SOC systems, the bus numbers should match the numbers defined by the chip508manufacturer. For example, hardware controller SPI2 would be bus number 2,509and spi_board_info for devices connected to it would use that number.510 511If you don't have such hardware-assigned bus number, and for some reason512you can't just assign them, then provide a negative bus number. That will513then be replaced by a dynamically assigned number. You'd then need to treat514this as a non-static configuration (see above).515 516 517SPI Host Controller Methods518^^^^^^^^^^^^^^^^^^^^^^^^^^^519 520``ctlr->setup(struct spi_device *spi)``521 This sets up the device clock rate, SPI mode, and word sizes.522 Drivers may change the defaults provided by board_info, and then523 call spi_setup(spi) to invoke this routine. It may sleep.524 525 Unless each SPI target has its own configuration registers, don't526 change them right away ... otherwise drivers could corrupt I/O527 that's in progress for other SPI devices.528 529 .. note::530 531 BUG ALERT: for some reason the first version of532 many spi_controller drivers seems to get this wrong.533 When you code setup(), ASSUME that the controller534 is actively processing transfers for another device.535 536``ctlr->cleanup(struct spi_device *spi)``537 Your controller driver may use spi_device.controller_state to hold538 state it dynamically associates with that device. If you do that,539 be sure to provide the cleanup() method to free that state.540 541``ctlr->prepare_transfer_hardware(struct spi_controller *ctlr)``542 This will be called by the queue mechanism to signal to the driver543 that a message is coming in soon, so the subsystem requests the544 driver to prepare the transfer hardware by issuing this call.545 This may sleep.546 547``ctlr->unprepare_transfer_hardware(struct spi_controller *ctlr)``548 This will be called by the queue mechanism to signal to the driver549 that there are no more messages pending in the queue and it may550 relax the hardware (e.g. by power management calls). This may sleep.551 552``ctlr->transfer_one_message(struct spi_controller *ctlr, struct spi_message *mesg)``553 The subsystem calls the driver to transfer a single message while554 queuing transfers that arrive in the meantime. When the driver is555 finished with this message, it must call556 spi_finalize_current_message() so the subsystem can issue the next557 message. This may sleep.558 559``ctrl->transfer_one(struct spi_controller *ctlr, struct spi_device *spi, struct spi_transfer *transfer)``560 The subsystem calls the driver to transfer a single transfer while561 queuing transfers that arrive in the meantime. When the driver is562 finished with this transfer, it must call563 spi_finalize_current_transfer() so the subsystem can issue the next564 transfer. This may sleep. Note: transfer_one and transfer_one_message565 are mutually exclusive; when both are set, the generic subsystem does566 not call your transfer_one callback.567 568 Return values:569 570 * negative errno: error571 * 0: transfer is finished572 * 1: transfer is still in progress573 574``ctrl->set_cs_timing(struct spi_device *spi, u8 setup_clk_cycles, u8 hold_clk_cycles, u8 inactive_clk_cycles)``575 This method allows SPI client drivers to request SPI host controller576 for configuring device specific CS setup, hold and inactive timing577 requirements.578 579Deprecated Methods580^^^^^^^^^^^^^^^^^^581 582``ctrl->transfer(struct spi_device *spi, struct spi_message *message)``583 This must not sleep. Its responsibility is to arrange that the584 transfer happens and its complete() callback is issued. The two585 will normally happen later, after other transfers complete, and586 if the controller is idle it will need to be kickstarted. This587 method is not used on queued controllers and must be NULL if588 transfer_one_message() and (un)prepare_transfer_hardware() are589 implemented.590 591 592SPI Message Queue593^^^^^^^^^^^^^^^^^594 595If you are happy with the standard queueing mechanism provided by the596SPI subsystem, just implement the queued methods specified above. Using597the message queue has the upside of centralizing a lot of code and598providing pure process-context execution of methods. The message queue599can also be elevated to realtime priority on high-priority SPI traffic.600 601Unless the queueing mechanism in the SPI subsystem is selected, the bulk602of the driver will be managing the I/O queue fed by the now deprecated603function transfer().604 605That queue could be purely conceptual. For example, a driver used only606for low-frequency sensor access might be fine using synchronous PIO.607 608But the queue will probably be very real, using message->queue, PIO,609often DMA (especially if the root filesystem is in SPI flash), and610execution contexts like IRQ handlers, tasklets, or workqueues (such611as keventd). Your driver can be as fancy, or as simple, as you need.612Such a transfer() method would normally just add the message to a613queue, and then start some asynchronous transfer engine (unless it's614already running).615 616 617Extensions to the SPI protocol618------------------------------619The fact that SPI doesn't have a formal specification or standard permits chip620manufacturers to implement the SPI protocol in slightly different ways. In most621cases, SPI protocol implementations from different vendors are compatible among622each other. For example, in SPI mode 0 (CPOL=0, CPHA=0) the bus lines may behave623like the following:624 625::626 627 nCSx ___ ___628 \_________________________________________________________________/629 • •630 • •631 SCLK ___ ___ ___ ___ ___ ___ ___ ___632 _______/ \___/ \___/ \___/ \___/ \___/ \___/ \___/ \_____633 • : ; : ; : ; : ; : ; : ; : ; : ; •634 • : ; : ; : ; : ; : ; : ; : ; : ; •635 MOSI XXX__________ _______ _______ ________XXX636 0xA5 XXX__/ 1 \_0_____/ 1 \_0_______0_____/ 1 \_0_____/ 1 \_XXX637 • ; ; ; ; ; ; ; ; •638 • ; ; ; ; ; ; ; ; •639 MISO XXX__________ _______________________ _______ XXX640 0xBA XXX__/ 1 \_____0_/ 1 1 1 \_____0__/ 1 \____0__XXX641 642Legend::643 644 • marks the start/end of transmission;645 : marks when data is clocked into the peripheral;646 ; marks when data is clocked into the controller;647 X marks when line states are not specified.648 649In some few cases, chips extend the SPI protocol by specifying line behaviors650that other SPI protocols don't (e.g. data line state for when CS is not651asserted). Those distinct SPI protocols, modes, and configurations are supported652by different SPI mode flags.653 654MOSI idle state configuration655^^^^^^^^^^^^^^^^^^^^^^^^^^^^^656 657Common SPI protocol implementations don't specify any state or behavior for the658MOSI line when the controller is not clocking out data. However, there do exist659peripherals that require specific MOSI line state when data is not being clocked660out. For example, if the peripheral expects the MOSI line to be high when the661controller is not clocking out data (``SPI_MOSI_IDLE_HIGH``), then a transfer in662SPI mode 0 would look like the following:663 664::665 666 nCSx ___ ___667 \_________________________________________________________________/668 • •669 • •670 SCLK ___ ___ ___ ___ ___ ___ ___ ___671 _______/ \___/ \___/ \___/ \___/ \___/ \___/ \___/ \_____672 • : ; : ; : ; : ; : ; : ; : ; : ; •673 • : ; : ; : ; : ; : ; : ; : ; : ; •674 MOSI _____ _______ _______ _______________ ___675 0x56 \_0_____/ 1 \_0_____/ 1 \_0_____/ 1 1 \_0_____/676 • ; ; ; ; ; ; ; ; •677 • ; ; ; ; ; ; ; ; •678 MISO XXX__________ _______________________ _______ XXX679 0xBA XXX__/ 1 \_____0_/ 1 1 1 \_____0__/ 1 \____0__XXX680 681Legend::682 683 • marks the start/end of transmission;684 : marks when data is clocked into the peripheral;685 ; marks when data is clocked into the controller;686 X marks when line states are not specified.687 688In this extension to the usual SPI protocol, the MOSI line state is specified to689be kept high when CS is asserted but the controller is not clocking out data to690the peripheral and also when CS is not asserted.691 692Peripherals that require this extension must request it by setting the693``SPI_MOSI_IDLE_HIGH`` bit into the mode attribute of their ``struct694spi_device`` and call spi_setup(). Controllers that support this extension695should indicate it by setting ``SPI_MOSI_IDLE_HIGH`` in the mode_bits attribute696of their ``struct spi_controller``. The configuration to idle MOSI low is697analogous but uses the ``SPI_MOSI_IDLE_LOW`` mode bit.698 699 700THANKS TO701---------702Contributors to Linux-SPI discussions include (in alphabetical order,703by last name):704 705- Mark Brown706- David Brownell707- Russell King708- Grant Likely709- Dmitry Pervushin710- Stephen Street711- Mark Underwood712- Andrew Victor713- Linus Walleij714- Vitaly Wool715