Rewrite gpioiic(4) to use the gpio_pin_* API, and to conform to the modern

FDT bindings document for gpio-i2c devices.

Using the gpio_pin_* functions to acquire/release/manipulate gpio pins
removes the constraint that both gpio pins must belong to the same gpio
controller/bank, and that the gpioiic instance must be a child of gpiobus.
Removing those constraints allows the driver to be fully compatible with
the modern dts bindings for a gpio bitbanged i2c bus.

For hinted attachment, the two gpio pins still must be on the same gpiobus,
and the device instance must be a child of that bus.  This preserves
compatibility for existing installations that have use gpioiic(4) with hints.

1 files changed, 53 insertions, 65 deletions

diff --git a/share/man/man4/gpioiic.4 b/share/man/man4/gpioiic.4
index ff3b9210eb3f..0a15ee85f9a0 100644
--- a/share/man/man4/gpioiic.4
+++ b/share/man/man4/gpioiic.4
@@ -24,7 +24,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd May 14, 2014
+.Dd December 1, 2019
 .Dt GPIOIIC 4
 .Os
 .Sh NAME
@@ -37,38 +37,42 @@ kernel configuration file:
 .Bd -ragged -offset indent
 .Cd "device gpio"
 .Cd "device gpioiic"
-.Cd "device iic"
 .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 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
+SCL and SDA lines on the bus.
+.Pp
 .Nm
-can work.
+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.
 .Pp
+.Sh HINTS CONFIGURATION
 On a
 .Xr device.hints 5
-based system, like
-.Li MIPS ,
-these values are configurable for the
+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.
+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
@@ -78,6 +82,9 @@ 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
@@ -91,35 +98,32 @@ should be used as the SDATA
 source.
 Optional, defaults to 1.
 .El
-.Pp
-On a
+.Sh FDT CONFIGURATION
+On an
 .Xr FDT 4
-based system, like
-.Li ARM ,
-the DTS part for a
+based system, such as ARM, the DTS node for
 .Nm gpioiic
-device usually looks like:
+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
-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 */
+		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";
 
-		/* This is an example of a gpioiic child. */
-		gpioiic-child0 {
-			compatible = "lm75";
-			i2c-address = <0x4f>;
+		/* One slave device on the i2c bus. */
+		rtc@51 {
+			compatible="nxp,pcf2127";
+			reg = <0x51>;
+			status = "okay";
 		};
 	};
 };
@@ -128,35 +132,19 @@ gpio: gpio {
 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/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.
+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 gpioled 4 ,
 .Xr iic 4 ,
 .Xr iicbb 4 ,
 .Xr iicbus 4