Thu Mar 11 15:46:03 2021 UTC ()
Use inline cross-references.


(nia)
diff -r1.10 -r1.11 src/share/man/man4/spi.4
cvs diff -r1.10 -r1.11 src/share/man/man4/spi.4 (switch to unified diff)

--- src/share/man/man4/spi.4 2021/02/27 09:54:59 1.10
+++ src/share/man/man4/spi.4 2021/03/11 15:46:03 1.11
@@ -1,174 +1,168 @@ @@ -1,174 +1,168 @@
1.\" $NetBSD: spi.4,v 1.10 2021/02/27 09:54:59 nia Exp $ 1.\" $NetBSD: spi.4,v 1.11 2021/03/11 15:46:03 nia 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.
15.\" 2. Redistributions in binary form must reproduce the above 15.\" 2. Redistributions in binary form must reproduce the above
16.\" copyright notice, this list of conditions and the following 16.\" copyright notice, this list of conditions and the following
17.\" disclaimer in the documentation and/or other materials provided 17.\" disclaimer in the documentation and/or other materials provided
18.\" with the distribution. 18.\" with the distribution.
19.\" 3. All advertising materials mentioning features or use of this 19.\" 3. All advertising materials mentioning features or use of this
20.\" software must display the following acknowledgements: 20.\" software must display the following acknowledgements:
21.\" This product includes software developed by the Urbana-Champaign 21.\" This product includes software developed by the Urbana-Champaign
22.\" Independent Media Center. 22.\" Independent Media Center.
23.\" This product includes software developed by Garrett D'Amore. 23.\" This product includes software developed by Garrett D'Amore.
24.\" 4. Urbana-Champaign Independent Media Center's name and Garrett 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 25.\" D'Amore's name may not be used to endorse or promote products
26.\" derived from this software without specific prior written permission. 26.\" derived from this software without specific prior written permission.
27.\" 27.\"
28.\" THIS SOFTWARE IS PROVIDED BY THE URBANA-CHAMPAIGN INDEPENDENT 28.\" THIS SOFTWARE IS PROVIDED BY THE URBANA-CHAMPAIGN INDEPENDENT
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 February 27, 2021 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.
56.Sh DESCRIPTION 56.Sh DESCRIPTION
57.Nx 57.Nx
58includes a machine dependent 58includes a machine dependent
59.Tn SPI 59.Tn SPI
60(Serial Peripheral Interface) bus subsystem, and several different 60(Serial Peripheral Interface) bus subsystem, and several different
61machine-independent 61machine-independent
62.Tn SPI 62.Tn SPI
63device drivers. 63device drivers.
64.Pp 64.Pp
65Your system may support additional machine-dependent SPI devices. 65Your system may support additional machine-dependent SPI devices.
66Consult your system's 66Consult your system's
67.Xr intro 4 67.Xr intro 4
68for additional information. 68for additional information.
69.Pp 69.Pp
70.Tn SPI 70.Tn SPI
71is a 4-wire synchronous full-duplex serial bus. 71is a 4-wire synchronous full-duplex serial bus.
72Some systems provide support for 72Some systems provide support for
73.Tn Microwire , 73.Tn Microwire ,
74which is 74which is
75.Tn Philips' 75.Tn Philips'
76name for a strict subset of SPI, with more rigidly defined signaling. 76name for a strict subset of SPI, with more rigidly defined signaling.
77Therefore, 77Therefore,
78.Tn Microwire 78.Tn Microwire
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 92.Sh IOCTLS
93The following 93The following
94.Xr ioctl 2 94.Xr ioctl 2
95calls apply to 95calls apply to
96.Em SPI 96.Em SPI
97devices. 97devices.
98They are defined in the header file 98They are defined in the header file
99.In dev/spi/spi_io.h : 99.In dev/spi/spi_io.h :
100.Bl -tag -width indent 100.Bl -tag -width indent
101.It Dv SPI_IOCTL_CONFIGURE (spi_ioctl_configure_t) 101.It Dv SPI_IOCTL_CONFIGURE (spi_ioctl_configure_t)
102Used to choose the operational mode and clock. 102Used to choose the operational mode and clock.
103The 103The
104.Li sic_mode 104.Li sic_mode
105defines polarity and phase of the clock. 105defines polarity and phase of the clock.
106.Li sic_speed 106.Li sic_speed
107is the clock speed in Hz, a value of 0 means to keep the default speed 107is the clock speed in Hz, a value of 0 means to keep the default speed
108of the device. 108of the device.
109.Bd -literal 109.Bd -literal
110typedef struct spi_ioctl_configure { 110typedef struct spi_ioctl_configure {
111 int sic_addr; 111 int sic_addr;
112 int sic_mode; 112 int sic_mode;
113 int sic_speed; 113 int sic_speed;
114} spi_ioctl_configure_t; 114} spi_ioctl_configure_t;
115.Ed 115.Ed
116.It Dv SPI_IOCTL_TRANSFER (spi_ioctl_transfer_t) 116.It Dv SPI_IOCTL_TRANSFER (spi_ioctl_transfer_t)
117Used to handle an I/O transaction. 117Used to handle an I/O transaction.
118.Bd -literal 118.Bd -literal
119typedef struct spi_ioctl_transfer { 119typedef struct spi_ioctl_transfer {
120 int sit_addr; 120 int sit_addr;
121 const void *sit_send; 121 const void *sit_send;
122 size_t sit_sendlen; 122 size_t sit_sendlen;
123 void *sit_recv; 123 void *sit_recv;
124 size_t sit_recvlen; 124 size_t sit_recvlen;
125} spi_ioctl_transfer_t; 125} spi_ioctl_transfer_t;
126.Ed 126.Ed
127.El 127.El
128.Sh HARDWARE 128.Sh HARDWARE
129.Nx 129.Nx
130includes the following machine-independent 130includes the following machine-independent
131.Tn SPI 131.Tn SPI
132drivers: 132drivers:
133.Bl -tag -width pcdisplay -offset indent 133.Bl -tag -width mcp23s17gpio(4) -offset indent
134.It m25p 134.It Xr m25p 4
135STMicroelectronics M25P family of NOR flash devices. 135STMicroelectronics M25P family of NOR flash devices.
136.It mcp23s17gpio 136.It Xr mcp23s17gpio 4
137Microchip MCP23S17 16-bit GPIO chip. 137Microchip MCP23S17 16-bit GPIO chip.
138.It mcp3kadc 138.It Xr mcp3kadc 4
139Microchip MCP3x0x SAR analog to digital converter. 139Microchip MCP3x0x SAR analog to digital converter.
140.It mcp48x1dac 140.It Xr mcp48x1dac 4
141Microchip MCP4801/MCP4811/MCP4821 digital to analog converter. 141Microchip MCP4801/MCP4811/MCP4821 digital to analog converter.
142.It tm121temp 142.It Xr tm121temp 4
143Texas Instruments TMP121 temperature sensor. 143Texas Instruments TMP121 temperature sensor.
144.It ssdfb 144.It Xr ssdfb 4
145OLED/PLED framebuffer modules. 145OLED/PLED framebuffer modules.
146.El 146.El
147.Sh FILES 147.Sh FILES
148.Bl -tag -width "/dev/spiu" -compact 148.Bl -tag -width "/dev/spiu" -compact
149.It /dev/spi Ns Ar u 149.It /dev/spi Ns Ar u
150SPI device unit 150SPI device unit
151.Ar u 151.Ar u
152file. 152file.
153.El 153.El
154.Sh SEE ALSO 154.Sh SEE ALSO
155.Xr m25p 4 , 
156.Xr mcp23s17gpio 4 , 
157.Xr mcp3kadc 4 , 
158.Xr mcp48x1dac 4 , 
159.Xr ssdfb 4 , 
160.Xr tm121temp 4 , 
161.Xr spi 9 155.Xr spi 9
162.Sh HISTORY 156.Sh HISTORY
163The machine-independent 157The machine-independent
164.Tn SPI 158.Tn SPI
165framework was written by 159framework was written by
166.An Garrett D'Amore 160.An Garrett D'Amore
167for the 161for the
168Champaign-Urbana Community Wireless Network Project (CUWiN), and 162Champaign-Urbana Community Wireless Network Project (CUWiN), and
169appeared in 163appeared in
170.Nx 4.0 . 164.Nx 4.0 .
171The 165The
172.Xr ioctl 2 166.Xr ioctl 2
173interface allowing configuration from userspace appeared in 167interface allowing configuration from userspace appeared in
174.Nx 9.0 . 168.Nx 9.0 .