Documentation/spi/spidev.rst

   1 =================
   2 SPI userspace API
   3 =================
   4
   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
   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
  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
  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
  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
  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
 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
 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
 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.