Fri Mar 5 13:52:58 2021 UTC ()
Pull up following revision(s) (requested by nia in ticket #1223):

	share/man/man4/spi.4: revision 1.10
	share/man/man4/spi.4: revision 1.8
	share/man/man4/spi.4: revision 1.9

Document the userspace /dev/spi interface to the best of my ability.

Add ssdfb(4).

Based mostly on a mailing list post by mlelstv;
https://mail-index.netbsd.org/port-arm/2019/02/07/msg005454.html

spi.4: Add a FILES section

spi.4: mention history of ioctl interface


(martin)
diff -r1.7 -r1.7.2.1 src/share/man/man4/spi.4
cvs diff -r1.7 -r1.7.2.1 src/share/man/man4/spi.4 (expand / switch to unified diff)

--- src/share/man/man4/spi.4 2019/02/23 17:34:04 1.7
+++ src/share/man/man4/spi.4 2021/03/05 13:52:58 1.7.2.1
@@ -1,14 +1,14 @@ @@ -1,14 +1,14 @@
1.\" $NetBSD: spi.4,v 1.7 2019/02/23 17:34:04 wiz Exp $ 1.\" $NetBSD: spi.4,v 1.7.2.1 2021/03/05 13:52:58 martin Exp $
2.\" 2.\"
3.\" Copyright (c) 2006 Urbana-Champaign Independent Media Center. 3.\" Copyright (c) 2006 Urbana-Champaign Independent Media Center.
4.\" Copyright (c) 2006 Garrett D'Amore. 4.\" Copyright (c) 2006 Garrett D'Amore.
5.\" All rights reserved. 5.\" All rights reserved.
6.\" 6.\"
7.\" Portions of this code were written by Garrett D'Amore for the 7.\" Portions of this code were written by Garrett D'Amore for the
8.\" Champaign-Urbana Community Wireless Network Project. 8.\" Champaign-Urbana Community Wireless Network Project.
9.\" 9.\"
10.\" Redistribution and use in source and binary forms, with or 10.\" Redistribution and use in source and binary forms, with or
11.\" without modification, are permitted provided that the following 11.\" without modification, are permitted provided that the following
12.\" conditions are met: 12.\" conditions are met:
13.\" 1. Redistributions of source code must retain the above copyright 13.\" 1. Redistributions of source code must retain the above copyright
14.\" notice, this list of conditions and the following disclaimer. 14.\" notice, this list of conditions and the following disclaimer.
@@ -29,27 +29,27 @@ @@ -29,27 +29,27 @@
29.\" MEDIA CENTER AND GARRETT D'AMORE ``AS IS'' AND ANY EXPRESS OR 29.\" MEDIA CENTER AND GARRETT D'AMORE ``AS IS'' AND ANY EXPRESS OR
30.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 30.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
31.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 31.\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
32.\" ARE DISCLAIMED. IN NO EVENT SHALL THE URBANA-CHAMPAIGN INDEPENDENT 32.\" ARE DISCLAIMED. IN NO EVENT SHALL THE URBANA-CHAMPAIGN INDEPENDENT
33.\" MEDIA CENTER OR GARRETT D'AMORE BE LIABLE FOR ANY DIRECT, INDIRECT, 33.\" MEDIA CENTER OR GARRETT D'AMORE BE LIABLE FOR ANY DIRECT, INDIRECT,
34.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 34.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
35.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 35.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
36.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 36.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
37.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 37.\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
38.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 38.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
39.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF 39.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
40.\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 40.\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
41.\" 41.\"
42.Dd October 9, 2006 42.Dd February 27, 2021
43.Dt SPI 4 43.Dt SPI 4
44.Os 44.Os
45.Sh NAME 45.Sh NAME
46.Nm spi 46.Nm spi
47.Nd introduction to machine-independent SPI bus support and drivers 47.Nd introduction to machine-independent SPI bus support and drivers
48.Sh SYNOPSIS 48.Sh SYNOPSIS
49.Cd "spi* at mainbus?" 49.Cd "spi* at mainbus?"
50.Pp 50.Pp
51Other attachments are machine-dependent and will depend on the bus topology 51Other attachments are machine-dependent and will depend on the bus topology
52of your system. 52of your system.
53See 53See
54.Xr intro 4 54.Xr intro 4
55for your system for more information. 55for your system for more information.
@@ -79,46 +79,96 @@ Therefore, @@ -79,46 +79,96 @@ Therefore,
79devices are also supported by the 79devices are also supported by the
80.Tn SPI 80.Tn SPI
81framework. 81framework.
82.Pp 82.Pp
83Note that when referencing 83Note that when referencing
84.Tn SPI 84.Tn SPI
85devices in a 85devices in a
86.Xr config 1 86.Xr config 1
87file, the 87file, the
88.Sq slave 88.Sq slave
89must be provided, as 89must be provided, as
90.Tn SPI 90.Tn SPI
91lacks any way to automatically probe devices. 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
92.Sh HARDWARE 128.Sh HARDWARE
93.Nx 129.Nx
94includes the following machine-independent 130includes the following machine-independent
95.Tn SPI 131.Tn SPI
96drivers 132drivers:
97.Bl -tag -width pcdisplay -offset indent 133.Bl -tag -width pcdisplay -offset indent
98.It m25p 134.It m25p
99STMicroelectronics M25P family of NOR flash devices. 135STMicroelectronics M25P family of NOR flash devices.
100.It mcp23s17gpio 136.It mcp23s17gpio
101Microchip MCP23S17 16-bit GPIO chip. 137Microchip MCP23S17 16-bit GPIO chip.
102.It mcp3kadc 138.It mcp3kadc
103Microchip MCP3x0x SAR analog to digital converter. 139Microchip MCP3x0x SAR analog to digital converter.
104.It mcp48x1dac 140.It mcp48x1dac
105Microchip MCP4801/MCP4811/MCP4821 digital to analog converter. 141Microchip MCP4801/MCP4811/MCP4821 digital to analog converter.
106.It tm121temp 142.It tm121temp
107Texas Instruments TMP121 temperature sensor. 143Texas Instruments TMP121 temperature sensor.
 144.It ssdfb
 145OLED/PLED framebuffer modules.
 146.El
 147.Sh FILES
 148.Bl -tag -width "/dev/spiu" -compact
 149.It /dev/spi Ns Ar u
 150SPI device unit
 151.Ar u
 152file.
108.El 153.El
109.Sh SEE ALSO 154.Sh SEE ALSO
110.Xr m25p 4 , 155.Xr m25p 4 ,
111.Xr mcp23s17gpio 4 , 156.Xr mcp23s17gpio 4 ,
112.Xr mcp3kadc 4 , 157.Xr mcp3kadc 4 ,
113.Xr mcp48x1dac 4 , 158.Xr mcp48x1dac 4 ,
 159.Xr ssdfb 4 ,
114.Xr tm121temp 4 , 160.Xr tm121temp 4 ,
115.Xr spi 9 161.Xr spi 9
116.Sh HISTORY 162.Sh HISTORY
117The machine-independent 163The machine-independent
118.Tn SPI 164.Tn SPI
119framework was written by 165framework was written by
120.An Garrett D'Amore 166.An Garrett D'Amore
121for the 167for the
122Champaign-Urbana Community Wireless Network Project (CUWiN), and 168Champaign-Urbana Community Wireless Network Project (CUWiN), and
123appeared in 169appeared in
124.Nx 4.0 . 170.Nx 4.0 .
 171The
 172.Xr ioctl 2
 173interface allowing configuration from userspace appeared in
 174.Nx 9.0 .