Andrea Paterniani | 814a8d5 | 2007-05-08 00:32:15 -0700 | [diff] [blame] | 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 | |
Randy Dunlap | 31a16294 | 2008-04-28 02:14:18 -0700 | [diff] [blame] | 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 |
Andrea Paterniani | 814a8d5 | 2007-05-08 00:32:15 -0700 | [diff] [blame] | 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. |