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 | =============================== | |
32 | The simplest way to arrange to use this driver is to just list it in the | |
33 | spi_board_info for a device as the driver it should use: the "modalias" | |
34 | entry is "spidev", matching the name of the driver exposing this API. | |
35 | Set up the other device characteristics (bits per word, SPI clocking, | |
36 | chipselect polarity, etc) as usual, so you won't always need to override | |
37 | them later. | |
38 | ||
39 | (Sysfs also supports userspace driven binding/unbinding of drivers to | |
40 | devices. That mechanism might be supported here in the future.) | |
41 | ||
42 | When you do that, the sysfs node for the SPI device will include a child | |
43 | device 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 | |
45 | busybox; it's less featureful, but often enough.) For a SPI device with | |
46 | chipselect C on bus B, you should see: | |
47 | ||
9cdd273e MCC |
48 | /dev/spidevB.C ... |
49 | character special device, major number 153 with | |
814a8d50 AP |
50 | a dynamically chosen minor device number. This is the node |
51 | that userspace programs will open, created by "udev" or "mdev". | |
52 | ||
9cdd273e MCC |
53 | /sys/devices/.../spiB.C ... |
54 | as usual, the SPI device node will | |
814a8d50 AP |
55 | be a child of its SPI master controller. |
56 | ||
9cdd273e MCC |
57 | /sys/class/spidev/spidevB.C ... |
58 | created when the "spidev" driver | |
814a8d50 AP |
59 | binds to that device. (Directory or symlink, based on whether |
60 | or not you enabled the "deprecated sysfs files" Kconfig option.) | |
61 | ||
62 | Do not try to manage the /dev character device special file nodes by hand. | |
63 | That's error prone, and you'd need to pay careful attention to system | |
64 | security issues; udev/mdev should already be configured securely. | |
65 | ||
66 | If 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 | |
68 | kernel and by udev/mdev). You can unbind by removing the "spidev" driver | |
69 | module, which will affect all devices using this driver. You can also unbind | |
70 | by having kernel code remove the SPI device, probably by removing the driver | |
71 | for its SPI controller (so its spi_master vanishes). | |
72 | ||
73 | Since this is a standard Linux device driver -- even though it just happens | |
74 | to expose a low level API to userspace -- it can be associated with any number | |
75 | of devices at a time. Just provide one spi_board_info record for each such | |
76 | SPI device, and you'll get a /dev device node for each device. | |
77 | ||
78 | ||
79 | BASIC CHARACTER DEVICE API | |
80 | ========================== | |
81 | Normal open() and close() operations on /dev/spidevB.D files work as you | |
82 | would expect. | |
83 | ||
84 | Standard read() and write() operations are obviously only half-duplex, and | |
85 | the chipselect is deactivated between those operations. Full-duplex access, | |
86 | and composite operation without chipselect de-activation, is available using | |
87 | the SPI_IOC_MESSAGE(N) request. | |
88 | ||
89 | Several ioctl() requests let your driver read or override the device's current | |
90 | settings for data transfer parameters: | |
91 | ||
9cdd273e MCC |
92 | SPI_IOC_RD_MODE, SPI_IOC_WR_MODE ... |
93 | pass a pointer to a byte which will | |
814a8d50 AP |
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. | |
dc64d39b GU |
98 | Note that this request is limited to SPI mode flags that fit in a |
99 | single byte. | |
100 | ||
9cdd273e MCC |
101 | SPI_IOC_RD_MODE32, SPI_IOC_WR_MODE32 ... |
102 | pass a pointer to a uin32_t | |
dc64d39b GU |
103 | which will return (RD) or assign (WR) the full SPI transfer mode, |
104 | not limited to the bits that fit in one byte. | |
814a8d50 | 105 | |
9cdd273e MCC |
106 | SPI_IOC_RD_LSB_FIRST, SPI_IOC_WR_LSB_FIRST ... |
107 | pass a pointer to a byte | |
814a8d50 AP |
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 | ||
9cdd273e MCC |
114 | SPI_IOC_RD_BITS_PER_WORD, SPI_IOC_WR_BITS_PER_WORD ... |
115 | pass a pointer to | |
814a8d50 AP |
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 | ||
9cdd273e MCC |
119 | SPI_IOC_RD_MAX_SPEED_HZ, SPI_IOC_WR_MAX_SPEED_HZ ... |
120 | pass a pointer to a | |
814a8d50 AP |
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 | ||
125 | NOTES: | |
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 | ||
146 | FULL DUPLEX CHARACTER DEVICE API | |
147 | ================================ | |
148 | ||
31a16294 RD |
149 | See the spidev_fdx.c sample program for one example showing the use of the |
150 | full duplex programming interface. (Although it doesn't perform a full duplex | |
814a8d50 AP |
151 | transfer.) The model is the same as that used in the kernel spi_sync() |
152 | request; the individual transfers offer the same capabilities as are | |
153 | available to kernel drivers (except that it's not asynchronous). | |
154 | ||
155 | The example shows one half-duplex RPC-style request and response message. | |
156 | These requests commonly require that the chip not be deselected between | |
157 | the request and response. Several such requests could be chained into | |
158 | a single kernel request, even allowing the chip to be deselected after | |
159 | each response. (Other protocol options include changing the word size | |
160 | and bitrate for each transfer segment.) | |
161 | ||
162 | To make a full duplex request, provide both rx_buf and tx_buf for the | |
163 | same transfer. It's even OK if those are the same buffer. |