sys/sys/gpio.h

   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-FreeBSD 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 #ifndef _KERNEL
  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__ */