19cdd273eSMauro Carvalho Chehab==================================== 29cdd273eSMauro Carvalho ChehabOverview of Linux kernel SPI support 39cdd273eSMauro Carvalho Chehab==================================== 49cdd273eSMauro Carvalho Chehab 59cdd273eSMauro Carvalho Chehab02-Feb-2012 69cdd273eSMauro Carvalho Chehab 79cdd273eSMauro Carvalho ChehabWhat is SPI? 89cdd273eSMauro Carvalho Chehab------------ 99cdd273eSMauro Carvalho ChehabThe "Serial Peripheral Interface" (SPI) is a synchronous four wire serial 109cdd273eSMauro Carvalho Chehablink used to connect microcontrollers to sensors, memory, and peripherals. 119cdd273eSMauro Carvalho ChehabIt's a simple "de facto" standard, not complicated enough to acquire a 1276b31eb4SUwe Kleine-Königstandardization body. SPI uses a host/target configuration. 139cdd273eSMauro Carvalho Chehab 149cdd273eSMauro Carvalho ChehabThe three signal wires hold a clock (SCK, often on the order of 10 MHz), 159cdd273eSMauro Carvalho Chehaband parallel data lines with "Master Out, Slave In" (MOSI) or "Master In, 169cdd273eSMauro Carvalho ChehabSlave Out" (MISO) signals. (Other names are also used.) There are four 179cdd273eSMauro Carvalho Chehabclocking modes through which data is exchanged; mode-0 and mode-3 are most 189cdd273eSMauro Carvalho Chehabcommonly used. Each clock cycle shifts data out and data in; the clock 199cdd273eSMauro Carvalho Chehabdoesn't cycle except when there is a data bit to shift. Not all data bits 209cdd273eSMauro Carvalho Chehabare used though; not every protocol uses those full duplex capabilities. 219cdd273eSMauro Carvalho Chehab 2299769a52SDhruva GoleSPI hosts use a fourth "chip select" line to activate a given SPI target 239cdd273eSMauro Carvalho Chehabdevice, so those three signal wires may be connected to several chips 2499769a52SDhruva Golein parallel. All SPI targets support chipselects; they are usually active 2599769a52SDhruva Golelow signals, labeled nCSx for target 'x' (e.g. nCS0). Some devices have 2676b31eb4SUwe Kleine-Königother signals, often including an interrupt to the host. 279cdd273eSMauro Carvalho Chehab 289cdd273eSMauro Carvalho ChehabUnlike serial busses like USB or SMBus, even low level protocols for 2999769a52SDhruva GoleSPI target functions are usually not interoperable between vendors 309cdd273eSMauro Carvalho Chehab(except for commodities like SPI memory chips). 319cdd273eSMauro Carvalho Chehab 329cdd273eSMauro Carvalho Chehab - SPI may be used for request/response style device protocols, as with 339cdd273eSMauro Carvalho Chehab touchscreen sensors and memory chips. 349cdd273eSMauro Carvalho Chehab 359cdd273eSMauro Carvalho Chehab - It may also be used to stream data in either direction (half duplex), 369cdd273eSMauro Carvalho Chehab or both of them at the same time (full duplex). 379cdd273eSMauro Carvalho Chehab 389cdd273eSMauro Carvalho Chehab - Some devices may use eight bit words. Others may use different word 399cdd273eSMauro Carvalho Chehab lengths, such as streams of 12-bit or 20-bit digital samples. 409cdd273eSMauro Carvalho Chehab 419cdd273eSMauro Carvalho Chehab - Words are usually sent with their most significant bit (MSB) first, 429cdd273eSMauro Carvalho Chehab but sometimes the least significant bit (LSB) goes first instead. 439cdd273eSMauro Carvalho Chehab 449cdd273eSMauro Carvalho Chehab - Sometimes SPI is used to daisy-chain devices, like shift registers. 459cdd273eSMauro Carvalho Chehab 4699769a52SDhruva GoleIn the same way, SPI targets will only rarely support any kind of automatic 4799769a52SDhruva Golediscovery/enumeration protocol. The tree of target devices accessible from 4876b31eb4SUwe Kleine-Königa given SPI host controller will normally be set up manually, with 4976b31eb4SUwe Kleine-Königconfiguration tables. 509cdd273eSMauro Carvalho Chehab 519cdd273eSMauro Carvalho ChehabSPI is only one of the names used by such four-wire protocols, and 529cdd273eSMauro Carvalho Chehabmost controllers have no problem handling "MicroWire" (think of it as 539cdd273eSMauro Carvalho Chehabhalf-duplex SPI, for request/response protocols), SSP ("Synchronous 549cdd273eSMauro Carvalho ChehabSerial Protocol"), PSP ("Programmable Serial Protocol"), and other 559cdd273eSMauro Carvalho Chehabrelated protocols. 569cdd273eSMauro Carvalho Chehab 579cdd273eSMauro Carvalho ChehabSome chips eliminate a signal line by combining MOSI and MISO, and 589cdd273eSMauro Carvalho Chehablimiting themselves to half-duplex at the hardware level. In fact 599cdd273eSMauro Carvalho Chehabsome SPI chips have this signal mode as a strapping option. These 609cdd273eSMauro Carvalho Chehabcan be accessed using the same programming interface as SPI, but of 619cdd273eSMauro Carvalho Chehabcourse they won't handle full duplex transfers. You may find such 629cdd273eSMauro Carvalho Chehabchips described as using "three wire" signaling: SCK, data, nCSx. 639cdd273eSMauro Carvalho Chehab(That data line is sometimes called MOMI or SISO.) 649cdd273eSMauro Carvalho Chehab 6576b31eb4SUwe Kleine-KönigMicrocontrollers often support both host and target sides of the SPI 6676b31eb4SUwe Kleine-Königprotocol. This document (and Linux) supports both the host and target 679cdd273eSMauro Carvalho Chehabsides of SPI interactions. 689cdd273eSMauro Carvalho Chehab 699cdd273eSMauro Carvalho Chehab 709cdd273eSMauro Carvalho ChehabWho uses it? On what kinds of systems? 719cdd273eSMauro Carvalho Chehab--------------------------------------- 729cdd273eSMauro Carvalho ChehabLinux developers using SPI are probably writing device drivers for embedded 739cdd273eSMauro Carvalho Chehabsystems boards. SPI is used to control external chips, and it is also a 749cdd273eSMauro Carvalho Chehabprotocol supported by every MMC or SD memory card. (The older "DataFlash" 759cdd273eSMauro Carvalho Chehabcards, predating MMC cards but using the same connectors and card shape, 769cdd273eSMauro Carvalho Chehabsupport only SPI.) Some PC hardware uses SPI flash for BIOS code. 779cdd273eSMauro Carvalho Chehab 7899769a52SDhruva GoleSPI target chips range from digital/analog converters used for analog 799cdd273eSMauro Carvalho Chehabsensors and codecs, to memory, to peripherals like USB controllers 809cdd273eSMauro Carvalho Chehabor Ethernet adapters; and more. 819cdd273eSMauro Carvalho Chehab 829cdd273eSMauro Carvalho ChehabMost systems using SPI will integrate a few devices on a mainboard. 839cdd273eSMauro Carvalho ChehabSome provide SPI links on expansion connectors; in cases where no 849cdd273eSMauro Carvalho Chehabdedicated SPI controller exists, GPIO pins can be used to create a 859cdd273eSMauro Carvalho Chehablow speed "bitbanging" adapter. Very few systems will "hotplug" an SPI 869cdd273eSMauro Carvalho Chehabcontroller; the reasons to use SPI focus on low cost and simple operation, 879cdd273eSMauro Carvalho Chehaband if dynamic reconfiguration is important, USB will often be a more 889cdd273eSMauro Carvalho Chehabappropriate low-pincount peripheral bus. 899cdd273eSMauro Carvalho Chehab 909cdd273eSMauro Carvalho ChehabMany microcontrollers that can run Linux integrate one or more I/O 919cdd273eSMauro Carvalho Chehabinterfaces with SPI modes. Given SPI support, they could use MMC or SD 929cdd273eSMauro Carvalho Chehabcards without needing a special purpose MMC/SD/SDIO controller. 939cdd273eSMauro Carvalho Chehab 949cdd273eSMauro Carvalho Chehab 959cdd273eSMauro Carvalho ChehabI'm confused. What are these four SPI "clock modes"? 969cdd273eSMauro Carvalho Chehab----------------------------------------------------- 979cdd273eSMauro Carvalho ChehabIt's easy to be confused here, and the vendor documentation you'll 989cdd273eSMauro Carvalho Chehabfind isn't necessarily helpful. The four modes combine two mode bits: 999cdd273eSMauro Carvalho Chehab 1009cdd273eSMauro Carvalho Chehab - CPOL indicates the initial clock polarity. CPOL=0 means the 1019cdd273eSMauro Carvalho Chehab clock starts low, so the first (leading) edge is rising, and 1029cdd273eSMauro Carvalho Chehab the second (trailing) edge is falling. CPOL=1 means the clock 1039cdd273eSMauro Carvalho Chehab starts high, so the first (leading) edge is falling. 1049cdd273eSMauro Carvalho Chehab 1059cdd273eSMauro Carvalho Chehab - CPHA indicates the clock phase used to sample data; CPHA=0 says 1069cdd273eSMauro Carvalho Chehab sample on the leading edge, CPHA=1 means the trailing edge. 1079cdd273eSMauro Carvalho Chehab 1080f6d2ceeSRandy Dunlap Since the signal needs to stabilize before it's sampled, CPHA=0 1099cdd273eSMauro Carvalho Chehab implies that its data is written half a clock before the first 1109cdd273eSMauro Carvalho Chehab clock edge. The chipselect may have made it become available. 1119cdd273eSMauro Carvalho Chehab 1129cdd273eSMauro Carvalho ChehabChip specs won't always say "uses SPI mode X" in as many words, 1139cdd273eSMauro Carvalho Chehabbut their timing diagrams will make the CPOL and CPHA modes clear. 1149cdd273eSMauro Carvalho Chehab 1159cdd273eSMauro Carvalho ChehabIn the SPI mode number, CPOL is the high order bit and CPHA is the 1169cdd273eSMauro Carvalho Chehablow order bit. So when a chip's timing diagram shows the clock 1179cdd273eSMauro Carvalho Chehabstarting low (CPOL=0) and data stabilized for sampling during the 1189cdd273eSMauro Carvalho Chehabtrailing clock edge (CPHA=1), that's SPI mode 1. 1199cdd273eSMauro Carvalho Chehab 1209cdd273eSMauro Carvalho ChehabNote that the clock mode is relevant as soon as the chipselect goes 12176b31eb4SUwe Kleine-Königactive. So the host must set the clock to inactive before selecting 12299769a52SDhruva Golea target, and the target can tell the chosen polarity by sampling the 1239cdd273eSMauro Carvalho Chehabclock level when its select line goes active. That's why many devices 1249cdd273eSMauro Carvalho Chehabsupport for example both modes 0 and 3: they don't care about polarity, 1259cdd273eSMauro Carvalho Chehaband always clock data in/out on rising clock edges. 1269cdd273eSMauro Carvalho Chehab 1279cdd273eSMauro Carvalho Chehab 1289cdd273eSMauro Carvalho ChehabHow do these driver programming interfaces work? 1299cdd273eSMauro Carvalho Chehab------------------------------------------------ 1309cdd273eSMauro Carvalho ChehabThe <linux/spi/spi.h> header file includes kerneldoc, as does the 1319cdd273eSMauro Carvalho Chehabmain source code, and you should certainly read that chapter of the 1329cdd273eSMauro Carvalho Chehabkernel API document. This is just an overview, so you get the big 1339cdd273eSMauro Carvalho Chehabpicture before those details. 1349cdd273eSMauro Carvalho Chehab 1359cdd273eSMauro Carvalho ChehabSPI requests always go into I/O queues. Requests for a given SPI device 1369cdd273eSMauro Carvalho Chehabare always executed in FIFO order, and complete asynchronously through 1379cdd273eSMauro Carvalho Chehabcompletion callbacks. There are also some simple synchronous wrappers 1389cdd273eSMauro Carvalho Chehabfor those calls, including ones for common transaction types like writing 1399cdd273eSMauro Carvalho Chehaba command and then reading its response. 1409cdd273eSMauro Carvalho Chehab 1419cdd273eSMauro Carvalho ChehabThere are two types of SPI driver, here called: 1429cdd273eSMauro Carvalho Chehab 1439cdd273eSMauro Carvalho Chehab Controller drivers ... 1449cdd273eSMauro Carvalho Chehab controllers may be built into System-On-Chip 14599769a52SDhruva Gole processors, and often support both Controller and target roles. 1469cdd273eSMauro Carvalho Chehab These drivers touch hardware registers and may use DMA. 1479cdd273eSMauro Carvalho Chehab Or they can be PIO bitbangers, needing just GPIO pins. 1489cdd273eSMauro Carvalho Chehab 1499cdd273eSMauro Carvalho Chehab Protocol drivers ... 1509cdd273eSMauro Carvalho Chehab these pass messages through the controller 15199769a52SDhruva Gole driver to communicate with a target or Controller device on the 1529cdd273eSMauro Carvalho Chehab other side of an SPI link. 1539cdd273eSMauro Carvalho Chehab 1549cdd273eSMauro Carvalho ChehabSo for example one protocol driver might talk to the MTD layer to export 1559cdd273eSMauro Carvalho Chehabdata to filesystems stored on SPI flash like DataFlash; and others might 1569cdd273eSMauro Carvalho Chehabcontrol audio interfaces, present touchscreen sensors as input interfaces, 1579cdd273eSMauro Carvalho Chehabor monitor temperature and voltage levels during industrial processing. 1589cdd273eSMauro Carvalho ChehabAnd those might all be sharing the same controller driver. 1599cdd273eSMauro Carvalho Chehab 1609cdd273eSMauro Carvalho ChehabA "struct spi_device" encapsulates the controller-side interface between 1619cdd273eSMauro Carvalho Chehabthose two types of drivers. 1629cdd273eSMauro Carvalho Chehab 1639cdd273eSMauro Carvalho ChehabThere is a minimal core of SPI programming interfaces, focussing on 1649cdd273eSMauro Carvalho Chehabusing the driver model to connect controller and protocol drivers using 1659cdd273eSMauro Carvalho Chehabdevice tables provided by board specific initialization code. SPI 1669cdd273eSMauro Carvalho Chehabshows up in sysfs in several locations:: 1679cdd273eSMauro Carvalho Chehab 1689cdd273eSMauro Carvalho Chehab /sys/devices/.../CTLR ... physical node for a given SPI controller 1699cdd273eSMauro Carvalho Chehab 1709cdd273eSMauro Carvalho Chehab /sys/devices/.../CTLR/spiB.C ... spi_device on bus "B", 1719cdd273eSMauro Carvalho Chehab chipselect C, accessed through CTLR. 1729cdd273eSMauro Carvalho Chehab 1739cdd273eSMauro Carvalho Chehab /sys/bus/spi/devices/spiB.C ... symlink to that physical 1749cdd273eSMauro Carvalho Chehab .../CTLR/spiB.C device 1759cdd273eSMauro Carvalho Chehab 1769cdd273eSMauro Carvalho Chehab /sys/devices/.../CTLR/spiB.C/modalias ... identifies the driver 1779cdd273eSMauro Carvalho Chehab that should be used with this device (for hotplug/coldplug) 1789cdd273eSMauro Carvalho Chehab 1799cdd273eSMauro Carvalho Chehab /sys/bus/spi/drivers/D ... driver for one or more spi*.* devices 1809cdd273eSMauro Carvalho Chehab 18193d20545SLukas Bulwahn /sys/class/spi_master/spiB ... symlink to a logical node which could hold 18276b31eb4SUwe Kleine-König class related state for the SPI host controller managing bus "B". 18393d20545SLukas Bulwahn All spiB.* devices share one physical SPI bus segment, with SCLK, 18493d20545SLukas Bulwahn MOSI, and MISO. 1859cdd273eSMauro Carvalho Chehab 1869cdd273eSMauro Carvalho Chehab /sys/devices/.../CTLR/slave ... virtual file for (un)registering the 18799769a52SDhruva Gole target device for an SPI target controller. 18899769a52SDhruva Gole Writing the driver name of an SPI target handler to this file 18999769a52SDhruva Gole registers the target device; writing "(null)" unregisters the target 1909cdd273eSMauro Carvalho Chehab device. 19199769a52SDhruva Gole Reading from this file shows the name of the target device ("(null)" 1929cdd273eSMauro Carvalho Chehab if not registered). 1939cdd273eSMauro Carvalho Chehab 19493d20545SLukas Bulwahn /sys/class/spi_slave/spiB ... symlink to a logical node which could hold 19599769a52SDhruva Gole class related state for the SPI target controller on bus "B". When 19693d20545SLukas Bulwahn registered, a single spiB.* device is present here, possible sharing 19799769a52SDhruva Gole the physical SPI bus segment with other SPI target devices. 1989cdd273eSMauro Carvalho Chehab 19993d20545SLukas BulwahnAt this time, the only class-specific state is the bus number ("B" in "spiB"), 20093d20545SLukas Bulwahnso those /sys/class entries are only useful to quickly identify busses. 2019cdd273eSMauro Carvalho Chehab 2029cdd273eSMauro Carvalho Chehab 2039cdd273eSMauro Carvalho ChehabHow does board-specific init code declare SPI devices? 2049cdd273eSMauro Carvalho Chehab------------------------------------------------------ 2059cdd273eSMauro Carvalho ChehabLinux needs several kinds of information to properly configure SPI devices. 2069cdd273eSMauro Carvalho ChehabThat information is normally provided by board-specific code, even for 2079cdd273eSMauro Carvalho Chehabchips that do support some of automated discovery/enumeration. 2089cdd273eSMauro Carvalho Chehab 2099cdd273eSMauro Carvalho ChehabDeclare Controllers 2109cdd273eSMauro Carvalho Chehab^^^^^^^^^^^^^^^^^^^ 2119cdd273eSMauro Carvalho Chehab 2129cdd273eSMauro Carvalho ChehabThe first kind of information is a list of what SPI controllers exist. 2139cdd273eSMauro Carvalho ChehabFor System-on-Chip (SOC) based boards, these will usually be platform 2149cdd273eSMauro Carvalho Chehabdevices, and the controller may need some platform_data in order to 2159cdd273eSMauro Carvalho Chehaboperate properly. The "struct platform_device" will include resources 2169cdd273eSMauro Carvalho Chehablike the physical address of the controller's first register and its IRQ. 2179cdd273eSMauro Carvalho Chehab 2189cdd273eSMauro Carvalho ChehabPlatforms will often abstract the "register SPI controller" operation, 2199cdd273eSMauro Carvalho Chehabmaybe coupling it with code to initialize pin configurations, so that 2209cdd273eSMauro Carvalho Chehabthe arch/.../mach-*/board-*.c files for several boards can all share the 2219cdd273eSMauro Carvalho Chehabsame basic controller setup code. This is because most SOCs have several 2229cdd273eSMauro Carvalho ChehabSPI-capable controllers, and only the ones actually usable on a given 2239cdd273eSMauro Carvalho Chehabboard should normally be set up and registered. 2249cdd273eSMauro Carvalho Chehab 2259cdd273eSMauro Carvalho ChehabSo for example arch/.../mach-*/board-*.c files might have code like:: 2269cdd273eSMauro Carvalho Chehab 2279cdd273eSMauro Carvalho Chehab #include <mach/spi.h> /* for mysoc_spi_data */ 2289cdd273eSMauro Carvalho Chehab 2299cdd273eSMauro Carvalho Chehab /* if your mach-* infrastructure doesn't support kernels that can 2309cdd273eSMauro Carvalho Chehab * run on multiple boards, pdata wouldn't benefit from "__init". 2319cdd273eSMauro Carvalho Chehab */ 2329cdd273eSMauro Carvalho Chehab static struct mysoc_spi_data pdata __initdata = { ... }; 2339cdd273eSMauro Carvalho Chehab 2349cdd273eSMauro Carvalho Chehab static __init board_init(void) 2359cdd273eSMauro Carvalho Chehab { 2369cdd273eSMauro Carvalho Chehab ... 2379cdd273eSMauro Carvalho Chehab /* this board only uses SPI controller #2 */ 2389cdd273eSMauro Carvalho Chehab mysoc_register_spi(2, &pdata); 2399cdd273eSMauro Carvalho Chehab ... 2409cdd273eSMauro Carvalho Chehab } 2419cdd273eSMauro Carvalho Chehab 2429cdd273eSMauro Carvalho ChehabAnd SOC-specific utility code might look something like:: 2439cdd273eSMauro Carvalho Chehab 2449cdd273eSMauro Carvalho Chehab #include <mach/spi.h> 2459cdd273eSMauro Carvalho Chehab 2469cdd273eSMauro Carvalho Chehab static struct platform_device spi2 = { ... }; 2479cdd273eSMauro Carvalho Chehab 2489cdd273eSMauro Carvalho Chehab void mysoc_register_spi(unsigned n, struct mysoc_spi_data *pdata) 2499cdd273eSMauro Carvalho Chehab { 2509cdd273eSMauro Carvalho Chehab struct mysoc_spi_data *pdata2; 2519cdd273eSMauro Carvalho Chehab 2529cdd273eSMauro Carvalho Chehab pdata2 = kmalloc(sizeof *pdata2, GFP_KERNEL); 2539cdd273eSMauro Carvalho Chehab *pdata2 = pdata; 2549cdd273eSMauro Carvalho Chehab ... 2559cdd273eSMauro Carvalho Chehab if (n == 2) { 2569cdd273eSMauro Carvalho Chehab spi2->dev.platform_data = pdata2; 2579cdd273eSMauro Carvalho Chehab register_platform_device(&spi2); 2589cdd273eSMauro Carvalho Chehab 2599cdd273eSMauro Carvalho Chehab /* also: set up pin modes so the spi2 signals are 2609cdd273eSMauro Carvalho Chehab * visible on the relevant pins ... bootloaders on 2619cdd273eSMauro Carvalho Chehab * production boards may already have done this, but 2629cdd273eSMauro Carvalho Chehab * developer boards will often need Linux to do it. 2639cdd273eSMauro Carvalho Chehab */ 2649cdd273eSMauro Carvalho Chehab } 2659cdd273eSMauro Carvalho Chehab ... 2669cdd273eSMauro Carvalho Chehab } 2679cdd273eSMauro Carvalho Chehab 2689cdd273eSMauro Carvalho ChehabNotice how the platform_data for boards may be different, even if the 2699cdd273eSMauro Carvalho Chehabsame SOC controller is used. For example, on one board SPI might use 2709cdd273eSMauro Carvalho Chehaban external clock, where another derives the SPI clock from current 2719cdd273eSMauro Carvalho Chehabsettings of some master clock. 2729cdd273eSMauro Carvalho Chehab 27399769a52SDhruva GoleDeclare target Devices 274*afd2a4aeSRandy Dunlap^^^^^^^^^^^^^^^^^^^^^^ 2759cdd273eSMauro Carvalho Chehab 27699769a52SDhruva GoleThe second kind of information is a list of what SPI target devices exist 2779cdd273eSMauro Carvalho Chehabon the target board, often with some board-specific data needed for the 2789cdd273eSMauro Carvalho Chehabdriver to work correctly. 2799cdd273eSMauro Carvalho Chehab 2809cdd273eSMauro Carvalho ChehabNormally your arch/.../mach-*/board-*.c files would provide a small table 2819cdd273eSMauro Carvalho Chehablisting the SPI devices on each board. (This would typically be only a 2829cdd273eSMauro Carvalho Chehabsmall handful.) That might look like:: 2839cdd273eSMauro Carvalho Chehab 2849cdd273eSMauro Carvalho Chehab static struct ads7846_platform_data ads_info = { 2859cdd273eSMauro Carvalho Chehab .vref_delay_usecs = 100, 2869cdd273eSMauro Carvalho Chehab .x_plate_ohms = 580, 2879cdd273eSMauro Carvalho Chehab .y_plate_ohms = 410, 2889cdd273eSMauro Carvalho Chehab }; 2899cdd273eSMauro Carvalho Chehab 2909cdd273eSMauro Carvalho Chehab static struct spi_board_info spi_board_info[] __initdata = { 2919cdd273eSMauro Carvalho Chehab { 2929cdd273eSMauro Carvalho Chehab .modalias = "ads7846", 2939cdd273eSMauro Carvalho Chehab .platform_data = &ads_info, 2949cdd273eSMauro Carvalho Chehab .mode = SPI_MODE_0, 2959cdd273eSMauro Carvalho Chehab .irq = GPIO_IRQ(31), 2969cdd273eSMauro Carvalho Chehab .max_speed_hz = 120000 /* max sample rate at 3V */ * 16, 2979cdd273eSMauro Carvalho Chehab .bus_num = 1, 2989cdd273eSMauro Carvalho Chehab .chip_select = 0, 2999cdd273eSMauro Carvalho Chehab }, 3009cdd273eSMauro Carvalho Chehab }; 3019cdd273eSMauro Carvalho Chehab 3029cdd273eSMauro Carvalho ChehabAgain, notice how board-specific information is provided; each chip may need 3039cdd273eSMauro Carvalho Chehabseveral types. This example shows generic constraints like the fastest SPI 3049cdd273eSMauro Carvalho Chehabclock to allow (a function of board voltage in this case) or how an IRQ pin 3059cdd273eSMauro Carvalho Chehabis wired, plus chip-specific constraints like an important delay that's 3069cdd273eSMauro Carvalho Chehabchanged by the capacitance at one pin. 3079cdd273eSMauro Carvalho Chehab 3089cdd273eSMauro Carvalho Chehab(There's also "controller_data", information that may be useful to the 3099cdd273eSMauro Carvalho Chehabcontroller driver. An example would be peripheral-specific DMA tuning 3109cdd273eSMauro Carvalho Chehabdata or chipselect callbacks. This is stored in spi_device later.) 3119cdd273eSMauro Carvalho Chehab 3129cdd273eSMauro Carvalho ChehabThe board_info should provide enough information to let the system work 3139cdd273eSMauro Carvalho Chehabwithout the chip's driver being loaded. The most troublesome aspect of 3149cdd273eSMauro Carvalho Chehabthat is likely the SPI_CS_HIGH bit in the spi_device.mode field, since 3159cdd273eSMauro Carvalho Chehabsharing a bus with a device that interprets chipselect "backwards" is 3169cdd273eSMauro Carvalho Chehabnot possible until the infrastructure knows how to deselect it. 3179cdd273eSMauro Carvalho Chehab 3189cdd273eSMauro Carvalho ChehabThen your board initialization code would register that table with the SPI 31976b31eb4SUwe Kleine-Königinfrastructure, so that it's available later when the SPI host controller 3209cdd273eSMauro Carvalho Chehabdriver is registered:: 3219cdd273eSMauro Carvalho Chehab 3229cdd273eSMauro Carvalho Chehab spi_register_board_info(spi_board_info, ARRAY_SIZE(spi_board_info)); 3239cdd273eSMauro Carvalho Chehab 3249cdd273eSMauro Carvalho ChehabLike with other static board-specific setup, you won't unregister those. 3259cdd273eSMauro Carvalho Chehab 3269cdd273eSMauro Carvalho ChehabThe widely used "card" style computers bundle memory, cpu, and little else 3279cdd273eSMauro Carvalho Chehabonto a card that's maybe just thirty square centimeters. On such systems, 3289cdd273eSMauro Carvalho Chehabyour ``arch/.../mach-.../board-*.c`` file would primarily provide information 3299cdd273eSMauro Carvalho Chehababout the devices on the mainboard into which such a card is plugged. That 3309cdd273eSMauro Carvalho Chehabcertainly includes SPI devices hooked up through the card connectors! 3319cdd273eSMauro Carvalho Chehab 3329cdd273eSMauro Carvalho Chehab 3339cdd273eSMauro Carvalho ChehabNon-static Configurations 3349cdd273eSMauro Carvalho Chehab^^^^^^^^^^^^^^^^^^^^^^^^^ 3359cdd273eSMauro Carvalho Chehab 3369cdd273eSMauro Carvalho ChehabWhen Linux includes support for MMC/SD/SDIO/DataFlash cards through SPI, those 3379cdd273eSMauro Carvalho Chehabconfigurations will also be dynamic. Fortunately, such devices all support 3389cdd273eSMauro Carvalho Chehabbasic device identification probes, so they should hotplug normally. 3399cdd273eSMauro Carvalho Chehab 3409cdd273eSMauro Carvalho Chehab 3419cdd273eSMauro Carvalho ChehabHow do I write an "SPI Protocol Driver"? 3429cdd273eSMauro Carvalho Chehab---------------------------------------- 3439cdd273eSMauro Carvalho ChehabMost SPI drivers are currently kernel drivers, but there's also support 3449cdd273eSMauro Carvalho Chehabfor userspace drivers. Here we talk only about kernel drivers. 3459cdd273eSMauro Carvalho Chehab 3469cdd273eSMauro Carvalho ChehabSPI protocol drivers somewhat resemble platform device drivers:: 3479cdd273eSMauro Carvalho Chehab 3489cdd273eSMauro Carvalho Chehab static struct spi_driver CHIP_driver = { 3499cdd273eSMauro Carvalho Chehab .driver = { 3509cdd273eSMauro Carvalho Chehab .name = "CHIP", 3519cdd273eSMauro Carvalho Chehab .pm = &CHIP_pm_ops, 3529cdd273eSMauro Carvalho Chehab }, 3539cdd273eSMauro Carvalho Chehab 3549cdd273eSMauro Carvalho Chehab .probe = CHIP_probe, 3559cdd273eSMauro Carvalho Chehab .remove = CHIP_remove, 3569cdd273eSMauro Carvalho Chehab }; 3579cdd273eSMauro Carvalho Chehab 3589cdd273eSMauro Carvalho ChehabThe driver core will automatically attempt to bind this driver to any SPI 3599cdd273eSMauro Carvalho Chehabdevice whose board_info gave a modalias of "CHIP". Your probe() code 3609cdd273eSMauro Carvalho Chehabmight look like this unless you're creating a device which is managing 3619cdd273eSMauro Carvalho Chehaba bus (appearing under /sys/class/spi_master). 3629cdd273eSMauro Carvalho Chehab 3639cdd273eSMauro Carvalho Chehab:: 3649cdd273eSMauro Carvalho Chehab 3659cdd273eSMauro Carvalho Chehab static int CHIP_probe(struct spi_device *spi) 3669cdd273eSMauro Carvalho Chehab { 3679cdd273eSMauro Carvalho Chehab struct CHIP *chip; 3689cdd273eSMauro Carvalho Chehab struct CHIP_platform_data *pdata; 3699cdd273eSMauro Carvalho Chehab 3709cdd273eSMauro Carvalho Chehab /* assuming the driver requires board-specific data: */ 3719cdd273eSMauro Carvalho Chehab pdata = &spi->dev.platform_data; 3729cdd273eSMauro Carvalho Chehab if (!pdata) 3739cdd273eSMauro Carvalho Chehab return -ENODEV; 3749cdd273eSMauro Carvalho Chehab 3759cdd273eSMauro Carvalho Chehab /* get memory for driver's per-chip state */ 3769cdd273eSMauro Carvalho Chehab chip = kzalloc(sizeof *chip, GFP_KERNEL); 3779cdd273eSMauro Carvalho Chehab if (!chip) 3789cdd273eSMauro Carvalho Chehab return -ENOMEM; 3799cdd273eSMauro Carvalho Chehab spi_set_drvdata(spi, chip); 3809cdd273eSMauro Carvalho Chehab 3819cdd273eSMauro Carvalho Chehab ... etc 3829cdd273eSMauro Carvalho Chehab return 0; 3839cdd273eSMauro Carvalho Chehab } 3849cdd273eSMauro Carvalho Chehab 3859cdd273eSMauro Carvalho ChehabAs soon as it enters probe(), the driver may issue I/O requests to 3869cdd273eSMauro Carvalho Chehabthe SPI device using "struct spi_message". When remove() returns, 3879cdd273eSMauro Carvalho Chehabor after probe() fails, the driver guarantees that it won't submit 3889cdd273eSMauro Carvalho Chehabany more such messages. 3899cdd273eSMauro Carvalho Chehab 3909cdd273eSMauro Carvalho Chehab - An spi_message is a sequence of protocol operations, executed 3919cdd273eSMauro Carvalho Chehab as one atomic sequence. SPI driver controls include: 3929cdd273eSMauro Carvalho Chehab 3939cdd273eSMauro Carvalho Chehab + when bidirectional reads and writes start ... by how its 3949cdd273eSMauro Carvalho Chehab sequence of spi_transfer requests is arranged; 3959cdd273eSMauro Carvalho Chehab 3969cdd273eSMauro Carvalho Chehab + which I/O buffers are used ... each spi_transfer wraps a 3979cdd273eSMauro Carvalho Chehab buffer for each transfer direction, supporting full duplex 3989cdd273eSMauro Carvalho Chehab (two pointers, maybe the same one in both cases) and half 3999cdd273eSMauro Carvalho Chehab duplex (one pointer is NULL) transfers; 4009cdd273eSMauro Carvalho Chehab 4019cdd273eSMauro Carvalho Chehab + optionally defining short delays after transfers ... using 40205d8a019SAlexandru Ardelean the spi_transfer.delay.value setting (this delay can be the 40305d8a019SAlexandru Ardelean only protocol effect, if the buffer length is zero) ... 40405d8a019SAlexandru Ardelean when specifying this delay the default spi_transfer.delay.unit 40505d8a019SAlexandru Ardelean is microseconds, however this can be adjusted to clock cycles 40605d8a019SAlexandru Ardelean or nanoseconds if needed; 4079cdd273eSMauro Carvalho Chehab 4089cdd273eSMauro Carvalho Chehab + whether the chipselect becomes inactive after a transfer and 4099cdd273eSMauro Carvalho Chehab any delay ... by using the spi_transfer.cs_change flag; 4109cdd273eSMauro Carvalho Chehab 4119cdd273eSMauro Carvalho Chehab + hinting whether the next message is likely to go to this same 4129cdd273eSMauro Carvalho Chehab device ... using the spi_transfer.cs_change flag on the last 4139cdd273eSMauro Carvalho Chehab transfer in that atomic group, and potentially saving costs 4149cdd273eSMauro Carvalho Chehab for chip deselect and select operations. 4159cdd273eSMauro Carvalho Chehab 4169cdd273eSMauro Carvalho Chehab - Follow standard kernel rules, and provide DMA-safe buffers in 4179cdd273eSMauro Carvalho Chehab your messages. That way controller drivers using DMA aren't forced 4189cdd273eSMauro Carvalho Chehab to make extra copies unless the hardware requires it (e.g. working 4199cdd273eSMauro Carvalho Chehab around hardware errata that force the use of bounce buffering). 4209cdd273eSMauro Carvalho Chehab 4219cdd273eSMauro Carvalho Chehab - The basic I/O primitive is spi_async(). Async requests may be 4229cdd273eSMauro Carvalho Chehab issued in any context (irq handler, task, etc) and completion 4239cdd273eSMauro Carvalho Chehab is reported using a callback provided with the message. 4249cdd273eSMauro Carvalho Chehab After any detected error, the chip is deselected and processing 4259cdd273eSMauro Carvalho Chehab of that spi_message is aborted. 4269cdd273eSMauro Carvalho Chehab 4279cdd273eSMauro Carvalho Chehab - There are also synchronous wrappers like spi_sync(), and wrappers 4289cdd273eSMauro Carvalho Chehab like spi_read(), spi_write(), and spi_write_then_read(). These 4299cdd273eSMauro Carvalho Chehab may be issued only in contexts that may sleep, and they're all 4309cdd273eSMauro Carvalho Chehab clean (and small, and "optional") layers over spi_async(). 4319cdd273eSMauro Carvalho Chehab 4329cdd273eSMauro Carvalho Chehab - The spi_write_then_read() call, and convenience wrappers around 4339cdd273eSMauro Carvalho Chehab it, should only be used with small amounts of data where the 4349cdd273eSMauro Carvalho Chehab cost of an extra copy may be ignored. It's designed to support 4359cdd273eSMauro Carvalho Chehab common RPC-style requests, such as writing an eight bit command 4369cdd273eSMauro Carvalho Chehab and reading a sixteen bit response -- spi_w8r16() being one its 4379cdd273eSMauro Carvalho Chehab wrappers, doing exactly that. 4389cdd273eSMauro Carvalho Chehab 4399cdd273eSMauro Carvalho ChehabSome drivers may need to modify spi_device characteristics like the 4409cdd273eSMauro Carvalho Chehabtransfer mode, wordsize, or clock rate. This is done with spi_setup(), 4419cdd273eSMauro Carvalho Chehabwhich would normally be called from probe() before the first I/O is 4429cdd273eSMauro Carvalho Chehabdone to the device. However, that can also be called at any time 4439cdd273eSMauro Carvalho Chehabthat no message is pending for that device. 4449cdd273eSMauro Carvalho Chehab 4459cdd273eSMauro Carvalho ChehabWhile "spi_device" would be the bottom boundary of the driver, the 4469cdd273eSMauro Carvalho Chehabupper boundaries might include sysfs (especially for sensor readings), 4479cdd273eSMauro Carvalho Chehabthe input layer, ALSA, networking, MTD, the character device framework, 4489cdd273eSMauro Carvalho Chehabor other Linux subsystems. 4499cdd273eSMauro Carvalho Chehab 4509cdd273eSMauro Carvalho ChehabNote that there are two types of memory your driver must manage as part 4519cdd273eSMauro Carvalho Chehabof interacting with SPI devices. 4529cdd273eSMauro Carvalho Chehab 4539cdd273eSMauro Carvalho Chehab - I/O buffers use the usual Linux rules, and must be DMA-safe. 4549cdd273eSMauro Carvalho Chehab You'd normally allocate them from the heap or free page pool. 4559cdd273eSMauro Carvalho Chehab Don't use the stack, or anything that's declared "static". 4569cdd273eSMauro Carvalho Chehab 4579cdd273eSMauro Carvalho Chehab - The spi_message and spi_transfer metadata used to glue those 4589cdd273eSMauro Carvalho Chehab I/O buffers into a group of protocol transactions. These can 4599cdd273eSMauro Carvalho Chehab be allocated anywhere it's convenient, including as part of 4609cdd273eSMauro Carvalho Chehab other allocate-once driver data structures. Zero-init these. 4619cdd273eSMauro Carvalho Chehab 4629cdd273eSMauro Carvalho ChehabIf you like, spi_message_alloc() and spi_message_free() convenience 4639cdd273eSMauro Carvalho Chehabroutines are available to allocate and zero-initialize an spi_message 4649cdd273eSMauro Carvalho Chehabwith several transfers. 4659cdd273eSMauro Carvalho Chehab 4669cdd273eSMauro Carvalho Chehab 46799769a52SDhruva GoleHow do I write an "SPI Controller Driver"? 4689cdd273eSMauro Carvalho Chehab------------------------------------------------- 4699cdd273eSMauro Carvalho ChehabAn SPI controller will probably be registered on the platform_bus; write 4709cdd273eSMauro Carvalho Chehaba driver to bind to the device, whichever bus is involved. 4719cdd273eSMauro Carvalho Chehab 47276b31eb4SUwe Kleine-KönigThe main task of this type of driver is to provide an "spi_controller". 47376b31eb4SUwe Kleine-KönigUse spi_alloc_host() to allocate the host controller, and 47476b31eb4SUwe Kleine-Königspi_controller_get_devdata() to get the driver-private data allocated for that 47576b31eb4SUwe Kleine-Königdevice. 4769cdd273eSMauro Carvalho Chehab 4779cdd273eSMauro Carvalho Chehab:: 4789cdd273eSMauro Carvalho Chehab 47976b31eb4SUwe Kleine-König struct spi_controller *ctlr; 4809cdd273eSMauro Carvalho Chehab struct CONTROLLER *c; 4819cdd273eSMauro Carvalho Chehab 48276b31eb4SUwe Kleine-König ctlr = spi_alloc_host(dev, sizeof *c); 48376b31eb4SUwe Kleine-König if (!ctlr) 4849cdd273eSMauro Carvalho Chehab return -ENODEV; 4859cdd273eSMauro Carvalho Chehab 48676b31eb4SUwe Kleine-König c = spi_controller_get_devdata(ctlr); 4879cdd273eSMauro Carvalho Chehab 48876b31eb4SUwe Kleine-KönigThe driver will initialize the fields of that spi_controller, including the bus 48976b31eb4SUwe Kleine-Könignumber (maybe the same as the platform device ID) and three methods used to 49076b31eb4SUwe Kleine-Königinteract with the SPI core and SPI protocol drivers. It will also initialize 49176b31eb4SUwe Kleine-Königits own internal state. (See below about bus numbering and those methods.) 4929cdd273eSMauro Carvalho Chehab 49376b31eb4SUwe Kleine-KönigAfter you initialize the spi_controller, then use spi_register_controller() to 4949cdd273eSMauro Carvalho Chehabpublish it to the rest of the system. At that time, device nodes for the 4959cdd273eSMauro Carvalho Chehabcontroller and any predeclared spi devices will be made available, and 4969cdd273eSMauro Carvalho Chehabthe driver model core will take care of binding them to drivers. 4979cdd273eSMauro Carvalho Chehab 49876b31eb4SUwe Kleine-KönigIf you need to remove your SPI controller driver, spi_unregister_controller() 49976b31eb4SUwe Kleine-Königwill reverse the effect of spi_register_controller(). 5009cdd273eSMauro Carvalho Chehab 5019cdd273eSMauro Carvalho Chehab 5029cdd273eSMauro Carvalho ChehabBus Numbering 5039cdd273eSMauro Carvalho Chehab^^^^^^^^^^^^^ 5049cdd273eSMauro Carvalho Chehab 5059cdd273eSMauro Carvalho ChehabBus numbering is important, since that's how Linux identifies a given 5069cdd273eSMauro Carvalho ChehabSPI bus (shared SCK, MOSI, MISO). Valid bus numbers start at zero. On 5079cdd273eSMauro Carvalho ChehabSOC systems, the bus numbers should match the numbers defined by the chip 5089cdd273eSMauro Carvalho Chehabmanufacturer. For example, hardware controller SPI2 would be bus number 2, 5099cdd273eSMauro Carvalho Chehaband spi_board_info for devices connected to it would use that number. 5109cdd273eSMauro Carvalho Chehab 5119cdd273eSMauro Carvalho ChehabIf you don't have such hardware-assigned bus number, and for some reason 5129cdd273eSMauro Carvalho Chehabyou can't just assign them, then provide a negative bus number. That will 5139cdd273eSMauro Carvalho Chehabthen be replaced by a dynamically assigned number. You'd then need to treat 5149cdd273eSMauro Carvalho Chehabthis as a non-static configuration (see above). 5159cdd273eSMauro Carvalho Chehab 5169cdd273eSMauro Carvalho Chehab 51776b31eb4SUwe Kleine-KönigSPI Host Controller Methods 51876b31eb4SUwe Kleine-König^^^^^^^^^^^^^^^^^^^^^^^^^^^ 5199cdd273eSMauro Carvalho Chehab 52076b31eb4SUwe Kleine-König``ctlr->setup(struct spi_device *spi)`` 5219cdd273eSMauro Carvalho Chehab This sets up the device clock rate, SPI mode, and word sizes. 5229cdd273eSMauro Carvalho Chehab Drivers may change the defaults provided by board_info, and then 5239cdd273eSMauro Carvalho Chehab call spi_setup(spi) to invoke this routine. It may sleep. 5249cdd273eSMauro Carvalho Chehab 52599769a52SDhruva Gole Unless each SPI target has its own configuration registers, don't 5269cdd273eSMauro Carvalho Chehab change them right away ... otherwise drivers could corrupt I/O 5279cdd273eSMauro Carvalho Chehab that's in progress for other SPI devices. 5289cdd273eSMauro Carvalho Chehab 5299cdd273eSMauro Carvalho Chehab .. note:: 5309cdd273eSMauro Carvalho Chehab 5319cdd273eSMauro Carvalho Chehab BUG ALERT: for some reason the first version of 53276b31eb4SUwe Kleine-König many spi_controller drivers seems to get this wrong. 5339cdd273eSMauro Carvalho Chehab When you code setup(), ASSUME that the controller 5349cdd273eSMauro Carvalho Chehab is actively processing transfers for another device. 5359cdd273eSMauro Carvalho Chehab 53676b31eb4SUwe Kleine-König``ctlr->cleanup(struct spi_device *spi)`` 5379cdd273eSMauro Carvalho Chehab Your controller driver may use spi_device.controller_state to hold 5389cdd273eSMauro Carvalho Chehab state it dynamically associates with that device. If you do that, 5399cdd273eSMauro Carvalho Chehab be sure to provide the cleanup() method to free that state. 5409cdd273eSMauro Carvalho Chehab 54176b31eb4SUwe Kleine-König``ctlr->prepare_transfer_hardware(struct spi_controller *ctlr)`` 5429cdd273eSMauro Carvalho Chehab This will be called by the queue mechanism to signal to the driver 5439cdd273eSMauro Carvalho Chehab that a message is coming in soon, so the subsystem requests the 5449cdd273eSMauro Carvalho Chehab driver to prepare the transfer hardware by issuing this call. 5459cdd273eSMauro Carvalho Chehab This may sleep. 5469cdd273eSMauro Carvalho Chehab 54776b31eb4SUwe Kleine-König``ctlr->unprepare_transfer_hardware(struct spi_controller *ctlr)`` 5489cdd273eSMauro Carvalho Chehab This will be called by the queue mechanism to signal to the driver 5499cdd273eSMauro Carvalho Chehab that there are no more messages pending in the queue and it may 5509cdd273eSMauro Carvalho Chehab relax the hardware (e.g. by power management calls). This may sleep. 5519cdd273eSMauro Carvalho Chehab 55276b31eb4SUwe Kleine-König``ctlr->transfer_one_message(struct spi_controller *ctlr, struct spi_message *mesg)`` 5539cdd273eSMauro Carvalho Chehab The subsystem calls the driver to transfer a single message while 5549cdd273eSMauro Carvalho Chehab queuing transfers that arrive in the meantime. When the driver is 5559cdd273eSMauro Carvalho Chehab finished with this message, it must call 5569cdd273eSMauro Carvalho Chehab spi_finalize_current_message() so the subsystem can issue the next 5579cdd273eSMauro Carvalho Chehab message. This may sleep. 5589cdd273eSMauro Carvalho Chehab 55976b31eb4SUwe Kleine-König``ctrl->transfer_one(struct spi_controller *ctlr, struct spi_device *spi, struct spi_transfer *transfer)`` 5609cdd273eSMauro Carvalho Chehab The subsystem calls the driver to transfer a single transfer while 5619cdd273eSMauro Carvalho Chehab queuing transfers that arrive in the meantime. When the driver is 5629cdd273eSMauro Carvalho Chehab finished with this transfer, it must call 5639cdd273eSMauro Carvalho Chehab spi_finalize_current_transfer() so the subsystem can issue the next 5649cdd273eSMauro Carvalho Chehab transfer. This may sleep. Note: transfer_one and transfer_one_message 5659cdd273eSMauro Carvalho Chehab are mutually exclusive; when both are set, the generic subsystem does 5669cdd273eSMauro Carvalho Chehab not call your transfer_one callback. 5679cdd273eSMauro Carvalho Chehab 5689cdd273eSMauro Carvalho Chehab Return values: 5699cdd273eSMauro Carvalho Chehab 5709cdd273eSMauro Carvalho Chehab * negative errno: error 5719cdd273eSMauro Carvalho Chehab * 0: transfer is finished 5729cdd273eSMauro Carvalho Chehab * 1: transfer is still in progress 5739cdd273eSMauro Carvalho Chehab 57476b31eb4SUwe Kleine-König``ctrl->set_cs_timing(struct spi_device *spi, u8 setup_clk_cycles, u8 hold_clk_cycles, u8 inactive_clk_cycles)`` 57576b31eb4SUwe Kleine-König This method allows SPI client drivers to request SPI host controller 5769cdd273eSMauro Carvalho Chehab for configuring device specific CS setup, hold and inactive timing 5779cdd273eSMauro Carvalho Chehab requirements. 5789cdd273eSMauro Carvalho Chehab 5799cdd273eSMauro Carvalho ChehabDeprecated Methods 5809cdd273eSMauro Carvalho Chehab^^^^^^^^^^^^^^^^^^ 5819cdd273eSMauro Carvalho Chehab 58276b31eb4SUwe Kleine-König``ctrl->transfer(struct spi_device *spi, struct spi_message *message)`` 5839cdd273eSMauro Carvalho Chehab This must not sleep. Its responsibility is to arrange that the 5849cdd273eSMauro Carvalho Chehab transfer happens and its complete() callback is issued. The two 5859cdd273eSMauro Carvalho Chehab will normally happen later, after other transfers complete, and 5869cdd273eSMauro Carvalho Chehab if the controller is idle it will need to be kickstarted. This 5879cdd273eSMauro Carvalho Chehab method is not used on queued controllers and must be NULL if 5889cdd273eSMauro Carvalho Chehab transfer_one_message() and (un)prepare_transfer_hardware() are 5899cdd273eSMauro Carvalho Chehab implemented. 5909cdd273eSMauro Carvalho Chehab 5919cdd273eSMauro Carvalho Chehab 5929cdd273eSMauro Carvalho ChehabSPI Message Queue 5939cdd273eSMauro Carvalho Chehab^^^^^^^^^^^^^^^^^ 5949cdd273eSMauro Carvalho Chehab 5959cdd273eSMauro Carvalho ChehabIf you are happy with the standard queueing mechanism provided by the 5969cdd273eSMauro Carvalho ChehabSPI subsystem, just implement the queued methods specified above. Using 5979cdd273eSMauro Carvalho Chehabthe message queue has the upside of centralizing a lot of code and 5989cdd273eSMauro Carvalho Chehabproviding pure process-context execution of methods. The message queue 5999cdd273eSMauro Carvalho Chehabcan also be elevated to realtime priority on high-priority SPI traffic. 6009cdd273eSMauro Carvalho Chehab 6019cdd273eSMauro Carvalho ChehabUnless the queueing mechanism in the SPI subsystem is selected, the bulk 6029cdd273eSMauro Carvalho Chehabof the driver will be managing the I/O queue fed by the now deprecated 6039cdd273eSMauro Carvalho Chehabfunction transfer(). 6049cdd273eSMauro Carvalho Chehab 6059cdd273eSMauro Carvalho ChehabThat queue could be purely conceptual. For example, a driver used only 6069cdd273eSMauro Carvalho Chehabfor low-frequency sensor access might be fine using synchronous PIO. 6079cdd273eSMauro Carvalho Chehab 6089cdd273eSMauro Carvalho ChehabBut the queue will probably be very real, using message->queue, PIO, 6099cdd273eSMauro Carvalho Chehaboften DMA (especially if the root filesystem is in SPI flash), and 6109cdd273eSMauro Carvalho Chehabexecution contexts like IRQ handlers, tasklets, or workqueues (such 6119cdd273eSMauro Carvalho Chehabas keventd). Your driver can be as fancy, or as simple, as you need. 6129cdd273eSMauro Carvalho ChehabSuch a transfer() method would normally just add the message to a 6139cdd273eSMauro Carvalho Chehabqueue, and then start some asynchronous transfer engine (unless it's 6149cdd273eSMauro Carvalho Chehabalready running). 6159cdd273eSMauro Carvalho Chehab 6169cdd273eSMauro Carvalho Chehab 6179cdd273eSMauro Carvalho ChehabTHANKS TO 6189cdd273eSMauro Carvalho Chehab--------- 6199cdd273eSMauro Carvalho ChehabContributors to Linux-SPI discussions include (in alphabetical order, 6209cdd273eSMauro Carvalho Chehabby last name): 6219cdd273eSMauro Carvalho Chehab 6229cdd273eSMauro Carvalho Chehab- Mark Brown 6239cdd273eSMauro Carvalho Chehab- David Brownell 6249cdd273eSMauro Carvalho Chehab- Russell King 6259cdd273eSMauro Carvalho Chehab- Grant Likely 6269cdd273eSMauro Carvalho Chehab- Dmitry Pervushin 6279cdd273eSMauro Carvalho Chehab- Stephen Street 6289cdd273eSMauro Carvalho Chehab- Mark Underwood 6299cdd273eSMauro Carvalho Chehab- Andrew Victor 6309cdd273eSMauro Carvalho Chehab- Linus Walleij 6319cdd273eSMauro Carvalho Chehab- Vitaly Wool 632