xref: /freebsd/share/man/man4/gpioiic.4 (revision fa9896e082a1046ff4fbc75fcba4d18d1f2efc19)

.\" 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.
.\"
.Dd December 1, 2019
.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 iicbb"
.Cd "device iicbus"
.Ed
.Pp
Alternatively, to load the driver as a
module at boot time, place the following line in
.Xr loader.conf 5 :
.Bd -literal -offset indent
gpioiic_load="YES"
.Ed
.Sh DESCRIPTION
The
.Nm
driver provides an IIC bit-banging interface using two GPIO pins for the
SCL and SDA lines on the bus.
.Pp
.Nm
simulates an open collector kind of output when managing the pins on the
bus, even on systems which don't directly support configuring gpio pins
in that mode.
The pins are never driven to the logical value of '1'.
They are driven to '0' or switched to input mode (Hi-Z/tri-state), and
an external pullup resistor pulls the line to the 1 state unless some
other device on the bus is driving it to 0.
.Sh HINTS CONFIGURATION
On a
.Xr device.hints 5
based system, such as MIPS, these values are configurable for
.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 on systems with a single bank of gpio pins.
.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).
Because
.Nm
must be a child of the gpiobus, both gpio pins must be part of that bus.
.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
.Sh FDT CONFIGURATION
On an
.Xr FDT 4
based system, such as ARM, the DTS node for
.Nm gpioiic
conforms to the standard bindings document i2c/i2c-gpio.yaml.
The device node typically appears at the root of the device tree.
The following is an example of a
.Nm
node with one slave device
on the IIC bus:
.Bd -literal
/ {
	gpioiic0 {
		compatible = "i2c-gpio";
		pinctrl-names = "default";
		pinctrl-0 = <&pinctrl_gpioiic0>;
		scl-gpios = <&gpio1  5 GPIO_ACTIVE_HIGH>;
		sda-gpios = <&gpio7 11 GPIO_ACTIVE_HIGH>;
		status = "okay";

		/* One slave device on the i2c bus. */
		rtc@51 {
			compatible="nxp,pcf2127";
			reg = <0x51>;
			status = "okay";
		};
	};
};
.Ed
.Pp
Where:
.Bl -tag -width ".Va compatible"
.It Va compatible
Should be set to "i2c-gpio".
The deprecated string "gpioiic" is also accepted for backwards compatibility.
.It Va scl-gpios Va sda-gpios
These properties indicate which GPIO pins should be used for clock
and data on the GPIO IIC bit-banging bus.
There is no requirement that the two pins belong to the same gpio controller.
.It Va pinctrl-names pinctrl-0
These properties may be required to configure the chosen pins as gpio
pins, unless the pins default to that state on your system.
.El
.Sh SEE ALSO
.Xr fdt 4 ,
.Xr gpio 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 .