About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / spi / spidev




Custom Search

Based on kernel version 3.13. Page generated on 2014-01-20 22:04 EST.

1	SPI devices have a limited userspace API, supporting basic half-duplex
2	read() and write() access to SPI slave devices.  Using ioctl() requests,
3	full duplex transfers and device I/O configuration are also available.
4	
5		#include <fcntl.h>
6		#include <unistd.h>
7		#include <sys/ioctl.h>
8		#include <linux/types.h>
9		#include <linux/spi/spidev.h>
10	
11	Some reasons you might want to use this programming interface include:
12	
13	 * Prototyping in an environment that's not crash-prone; stray pointers
14	   in userspace won't normally bring down any Linux system.
15	
16	 * Developing simple protocols used to talk to microcontrollers acting
17	   as SPI slaves, which you may need to change quite often.
18	
19	Of course there are drivers that can never be written in userspace, because
20	they need to access kernel interfaces (such as IRQ handlers or other layers
21	of the driver stack) that are not accessible to userspace.
22	
23	
24	DEVICE CREATION, DRIVER BINDING
25	===============================
26	The simplest way to arrange to use this driver is to just list it in the
27	spi_board_info for a device as the driver it should use:  the "modalias"
28	entry is "spidev", matching the name of the driver exposing this API.
29	Set up the other device characteristics (bits per word, SPI clocking,
30	chipselect polarity, etc) as usual, so you won't always need to override
31	them later.
32	
33	(Sysfs also supports userspace driven binding/unbinding of drivers to
34	devices.  That mechanism might be supported here in the future.)
35	
36	When you do that, the sysfs node for the SPI device will include a child
37	device node with a "dev" attribute that will be understood by udev or mdev.
38	(Larger systems will have "udev".  Smaller ones may configure "mdev" into
39	busybox; it's less featureful, but often enough.)  For a SPI device with
40	chipselect C on bus B, you should see:
41	
42	    /dev/spidevB.C ... character special device, major number 153 with
43		a dynamically chosen minor device number.  This is the node
44		that userspace programs will open, created by "udev" or "mdev".
45	
46	    /sys/devices/.../spiB.C ... as usual, the SPI device node will
47		be a child of its SPI master controller.
48	
49	    /sys/class/spidev/spidevB.C ... created when the "spidev" driver
50		binds to that device.  (Directory or symlink, based on whether
51		or not you enabled the "deprecated sysfs files" Kconfig option.)
52	
53	Do not try to manage the /dev character device special file nodes by hand.
54	That's error prone, and you'd need to pay careful attention to system
55	security issues; udev/mdev should already be configured securely.
56	
57	If you unbind the "spidev" driver from that device, those two "spidev" nodes
58	(in sysfs and in /dev) should automatically be removed (respectively by the
59	kernel and by udev/mdev).  You can unbind by removing the "spidev" driver
60	module, which will affect all devices using this driver.  You can also unbind
61	by having kernel code remove the SPI device, probably by removing the driver
62	for its SPI controller (so its spi_master vanishes).
63	
64	Since this is a standard Linux device driver -- even though it just happens
65	to expose a low level API to userspace -- it can be associated with any number
66	of devices at a time.  Just provide one spi_board_info record for each such
67	SPI device, and you'll get a /dev device node for each device.
68	
69	
70	BASIC CHARACTER DEVICE API
71	==========================
72	Normal open() and close() operations on /dev/spidevB.D files work as you
73	would expect.
74	
75	Standard read() and write() operations are obviously only half-duplex, and
76	the chipselect is deactivated between those operations.  Full-duplex access,
77	and composite operation without chipselect de-activation, is available using
78	the SPI_IOC_MESSAGE(N) request.
79	
80	Several ioctl() requests let your driver read or override the device's current
81	settings for data transfer parameters:
82	
83	    SPI_IOC_RD_MODE, SPI_IOC_WR_MODE ... pass a pointer to a byte which will
84		return (RD) or assign (WR) the SPI transfer mode.  Use the constants
85		SPI_MODE_0..SPI_MODE_3; or if you prefer you can combine SPI_CPOL
86		(clock polarity, idle high iff this is set) or SPI_CPHA (clock phase,
87		sample on trailing edge iff this is set) flags.
88	
89	    SPI_IOC_RD_LSB_FIRST, SPI_IOC_WR_LSB_FIRST ... pass a pointer to a byte
90		which will return (RD) or assign (WR) the bit justification used to
91		transfer SPI words.  Zero indicates MSB-first; other values indicate
92		the less common LSB-first encoding.  In both cases the specified value
93		is right-justified in each word, so that unused (TX) or undefined (RX)
94		bits are in the MSBs.
95	
96	    SPI_IOC_RD_BITS_PER_WORD, SPI_IOC_WR_BITS_PER_WORD ... pass a pointer to
97		a byte which will return (RD) or assign (WR) the number of bits in
98		each SPI transfer word.  The value zero signifies eight bits.
99	
100	    SPI_IOC_RD_MAX_SPEED_HZ, SPI_IOC_WR_MAX_SPEED_HZ ... pass a pointer to a
101		u32 which will return (RD) or assign (WR) the maximum SPI transfer
102		speed, in Hz.  The controller can't necessarily assign that specific
103		clock speed.
104	
105	NOTES:
106	
107	    - At this time there is no async I/O support; everything is purely
108	      synchronous.
109	
110	    - There's currently no way to report the actual bit rate used to
111	      shift data to/from a given device.
112	
113	    - From userspace, you can't currently change the chip select polarity;
114	      that could corrupt transfers to other devices sharing the SPI bus.
115	      Each SPI device is deselected when it's not in active use, allowing
116	      other drivers to talk to other devices.
117	
118	    - There's a limit on the number of bytes each I/O request can transfer
119	      to the SPI device.  It defaults to one page, but that can be changed
120	      using a module parameter.
121	
122	    - Because SPI has no low-level transfer acknowledgement, you usually
123	      won't see any I/O errors when talking to a non-existent device.
124	
125	
126	FULL DUPLEX CHARACTER DEVICE API
127	================================
128	
129	See the spidev_fdx.c sample program for one example showing the use of the
130	full duplex programming interface.  (Although it doesn't perform a full duplex
131	transfer.)  The model is the same as that used in the kernel spi_sync()
132	request; the individual transfers offer the same capabilities as are
133	available to kernel drivers (except that it's not asynchronous).
134	
135	The example shows one half-duplex RPC-style request and response message.
136	These requests commonly require that the chip not be deselected between
137	the request and response.  Several such requests could be chained into
138	a single kernel request, even allowing the chip to be deselected after
139	each response.  (Other protocol options include changing the word size
140	and bitrate for each transfer segment.)
141	
142	To make a full duplex request, provide both rx_buf and tx_buf for the
143	same transfer.  It's even OK if those are the same buffer.
Hide Line Numbers
About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.