1 /* $NetBSD: gpio.h,v 1.7 2009/09/25 20:27:50 mbalmer Exp $ */ 2 /* $OpenBSD: gpio.h,v 1.7 2008/11/26 14:51:20 mbalmer Exp $ */ 3 /*- 4 * SPDX-License-Identifier: (BSD-2-Clause AND ISC) 5 * 6 * Copyright (c) 2009, Oleksandr Tymoshenko <gonzo@FreeBSD.org> 7 * All rights reserved. 8 * 9 * Redistribution and use in source and binary forms, with or without 10 * modification, are permitted provided that the following conditions 11 * are met: 12 * 1. Redistributions of source code must retain the above copyright 13 * notice unmodified, this list of conditions, and the following 14 * disclaimer. 15 * 2. Redistributions in binary form must reproduce the above copyright 16 * notice, this list of conditions and the following disclaimer in the 17 * documentation and/or other materials provided with the distribution. 18 * 19 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 20 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 21 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 22 * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 23 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 24 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 25 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 26 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 27 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 28 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 29 * SUCH DAMAGE. 30 * 31 * $FreeBSD$ 32 * 33 */ 34 35 /* 36 * Copyright (c) 2009 Marc Balmer <marc@msys.ch> 37 * Copyright (c) 2004 Alexander Yurchenko <grange@openbsd.org> 38 * 39 * Permission to use, copy, modify, and distribute this software for any 40 * purpose with or without fee is hereby granted, provided that the above 41 * copyright notice and this permission notice appear in all copies. 42 * 43 * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 44 * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 45 * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 46 * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 47 * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 48 * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 49 * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 50 */ 51 52 #ifndef __GPIO_H__ 53 #define __GPIO_H__ 54 55 #include <sys/ioccom.h> 56 #if !defined(_KERNEL) && !defined(_STANDALONE) 57 #include <stdbool.h> 58 #endif 59 60 /* GPIO pin states */ 61 #define GPIO_PIN_LOW 0x00 /* low level (logical 0) */ 62 #define GPIO_PIN_HIGH 0x01 /* high level (logical 1) */ 63 64 /* Max name length of a pin */ 65 #define GPIOMAXNAME 64 66 67 /* GPIO pin configuration flags */ 68 #define GPIO_PIN_INPUT 0x00000001 /* input direction */ 69 #define GPIO_PIN_OUTPUT 0x00000002 /* output direction */ 70 #define GPIO_PIN_OPENDRAIN 0x00000004 /* open-drain output */ 71 #define GPIO_PIN_PUSHPULL 0x00000008 /* push-pull output */ 72 #define GPIO_PIN_TRISTATE 0x00000010 /* output disabled */ 73 #define GPIO_PIN_PULLUP 0x00000020 /* internal pull-up enabled */ 74 #define GPIO_PIN_PULLDOWN 0x00000040 /* internal pull-down enabled */ 75 #define GPIO_PIN_INVIN 0x00000080 /* invert input */ 76 #define GPIO_PIN_INVOUT 0x00000100 /* invert output */ 77 #define GPIO_PIN_PULSATE 0x00000200 /* pulsate in hardware */ 78 #define GPIO_PIN_PRESET_LOW 0x00000400 /* preset pin to high or */ 79 #define GPIO_PIN_PRESET_HIGH 0x00000800 /* low before enabling output */ 80 /* GPIO interrupt capabilities */ 81 #define GPIO_INTR_NONE 0x00000000 /* no interrupt support */ 82 #define GPIO_INTR_LEVEL_LOW 0x00010000 /* level trigger, low */ 83 #define GPIO_INTR_LEVEL_HIGH 0x00020000 /* level trigger, high */ 84 #define GPIO_INTR_EDGE_RISING 0x00040000 /* edge trigger, rising */ 85 #define GPIO_INTR_EDGE_FALLING 0x00080000 /* edge trigger, falling */ 86 #define GPIO_INTR_EDGE_BOTH 0x00100000 /* edge trigger, both */ 87 #define GPIO_INTR_ATTACHED 0x00200000 /* interrupt attached to file */ 88 #define GPIO_INTR_MASK (GPIO_INTR_LEVEL_LOW | GPIO_INTR_LEVEL_HIGH | \ 89 GPIO_INTR_EDGE_RISING | \ 90 GPIO_INTR_EDGE_FALLING | GPIO_INTR_EDGE_BOTH | \ 91 GPIO_INTR_ATTACHED) 92 93 struct gpio_pin { 94 uint32_t gp_pin; /* pin number */ 95 char gp_name[GPIOMAXNAME]; /* human-readable name */ 96 uint32_t gp_caps; /* capabilities */ 97 uint32_t gp_flags; /* current flags */ 98 }; 99 100 /* GPIO pin request (read/write/toggle) */ 101 struct gpio_req { 102 uint32_t gp_pin; /* pin number */ 103 uint32_t gp_value; /* value */ 104 }; 105 106 /* 107 * Reporting gpio pin-change per-event details to userland. 108 * 109 * When configured for detail reporting, each call to read(2) will return one or 110 * more of these structures (or will return EWOULDBLOCK in non-blocking IO mode 111 * when there are no new events to report). 112 */ 113 struct gpio_event_detail { 114 sbintime_t gp_time; /* Time of event */ 115 uint16_t gp_pin; /* Pin number */ 116 bool gp_pinstate; /* Pin state at time of event */ 117 }; 118 119 /* 120 * Reporting gpio pin-change summary data to userland. 121 * 122 * When configured for summary reporting, each call to read(2) will return one 123 * or more of these structures (or will return EWOULDBLOCK in non-blocking IO 124 * mode when there are no new events to report). 125 */ 126 struct gpio_event_summary { 127 sbintime_t gp_first_time; /* Time of first event */ 128 sbintime_t gp_last_time; /* Time of last event */ 129 uint16_t gp_pin; /* Pin number */ 130 uint16_t gp_count; /* Event count */ 131 bool gp_first_state; /* Pin state at first event */ 132 bool gp_last_state; /* Pin state at last event */ 133 }; 134 135 /* 136 * Configuring event reporting to userland. 137 * 138 * The default is to deliver gpio_event_detail reporting, with a default fifo 139 * size of 2 * number of pins belonging to the gpioc device instance. To change 140 * it, you must use the GPIOCONFIGEVENTS ioctl before using GPIOSETCONFIG to 141 * configure reporting interrupt events on any pins. This config is tracked on 142 * a per-open-descriptor basis. 143 */ 144 enum { 145 GPIO_EVENT_REPORT_DETAIL, /* Report detail on each event */ 146 GPIO_EVENT_REPORT_SUMMARY, /* Report summary of events */ 147 }; 148 struct gpio_event_config { 149 uint32_t gp_report_type; /* Detail or summary reporting */ 150 uint32_t gp_fifo_size; /* FIFO size (used for detail only) */ 151 }; 152 153 /* 154 * gpio_access_32 / GPIOACCESS32 155 * 156 * Simultaneously read and/or change up to 32 adjacent pins. 157 * If the device cannot change the pins simultaneously, returns EOPNOTSUPP. 158 * 159 * This accesses an adjacent set of up to 32 pins starting at first_pin within 160 * the device's collection of pins. How the hardware pins are mapped to the 32 161 * bits in the arguments is device-specific. It is expected that lower-numbered 162 * pins in the device's number space map linearly to lower-ordered bits within 163 * the 32-bit words (i.e., bit 0 is first_pin, bit 1 is first_pin+1, etc). 164 * Other mappings are possible; know your device. 165 * 166 * Some devices may limit the value of first_pin to 0, or to multiples of 16 or 167 * 32 or some other hardware-specific number; to access pin 2 would require 168 * first_pin to be zero and then manipulate bit (1 << 2) in the 32-bit word. 169 * Invalid values in first_pin result in an EINVAL error return. 170 * 171 * The starting state of the pins is captured and stored in orig_pins, then the 172 * pins are set to ((starting_state & ~clear_pins) ^ change_pins). 173 * 174 * Clear Change Hardware pin after call 175 * 0 0 No change 176 * 0 1 Opposite of current value 177 * 1 0 Cleared 178 * 1 1 Set 179 */ 180 struct gpio_access_32 { 181 uint32_t first_pin; /* First pin in group of 32 adjacent */ 182 uint32_t clear_pins; /* Pins are changed using: */ 183 uint32_t change_pins; /* ((hwstate & ~clear_pins) ^ change_pins) */ 184 uint32_t orig_pins; /* Returned hwstate of pins before change. */ 185 }; 186 187 /* 188 * gpio_config_32 / GPIOCONFIG32 189 * 190 * Simultaneously configure up to 32 adjacent pins. This is intended to change 191 * the configuration of all the pins simultaneously, such that pins configured 192 * for output all begin to drive the configured values simultaneously, but not 193 * all hardware can do that, so the driver "does the best it can" in this 194 * regard. Notably unlike pin_access_32(), this does NOT fail if the pins 195 * cannot be atomically configured; it is expected that callers understand the 196 * hardware and have decided to live with any such limitations it may have. 197 * 198 * The pin_flags argument is an array of GPIO_PIN_xxxx flags. If the array 199 * contains any GPIO_PIN_OUTPUT flags, the driver will manipulate the hardware 200 * such that all output pins become driven with the proper initial values 201 * simultaneously if it can. The elements in the array map to pins in the same 202 * way that bits are mapped by pin_access_32(), and the same restrictions may 203 * apply. For example, to configure pins 2 and 3 it may be necessary to set 204 * first_pin to zero and only populate pin_flags[2] and pin_flags[3]. If a 205 * given array entry doesn't contain GPIO_PIN_INPUT or GPIO_PIN_OUTPUT then no 206 * configuration is done for that pin. 207 * 208 * Some devices may limit the value of first_pin to 0, or to multiples of 16 or 209 * 32 or some other hardware-specific number. Invalid values in first_pin or 210 * num_pins result in an error return with errno set to EINVAL. 211 * 212 * You cannot configure interrupts (userland pin-change notifications) with 213 * this function; each interrupt pin must be individually configured. 214 */ 215 struct gpio_config_32 { 216 uint32_t first_pin; 217 uint32_t num_pins; 218 uint32_t pin_flags[32]; 219 }; 220 221 /* 222 * ioctls 223 */ 224 #define GPIOMAXPIN _IOR('G', 0, int) 225 #define GPIOGETCONFIG _IOWR('G', 1, struct gpio_pin) 226 #define GPIOSETCONFIG _IOW('G', 2, struct gpio_pin) 227 #define GPIOGET _IOWR('G', 3, struct gpio_req) 228 #define GPIOSET _IOW('G', 4, struct gpio_req) 229 #define GPIOTOGGLE _IOWR('G', 5, struct gpio_req) 230 #define GPIOSETNAME _IOW('G', 6, struct gpio_pin) 231 #define GPIOACCESS32 _IOWR('G', 7, struct gpio_access_32) 232 #define GPIOCONFIG32 _IOW('G', 8, struct gpio_config_32) 233 #define GPIOCONFIGEVENTS _IOW('G', 9, struct gpio_event_config) 234 235 #endif /* __GPIO_H__ */ 236