1.\" 2.\" Copyright (c) 2018 Ian Lepore <ian@freebsd.org> 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 15.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 16.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 17.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 18.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 19.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 20.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 21.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 22.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 23.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 24.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 25.\" 26.Dd August 21, 2020 27.Dt SPIGEN 4 28.Os 29.Sh NAME 30.Nm spigen 31.Nd SPI generic I/O device driver 32.Sh SYNOPSIS 33To compile this driver into the kernel, 34place the following lines in your 35kernel configuration file: 36.Bd -ragged -offset indent 37.Cd "device spi" 38.Cd "device spibus" 39.Cd "device spigen" 40.Ed 41.Pp 42Alternatively, to load the driver as a 43module at boot time, place the following line in 44.Xr loader.conf 5 : 45.Bd -literal -offset indent 46spigen_load="YES" 47.Ed 48.Sh DESCRIPTION 49The 50.Nm 51driver provides direct access to a slave device on the SPI bus. 52Each instance of a 53.Nm 54device is associated with a single chip-select 55line on the bus, and all I/O performed through that instance is done 56with that chip-select line asserted. 57.Pp 58SPI data transfers are inherently bi-directional; there are no separate 59read and write operations. 60When commands and data are sent to a device, data also comes back from 61the device, although in some cases the data may not be useful (or even 62documented or predictable for some devices). 63Likewise on a read operation, whatever data is in the buffer at the start 64of the operation is sent to (and typically ignored by) the device, with each 65outgoing byte then replaced in the buffer by the corresponding incoming byte. 66Thus, all buffers passed to the transfer functions are both input and 67output buffers. 68.Pp 69The 70.Nm 71driver provides access to the SPI slave device with the following 72.Xr ioctl 2 73calls, defined in 74.In sys/spigenio.h : 75.Bl -tag -width indent 76.It Dv SPIGENIOC_TRANSFER Pq Vt "struct spigen_transfer" 77Transfer a command and optional associated data to/from the device, 78using the buffers described by the st_command and st_data fields in the 79.Vt spigen_transfer . 80Set 81.Vt st_data.iov_len 82to zero if there is no data associated with the command. 83.Bd -literal 84struct spigen_transfer { 85 struct iovec st_command; 86 struct iovec st_data; 87}; 88.Ed 89.It Dv SPIGENIOC_TRANSFER_MMAPPED Pq Vt "spigen_transfer_mmapped" 90Transfer a command and optional associated data to/from the device. 91The buffers for the transfer are a previously-mmap'd region. 92The length of the command and data within that region are described by the 93.Vt stm_command_length 94and 95.Vt stm_data_length 96fields of 97.Vt spigen_transfer_mmapped . 98If 99.Vt stm_data_length 100is non-zero, the data appears in the memory region immediately 101following the command (that is, at offset 102.Vt stm_command_length 103from the start of the mapped region). 104.Bd -literal 105struct spigen_transfer_mmapped { 106 size_t stm_command_length; 107 size_t stm_data_length; 108}; 109.Ed 110.It Dv SPIGENIOC_GET_CLOCK_SPEED Pq Vt uint32_t 111Get the maximum clock speed (bus frequency in Hertz) to be used 112when communicating with this slave device. 113.It Dv SPIGENIOC_SET_CLOCK_SPEED Pq Vt uint32_t 114Set the maximum clock speed (bus frequency in Hertz) to be used 115when communicating with this slave device. 116The setting remains in effect for subsequent transfers; it 117is not necessary to reset this before each transfer. 118The actual bus frequency may be lower due to hardware limitations 119of the SPI bus controller device. 120.It Dv SPIGENIOC_GET_SPI_MODE Pq Vt uint32_t 121Get the SPI mode (clock polarity and phase) to be used 122when communicating with this device. 123.It Dv SPIGENIOC_SET_SPI_MODE Pq Vt uint32_t 124Set the SPI mode (clock polarity and phase) to be used 125when communicating with this device. 126The setting remains in effect for subsequent transfers; it 127is not necessary to reset this before each transfer. 128.El 129.Sh HINTS CONFIGURATION 130On a 131.Xr device.hints 5 132based system, such as 133.Li MIPS , 134these values are configurable for 135.Nm : 136.Bl -tag -width indent 137.It Va hint.spigen.%d.at 138The spibus the 139.Nm 140instance is attached to. 141.It Va hint.spigen.%d.clock 142The maximum bus frequency to use when communicating with this device. 143Actual bus speed may be lower, depending on the capabilities of the SPI 144bus controller hardware. 145.It Va hint.spigen.%d.cs 146The chip-select number to assert when performing I/O for this device. 147Set the high bit (1 << 31) to invert the logic level of the chip select line. 148.It Va hint.spigen.%d.mode 149The SPI mode (0-3) to use when communicating with this device. 150.El 151.Sh FDT CONFIGURATION 152On an 153.Xr fdt 4 154based system, the spigen device is defined as a slave device subnode 155of the SPI bus controller node. 156All properties documented in the 157.Va spibus.txt 158bindings document can be used with the 159.Nm 160device. 161The most commonly-used ones are documented below. 162.Pp 163The following properties are required in the 164.Nm 165device subnode: 166.Bl -tag -width indent 167.It Va compatible 168Must be the string "freebsd,spigen". 169.It Va reg 170Chip select address of device. 171.It Va spi-max-frequency 172The maximum bus frequency to use when communicating with this slave device. 173Actual bus speed may be lower, depending on the capabilities of the SPI 174bus controller hardware. 175.El 176.Pp 177The following properties are optional for the 178.Nm 179device subnode: 180.Bl -tag -width indent 181.It Va spi-cpha 182Empty property indicating the slave device requires shifted clock 183phase (CPHA) mode. 184.It Va spi-cpol 185Empty property indicating the slave device requires inverse clock 186polarity (CPOL) mode. 187.It Va spi-cs-high 188Empty property indicating the slave device requires chip select active high. 189.El 190.Sh FILES 191.Bl -tag -width -compact 192.It Pa /dev/spigen* 193.El 194.Sh SEE ALSO 195.Xr fdt 4 , 196.Xr device.hints 5 , 197.Xr spi 8 198.Sh HISTORY 199The 200.Nm 201driver 202appeared in 203.Fx 11.0 . 204FDT support appeared in 205.Fx 11.2 . 206