From 8ce07fe72eb5ca0925f192cb74ff8097a81f68c2 Mon Sep 17 00:00:00 2001 From: Luiz Otavio O Souza Date: Tue, 12 Nov 2013 12:44:59 +0000 Subject: [PATCH] Adds gpioiic.4 and gpioled.4 man pages. Moves some of the information that was previously available on gpio.4 to their respectives pages. Add the cross references on gpioctl.8. Approved by: adrian (mentor) --- share/man/man4/gpio.4 | 63 ++++++------------------- share/man/man4/gpioiic.4 | 96 ++++++++++++++++++++++++++++++++++++++ share/man/man4/gpioled.4 | 83 ++++++++++++++++++++++++++++++++ usr.sbin/gpioctl/gpioctl.8 | 4 +- 4 files changed, 197 insertions(+), 49 deletions(-) create mode 100644 share/man/man4/gpioiic.4 create mode 100644 share/man/man4/gpioled.4 diff --git a/share/man/man4/gpio.4 b/share/man/man4/gpio.4 index 614a722c4d22..f0bd8a34b20b 100644 --- a/share/man/man4/gpio.4 +++ b/share/man/man4/gpio.4 @@ -24,7 +24,7 @@ .\" .\" $FreeBSD$ .\" -.Dd September 13, 2013 +.Dd November 5, 2013 .Dt GPIO 4 .Os .Sh NAME @@ -34,10 +34,9 @@ To compile these devices into your kernel and use the device hints, place the following lines in your kernel configuration file: .Bd -ragged -offset indent -.Cd "device gpiobus" -.Cd "device gpioiic" .Cd "device gpio" .Cd "device gpioc" +.Cd "device gpioiic" .Cd "device gpioled" .Ed .Pp @@ -76,8 +75,9 @@ architecure include: .Sh DESCRIPTION The .Em gpiobus -system provides a simple interface to the bit banging style GPIO bus -found on embedded architectures. +system provides a simple interface to the GPIO pins that are usually +available on embedded architectures and can provide bit banging style +devices to the system. .Pp The acronym .Li GPIO @@ -88,36 +88,20 @@ The BUS physically consists of multiple pins that can be configured for input/output, IRQ delivery, SDA/SCL .Em iicbus use, etc. -On most embedded architechtures (mips/arm), discovery of the bus and +.Pp +On some embedded architechtures (like MIPS), discovery of the bus and configuration of the pins is done via .Xr device.hints 5 in the platform's kernel .Xr config 5 file. .Pp -Assignment of -.Xr gpioiic 4 -bus variables is done via: -.Bl -tag -width ".Va hint.gpioiic.%d.atXXX" -.It Va hint.gpioiic.%d.at -Normally just gpiobus0. -.It Va hint.gpioiic.%d.pins -This is a bitmask of the pins on the gpio board that are to be used for -SCLOCK and SDATA from the IIC bus. -To configure pin 0 and 7, use the bitmask of -10000001 and convert it to a hexadecimal value of 0x0081. -Should only ever have two bits set in mask. -.It Va hint.gpioiic.%d.scl -Indicates which bit in the -.Va hint.gpioiic.%d.pins -should be used as the SCLOCK -source. -.It Va hint.gpioiic.%d.sda -Indicates which bit in the -.Va hint.gpioiic.%d.pins -should be used as the SDATA -source. -.El +On some others (like ARM), where +.Xr FDT 4 +is used to describe the device tree, the bus discovery is done via the DTS +passed to the kernel, being either statically compiled in, or by a variety +of ways where the boot loader (or Open Firmware enabled system) passes the +DTS blob to kernel at boot. .Pp The following are only provided by the .Cd ar71xx_gpio @@ -141,28 +125,11 @@ This is mainly used to set/clear functions that we need when they are setup or not setup by uBoot. .El .Pp -These values are configureable from the -.Xr gpioled 4 -interface and help create -.Xr led 4 -compatible devices in -.Pa /dev/led/ . -.Bl -tag -width ".Va hint.gpioiic.%d.atXXX" -.It Va hint.gpioled.%d.at -Normally assigned to gpiobus0. -.It Va hint.gpioled.%d.name -Arbitrary name of device in -.Pa /dev/led/ -to create for -.Xr led 4 -interfaces. -.It Va hint.gpioled.%d.pins -Which pin on the GPIO interface to map to this instance. -.El -.Pp Simply put, each pin of the GPIO interface is connected to an input/output of some device in a system. .Sh SEE ALSO +.Xr gpioiic 4 , +.Xr gpioled 4 , .Xr iicbus 4 , .Xr gpioctl 8 .Sh HISTORY diff --git a/share/man/man4/gpioiic.4 b/share/man/man4/gpioiic.4 new file mode 100644 index 000000000000..cbcaec9ccc1d --- /dev/null +++ b/share/man/man4/gpioiic.4 @@ -0,0 +1,96 @@ +.\" Copyright (c) 2013, Luiz Otavio O Souza +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd November 5, 2013 +.Dt GPIOIIC 4 +.Os +.Sh NAME +.Nm gpioiic +.Nd GPIO I2C bit-banging device driver +.Sh SYNOPSIS +.Cd "device gpio" +.Cd "device gpioiic" +.Cd "device iic" +.Cd "device iicbb" +.Cd "device iicbus" +.Sh DESCRIPTION +The +.Em gpioiic +driver provides an IIC bit-banging interface using two GPIO pins for the +SCL and SDA on the +.Em gpiobus . +.Nm +implements an open colector kind of output, as recommended by the standard, +when driving the pins on the +.Em gpiobus , +i.e, they are never switched to the logical value of '1', +or they are '0' or simply open (Hi-Z/tri-state). +So the pullup resistors are required so +.Nm +can work. +.Pp +On a hint based system, like +.Li MIPS , these values are configureable for the +.Nm gpioiic : +.Bl -tag -width ".Va hint.gpioiic.%d.atXXX" +.It Va hint.gpioiic.%d.at +The gpiobus you are attaching to. +Normally just gpiobus0. +.It Va hint.gpioiic.%d.pins +This is a bitmask of the pins on the +.Em gpiobus +that are to be used for SCLOCK and SDATA from the GPIO IIC +bit-banging bus. +To configure pin 0 and 7, use the bitmask of +10000001 and convert it to a hexadecimal value of 0x0081. +Please note that this mask should only ever have two bits set +(any others bits - i.e., pins - will be ignored). +.It Va hint.gpioiic.%d.scl +Indicates which bit in the +.Va hint.gpioiic.%d.pins +should be used as the SCLOCK +source. +.It Va hint.gpioiic.%d.sda +Indicates which bit in the +.Va hint.gpioiic.%d.pins +should be used as the SDATA +source. +.El +.Sh SEE ALSO +.Xr gpio 4 , +.Xr gpioled 4 , +.Xr iic 4 , +.Xr iicbb 4 , +.Xr iicbus 4 +.Sh HISTORY +The +.Nm +manual page first appeared in +.Fx 11.0 . +.Sh AUTHORS +This +manual page was written by +.An Luiz Otavio O Souza . diff --git a/share/man/man4/gpioled.4 b/share/man/man4/gpioled.4 new file mode 100644 index 000000000000..76f59fa88240 --- /dev/null +++ b/share/man/man4/gpioled.4 @@ -0,0 +1,83 @@ +.\" Copyright (c) 2013, Luiz Otavio O Souza +.\" All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" $FreeBSD$ +.\" +.Dd November 5, 2013 +.Dt GPIOLED 4 +.Os +.Sh NAME +.Nm gpioled +.Nd GPIO led generic device driver +.Sh SYNOPSIS +.Cd "device gpio" +.Cd "device gpioled" +.Pp +This driver attaches a +.Xr led 4 +device to a GPIO pin. +.Sh DESCRIPTION +The +.Em gpioled +driver provides a glue to attach a +.Xr led 4 +compatible device to a GPIO pin. +Each led on the system has a +.Pa name +which is used to export a device in +.Pa /dev/led/ . +The GPIO pin can then be controlled by writing to this device as described +on +.Xr led 4 . +.Pp +On a hint based system, like +.Li MIPS , these values are configureable for +.Nm : +.Bl -tag -width ".Va hint.gpioiic.%d.atXXX" +.It Va hint.gpioled.%d.at +The gpiobus you are attaching to. +Normally assigned to gpiobus0. +.It Va hint.gpioled.%d.name +Arbitrary name of device in +.Pa /dev/led/ +to create for +.Xr led 4 . +.It Va hint.gpioled.%d.pins +Which pin on the GPIO interface to map to this instance. +Please note that this mask should only ever have one bit set +(any others bits - i.e., pins - will be ignored). +.El +.Sh SEE ALSO +.Xr gpio 4 , +.Xr led 4 , +.Xr gpioiic 4 +.Sh HISTORY +The +.Nm +manual page first appeared in +.Fx 11.0 . +.Sh AUTHORS +This +manual page was written by +.An Luiz Otavio O Souza . diff --git a/usr.sbin/gpioctl/gpioctl.8 b/usr.sbin/gpioctl/gpioctl.8 index c1abb5e399f4..4db6714f5bdc 100644 --- a/usr.sbin/gpioctl/gpioctl.8 +++ b/usr.sbin/gpioctl/gpioctl.8 @@ -27,7 +27,7 @@ .\" .\" $FreeBSD$ .\" -.Dd August 13, 2013 +.Dd November 7, 2013 .Dt GPIOCTL 1 .Os .Sh NAME @@ -109,6 +109,8 @@ gpioctl -f /dev/gpioc0 -c 12 IN .El .Sh SEE ALSO .Xr gpio 4 +.Xr gpioiic 4 +.Xr gpioled 4 .Sh HISTORY The .Nm