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 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 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 hosts use a fourth "chip select" line to activate a given SPI target 23device, so those three signal wires may be connected to several chips 24in parallel. All SPI targets support chipselects; they are usually active 25low signals, labeled nCSx for target 'x' (e.g. nCS0). Some devices have 26other signals, often including an interrupt to the host. 27 28Unlike serial busses like USB or SMBus, even low level protocols for 29SPI target 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 targets will only rarely support any kind of automatic 47discovery/enumeration protocol. The tree of target devices accessible from 48a given SPI host controller will normally be set up manually, with 49configuration tables. 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 host and target sides of the SPI 66protocol. This document (and Linux) supports both the host and target 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 target 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 stabilize 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 host must set the clock to inactive before selecting 122a target, and the target 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 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 controller 151 driver to communicate with a target or Controller 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 to a logical node which could hold 182 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 the 187 target device for an SPI target controller. 188 Writing the driver name of an SPI target handler to this file 189 registers the target device; writing "(null)" unregisters the target 190 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 hold 195 class related state for the SPI target controller on bus "B". When 196 registered, a single spiB.* device is present here, possible sharing 197 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 for 207chips that do support some of automated discovery/enumeration. 208 209Declare Controllers 210^^^^^^^^^^^^^^^^^^^ 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 platform 214devices, and the controller may need some platform_data in order to 215operate properly. The "struct platform_device" will include resources 216like 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 that 220the arch/.../mach-*/board-*.c files for several boards can all share the 221same basic controller setup code. This is because most SOCs have several 222SPI-capable controllers, and only the ones actually usable on a given 223board 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 can 230 * 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 are 260 * visible on the relevant pins ... bootloaders on 261 * production boards may already have done this, but 262 * 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 the 269same SOC controller is used. For example, on one board SPI might use 270an external clock, where another derives the SPI clock from current 271settings of some master clock. 272 273Declare target Devices 274^^^^^^^^^^^^^^^^^^^^^^ 275 276The second kind of information is a list of what SPI target devices exist 277on the target board, often with some board-specific data needed for the 278driver to work correctly. 279 280Normally your arch/.../mach-*/board-*.c files would provide a small table 281listing the SPI devices on each board. (This would typically be only a 282small 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 need 303several types. This example shows generic constraints like the fastest SPI 304clock to allow (a function of board voltage in this case) or how an IRQ pin 305is wired, plus chip-specific constraints like an important delay that's 306changed by the capacitance at one pin. 307 308(There's also "controller_data", information that may be useful to the 309controller driver. An example would be peripheral-specific DMA tuning 310data or chipselect callbacks. This is stored in spi_device later.) 311 312The board_info should provide enough information to let the system work 313without the chip's driver being loaded. The most troublesome aspect of 314that is likely the SPI_CS_HIGH bit in the spi_device.mode field, since 315sharing a bus with a device that interprets chipselect "backwards" is 316not possible until the infrastructure knows how to deselect it. 317 318Then your board initialization code would register that table with the SPI 319infrastructure, so that it's available later when the SPI host controller 320driver 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 else 327onto a card that's maybe just thirty square centimeters. On such systems, 328your ``arch/.../mach-.../board-*.c`` file would primarily provide information 329about the devices on the mainboard into which such a card is plugged. That 330certainly includes SPI devices hooked up through the card connectors! 331 332 333Non-static Configurations 334^^^^^^^^^^^^^^^^^^^^^^^^^ 335 336When Linux includes support for MMC/SD/SDIO/DataFlash cards through SPI, those 337configurations will also be dynamic. Fortunately, such devices all support 338basic 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 support 344for 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 .owner = THIS_MODULE, 352 .pm = &CHIP_pm_ops, 353 }, 354 355 .probe = CHIP_probe, 356 .remove = CHIP_remove, 357 }; 358 359The driver core will automatically attempt to bind this driver to any SPI 360device whose board_info gave a modalias of "CHIP". Your probe() code 361might look like this unless you're creating a device which is managing 362a bus (appearing under /sys/class/spi_master). 363 364:: 365 366 static int CHIP_probe(struct spi_device *spi) 367 { 368 struct CHIP *chip; 369 struct CHIP_platform_data *pdata; 370 371 /* assuming the driver requires board-specific data: */ 372 pdata = &spi->dev.platform_data; 373 if (!pdata) 374 return -ENODEV; 375 376 /* get memory for driver's per-chip state */ 377 chip = kzalloc(sizeof *chip, GFP_KERNEL); 378 if (!chip) 379 return -ENOMEM; 380 spi_set_drvdata(spi, chip); 381 382 ... etc 383 return 0; 384 } 385 386As soon as it enters probe(), the driver may issue I/O requests to 387the SPI device using "struct spi_message". When remove() returns, 388or after probe() fails, the driver guarantees that it won't submit 389any more such messages. 390 391 - An spi_message is a sequence of protocol operations, executed 392 as one atomic sequence. SPI driver controls include: 393 394 + when bidirectional reads and writes start ... by how its 395 sequence of spi_transfer requests is arranged; 396 397 + which I/O buffers are used ... each spi_transfer wraps a 398 buffer for each transfer direction, supporting full duplex 399 (two pointers, maybe the same one in both cases) and half 400 duplex (one pointer is NULL) transfers; 401 402 + optionally defining short delays after transfers ... using 403 the spi_transfer.delay.value setting (this delay can be the 404 only protocol effect, if the buffer length is zero) ... 405 when specifying this delay the default spi_transfer.delay.unit 406 is microseconds, however this can be adjusted to clock cycles 407 or nanoseconds if needed; 408 409 + whether the chipselect becomes inactive after a transfer and 410 any delay ... by using the spi_transfer.cs_change flag; 411 412 + hinting whether the next message is likely to go to this same 413 device ... using the spi_transfer.cs_change flag on the last 414 transfer in that atomic group, and potentially saving costs 415 for chip deselect and select operations. 416 417 - Follow standard kernel rules, and provide DMA-safe buffers in 418 your messages. That way controller drivers using DMA aren't forced 419 to make extra copies unless the hardware requires it (e.g. working 420 around hardware errata that force the use of bounce buffering). 421 422 If standard dma_map_single() handling of these buffers is inappropriate, 423 you can use spi_message.is_dma_mapped to tell the controller driver 424 that you've already provided the relevant DMA addresses. 425 426 - The basic I/O primitive is spi_async(). Async requests may be 427 issued in any context (irq handler, task, etc) and completion 428 is reported using a callback provided with the message. 429 After any detected error, the chip is deselected and processing 430 of that spi_message is aborted. 431 432 - There are also synchronous wrappers like spi_sync(), and wrappers 433 like spi_read(), spi_write(), and spi_write_then_read(). These 434 may be issued only in contexts that may sleep, and they're all 435 clean (and small, and "optional") layers over spi_async(). 436 437 - The spi_write_then_read() call, and convenience wrappers around 438 it, should only be used with small amounts of data where the 439 cost of an extra copy may be ignored. It's designed to support 440 common RPC-style requests, such as writing an eight bit command 441 and reading a sixteen bit response -- spi_w8r16() being one its 442 wrappers, doing exactly that. 443 444Some drivers may need to modify spi_device characteristics like the 445transfer mode, wordsize, or clock rate. This is done with spi_setup(), 446which would normally be called from probe() before the first I/O is 447done to the device. However, that can also be called at any time 448that no message is pending for that device. 449 450While "spi_device" would be the bottom boundary of the driver, the 451upper boundaries might include sysfs (especially for sensor readings), 452the input layer, ALSA, networking, MTD, the character device framework, 453or other Linux subsystems. 454 455Note that there are two types of memory your driver must manage as part 456of interacting with SPI devices. 457 458 - I/O buffers use the usual Linux rules, and must be DMA-safe. 459 You'd normally allocate them from the heap or free page pool. 460 Don't use the stack, or anything that's declared "static". 461 462 - The spi_message and spi_transfer metadata used to glue those 463 I/O buffers into a group of protocol transactions. These can 464 be allocated anywhere it's convenient, including as part of 465 other allocate-once driver data structures. Zero-init these. 466 467If you like, spi_message_alloc() and spi_message_free() convenience 468routines are available to allocate and zero-initialize an spi_message 469with several transfers. 470 471 472How do I write an "SPI Controller Driver"? 473------------------------------------------------- 474An SPI controller will probably be registered on the platform_bus; write 475a driver to bind to the device, whichever bus is involved. 476 477The main task of this type of driver is to provide an "spi_controller". 478Use spi_alloc_host() to allocate the host controller, and 479spi_controller_get_devdata() to get the driver-private data allocated for that 480device. 481 482:: 483 484 struct spi_controller *ctlr; 485 struct CONTROLLER *c; 486 487 ctlr = spi_alloc_host(dev, sizeof *c); 488 if (!ctlr) 489 return -ENODEV; 490 491 c = spi_controller_get_devdata(ctlr); 492 493The driver will initialize the fields of that spi_controller, including the bus 494number (maybe the same as the platform device ID) and three methods used to 495interact with the SPI core and SPI protocol drivers. It will also initialize 496its own internal state. (See below about bus numbering and those methods.) 497 498After you initialize the spi_controller, then use spi_register_controller() to 499publish it to the rest of the system. At that time, device nodes for the 500controller and any predeclared spi devices will be made available, and 501the driver model core will take care of binding them to drivers. 502 503If you need to remove your SPI controller driver, spi_unregister_controller() 504will reverse the effect of spi_register_controller(). 505 506 507Bus Numbering 508^^^^^^^^^^^^^ 509 510Bus numbering is important, since that's how Linux identifies a given 511SPI bus (shared SCK, MOSI, MISO). Valid bus numbers start at zero. On 512SOC systems, the bus numbers should match the numbers defined by the chip 513manufacturer. For example, hardware controller SPI2 would be bus number 2, 514and spi_board_info for devices connected to it would use that number. 515 516If you don't have such hardware-assigned bus number, and for some reason 517you can't just assign them, then provide a negative bus number. That will 518then be replaced by a dynamically assigned number. You'd then need to treat 519this as a non-static configuration (see above). 520 521 522SPI Host Controller Methods 523^^^^^^^^^^^^^^^^^^^^^^^^^^^ 524 525``ctlr->setup(struct spi_device *spi)`` 526 This sets up the device clock rate, SPI mode, and word sizes. 527 Drivers may change the defaults provided by board_info, and then 528 call spi_setup(spi) to invoke this routine. It may sleep. 529 530 Unless each SPI target has its own configuration registers, don't 531 change them right away ... otherwise drivers could corrupt I/O 532 that's in progress for other SPI devices. 533 534 .. note:: 535 536 BUG ALERT: for some reason the first version of 537 many spi_controller drivers seems to get this wrong. 538 When you code setup(), ASSUME that the controller 539 is actively processing transfers for another device. 540 541``ctlr->cleanup(struct spi_device *spi)`` 542 Your controller driver may use spi_device.controller_state to hold 543 state it dynamically associates with that device. If you do that, 544 be sure to provide the cleanup() method to free that state. 545 546``ctlr->prepare_transfer_hardware(struct spi_controller *ctlr)`` 547 This will be called by the queue mechanism to signal to the driver 548 that a message is coming in soon, so the subsystem requests the 549 driver to prepare the transfer hardware by issuing this call. 550 This may sleep. 551 552``ctlr->unprepare_transfer_hardware(struct spi_controller *ctlr)`` 553 This will be called by the queue mechanism to signal to the driver 554 that there are no more messages pending in the queue and it may 555 relax the hardware (e.g. by power management calls). This may sleep. 556 557``ctlr->transfer_one_message(struct spi_controller *ctlr, struct spi_message *mesg)`` 558 The subsystem calls the driver to transfer a single message while 559 queuing transfers that arrive in the meantime. When the driver is 560 finished with this message, it must call 561 spi_finalize_current_message() so the subsystem can issue the next 562 message. This may sleep. 563 564``ctrl->transfer_one(struct spi_controller *ctlr, struct spi_device *spi, struct spi_transfer *transfer)`` 565 The subsystem calls the driver to transfer a single transfer while 566 queuing transfers that arrive in the meantime. When the driver is 567 finished with this transfer, it must call 568 spi_finalize_current_transfer() so the subsystem can issue the next 569 transfer. This may sleep. Note: transfer_one and transfer_one_message 570 are mutually exclusive; when both are set, the generic subsystem does 571 not call your transfer_one callback. 572 573 Return values: 574 575 * negative errno: error 576 * 0: transfer is finished 577 * 1: transfer is still in progress 578 579``ctrl->set_cs_timing(struct spi_device *spi, u8 setup_clk_cycles, u8 hold_clk_cycles, u8 inactive_clk_cycles)`` 580 This method allows SPI client drivers to request SPI host controller 581 for configuring device specific CS setup, hold and inactive timing 582 requirements. 583 584Deprecated Methods 585^^^^^^^^^^^^^^^^^^ 586 587``ctrl->transfer(struct spi_device *spi, struct spi_message *message)`` 588 This must not sleep. Its responsibility is to arrange that the 589 transfer happens and its complete() callback is issued. The two 590 will normally happen later, after other transfers complete, and 591 if the controller is idle it will need to be kickstarted. This 592 method is not used on queued controllers and must be NULL if 593 transfer_one_message() and (un)prepare_transfer_hardware() are 594 implemented. 595 596 597SPI Message Queue 598^^^^^^^^^^^^^^^^^ 599 600If you are happy with the standard queueing mechanism provided by the 601SPI subsystem, just implement the queued methods specified above. Using 602the message queue has the upside of centralizing a lot of code and 603providing pure process-context execution of methods. The message queue 604can also be elevated to realtime priority on high-priority SPI traffic. 605 606Unless the queueing mechanism in the SPI subsystem is selected, the bulk 607of the driver will be managing the I/O queue fed by the now deprecated 608function transfer(). 609 610That queue could be purely conceptual. For example, a driver used only 611for low-frequency sensor access might be fine using synchronous PIO. 612 613But the queue will probably be very real, using message->queue, PIO, 614often DMA (especially if the root filesystem is in SPI flash), and 615execution contexts like IRQ handlers, tasklets, or workqueues (such 616as keventd). Your driver can be as fancy, or as simple, as you need. 617Such a transfer() method would normally just add the message to a 618queue, and then start some asynchronous transfer engine (unless it's 619already running). 620 621 622THANKS TO 623--------- 624Contributors to Linux-SPI discussions include (in alphabetical order, 625by last name): 626 627- Mark Brown 628- David Brownell 629- Russell King 630- Grant Likely 631- Dmitry Pervushin 632- Stephen Street 633- Mark Underwood 634- Andrew Victor 635- Linus Walleij 636- Vitaly Wool 637