Loading...
1=================
2SPI userspace API
3=================
4
5SPI devices have a limited userspace API, supporting basic half-duplex
6read() and write() access to SPI slave devices. Using ioctl() requests,
7full duplex transfers and device I/O configuration are also available.
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
17Some 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
25Of course there are drivers that can never be written in userspace, because
26they need to access kernel interfaces (such as IRQ handlers or other layers
27of the driver stack) that are not accessible to userspace.
28
29
30DEVICE CREATION, DRIVER BINDING
31===============================
32
33The spidev driver contains lists of SPI devices that are supported for
34the different hardware topology representations.
35
36The 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
50You are encouraged to add an entry for your SPI device name to relevant
51tables, if these don't already have an entry for the device. To do that,
52post a patch for spidev to the linux-spi@vger.kernel.org mailing list.
53
54It used to be supported to define an SPI device using the "spidev" name.
55For example, as .modalias = "spidev" or compatible = "spidev". But this
56is no longer supported by the Linux kernel and instead a real SPI device
57name as listed in one of the tables must be used.
58
59Not having a real SPI device name will lead to an error being printed and
60the spidev driver failing to probe.
61
62Sysfs also supports userspace driven binding/unbinding of drivers to
63devices that do not bind automatically using one of the tables above.
64To 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
69When the spidev driver is bound to a SPI device, the sysfs node for the
70device will include a child device node with a "dev" attribute that will
71be understood by udev or mdev (udev replacement from BusyBox; it's less
72featureful, but often enough).
73
74For a SPI device with chipselect C on bus B, you should see:
75
76 /dev/spidevB.C ...
77 character special device, major number 153 with
78 a dynamically chosen minor device number. This is the node
79 that userspace programs will open, created by "udev" or "mdev".
80
81 /sys/devices/.../spiB.C ...
82 as usual, the SPI device node will
83 be a child of its SPI master controller.
84
85 /sys/class/spidev/spidevB.C ...
86 created when the "spidev" driver
87 binds to that device. (Directory or symlink, based on whether
88 or not you enabled the "deprecated sysfs files" Kconfig option.)
89
90Do not try to manage the /dev character device special file nodes by hand.
91That's error prone, and you'd need to pay careful attention to system
92security issues; udev/mdev should already be configured securely.
93
94If 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
96kernel and by udev/mdev). You can unbind by removing the "spidev" driver
97module, which will affect all devices using this driver. You can also unbind
98by having kernel code remove the SPI device, probably by removing the driver
99for its SPI controller (so its spi_master vanishes).
100
101Since this is a standard Linux device driver -- even though it just happens
102to expose a low level API to userspace -- it can be associated with any number
103of devices at a time. Just provide one spi_board_info record for each such
104SPI device, and you'll get a /dev device node for each device.
105
106
107BASIC CHARACTER DEVICE API
108==========================
109Normal open() and close() operations on /dev/spidevB.D files work as you
110would expect.
111
112Standard read() and write() operations are obviously only half-duplex, and
113the chipselect is deactivated between those operations. Full-duplex access,
114and composite operation without chipselect de-activation, is available using
115the SPI_IOC_MESSAGE(N) request.
116
117Several ioctl() requests let your driver read or override the device's current
118settings 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 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.
126 Note that this request is limited to SPI mode flags that fit in a
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) the full SPI transfer mode,
132 not limited to the bits that fit in one byte.
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) 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
142 SPI_IOC_RD_BITS_PER_WORD, SPI_IOC_WR_BITS_PER_WORD ...
143 pass a pointer to
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
147 SPI_IOC_RD_MAX_SPEED_HZ, SPI_IOC_WR_MAX_SPEED_HZ ...
148 pass a pointer to a
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
153NOTES:
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
174FULL DUPLEX CHARACTER DEVICE API
175================================
176
177See the spidev_fdx.c sample program for one example showing the use of the
178full duplex programming interface. (Although it doesn't perform a full duplex
179transfer.) The model is the same as that used in the kernel spi_sync()
180request; the individual transfers offer the same capabilities as are
181available to kernel drivers (except that it's not asynchronous).
182
183The example shows one half-duplex RPC-style request and response message.
184These requests commonly require that the chip not be deselected between
185the request and response. Several such requests could be chained into
186a single kernel request, even allowing the chip to be deselected after
187each response. (Other protocol options include changing the word size
188and bitrate for each transfer segment.)
189
190To make a full duplex request, provide both rx_buf and tx_buf for the
191same transfer. It's even OK if those are the same buffer.
1=================
2SPI userspace API
3=================
4
5SPI devices have a limited userspace API, supporting basic half-duplex
6read() and write() access to SPI slave devices. Using ioctl() requests,
7full duplex transfers and device I/O configuration are also available.
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
17Some 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
25Of course there are drivers that can never be written in userspace, because
26they need to access kernel interfaces (such as IRQ handlers or other layers
27of the driver stack) that are not accessible to userspace.
28
29
30DEVICE CREATION, DRIVER BINDING
31===============================
32The simplest way to arrange to use this driver is to just list it in the
33spi_board_info for a device as the driver it should use: the "modalias"
34entry is "spidev", matching the name of the driver exposing this API.
35Set up the other device characteristics (bits per word, SPI clocking,
36chipselect polarity, etc) as usual, so you won't always need to override
37them later.
38
39(Sysfs also supports userspace driven binding/unbinding of drivers to
40devices. That mechanism might be supported here in the future.)
41
42When you do that, the sysfs node for the SPI device will include a child
43device 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
45busybox; it's less featureful, but often enough.) For a SPI device with
46chipselect C on bus B, you should see:
47
48 /dev/spidevB.C ...
49 character special device, major number 153 with
50 a dynamically chosen minor device number. This is the node
51 that userspace programs will open, created by "udev" or "mdev".
52
53 /sys/devices/.../spiB.C ...
54 as usual, the SPI device node will
55 be a child of its SPI master controller.
56
57 /sys/class/spidev/spidevB.C ...
58 created when the "spidev" driver
59 binds to that device. (Directory or symlink, based on whether
60 or not you enabled the "deprecated sysfs files" Kconfig option.)
61
62Do not try to manage the /dev character device special file nodes by hand.
63That's error prone, and you'd need to pay careful attention to system
64security issues; udev/mdev should already be configured securely.
65
66If 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
68kernel and by udev/mdev). You can unbind by removing the "spidev" driver
69module, which will affect all devices using this driver. You can also unbind
70by having kernel code remove the SPI device, probably by removing the driver
71for its SPI controller (so its spi_master vanishes).
72
73Since this is a standard Linux device driver -- even though it just happens
74to expose a low level API to userspace -- it can be associated with any number
75of devices at a time. Just provide one spi_board_info record for each such
76SPI device, and you'll get a /dev device node for each device.
77
78
79BASIC CHARACTER DEVICE API
80==========================
81Normal open() and close() operations on /dev/spidevB.D files work as you
82would expect.
83
84Standard read() and write() operations are obviously only half-duplex, and
85the chipselect is deactivated between those operations. Full-duplex access,
86and composite operation without chipselect de-activation, is available using
87the SPI_IOC_MESSAGE(N) request.
88
89Several ioctl() requests let your driver read or override the device's current
90settings for data transfer parameters:
91
92 SPI_IOC_RD_MODE, SPI_IOC_WR_MODE ...
93 pass a pointer to a byte which will
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.
98 Note that this request is limited to SPI mode flags that fit in a
99 single byte.
100
101 SPI_IOC_RD_MODE32, SPI_IOC_WR_MODE32 ...
102 pass a pointer to a uin32_t
103 which will return (RD) or assign (WR) the full SPI transfer mode,
104 not limited to the bits that fit in one byte.
105
106 SPI_IOC_RD_LSB_FIRST, SPI_IOC_WR_LSB_FIRST ...
107 pass a pointer to a byte
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
114 SPI_IOC_RD_BITS_PER_WORD, SPI_IOC_WR_BITS_PER_WORD ...
115 pass a pointer to
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
119 SPI_IOC_RD_MAX_SPEED_HZ, SPI_IOC_WR_MAX_SPEED_HZ ...
120 pass a pointer to a
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
125NOTES:
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
146FULL DUPLEX CHARACTER DEVICE API
147================================
148
149See the spidev_fdx.c sample program for one example showing the use of the
150full duplex programming interface. (Although it doesn't perform a full duplex
151transfer.) The model is the same as that used in the kernel spi_sync()
152request; the individual transfers offer the same capabilities as are
153available to kernel drivers (except that it's not asynchronous).
154
155The example shows one half-duplex RPC-style request and response message.
156These requests commonly require that the chip not be deselected between
157the request and response. Several such requests could be chained into
158a single kernel request, even allowing the chip to be deselected after
159each response. (Other protocol options include changing the word size
160and bitrate for each transfer segment.)
161
162To make a full duplex request, provide both rx_buf and tx_buf for the
163same transfer. It's even OK if those are the same buffer.