1.\" $NetBSD: spi.9,v 1.2 2019/02/23 17:37:10 wiz Exp $ 2.\" 3.\" Copyright (c) 2019 The NetBSD Foundation 4.\" All rights reserved. 5.\" 6.\" Written by Michael van Elst 7.\" 8.\" Redistribution and use in source and binary forms, with or without 9.\" modification, are permitted provided that the following conditions 10.\" are met: 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 2. Redistributions in binary form must reproduce the above copyright 14.\" notice, this list of conditions and the following disclaimer in the 15.\" documentation and/or other materials provided with the distribution. 16.\" 17.\" THIS SOFTWARE IS PROVIDED BY WASABI SYSTEMS, INC. ``AS IS'' AND 18.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 19.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 20.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL WASABI SYSTEMS, INC 21.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 22.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 23.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 24.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 25.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 26.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 27.\" POSSIBILITY OF SUCH DAMAGE. 28.\" 29.Dd February 23, 2019 30.Dt SPI 9 31.Os 32.Sh NAME 33.Nm spi_configure , 34.Nm spi_transfer , 35.Nm spi_transfer_init , 36.Nm spi_chunk_init , 37.Nm spi_transfer_add , 38.Nm spi_wait , 39.Nm spi_done , 40.Nm spi_send , 41.Nm spi_recv , 42.Nm spi_send_recv 43.Nd Serial Peripheral Interface (SPI) kernel interface 44.Sh SYNOPSIS 45.In dev/spi/spivar.h 46.Ft int 47.Fo spi_configure 48.Fa "struct spi_handle *sh" 49.Fa "int mode" 50.Fa "int speed" 51.Fc 52.Ft int 53.Fo spi_transfer 54.Fa "struct spi_handle *sh" 55.Fa "struct spi_transfer *st" 56.Fc 57.Ft void 58.Fo spi_transfer_init 59.Fa "struct spi_transfer *st" 60.Fc 61.Ft void 62.Fo spi_chunk_init 63.Fa "struct spi_chunk *chunk" 64.Fa "int cnt" 65.Fa "const uint8_t *wptr" 66.Fa "uint8_t *rptr" 67.Fc 68.Ft void 69.Fo spi_transfer_add 70.Fa "struct spi_transfer *st" 71.Fa "struct spi_chunk *chunk" 72.Fc 73.Ft void 74.Fo spi_wait 75.Fa "struct spi_transfer *st" 76.Fc 77.Ft void 78.Fo spi_done 79.Fa "struct spi_transfer *st" 80.Fa "int err" 81.Fc 82.Ft int 83.Fo spi_recv 84.Fa "struct spi_handle *sh" 85.Fa "int cnt" 86.Fa "uint8_t *data" 87.Fc 88.Ft int 89.Fo spi_send 90.Fa "struct spi_handle *sh" 91.Fa "int cnt" 92.Fa "const uint8_t *data" 93.Fc 94.Ft int 95.Fo spi_send_recv 96.Fa "struct spi_handle *sh" 97.Fa "int scnt" 98.Fa "const uint8_t *snd" 99.Fa "int rcnt" 100.Fa "const uint8_t *rcv" 101.Fc 102.Sh DESCRIPTION 103SPI is a 4-wire synchronous full-duplex serial bus. 104It is commonly used for connecting devices such as EEPROMs, 105displays, and other types of integrated circuits. 106The 107.Nm spi 108interface provides a means of communicating with SPI-connected devices. 109.Sh FUNCTIONS 110The following functions comprise the API provided to drivers of 111SPI-connected devices. 112.Pp 113The 114.Fa struct spi_handle 115corresponding to the device is passed in the driver attachment. 116.Bl -tag -width spi_transfer_init 117.It Fn spi_configure "sh" "mode" "speed" 118Sets mode and speed for subsequent communication with a SPI slave. 119.It Fn spi_transfer "sh" "st" 120Queue transfer to SPI controller. 121.Fn spi_transfer 122returns an errno value when the transfer couldn't be queued. 123.It Fn spi_transfer_init "st" 124Initialize a transfer structure. 125.It Fn spi_chunk_init "chunk" "cnt" "wptr" rptr" 126Initialize a chunk structure, each chunk corresponds to 127a possibly bi-directional transfer where the same amount 128of bytes is shifted in and out. 129.It Fn spi_transfer_add "st" "chunk" 130Append a chunk to transfer structure. 131.It Fn spi_wait "st" 132Wait for a transfer to complete. 133When the transfer has failed for some reason, the field 134.Va st->st_errno 135is set to a non-zero value. 136.It Fn spi_done "st" "err" 137Called back machine-dependent backend to signal completion 138of a transfer. 139.El 140.Pp 141For simplicity there are convenience functions that combine 142common operations. 143These functions return an errno value when the transfer failed. 144.Bl -tag -width spi_transfer_init 145.It Fn spi_recv "sh" "cnt" "data" 146Prepares a chunk for receiving data, queues a transfer and 147waits for it to complete. 148.It Fn spi_send "sh" "cnt" "data" 149Prepares a chunk for sending data, queues a transfer and 150waits for it to complete. 151.It Fn spi_send_recv "sh" "scnt" "snd" "rcnt" "rcv" 152Prepares two chunks for sending data first and then receiving 153an answer, queues a transfer and waits for it to complete. 154This is not a full-duplex operation. 155.El 156.Sh SEE ALSO 157.Xr spi 4 158.Sh HISTORY 159The 160.Nm spi 161API first appeared in 162.Nx 4.0 . 163