.\" Copyright (c) 2013, Luiz Otavio O Souza <loos@FreeBSD.org>
.\" 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: head/share/man/man4/gpioiic.4 266092 2014-05-14 21:54:14Z loos $
.\"
.Dd May 14, 2014
.Dt GPIOIIC 4
.Os
.Sh NAME
.Nm gpioiic
.Nd GPIO I2C bit-banging device driver
.Sh SYNOPSIS
To compile this driver into the kernel,
place the following lines in your
kernel configuration file:
.Bd -ragged -offset indent
.Cd "device gpio"
.Cd "device gpioiic"
.Cd "device iic"
.Cd "device iicbb"
.Cd "device iicbus"
.Ed
.Sh DESCRIPTION
The
.Nm
driver provides an IIC bit-banging interface using two GPIO pins for the
SCL and SDA on the
.Nm gpiobus .
.Nm
implements an open collector kind of output, as recommended by the standard,
when driving the pins on the
.Nm 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
.Xr device.hints 5
based system, like
.Li MIPS ,
these values are configurable for the
.Nm :
.Bl -tag -width ".Va hint.gpioiic.%d.atXXX"
.It Va hint.gpioiic.%d.at
The
.Nm gpiobus
you are attaching to.
Normally just gpiobus0.
.It Va hint.gpioiic.%d.pins
This is a bitmask of the pins on the
.Nm 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
0b10000001 and convert it to a hexadecimal value of 0x0081.
Please note that this mask should only ever have two bits set
(any other 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.
Optional, defaults to 0.
.It Va hint.gpioiic.%d.sda
Indicates which bit in the
.Va hint.gpioiic.%d.pins
should be used as the SDATA
source.
Optional, defaults to 1.
.El
.Pp
On a
.Xr FDT 4
based system, like
.Li ARM ,
the DTS part for a
.Nm gpioiic
device usually looks like:
.Bd -literal
gpio: gpio {

	gpio-controller;
	...

	gpioiic0 {
		compatible = "gpioiic";
		/*
		 * Attach to GPIO pins 21 and 22.  Set them
		 * initially as inputs.
		 */
		gpios = <&gpio 21 1 0
			 &gpio 22 1 0>;
		scl = <0>;		/* GPIO pin 21 - optional */
		sda = <1>;		/* GPIO pin 22 - optional */

		/* This is an example of a gpioiic child. */
		gpioiic-child0 {
			compatible = "lm75";
			i2c-address = <0x4f>;
		};
	};
};
.Ed
.Pp
Where:
.Bl -tag -width ".Va compatible"
.It Va compatible
Should always be set to "gpioiic".
.It Va gpios
The
.Va gpios
property indicates which GPIO pins should be used for SCLOCK and SDATA
on the GPIO IIC bit-banging bus.
For more details about the
.Va gpios
property, please consult
.Pa /usr/src/sys/boot/fdt/dts/bindings-gpio.txt .
.It Va scl
The
.Va scl
option indicates which bit in the
.Va gpios
should be used as the SCLOCK source.
Optional, defaults to 0.
.It Va sda
The
.Va sda
option indicates which bit in the
.Va gpios
should be used as the SDATA source.
Optional, defaults to 1.
.El
.Sh SEE ALSO
.Xr fdt 4 ,
.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 10.1 .
.Sh AUTHORS
This
manual page was written by
.An Luiz Otavio O Souza .