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