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.\" $FreeBSD$ 27.\" 28.Dd August 21, 2020 29.Dt SPIGEN 4 30.Os 31.Sh NAME 32.Nm spigen 33.Nd SPI generic I/O device driver 34.Sh SYNOPSIS 35To compile this driver into the kernel, 36place the following lines in your 37kernel configuration file: 38.Bd -ragged -offset indent 39.Cd "device spi" 40.Cd "device spibus" 41.Cd "device spigen" 42.Ed 43.Pp 44Alternatively, to load the driver as a 45module at boot time, place the following line in 46.Xr loader.conf 5 : 47.Bd -literal -offset indent 48spigen_load="YES" 49.Ed 50.Sh DESCRIPTION 51The 52.Nm 53driver provides direct access to a slave device on the SPI bus. 54Each instance of a 55.Nm 56device is associated with a single chip-select 57line on the bus, and all I/O performed through that instance is done 58with that chip-select line asserted. 59.Pp 60SPI data transfers are inherently bi-directional; there are no separate 61read and write operations. 62When commands and data are sent to a device, data also comes back from 63the device, although in some cases the data may not be useful (or even 64documented or predictable for some devices). 65Likewise on a read operation, whatever data is in the buffer at the start 66of the operation is sent to (and typically ignored by) the device, with each 67outgoing byte then replaced in the buffer by the corresponding incoming byte. 68Thus, all buffers passed to the transfer functions are both input and 69output buffers. 70.Pp 71The 72.Nm 73driver provides access to the SPI slave device with the following 74.Xr ioctl 2 75calls, defined in 76.In sys/spigenio.h : 77.Bl -tag -width indent 78.It Dv SPIGENIOC_TRANSFER Pq Vt "struct spigen_transfer" 79Transfer a command and optional associated data to/from the device, 80using the buffers described by the st_command and st_data fields in the 81.Vt spigen_transfer . 82Set 83.Vt st_data.iov_len 84to zero if there is no data associated with the command. 85.Bd -literal 86struct spigen_transfer { 87 struct iovec st_command; 88 struct iovec st_data; 89}; 90.Ed 91.It Dv SPIGENIOC_TRANSFER_MMAPPED Pq Vt "spigen_transfer_mmapped" 92Transfer a command and optional associated data to/from the device. 93The buffers for the transfer are a previously-mmap'd region. 94The length of the command and data within that region are described by the 95.Vt stm_command_length 96and 97.Vt stm_data_length 98fields of 99.Vt spigen_transfer_mmapped . 100If 101.Vt stm_data_length 102is non-zero, the data appears in the memory region immediately 103following the command (that is, at offset 104.Vt stm_command_length 105from the start of the mapped region). 106.Bd -literal 107struct spigen_transfer_mmapped { 108 size_t stm_command_length; 109 size_t stm_data_length; 110}; 111.Ed 112.It Dv SPIGENIOC_GET_CLOCK_SPEED Pq Vt uint32_t 113Get the maximum clock speed (bus frequency in Hertz) to be used 114when communicating with this slave device. 115.It Dv SPIGENIOC_SET_CLOCK_SPEED Pq Vt uint32_t 116Set the maximum clock speed (bus frequency in Hertz) to be used 117when communicating with this slave device. 118The setting remains in effect for subsequent transfers; it 119is not necessary to reset this before each transfer. 120The actual bus frequency may be lower due to hardware limitations 121of the SPI bus controller device. 122.It Dv SPIGENIOC_GET_SPI_MODE Pq Vt uint32_t 123Get the SPI mode (clock polarity and phase) to be used 124when communicating with this device. 125.It Dv SPIGENIOC_SET_SPI_MODE Pq Vt uint32_t 126Set the SPI mode (clock polarity and phase) to be used 127when communicating with this device. 128The setting remains in effect for subsequent transfers; it 129is not necessary to reset this before each transfer. 130.El 131.Sh HINTS CONFIGURATION 132On a 133.Xr device.hints 5 134based system, such as 135.Li MIPS , 136these values are configurable for 137.Nm : 138.Bl -tag -width indent 139.It Va hint.spigen.%d.at 140The spibus the 141.Nm 142instance is attached to. 143.It Va hint.spigen.%d.clock 144The maximum bus frequency to use when communicating with this device. 145Actual bus speed may be lower, depending on the capabilities of the SPI 146bus controller hardware. 147.It Va hint.spigen.%d.cs 148The chip-select number to assert when performing I/O for this device. 149Set the high bit (1 << 31) to invert the logic level of the chip select line. 150.It Va hint.spigen.%d.mode 151The SPI mode (0-3) to use when communicating with this device. 152.El 153.Sh FDT CONFIGURATION 154On an 155.Xr fdt 4 156based system, the spigen device is defined as a slave device subnode 157of the SPI bus controller node. 158All properties documented in the 159.Va spibus.txt 160bindings document can be used with the 161.Nm 162device. 163The most commonly-used ones are documented below. 164.Pp 165The following properties are required in the 166.Nm 167device subnode: 168.Bl -tag -width indent 169.It Va compatible 170Must be the string "freebsd,spigen". 171.It Va reg 172Chip select address of device. 173.It Va spi-max-frequency 174The maximum bus frequency to use when communicating with this slave device. 175Actual bus speed may be lower, depending on the capabilities of the SPI 176bus controller hardware. 177.El 178.Pp 179The following properties are optional for the 180.Nm 181device subnode: 182.Bl -tag -width indent 183.It Va spi-cpha 184Empty property indicating the slave device requires shifted clock 185phase (CPHA) mode. 186.It Va spi-cpol 187Empty property indicating the slave device requires inverse clock 188polarity (CPOL) mode. 189.It Va spi-cs-high 190Empty property indicating the slave device requires chip select active high. 191.El 192.Sh FILES 193.Bl -tag -width -compact 194.It Pa /dev/spigen* 195.El 196.Sh SEE ALSO 197.Xr fdt 4 , 198.Xr device.hints 5 , 199.Xr spi 8 200.Sh HISTORY 201The 202.Nm 203driver 204appeared in 205.Fx 11.0 . 206FDT support appeared in 207.Fx 11.2 . 208