1.\" Copyright (c) 2013, Luiz Otavio O Souza <loos@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.Dd December 1, 2019 26.Dt GPIOIIC 4 27.Os 28.Sh NAME 29.Nm gpioiic 30.Nd GPIO I2C bit-banging device driver 31.Sh SYNOPSIS 32To compile this driver into the kernel, 33place the following lines in your 34kernel configuration file: 35.Bd -ragged -offset indent 36.Cd "device gpio" 37.Cd "device gpioiic" 38.Cd "device iicbb" 39.Cd "device iicbus" 40.Ed 41.Pp 42Alternatively, to load the driver as a 43module at boot time, place the following line in 44.Xr loader.conf 5 : 45.Bd -literal -offset indent 46gpioiic_load="YES" 47.Ed 48.Sh DESCRIPTION 49The 50.Nm 51driver provides an IIC bit-banging interface using two GPIO pins for the 52SCL and SDA lines on the bus. 53.Pp 54.Nm 55simulates an open collector kind of output when managing the pins on the 56bus, even on systems which don't directly support configuring gpio pins 57in that mode. 58The pins are never driven to the logical value of '1'. 59They are driven to '0' or switched to input mode (Hi-Z/tri-state), and 60an external pullup resistor pulls the line to the 1 state unless some 61other device on the bus is driving it to 0. 62.Sh HINTS CONFIGURATION 63On a 64.Xr device.hints 5 65based system, such as MIPS, these values are configurable for 66.Nm : 67.Bl -tag -width ".Va hint.gpioiic.%d.atXXX" 68.It Va hint.gpioiic.%d.at 69The 70.Nm gpiobus 71you are attaching to. 72Normally just gpiobus0 on systems with a single bank of gpio pins. 73.It Va hint.gpioiic.%d.pins 74This is a bitmask of the pins on the 75.Nm gpiobus 76that are to be used for SCLOCK and SDATA from the GPIO IIC 77bit-banging bus. 78To configure pin 0 and 7, use the bitmask of 790b10000001 and convert it to a hexadecimal value of 0x0081. 80Please note that this mask should only ever have two bits set 81(any other bits - i.e., pins - will be ignored). 82Because 83.Nm 84must be a child of the gpiobus, both gpio pins must be part of that bus. 85.It Va hint.gpioiic.%d.scl 86Indicates which bit in the 87.Va hint.gpioiic.%d.pins 88should be used as the SCLOCK 89source. 90Optional, defaults to 0. 91.It Va hint.gpioiic.%d.sda 92Indicates which bit in the 93.Va hint.gpioiic.%d.pins 94should be used as the SDATA 95source. 96Optional, defaults to 1. 97.El 98.Sh FDT CONFIGURATION 99On an 100.Xr FDT 4 101based system, such as ARM, the DTS node for 102.Nm gpioiic 103conforms to the standard bindings document i2c/i2c-gpio.yaml. 104The device node typically appears at the root of the device tree. 105The following is an example of a 106.Nm 107node with one slave device 108on the IIC bus: 109.Bd -literal 110/ { 111 gpioiic0 { 112 compatible = "i2c-gpio"; 113 pinctrl-names = "default"; 114 pinctrl-0 = <&pinctrl_gpioiic0>; 115 scl-gpios = <&gpio1 5 GPIO_ACTIVE_HIGH>; 116 sda-gpios = <&gpio7 11 GPIO_ACTIVE_HIGH>; 117 status = "okay"; 118 119 /* One slave device on the i2c bus. */ 120 rtc@51 { 121 compatible="nxp,pcf2127"; 122 reg = <0x51>; 123 status = "okay"; 124 }; 125 }; 126}; 127.Ed 128.Pp 129Where: 130.Bl -tag -width ".Va compatible" 131.It Va compatible 132Should be set to "i2c-gpio". 133The deprecated string "gpioiic" is also accepted for backwards compatibility. 134.It Va scl-gpios Va sda-gpios 135These properties indicate which GPIO pins should be used for clock 136and data on the GPIO IIC bit-banging bus. 137There is no requirement that the two pins belong to the same gpio controller. 138.It Va pinctrl-names pinctrl-0 139These properties may be required to configure the chosen pins as gpio 140pins, unless the pins default to that state on your system. 141.El 142.Sh SEE ALSO 143.Xr fdt 4 , 144.Xr gpio 4 , 145.Xr iic 4 , 146.Xr iicbb 4 , 147.Xr iicbus 4 148.Sh HISTORY 149The 150.Nm 151manual page first appeared in 152.Fx 10.1 . 153.Sh AUTHORS 154This 155manual page was written by 156.An Luiz Otavio O Souza . 157