xref: /freebsd/share/man/man4/gpio.4 (revision dbcb0e960adc9aa4be518b4aa918813655c24142)
1*dbcb0e96SSean Bruno.\" Copyright (c) 2013, Sean Bruno <sbruno@freebsd.org>
2*dbcb0e96SSean Bruno.\" All rights reserved.
3*dbcb0e96SSean Bruno.\"
4*dbcb0e96SSean Bruno.\" Redistribution and use in source and binary forms, with or without
5*dbcb0e96SSean Bruno.\" modification, are permitted provided that the following conditions
6*dbcb0e96SSean Bruno.\" are met:
7*dbcb0e96SSean Bruno.\" 1. Redistributions of source code must retain the above copyright
8*dbcb0e96SSean Bruno.\"    notice, this list of conditions and the following disclaimer.
9*dbcb0e96SSean Bruno.\" 2. Redistributions in binary form must reproduce the above copyright
10*dbcb0e96SSean Bruno.\"    notice, this list of conditions and the following disclaimer in the
11*dbcb0e96SSean Bruno.\"    documentation and/or other materials provided with the distribution.
12*dbcb0e96SSean Bruno.\"
13*dbcb0e96SSean Bruno.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
14*dbcb0e96SSean Bruno.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15*dbcb0e96SSean Bruno.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16*dbcb0e96SSean Bruno.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
17*dbcb0e96SSean Bruno.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18*dbcb0e96SSean Bruno.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19*dbcb0e96SSean Bruno.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20*dbcb0e96SSean Bruno.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21*dbcb0e96SSean Bruno.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22*dbcb0e96SSean Bruno.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
23*dbcb0e96SSean Bruno.\" SUCH DAMAGE.
24*dbcb0e96SSean Bruno.\"
25*dbcb0e96SSean Bruno.\" $FreeBSD$
26*dbcb0e96SSean Bruno.\"
27*dbcb0e96SSean Bruno.Dd September 13, 2013
28*dbcb0e96SSean Bruno.Dt GPIO 4
29*dbcb0e96SSean Bruno.Os
30*dbcb0e96SSean Bruno.Sh NAME
31*dbcb0e96SSean Bruno.Nm gpiobus
32*dbcb0e96SSean Bruno.Nd GPIO bus system
33*dbcb0e96SSean Bruno.Sh SYNOPSIS
34*dbcb0e96SSean BrunoTo compile these devices into your kernel and use the device hints, place the
35*dbcb0e96SSean Brunofollowing lines in your kernel configuration file:
36*dbcb0e96SSean Bruno.Bd -ragged -offset indent
37*dbcb0e96SSean Bruno.Cd "device gpiobus"
38*dbcb0e96SSean Bruno.Cd "device gpioiic"
39*dbcb0e96SSean Bruno.Cd "device gpio"
40*dbcb0e96SSean Bruno.Cd "device gpioc"
41*dbcb0e96SSean Bruno.Cd "device gpioled"
42*dbcb0e96SSean Bruno.Ed
43*dbcb0e96SSean Bruno.Pp
44*dbcb0e96SSean BrunoAdditional device entries for the
45*dbcb0e96SSean Bruno.Li ARM
46*dbcb0e96SSean Brunoarchitecure include:
47*dbcb0e96SSean Bruno.Bd -ragged -offset indent
48*dbcb0e96SSean Bruno.Cd "device a10_gpio"
49*dbcb0e96SSean Bruno.Cd "device bcm_gpio"
50*dbcb0e96SSean Bruno.Cd "device imx51_gpio"
51*dbcb0e96SSean Bruno.Cd "device lpcgpio"
52*dbcb0e96SSean Bruno.Cd "device mv_gpio"
53*dbcb0e96SSean Bruno.Cd "device ti_gpio"
54*dbcb0e96SSean Bruno.Cd "device gpio_avila"
55*dbcb0e96SSean Bruno.Cd "device gpio_cambria"
56*dbcb0e96SSean Bruno.Cd "device zy7_gpio"
57*dbcb0e96SSean Bruno.Cd "device pxagpio"
58*dbcb0e96SSean Bruno.Ed
59*dbcb0e96SSean Bruno.Pp
60*dbcb0e96SSean BrunoAdditional device entries for the
61*dbcb0e96SSean Bruno.Li MIPS
62*dbcb0e96SSean Brunoarchitecure include:
63*dbcb0e96SSean Bruno.Bd -ragged -offset indent
64*dbcb0e96SSean Bruno.Cd "device ar71xxx_gpio"
65*dbcb0e96SSean Bruno.Cd "device octeon_gpio"
66*dbcb0e96SSean Bruno.Cd "device rt305_gpio"
67*dbcb0e96SSean Bruno.Ed
68*dbcb0e96SSean Bruno.Pp
69*dbcb0e96SSean BrunoAdditional device entries for the
70*dbcb0e96SSean Bruno.Li POWERPC
71*dbcb0e96SSean Brunoarchitecure include:
72*dbcb0e96SSean Bruno.Bd -ragged -offset indent
73*dbcb0e96SSean Bruno.Cd "device wiigpio"
74*dbcb0e96SSean Bruno.Cd "device macgpio"
75*dbcb0e96SSean Bruno.Ed
76*dbcb0e96SSean Bruno.Sh DESCRIPTION
77*dbcb0e96SSean BrunoThe
78*dbcb0e96SSean Bruno.Em gpiobus
79*dbcb0e96SSean Brunosystem provides a simple interface to the bit banging style GPIO bus
80*dbcb0e96SSean Brunofound on embedded architectures.
81*dbcb0e96SSean Bruno.Pp
82*dbcb0e96SSean BrunoThe acronym
83*dbcb0e96SSean Bruno.Li GPIO
84*dbcb0e96SSean Brunomeans
85*dbcb0e96SSean Bruno.Dq General-Purpose Input/Output.
86*dbcb0e96SSean Bruno.Pp
87*dbcb0e96SSean BrunoThe BUS physically consists of multiple pins that can be configured
88*dbcb0e96SSean Brunofor input/output, IRQ delivery, SDA/SCL
89*dbcb0e96SSean Bruno.Em iicbus
90*dbcb0e96SSean Brunouse, etc.
91*dbcb0e96SSean BrunoOn most embedded architechtures (mips/arm), discovery of the bus and
92*dbcb0e96SSean Brunoconfiguration of the pins is done via
93*dbcb0e96SSean Bruno.Xr device.hints 5
94*dbcb0e96SSean Brunoin the platform's kernel
95*dbcb0e96SSean Bruno.Xr config 5
96*dbcb0e96SSean Brunofile.
97*dbcb0e96SSean Bruno.Pp
98*dbcb0e96SSean BrunoAssignment of
99*dbcb0e96SSean Bruno.Xr gpioiic 4
100*dbcb0e96SSean Brunobus variables is done via:
101*dbcb0e96SSean Bruno.Bl -tag -width ".Va hint.gpioiic.%d.atXXX"
102*dbcb0e96SSean Bruno.It Va hint.gpioiic.%d.at
103*dbcb0e96SSean BrunoNormally just gpiobus0.
104*dbcb0e96SSean Bruno.It Va hint.gpioiic.%d.pins
105*dbcb0e96SSean BrunoThis is a bitmask of the pins on the gpio board that are to be used for
106*dbcb0e96SSean BrunoSCLOCK and SDATA from the IIC bus.
107*dbcb0e96SSean BrunoTo configure pin 0 and 7, use the bitmask of
108*dbcb0e96SSean Bruno10000001 and convert it to a hexadecimal value of 0x0081.
109*dbcb0e96SSean BrunoShould only ever have two bits set in mask.
110*dbcb0e96SSean Bruno.It Va hint.gpioiic.%d.scl
111*dbcb0e96SSean BrunoIndicates which bit in the
112*dbcb0e96SSean Bruno.Va hint.gpioiic.%d.pins
113*dbcb0e96SSean Brunoshould be used as the SCLOCK
114*dbcb0e96SSean Brunosource.
115*dbcb0e96SSean Bruno.It Va hint.gpioiic.%d.sda
116*dbcb0e96SSean BrunoIndicates which bit in the
117*dbcb0e96SSean Bruno.Va hint.gpioiic.%d.pins
118*dbcb0e96SSean Brunoshould be used as the SDATA
119*dbcb0e96SSean Brunosource.
120*dbcb0e96SSean Bruno.El
121*dbcb0e96SSean Bruno.Pp
122*dbcb0e96SSean BrunoThe following are only provided by the
123*dbcb0e96SSean Bruno.Cd ar71xx_gpio
124*dbcb0e96SSean Brunodriver.
125*dbcb0e96SSean Bruno.Bl -tag -width ".Va hint.gpioiic.%d.atXXX"
126*dbcb0e96SSean Bruno.It Va hint.gpio.%d.pinmask
127*dbcb0e96SSean BrunoThis is a bitmask of pins on the gpio board that we would like to expose
128*dbcb0e96SSean Brunofor use to the host o/s.
129*dbcb0e96SSean BrunoTo expose pin 0, 4 and 7, use the bitmask of
130*dbcb0e96SSean Bruno10010001 converted to the hexadecimal value 0x0091.
131*dbcb0e96SSean Bruno.It Va hint.gpio.%d.pinon
132*dbcb0e96SSean BrunoThis is a bitmask of pins on the gpio board that will be set to ON at host
133*dbcb0e96SSean Brunostart.
134*dbcb0e96SSean BrunoTo set pin 2, 5 and 13 to be set ON at boot, use the bitmask of
135*dbcb0e96SSean Bruno10000000010010 converted to the hexadecimal value 0x2022.
136*dbcb0e96SSean Bruno.It Va hint.gpio.function_set
137*dbcb0e96SSean Bruno.It Va hint.gpio.function_clear
138*dbcb0e96SSean BrunoThese are a bitmask of pins that will remap a pin to handle a specific
139*dbcb0e96SSean Brunofunction (USB, UART TX/RX, etc) in the Atheros function registers.
140*dbcb0e96SSean BrunoThis is mainly used to set/clear functions that we need when they are setup or
141*dbcb0e96SSean Brunonot setup by uBoot.
142*dbcb0e96SSean Bruno.El
143*dbcb0e96SSean Bruno.Pp
144*dbcb0e96SSean BrunoThese values are configureable from the
145*dbcb0e96SSean Bruno.Xr gpioled 4
146*dbcb0e96SSean Brunointerface and help create
147*dbcb0e96SSean Bruno.Xr led 4
148*dbcb0e96SSean Brunocompatible devices in
149*dbcb0e96SSean Bruno.Pa /dev/led/<name> .
150*dbcb0e96SSean Bruno.Bl -tag -width ".Va hint.gpioiic.%d.atXXX"
151*dbcb0e96SSean Bruno.It Va hint.gpioled.%d.at
152*dbcb0e96SSean BrunoNormally assigned to gpiobus0.
153*dbcb0e96SSean Bruno.It Va hint.gpioled.%d.name
154*dbcb0e96SSean BrunoArbitrary name of device in
155*dbcb0e96SSean Bruno.Pa /dev/led/
156*dbcb0e96SSean Brunoto create for
157*dbcb0e96SSean Bruno.Xr led 4
158*dbcb0e96SSean Brunointerfaces.
159*dbcb0e96SSean Bruno.It Va hint.gpioled.%d.pins
160*dbcb0e96SSean BrunoWhich pin on the GPIO interface to map to this instance.
161*dbcb0e96SSean Bruno.El
162*dbcb0e96SSean Bruno.Pp
163*dbcb0e96SSean BrunoSimply put, each pin of the GPIO interface is connected to an input/output
164*dbcb0e96SSean Brunoof some device in a system.
165*dbcb0e96SSean Bruno.Sh SEE ALSO
166*dbcb0e96SSean Bruno.Xr iicbus 4 ,
167*dbcb0e96SSean Bruno.Xr gpioctl 8
168*dbcb0e96SSean Bruno.Sh HISTORY
169*dbcb0e96SSean BrunoThe
170*dbcb0e96SSean Bruno.Nm
171*dbcb0e96SSean Brunomanual page first appeared in
172*dbcb0e96SSean Bruno.Fx 10.0 .
173*dbcb0e96SSean Bruno.Sh AUTHORS
174*dbcb0e96SSean BrunoThis
175*dbcb0e96SSean Brunomanual page was written by
176*dbcb0e96SSean Bruno.An Sean Bruno Aq sbruno@FreeBSD.org .
177