1 =================
2 SPI userspace API
3 =================
4
5 SPI devices have a limited userspace API, supp
6 read() and write() access to SPI slave devices
7 full duplex transfers and device I/O configura
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
17 Some reasons you might want to use this progra
18
19 * Prototyping in an environment that's not cr
20 in userspace won't normally bring down any
21
22 * Developing simple protocols used to talk to
23 as SPI slaves, which you may need to change
24
25 Of course there are drivers that can never be
26 they need to access kernel interfaces (such as
27 of the driver stack) that are not accessible t
28
29
30 DEVICE CREATION, DRIVER BINDING
31 ===============================
32
33 The spidev driver contains lists of SPI device
34 the different hardware topology representation
35
36 The following are the SPI device tables suppor
37
38 - struct spi_device_id spidev_spi_ids[]: l
39 bound when these are defined using a str
40 .modalias field matching one of the entr
41
42 - struct of_device_id spidev_dt_ids[]: lis
43 bound when these are defined using a Dev
44 compatible string matching one of the en
45
46 - struct acpi_device_id spidev_acpi_ids[]:
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
76 /dev/spidevB.C ...
77 character special device, major number
78 a dynamically chosen minor device numb
79 that userspace programs will open, cre
80
81 /sys/devices/.../spiB.C ...
82 as usual, the SPI device node will
83 be a child of its SPI master controlle
84
85 /sys/class/spidev/spidevB.C ...
86 created when the "spidev" driver
87 binds to that device. (Directory or s
88 or not you enabled the "deprecated sys
89
90 Do not try to manage the /dev character device
91 That's error prone, and you'd need to pay care
92 security issues; udev/mdev should already be c
93
94 If you unbind the "spidev" driver from that de
95 (in sysfs and in /dev) should automatically be
96 kernel and by udev/mdev). You can unbind by r
97 module, which will affect all devices using th
98 by having kernel code remove the SPI device, p
99 for its SPI controller (so its spi_master vani
100
101 Since this is a standard Linux device driver -
102 to expose a low level API to userspace -- it c
103 of devices at a time. Just provide one spi_bo
104 SPI device, and you'll get a /dev device node
105
106
107 BASIC CHARACTER DEVICE API
108 ==========================
109 Normal open() and close() operations on /dev/s
110 would expect.
111
112 Standard read() and write() operations are obv
113 the chipselect is deactivated between those op
114 and composite operation without chipselect de-
115 the SPI_IOC_MESSAGE(N) request.
116
117 Several ioctl() requests let your driver read
118 settings for data transfer parameters:
119
120 SPI_IOC_RD_MODE, SPI_IOC_WR_MODE ...
121 pass a pointer to a byte which will
122 return (RD) or assign (WR) the SPI tra
123 SPI_MODE_0..SPI_MODE_3; or if you pref
124 (clock polarity, idle high iff this is
125 sample on trailing edge iff this is se
126 Note that this request is limited to S
127 single byte.
128
129 SPI_IOC_RD_MODE32, SPI_IOC_WR_MODE32 ...
130 pass a pointer to a uin32_t
131 which will return (RD) or assign (WR)
132 not limited to the bits that fit in on
133
134 SPI_IOC_RD_LSB_FIRST, SPI_IOC_WR_LSB_FIRST
135 pass a pointer to a byte
136 which will return (RD) or assign (WR)
137 transfer SPI words. Zero indicates MS
138 the less common LSB-first encoding. I
139 is right-justified in each word, so th
140 bits are in the MSBs.
141
142 SPI_IOC_RD_BITS_PER_WORD, SPI_IOC_WR_BITS_
143 pass a pointer to
144 a byte which will return (RD) or assig
145 each SPI transfer word. The value zer
146
147 SPI_IOC_RD_MAX_SPEED_HZ, SPI_IOC_WR_MAX_SP
148 pass a pointer to a
149 u32 which will return (RD) or assign (
150 speed, in Hz. The controller can't ne
151 clock speed.
152
153 NOTES:
154
155 - At this time there is no async I/O suppo
156 synchronous.
157
158 - There's currently no way to report the a
159 shift data to/from a given device.
160
161 - From userspace, you can't currently chan
162 that could corrupt transfers to other de
163 Each SPI device is deselected when it's
164 other drivers to talk to other devices.
165
166 - There's a limit on the number of bytes e
167 to the SPI device. It defaults to one p
168 using a module parameter.
169
170 - Because SPI has no low-level transfer ac
171 won't see any I/O errors when talking to
172
173
174 FULL DUPLEX CHARACTER DEVICE API
175 ================================
176
177 See the spidev_fdx.c sample program for one ex
178 full duplex programming interface. (Although
179 transfer.) The model is the same as that used
180 request; the individual transfers offer the sa
181 available to kernel drivers (except that it's
182
183 The example shows one half-duplex RPC-style re
184 These requests commonly require that the chip
185 the request and response. Several such reques
186 a single kernel request, even allowing the chi
187 each response. (Other protocol options includ
188 and bitrate for each transfer segment.)
189
190 To make a full duplex request, provide both rx
191 same transfer. It's even OK if those are the
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.