path: root/sys/sys/gpio.h
diff options
authorIan Lepore <ian@FreeBSD.org>2017-09-10 18:08:25 +0000
committerIan Lepore <ian@FreeBSD.org>2017-09-10 18:08:25 +0000
commite1275c6805dbbe2d5f63b72c39d01559c303fe92 (patch)
tree1d369ced9110c1c2030c47767c02013d84fdb385 /sys/sys/gpio.h
parentd027ed2e7ab4cda7be4c502efc466bffea027bf8 (diff)
Add gpio methods to read/write/configure up to 32 pins simultaneously.
Sometimes it is necessary to combine several gpio pins into an ad-hoc bus and manipulate the pins as a group. In such cases manipulating the pins individualy is not an option, because the value on the "bus" assumes potentially-invalid intermediate values as each pin is changed in turn. Note that the "bus" may be something as simple as a bi-color LED where changing colors requires changing both gpio pins at once, or something as complex as a bitbanged multiplexed address/data bus connected to a microcontroller. In addition to the absolute requirement of simultaneously changing the output values of driven pins, a desirable feature of these new methods is to provide a higher-performance mechanism for reading and writing multiple pins, especially from userland where pin-at-a-time access incurs a noticible syscall time penalty. These new interfaces are NOT intended to abstract away all the ugly details of how gpio is implemented on any given platform. In fact, to use these properly you absolutely must know something about how the gpio hardware is organized. Typically there are "banks" of gpio pins controlled by registers which group several pins together. A bank may be as small as 2 pins or as big as "all the pins on the device, hundreds of them." In the latter case, a driver might support this interface by allowing access to any 32 adjacent pins within the overall collection. Or, more likely, any 32 adjacent pins starting at any multiple of 32. Whatever the hardware restrictions may be, you would need to understand them to use this interface. In additional to defining the interfaces, two example implementations are included here, for imx5/6, and allwinner. These represent the two primary types of gpio hardware drivers. imx6 has multiple gpio devices, each implementing a single bank of 32 pins. Allwinner implements a single large gpio number space from 1-n pins, and the driver internally translates that linear number space to a bank+pin scheme based on how the pins are grouped into control registers. The allwinner implementation imposes the restriction that the first_pin argument to the new functions must always be pin 0 of a bank. Differential Revision: https://reviews.freebsd.org/D11810
Notes: svn path=/head/; revision=323392
Diffstat (limited to 'sys/sys/gpio.h')
1 files changed, 69 insertions, 0 deletions
diff --git a/sys/sys/gpio.h b/sys/sys/gpio.h
index 9b0a1b554984..dbe55872fe03 100644
--- a/sys/sys/gpio.h
+++ b/sys/sys/gpio.h
@@ -70,6 +70,8 @@
#define GPIO_PIN_INVIN 0x00000080 /* invert input */
#define GPIO_PIN_INVOUT 0x00000100 /* invert output */
#define GPIO_PIN_PULSATE 0x00000200 /* pulsate in hardware */
+#define GPIO_PIN_PRESET_LOW 0x00000400 /* preset pin to high or */
+#define GPIO_PIN_PRESET_HIGH 0x00000800 /* low before enabling output */
/* GPIO interrupt capabilities */
#define GPIO_INTR_NONE 0x00000000 /* no interrupt support */
#define GPIO_INTR_LEVEL_LOW 0x00010000 /* level trigger, low */
@@ -95,6 +97,71 @@ struct gpio_req {
+ * gpio_access_32 / GPIOACCESS32
+ *
+ * Simultaneously read and/or change up to 32 adjacent pins.
+ * If the device cannot change the pins simultaneously, returns EOPNOTSUPP.
+ *
+ * This accesses an adjacent set of up to 32 pins starting at first_pin within
+ * the device's collection of pins. How the hardware pins are mapped to the 32
+ * bits in the arguments is device-specific. It is expected that lower-numbered
+ * pins in the device's number space map linearly to lower-ordered bits within
+ * the 32-bit words (i.e., bit 0 is first_pin, bit 1 is first_pin+1, etc).
+ * Other mappings are possible; know your device.
+ *
+ * Some devices may limit the value of first_pin to 0, or to multiples of 16 or
+ * 32 or some other hardware-specific number; to access pin 2 would require
+ * first_pin to be zero and then manipulate bit (1 << 2) in the 32-bit word.
+ * Invalid values in first_pin result in an EINVAL error return.
+ *
+ * The starting state of the pins is captured and stored in orig_pins, then the
+ * pins are set to ((starting_state & ~clear_pins) ^ change_pins).
+ *
+ * Clear Change Hardware pin after call
+ * 0 0 No change
+ * 0 1 Opposite of current value
+ * 1 0 Cleared
+ * 1 1 Set
+ */
+struct gpio_access_32 {
+ uint32_t first_pin; /* First pin in group of 32 adjacent */
+ uint32_t clear_pins; /* Pins are changed using: */
+ uint32_t change_pins; /* ((hwstate & ~clear_pins) ^ change_pins) */
+ uint32_t orig_pins; /* Returned hwstate of pins before change. */
+ * gpio_config_32 / GPIOCONFIG32
+ *
+ * Simultaneously configure up to 32 adjacent pins. This is intended to change
+ * the configuration of all the pins simultaneously, such that pins configured
+ * for output all begin to drive the configured values simultaneously, but not
+ * all hardware can do that, so the driver "does the best it can" in this
+ * regard. Notably unlike pin_access_32(), this does NOT fail if the pins
+ * cannot be atomically configured; it is expected that callers understand the
+ * hardware and have decided to live with any such limitations it may have.
+ *
+ * The pin_flags argument is an array of GPIO_PIN_xxxx flags. If the array
+ * contains any GPIO_PIN_OUTPUT flags, the driver will manipulate the hardware
+ * such that all output pins become driven with the proper initial values
+ * simultaneously if it can. The elements in the array map to pins in the same
+ * way that bits are mapped by pin_acces_32(), and the same restrictions may
+ * apply. For example, to configure pins 2 and 3 it may be necessary to set
+ * first_pin to zero and only populate pin_flags[2] and pin_flags[3]. If a
+ * given array entry doesn't contain GPIO_PIN_INPUT or GPIO_PIN_OUTPUT then no
+ * configuration is done for that pin.
+ *
+ * Some devices may limit the value of first_pin to 0, or to multiples of 16 or
+ * 32 or some other hardware-specific number. Invalid values in first_pin or
+ * num_pins result in an error return with errno set to EINVAL.
+ */
+struct gpio_config_32 {
+ uint32_t first_pin;
+ uint32_t num_pins;
+ uint32_t pin_flags[32];
* ioctls
#define GPIOMAXPIN _IOR('G', 0, int)
@@ -104,5 +171,7 @@ struct gpio_req {
#define GPIOSET _IOW('G', 4, struct gpio_req)
#define GPIOTOGGLE _IOWR('G', 5, struct gpio_req)
#define GPIOSETNAME _IOW('G', 6, struct gpio_pin)
+#define GPIOACCESS32 _IOWR('G', 7, struct gpio_access_32)
+#define GPIOCONFIG32 _IOW('G', 8, struct gpio_config_32)
#endif /* __GPIO_H__ */