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
  33 The spidev driver contains lists of SPI devices that are supported for
  34 the different hardware topology representations.
  35
  36 The 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
  50 You are encouraged to add an entry for your SPI device name to relevant
  51 tables, if these don't already have an entry for the device. To do that,
  52 post a patch for spidev to the linux-spi@vger.kernel.org mailing list.
  53
  54 It used to be supported to define an SPI device using the "spidev" name.
  55 For example, as .modalias = "spidev" or compatible = "spidev".  But this
  56 is no longer supported by the Linux kernel and instead a real SPI device
  57 name as listed in one of the tables must be used.
  58
  59 Not having a real SPI device name will lead to an error being printed and
  60 the spidev driver failing to probe.
  61
  62 Sysfs also supports userspace driven binding/unbinding of drivers to
  63 devices that do not bind automatically using one of the tables above.
  64 To 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
  69 When the spidev driver is bound to a SPI device, the sysfs node for the
  70 device will include a child device node with a "dev" attribute that will
  71 be understood by udev or mdev (udev replacement from BusyBox; it's less
  72 featureful, but often enough).
  73
  74 For 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
  90 Do not try to manage the /dev character device special file nodes by hand.
  91 That's error prone, and you'd need to pay careful attention to system
  92 security issues; udev/mdev should already be configured securely.
  93
  94 If 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
  96 kernel and by udev/mdev).  You can unbind by removing the "spidev" driver
  97 module, which will affect all devices using this driver.  You can also unbind
  98 by having kernel code remove the SPI device, probably by removing the driver
  99 for its SPI controller (so its spi_master vanishes).
 100
 101 Since this is a standard Linux device driver -- even though it just happens
 102 to expose a low level API to userspace -- it can be associated with any number
 103 of devices at a time.  Just provide one spi_board_info record for each such
 104 SPI device, and you'll get a /dev device node for each device.
 105
 106
 107 BASIC CHARACTER DEVICE API
 108 ==========================
 109 Normal open() and close() operations on /dev/spidevB.D files work as you
 110 would expect.
 111
 112 Standard read() and write() operations are obviously only half-duplex, and
 113 the chipselect is deactivated between those operations.  Full-duplex access,
 114 and composite operation without chipselect de-activation, is available using
 115 the SPI_IOC_MESSAGE(N) request.
 116
 117 Several ioctl() requests let your driver read or override the device's current
 118 settings 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
 153 NOTES:
 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
 174 FULL DUPLEX CHARACTER DEVICE API
 175 ================================
 176
 177 See the spidev_fdx.c sample program for one example showing the use of the
 178 full duplex programming interface.  (Although it doesn't perform a full duplex
 179 transfer.)  The model is the same as that used in the kernel spi_sync()
 180 request; the individual transfers offer the same capabilities as are
 181 available to kernel drivers (except that it's not asynchronous).
 182
 183 The example shows one half-duplex RPC-style request and response message.
 184 These requests commonly require that the chip not be deselected between
 185 the request and response.  Several such requests could be chained into
 186 a single kernel request, even allowing the chip to be deselected after
 187 each response.  (Other protocol options include changing the word size
 188 and bitrate for each transfer segment.)
 189
 190 To make a full duplex request, provide both rx_buf and tx_buf for the
 191 same transfer.  It's even OK if those are the same buffer.