.\"	$NetBSD: spi.4,v 1.7.2.1 2021/03/05 13:52:58 martin Exp $
.\"
.\" Copyright (c) 2006 Urbana-Champaign Independent Media Center.
.\" Copyright (c) 2006 Garrett D'Amore.
.\" All rights reserved.
.\"
.\" Portions of this code were written by Garrett D'Amore for the
.\" Champaign-Urbana Community Wireless Network Project.
.\"
.\" Redistribution and use in source and binary forms, with or
.\" without modification, are permitted provided that the following
.\" conditions are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above
.\"    copyright notice, this list of conditions and the following
.\"    disclaimer in the documentation and/or other materials provided
.\"    with the distribution.
.\" 3. All advertising materials mentioning features or use of this
.\"    software must display the following acknowledgements:
.\"      This product includes software developed by the Urbana-Champaign
.\"      Independent Media Center.
.\"	This product includes software developed by Garrett D'Amore.
.\" 4. Urbana-Champaign Independent Media Center's name and Garrett
.\"    D'Amore's name may not be used to endorse or promote products
.\"    derived from this software without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE URBANA-CHAMPAIGN INDEPENDENT
.\" MEDIA CENTER AND GARRETT D'AMORE ``AS IS'' AND ANY EXPRESS OR
.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE URBANA-CHAMPAIGN INDEPENDENT
.\" MEDIA CENTER OR GARRETT D'AMORE BE LIABLE FOR ANY DIRECT, INDIRECT,
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
.\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.\"
.Dd February 27, 2021
.Dt SPI 4
.Os
.Sh NAME
.Nm spi
.Nd introduction to machine-independent SPI bus support and drivers
.Sh SYNOPSIS
.Cd "spi* at mainbus?"
.Pp
Other attachments are machine-dependent and will depend on the bus topology
of your system.
See
.Xr intro 4
for your system for more information.
.Sh DESCRIPTION
.Nx
includes a machine dependent
.Tn SPI
(Serial Peripheral Interface) bus subsystem, and several different
machine-independent
.Tn SPI
device drivers.
.Pp
Your system may support additional machine-dependent SPI devices.
Consult your system's
.Xr intro 4
for additional information.
.Pp
.Tn SPI
is a 4-wire synchronous full-duplex serial bus.
Some systems provide support for
.Tn Microwire ,
which is
.Tn Philips'
name for a strict subset of SPI, with more rigidly defined signaling.
Therefore,
.Tn Microwire
devices are also supported by the
.Tn SPI
framework.
.Pp
Note that when referencing
.Tn SPI
devices in a
.Xr config 1
file, the
.Sq slave
must be provided, as
.Tn SPI
lacks any way to automatically probe devices.
.Sh IOCTLS
The following
.Xr ioctl 2
calls apply to
.Em SPI
devices.
They are defined in the header file
.In dev/spi/spi_io.h :
.Bl -tag -width indent
.It Dv SPI_IOCTL_CONFIGURE (spi_ioctl_configure_t)
Used to choose the operational mode and clock.
The
.Li sic_mode
defines polarity and phase of the clock.
.Li sic_speed
is the clock speed in Hz, a value of 0 means to keep the default speed
of the device.
.Bd -literal
typedef struct spi_ioctl_configure {
	int sic_addr;
	int sic_mode;
	int sic_speed;
} spi_ioctl_configure_t;
.Ed
.It Dv SPI_IOCTL_TRANSFER (spi_ioctl_transfer_t)
Used to handle an I/O transaction.
.Bd -literal
typedef struct spi_ioctl_transfer {
	int sit_addr;
	const void *sit_send;
	size_t sit_sendlen;
	void *sit_recv;
	size_t sit_recvlen;
} spi_ioctl_transfer_t;
.Ed
.El
.Sh HARDWARE
.Nx
includes the following machine-independent
.Tn SPI
drivers:
.Bl -tag -width pcdisplay -offset indent
.It m25p
STMicroelectronics M25P family of NOR flash devices.
.It mcp23s17gpio
Microchip MCP23S17 16-bit GPIO chip.
.It mcp3kadc
Microchip MCP3x0x SAR analog to digital converter.
.It mcp48x1dac
Microchip MCP4801/MCP4811/MCP4821 digital to analog converter.
.It tm121temp
Texas Instruments TMP121 temperature sensor.
.It ssdfb
OLED/PLED framebuffer modules.
.El
.Sh FILES
.Bl -tag -width "/dev/spiu" -compact
.It /dev/spi Ns Ar u
SPI device unit
.Ar u
file.
.El
.Sh SEE ALSO
.Xr m25p 4 ,
.Xr mcp23s17gpio 4 ,
.Xr mcp3kadc 4 ,
.Xr mcp48x1dac 4 ,
.Xr ssdfb 4 ,
.Xr tm121temp 4 ,
.Xr spi 9
.Sh HISTORY
The machine-independent
.Tn SPI
framework was written by
.An Garrett D'Amore
for the
Champaign-Urbana Community Wireless Network Project (CUWiN), and
appeared in
.Nx 4.0 .
The
.Xr ioctl 2
interface allowing configuration from userspace appeared in
.Nx 9.0 .