1================= 2SPI userspace API 3================= 4 5SPI devices have a limited userspace API, supporting basic half-duplex 6read() and write() access to SPI slave devices. Using ioctl() requests, 7full duplex transfers and device I/O configuration are also available. 8 9:: 10 11 #include <fcntl.h> 12 #include <unistd.h> 13 #include <sys/ioctl.h> 14 #include <linux/types.h> 15 #include <linux/spi/spidev.h> 16 17Some reasons you might want to use this programming interface include: 18 19 * Prototyping in an environment that's not crash-prone; stray pointers 20 in userspace won't normally bring down any Linux system. 21 22 * Developing simple protocols used to talk to microcontrollers acting 23 as SPI slaves, which you may need to change quite often. 24 25Of course there are drivers that can never be written in userspace, because 26they need to access kernel interfaces (such as IRQ handlers or other layers 27of the driver stack) that are not accessible to userspace. 28 29 30DEVICE CREATION, DRIVER BINDING 31=============================== 32The simplest way to arrange to use this driver is to just list it in the 33spi_board_info for a device as the driver it should use: the "modalias" 34entry is "spidev", matching the name of the driver exposing this API. 35Set up the other device characteristics (bits per word, SPI clocking, 36chipselect polarity, etc) as usual, so you won't always need to override 37them later. 38 39(Sysfs also supports userspace driven binding/unbinding of drivers to 40devices. That mechanism might be supported here in the future.) 41 42When you do that, the sysfs node for the SPI device will include a child 43device node with a "dev" attribute that will be understood by udev or mdev. 44(Larger systems will have "udev". Smaller ones may configure "mdev" into 45busybox; it's less featureful, but often enough.) For a SPI device with 46chipselect C on bus B, you should see: 47 48 /dev/spidevB.C ... 49 character special device, major number 153 with 50 a dynamically chosen minor device number. This is the node 51 that userspace programs will open, created by "udev" or "mdev". 52 53 /sys/devices/.../spiB.C ... 54 as usual, the SPI device node will 55 be a child of its SPI master controller. 56 57 /sys/class/spidev/spidevB.C ... 58 created when the "spidev" driver 59 binds to that device. (Directory or symlink, based on whether 60 or not you enabled the "deprecated sysfs files" Kconfig option.) 61 62Do not try to manage the /dev character device special file nodes by hand. 63That's error prone, and you'd need to pay careful attention to system 64security issues; udev/mdev should already be configured securely. 65 66If you unbind the "spidev" driver from that device, those two "spidev" nodes 67(in sysfs and in /dev) should automatically be removed (respectively by the 68kernel and by udev/mdev). You can unbind by removing the "spidev" driver 69module, which will affect all devices using this driver. You can also unbind 70by having kernel code remove the SPI device, probably by removing the driver 71for its SPI controller (so its spi_master vanishes). 72 73Since this is a standard Linux device driver -- even though it just happens 74to expose a low level API to userspace -- it can be associated with any number 75of devices at a time. Just provide one spi_board_info record for each such 76SPI device, and you'll get a /dev device node for each device. 77 78 79BASIC CHARACTER DEVICE API 80========================== 81Normal open() and close() operations on /dev/spidevB.D files work as you 82would expect. 83 84Standard read() and write() operations are obviously only half-duplex, and 85the chipselect is deactivated between those operations. Full-duplex access, 86and composite operation without chipselect de-activation, is available using 87the SPI_IOC_MESSAGE(N) request. 88 89Several ioctl() requests let your driver read or override the device's current 90settings for data transfer parameters: 91 92 SPI_IOC_RD_MODE, SPI_IOC_WR_MODE ... 93 pass a pointer to a byte which will 94 return (RD) or assign (WR) the SPI transfer mode. Use the constants 95 SPI_MODE_0..SPI_MODE_3; or if you prefer you can combine SPI_CPOL 96 (clock polarity, idle high iff this is set) or SPI_CPHA (clock phase, 97 sample on trailing edge iff this is set) flags. 98 Note that this request is limited to SPI mode flags that fit in a 99 single byte. 100 101 SPI_IOC_RD_MODE32, SPI_IOC_WR_MODE32 ... 102 pass a pointer to a uin32_t 103 which will return (RD) or assign (WR) the full SPI transfer mode, 104 not limited to the bits that fit in one byte. 105 106 SPI_IOC_RD_LSB_FIRST, SPI_IOC_WR_LSB_FIRST ... 107 pass a pointer to a byte 108 which will return (RD) or assign (WR) the bit justification used to 109 transfer SPI words. Zero indicates MSB-first; other values indicate 110 the less common LSB-first encoding. In both cases the specified value 111 is right-justified in each word, so that unused (TX) or undefined (RX) 112 bits are in the MSBs. 113 114 SPI_IOC_RD_BITS_PER_WORD, SPI_IOC_WR_BITS_PER_WORD ... 115 pass a pointer to 116 a byte which will return (RD) or assign (WR) the number of bits in 117 each SPI transfer word. The value zero signifies eight bits. 118 119 SPI_IOC_RD_MAX_SPEED_HZ, SPI_IOC_WR_MAX_SPEED_HZ ... 120 pass a pointer to a 121 u32 which will return (RD) or assign (WR) the maximum SPI transfer 122 speed, in Hz. The controller can't necessarily assign that specific 123 clock speed. 124 125NOTES: 126 127 - At this time there is no async I/O support; everything is purely 128 synchronous. 129 130 - There's currently no way to report the actual bit rate used to 131 shift data to/from a given device. 132 133 - From userspace, you can't currently change the chip select polarity; 134 that could corrupt transfers to other devices sharing the SPI bus. 135 Each SPI device is deselected when it's not in active use, allowing 136 other drivers to talk to other devices. 137 138 - There's a limit on the number of bytes each I/O request can transfer 139 to the SPI device. It defaults to one page, but that can be changed 140 using a module parameter. 141 142 - Because SPI has no low-level transfer acknowledgement, you usually 143 won't see any I/O errors when talking to a non-existent device. 144 145 146FULL DUPLEX CHARACTER DEVICE API 147================================ 148 149See the spidev_fdx.c sample program for one example showing the use of the 150full duplex programming interface. (Although it doesn't perform a full duplex 151transfer.) The model is the same as that used in the kernel spi_sync() 152request; the individual transfers offer the same capabilities as are 153available to kernel drivers (except that it's not asynchronous). 154 155The example shows one half-duplex RPC-style request and response message. 156These requests commonly require that the chip not be deselected between 157the request and response. Several such requests could be chained into 158a single kernel request, even allowing the chip to be deselected after 159each response. (Other protocol options include changing the word size 160and bitrate for each transfer segment.) 161 162To make a full duplex request, provide both rx_buf and tx_buf for the 163same transfer. It's even OK if those are the same buffer. 164