Documentation/spi/spidev

   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 sample program below for one example showing the use of the full
 130 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.
 144
 145
 146 SAMPLE PROGRAM
 147 ==============
 148
 149 --------------------------------        CUT HERE
 150 #include <stdio.h>
 151 #include <unistd.h>
 152 #include <stdlib.h>
 153 #include <fcntl.h>
 154 #include <string.h>
 155
 156 #include <sys/ioctl.h>
 157 #include <sys/types.h>
 158 #include <sys/stat.h>
 159
 160 #include <linux/types.h>
 161 #include <linux/spi/spidev.h>
 162
 163
 164 static int verbose;
 165
 166 static void do_read(int fd, int len)
 167 {
 168         unsigned char   buf[32], *bp;
 169         int             status;
 170
 171         /* read at least 2 bytes, no more than 32 */
 172         if (len < 2)
 173                 len = 2;
 174         else if (len > sizeof(buf))
 175                 len = sizeof(buf);
 176         memset(buf, 0, sizeof buf);
 177
 178         status = read(fd, buf, len);
 179         if (status < 0) {
 180                 perror("read");
 181                 return;
 182         }
 183         if (status != len) {
 184                 fprintf(stderr, "short read\n");
 185                 return;
 186         }
 187
 188         printf("read(%2d, %2d): %02x %02x,", len, status,
 189                 buf[0], buf[1]);
 190         status -= 2;
 191         bp = buf + 2;
 192         while (status-- > 0)
 193                 printf(" %02x", *bp++);
 194         printf("\n");
 195 }
 196
 197 static void do_msg(int fd, int len)
 198 {
 199         struct spi_ioc_transfer xfer[2];
 200         unsigned char           buf[32], *bp;
 201         int                     status;
 202
 203         memset(xfer, 0, sizeof xfer);
 204         memset(buf, 0, sizeof buf);
 205
 206         if (len > sizeof buf)
 207                 len = sizeof buf;
 208
 209         buf[0] = 0xaa;
 210         xfer[0].tx_buf = (__u64) buf;
 211         xfer[0].len = 1;
 212
 213         xfer[1].rx_buf = (__u64) buf;
 214         xfer[1].len = len;
 215
 216         status = ioctl(fd, SPI_IOC_MESSAGE(2), xfer);
 217         if (status < 0) {
 218                 perror("SPI_IOC_MESSAGE");
 219                 return;
 220         }
 221
 222         printf("response(%2d, %2d): ", len, status);
 223         for (bp = buf; len; len--)
 224                 printf(" %02x", *bp++);
 225         printf("\n");
 226 }
 227
 228 static void dumpstat(const char *name, int fd)
 229 {
 230         __u8    mode, lsb, bits;
 231         __u32   speed;
 232
 233         if (ioctl(fd, SPI_IOC_RD_MODE, &mode) < 0) {
 234                 perror("SPI rd_mode");
 235                 return;
 236         }
 237         if (ioctl(fd, SPI_IOC_RD_LSB_FIRST, &lsb) < 0) {
 238                 perror("SPI rd_lsb_fist");
 239                 return;
 240         }
 241         if (ioctl(fd, SPI_IOC_RD_BITS_PER_WORD, &bits) < 0) {
 242                 perror("SPI bits_per_word");
 243                 return;
 244         }
 245         if (ioctl(fd, SPI_IOC_RD_MAX_SPEED_HZ, &speed) < 0) {
 246                 perror("SPI max_speed_hz");
 247                 return;
 248         }
 249
 250         printf("%s: spi mode %d, %d bits %sper word, %d Hz max\n",
 251                 name, mode, bits, lsb ? "(lsb first) " : "", speed);
 252 }
 253
 254 int main(int argc, char **argv)
 255 {
 256         int             c;
 257         int             readcount = 0;
 258         int             msglen = 0;
 259         int             fd;
 260         const char      *name;
 261
 262         while ((c = getopt(argc, argv, "hm:r:v")) != EOF) {
 263                 switch (c) {
 264                 case 'm':
 265                         msglen = atoi(optarg);
 266                         if (msglen < 0)
 267                                 goto usage;
 268                         continue;
 269                 case 'r':
 270                         readcount = atoi(optarg);
 271                         if (readcount < 0)
 272                                 goto usage;
 273                         continue;
 274                 case 'v':
 275                         verbose++;
 276                         continue;
 277                 case 'h':
 278                 case '?':
 279 usage:
 280                         fprintf(stderr,
 281                                 "usage: %s [-h] [-m N] [-r N] /dev/spidevB.D\n",
 282                                 argv[0]);
 283                         return 1;
 284                 }
 285         }
 286
 287         if ((optind + 1) != argc)
 288                 goto usage;
 289         name = argv[optind];
 290
 291         fd = open(name, O_RDWR);
 292         if (fd < 0) {
 293                 perror("open");
 294                 return 1;
 295         }
 296
 297         dumpstat(name, fd);
 298
 299         if (msglen)
 300                 do_msg(fd, msglen);
 301
 302         if (readcount)
 303                 do_read(fd, readcount);
 304
 305         close(fd);
 306         return 0;
 307 }