Orange Pi5 kernel

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