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