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