Commit | Line | Data |
---|---|---|
9cdd273e MCC |
1 | ================= |
2 | SPI userspace API | |
3 | ================= | |
4 | ||
814a8d50 AP |
5 | SPI devices have a limited userspace API, supporting basic half-duplex |
6 | read() and write() access to SPI slave devices. Using ioctl() requests, | |
7 | full duplex transfers and device I/O configuration are also available. | |
8 | ||
9cdd273e MCC |
9 | :: |
10 | ||
814a8d50 AP |
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 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 | ||
25 | Of course there are drivers that can never be written in userspace, because | |
26 | they need to access kernel interfaces (such as IRQ handlers or other layers | |
27 | of the driver stack) that are not accessible to userspace. | |
28 | ||
29 | ||
30 | DEVICE CREATION, DRIVER BINDING | |
31 | =============================== | |
f6f6a632 JMC |
32 | |
33 | The spidev driver contains lists of SPI devices that are supported for | |
34 | the different hardware topology representations. | |
35 | ||
36 | The following are the SPI device tables supported by the spidev driver: | |
37 | ||
38 | - struct spi_device_id spidev_spi_ids[]: list of devices that can be | |
39 | bound when these are defined using a struct spi_board_info with a | |
40 | .modalias field matching one of the entries in the table. | |
41 | ||
42 | - struct of_device_id spidev_dt_ids[]: list of devices that can be | |
43 | bound when these are defined using a Device Tree node that has a | |
44 | compatible string matching one of the entries in the table. | |
45 | ||
46 | - struct acpi_device_id spidev_acpi_ids[]: list of devices that can | |
47 | be bound when these are defined using a ACPI device object with a | |
48 | _HID matching one of the entries in the table. | |
49 | ||
50 | You are encouraged to add an entry for your SPI device name to relevant | |
51 | tables, if these don't already have an entry for the device. To do that, | |
52 | post a patch for spidev to the linux-spi@vger.kernel.org mailing list. | |
53 | ||
54 | It used to be supported to define an SPI device using the "spidev" name. | |
55 | For example, as .modalias = "spidev" or compatible = "spidev". But this | |
56 | is no longer supported by the Linux kernel and instead a real SPI device | |
57 | name as listed in one of the tables must be used. | |
58 | ||
59 | Not having a real SPI device name will lead to an error being printed and | |
60 | the spidev driver failing to probe. | |
61 | ||
62 | Sysfs also supports userspace driven binding/unbinding of drivers to | |
63 | devices that do not bind automatically using one of the tables above. | |
64 | To make the spidev driver bind to such a device, use the following: | |
65 | ||
66 | echo spidev > /sys/bus/spi/devices/spiB.C/driver_override | |
67 | echo spiB.C > /sys/bus/spi/drivers/spidev/bind | |
68 | ||
69 | When the spidev driver is bound to a SPI device, the sysfs node for the | |
70 | device will include a child device node with a "dev" attribute that will | |
71 | be understood by udev or mdev (udev replacement from BusyBox; it's less | |
72 | featureful, but often enough). | |
73 | ||
74 | For a SPI device with chipselect C on bus B, you should see: | |
814a8d50 | 75 | |
9cdd273e MCC |
76 | /dev/spidevB.C ... |
77 | character special device, major number 153 with | |
814a8d50 AP |
78 | a dynamically chosen minor device number. This is the node |
79 | that userspace programs will open, created by "udev" or "mdev". | |
80 | ||
9cdd273e MCC |
81 | /sys/devices/.../spiB.C ... |
82 | as usual, the SPI device node will | |
814a8d50 AP |
83 | be a child of its SPI master controller. |
84 | ||
9cdd273e MCC |
85 | /sys/class/spidev/spidevB.C ... |
86 | created when the "spidev" driver | |
814a8d50 AP |
87 | binds to that device. (Directory or symlink, based on whether |
88 | or not you enabled the "deprecated sysfs files" Kconfig option.) | |
89 | ||
90 | 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 careful attention to system | |
92 | security issues; udev/mdev should already be configured securely. | |
93 | ||
94 | If you unbind the "spidev" driver from that device, those two "spidev" nodes | |
95 | (in sysfs and in /dev) should automatically be removed (respectively by the | |
96 | kernel and by udev/mdev). You can unbind by removing the "spidev" driver | |
97 | module, which will affect all devices using this driver. You can also unbind | |
98 | by having kernel code remove the SPI device, probably by removing the driver | |
99 | for its SPI controller (so its spi_master vanishes). | |
100 | ||
101 | Since this is a standard Linux device driver -- even though it just happens | |
102 | 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_board_info record for each such | |
104 | SPI device, and you'll get a /dev device node for each device. | |
105 | ||
106 | ||
107 | BASIC CHARACTER DEVICE API | |
108 | ========================== | |
109 | Normal open() and close() operations on /dev/spidevB.D files work as you | |
110 | would expect. | |
111 | ||
112 | Standard read() and write() operations are obviously only half-duplex, and | |
113 | the chipselect is deactivated between those operations. Full-duplex access, | |
114 | and composite operation without chipselect de-activation, is available using | |
115 | the SPI_IOC_MESSAGE(N) request. | |
116 | ||
117 | Several ioctl() requests let your driver read or override the device's current | |
118 | settings for data transfer parameters: | |
119 | ||
9cdd273e MCC |
120 | SPI_IOC_RD_MODE, SPI_IOC_WR_MODE ... |
121 | pass a pointer to a byte which will | |
814a8d50 AP |
122 | return (RD) or assign (WR) the SPI transfer mode. Use the constants |
123 | SPI_MODE_0..SPI_MODE_3; or if you prefer you can combine SPI_CPOL | |
124 | (clock polarity, idle high iff this is set) or SPI_CPHA (clock phase, | |
125 | sample on trailing edge iff this is set) flags. | |
dc64d39b GU |
126 | Note that this request is limited to SPI mode flags that fit in a |
127 | single byte. | |
128 | ||
9cdd273e MCC |
129 | SPI_IOC_RD_MODE32, SPI_IOC_WR_MODE32 ... |
130 | pass a pointer to a uin32_t | |
dc64d39b GU |
131 | which will return (RD) or assign (WR) the full SPI transfer mode, |
132 | not limited to the bits that fit in one byte. | |
814a8d50 | 133 | |
9cdd273e MCC |
134 | SPI_IOC_RD_LSB_FIRST, SPI_IOC_WR_LSB_FIRST ... |
135 | pass a pointer to a byte | |
814a8d50 AP |
136 | which will return (RD) or assign (WR) the bit justification used to |
137 | transfer SPI words. Zero indicates MSB-first; other values indicate | |
138 | the less common LSB-first encoding. In both cases the specified value | |
139 | is right-justified in each word, so that unused (TX) or undefined (RX) | |
140 | bits are in the MSBs. | |
141 | ||
9cdd273e MCC |
142 | SPI_IOC_RD_BITS_PER_WORD, SPI_IOC_WR_BITS_PER_WORD ... |
143 | pass a pointer to | |
814a8d50 AP |
144 | a byte which will return (RD) or assign (WR) the number of bits in |
145 | each SPI transfer word. The value zero signifies eight bits. | |
146 | ||
9cdd273e MCC |
147 | SPI_IOC_RD_MAX_SPEED_HZ, SPI_IOC_WR_MAX_SPEED_HZ ... |
148 | pass a pointer to a | |
814a8d50 AP |
149 | u32 which will return (RD) or assign (WR) the maximum SPI transfer |
150 | speed, in Hz. The controller can't necessarily assign that specific | |
151 | clock speed. | |
152 | ||
153 | NOTES: | |
154 | ||
155 | - At this time there is no async I/O support; everything is purely | |
156 | synchronous. | |
157 | ||
158 | - There's currently no way to report the actual bit rate used to | |
159 | shift data to/from a given device. | |
160 | ||
161 | - From userspace, you can't currently change the chip select polarity; | |
162 | that could corrupt transfers to other devices sharing the SPI bus. | |
163 | Each SPI device is deselected when it's not in active use, allowing | |
164 | other drivers to talk to other devices. | |
165 | ||
166 | - There's a limit on the number of bytes each I/O request can transfer | |
167 | to the SPI device. It defaults to one page, but that can be changed | |
168 | using a module parameter. | |
169 | ||
170 | - Because SPI has no low-level transfer acknowledgement, you usually | |
171 | won't see any I/O errors when talking to a non-existent device. | |
172 | ||
173 | ||
174 | FULL DUPLEX CHARACTER DEVICE API | |
175 | ================================ | |
176 | ||
31a16294 RD |
177 | See the spidev_fdx.c sample program for one example showing the use of the |
178 | full duplex programming interface. (Although it doesn't perform a full duplex | |
814a8d50 AP |
179 | transfer.) The model is the same as that used in the kernel spi_sync() |
180 | request; the individual transfers offer the same capabilities as are | |
181 | available to kernel drivers (except that it's not asynchronous). | |
182 | ||
183 | The example shows one half-duplex RPC-style request and response message. | |
184 | These requests commonly require that the chip not be deselected between | |
185 | the request and response. Several such requests could be chained into | |
186 | a single kernel request, even allowing the chip to be deselected after | |
187 | each response. (Other protocol options include changing the word size | |
188 | and bitrate for each transfer segment.) | |
189 | ||
190 | 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 same buffer. |