1.\" $NetBSD: spi.4,v 1.13 2022/12/03 01:04:42 brad Exp $ 2.\" 3.\" Copyright (c) 2006 Urbana-Champaign Independent Media Center. 4.\" Copyright (c) 2006 Garrett D'Amore. 5.\" All rights reserved. 6.\" 7.\" Portions of this code were written by Garrett D'Amore for the 8.\" Champaign-Urbana Community Wireless Network Project. 9.\" 10.\" Redistribution and use in source and binary forms, with or 11.\" without modification, are permitted provided that the following 12.\" conditions are met: 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 2. Redistributions in binary form must reproduce the above 16.\" copyright notice, this list of conditions and the following 17.\" disclaimer in the documentation and/or other materials provided 18.\" with the distribution. 19.\" 3. All advertising materials mentioning features or use of this 20.\" software must display the following acknowledgements: 21.\" This product includes software developed by the Urbana-Champaign 22.\" Independent Media Center. 23.\" This product includes software developed by Garrett D'Amore. 24.\" 4. Urbana-Champaign Independent Media Center's name and Garrett 25.\" D'Amore's name may not be used to endorse or promote products 26.\" derived from this software without specific prior written permission. 27.\" 28.\" THIS SOFTWARE IS PROVIDED BY THE URBANA-CHAMPAIGN INDEPENDENT 29.\" MEDIA CENTER AND GARRETT D'AMORE ``AS IS'' AND ANY EXPRESS OR 30.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 31.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 32.\" ARE DISCLAIMED. IN NO EVENT SHALL THE URBANA-CHAMPAIGN INDEPENDENT 33.\" MEDIA CENTER OR GARRETT D'AMORE BE LIABLE FOR ANY DIRECT, INDIRECT, 34.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 35.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 36.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 37.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 38.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 39.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF 40.\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 41.\" 42.Dd February 27, 2021 43.Dt SPI 4 44.Os 45.Sh NAME 46.Nm spi 47.Nd introduction to machine-independent SPI bus support and drivers 48.Sh SYNOPSIS 49.Cd "spi* at mainbus?" 50.Pp 51Other attachments are machine-dependent and will depend on the bus topology 52of your system. 53See 54.Xr intro 4 55for your system for more information. 56.Sh DESCRIPTION 57.Nx 58includes a machine dependent 59.Tn SPI 60(Serial Peripheral Interface) bus subsystem, and several different 61machine-independent 62.Tn SPI 63device drivers. 64.Pp 65Your system may support additional machine-dependent SPI devices. 66Consult your system's 67.Xr intro 4 68for additional information. 69.Pp 70.Tn SPI 71is a 4-wire synchronous full-duplex serial bus. 72Some systems provide support for 73.Tn Microwire , 74which is 75.Tn Philips' 76name for a strict subset of SPI, with more rigidly defined signaling. 77Therefore, 78.Tn Microwire 79devices are also supported by the 80.Tn SPI 81framework. 82.Pp 83Note that when referencing 84.Tn SPI 85devices in a 86.Xr config 1 87file, the 88.Sq slave 89must be provided, as 90.Tn SPI 91lacks any way to automatically probe devices. 92.Sh IOCTLS 93The following 94.Xr ioctl 2 95calls apply to 96.Em SPI 97devices. 98They are defined in the header file 99.In dev/spi/spi_io.h : 100.Bl -tag -width indent 101.It Dv SPI_IOCTL_CONFIGURE (spi_ioctl_configure_t) 102Used to choose the operational mode and clock. 103The 104.Li sic_mode 105defines polarity and phase of the clock. 106.Li sic_speed 107is the clock speed in Hz, a value of 0 means to keep the default speed 108of the device. 109.Bd -literal 110typedef struct spi_ioctl_configure { 111 int sic_addr; 112 int sic_mode; 113 int sic_speed; 114} spi_ioctl_configure_t; 115.Ed 116.It Dv SPI_IOCTL_TRANSFER (spi_ioctl_transfer_t) 117Used to handle an I/O transaction. 118.Bd -literal 119typedef struct spi_ioctl_transfer { 120 int sit_addr; 121 const void *sit_send; 122 size_t sit_sendlen; 123 void *sit_recv; 124 size_t sit_recvlen; 125} spi_ioctl_transfer_t; 126.Ed 127.El 128.Sh HARDWARE 129.Nx 130includes the following machine-independent 131.Tn SPI 132drivers: 133.Bl -tag -width mcp23s17gpio(4) -offset indent 134.It Xr bmx280thp 4 135Bosch BMP280 / BME280 sensor. 136.It Xr m25p 4 137STMicroelectronics M25P family of NOR flash devices. 138.It Xr mcp23s17gpio 4 139Microchip MCP23S17 16-bit GPIO chip. 140.It Xr mcp3kadc 4 141Microchip MCP3x0x SAR analog to digital converter. 142.It Xr mcp48x1dac 4 143Microchip MCP4801/MCP4811/MCP4821 digital to analog converter. 144.It Xr tm121temp 4 145Texas Instruments TMP121 temperature sensor. 146.It Xr scmdspi 4 147SPI frontend for the Sparkfun Serial Controlled Motor Driver. 148.It Xr ssdfb 4 149OLED/PLED framebuffer modules. 150.El 151.Sh FILES 152.Bl -tag -width "/dev/spiu" -compact 153.It /dev/spi Ns Ar u 154SPI device unit 155.Ar u 156file. 157.El 158.Sh SEE ALSO 159.Xr spi 9 160.Sh HISTORY 161The machine-independent 162.Tn SPI 163framework was written by 164.An Garrett D'Amore 165for the 166Champaign-Urbana Community Wireless Network Project (CUWiN), and 167appeared in 168.Nx 4.0 . 169The 170.Xr ioctl 2 171interface allowing configuration from userspace appeared in 172.Nx 9.0 . 173