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