api/maa/gpio.h

   1 /*
   2  * Author: Thomas Ingleby <thomas.c.ingleby@intel.com>
   3  * Copyright (c) 2014 Intel Corporation.
   4  *
   5  * Permission is hereby granted, free of charge, to any person obtaining
   6  * a copy of this software and associated documentation files (the
   7  * "Software"), to deal in the Software without restriction, including
   8  * without limitation the rights to use, copy, modify, merge, publish,
   9  * distribute, sublicense, and/or sell copies of the Software, and to
  10  * permit persons to whom the Software is furnished to do so, subject to
  11  * the following conditions:
  12  *
  13  * The above copyright notice and this permission notice shall be
  14  * included in all copies or substantial portions of the Software.
  15  *
  16  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
  17  * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
  18  * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
  19  * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
  20  * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
  21  * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
  22  * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  23  */
  24
  25 #pragma once
  26
  27 /**
  28  * @file
  29  * @brief General Purpose IO
  30  *
  31  * Gpio is the General Purpose IO interface to libmaa. It's features depends on
  32  * the board type used, it can use gpiolibs (exported via a kernel module
  33  * through sysfs), or memory mapped IO via a /dev/uio device or /dev/mem
  34  * depending again on the board configuratio, or memory mapped IO via a
  35  * /dev/uio device or /dev/mem depending again on the board configuration
  36  *
  37  * @snippet gpio_read6.c Interesting
  38  */
  39
  40 #ifdef __cplusplus
  41 extern "C" {
  42 #endif
  43
  44 #ifdef SWIGPYTHON
  45 #include <Python.h>
  46 #endif
  47
  48 #include <stdio.h>
  49 #include <pthread.h>
  50
  51 #include "common.h"
  52
  53 /**
  54  * Opaque pointer definition to the internal struct _gpio
  55  */
  56 typedef struct _gpio* maa_gpio_context;
  57
  58 /**
  59  * Gpio Output modes
  60  */
  61 typedef enum {
  62     MAA_GPIO_STRONG     = 0, /**< Default. Strong high and low */
  63     MAA_GPIO_PULLUP     = 1, /**< Resistive High */
  64     MAA_GPIO_PULLDOWN   = 2, /**< Resistive Low */
  65     MAA_GPIO_HIZ        = 3  /**< High Z State */
  66 } gpio_mode_t;
  67
  68 /**
  69  * Gpio Direction options
  70  */
  71 typedef enum {
  72     MAA_GPIO_OUT    = 0, /**< Output. A Mode can also be set */
  73     MAA_GPIO_IN     = 1  /**< Input */
  74 } gpio_dir_t;
  75
  76 /**
  77  * Gpio Edge types for interupts
  78  */
  79 typedef enum {
  80     MAA_GPIO_EDGE_NONE    = 0, /**< No interrupt on Gpio */
  81     MAA_GPIO_EDGE_BOTH    = 1, /**< Interupt on rising & falling */
  82     MAA_GPIO_EDGE_RISING  = 2, /**< Interupt on rising only */
  83     MAA_GPIO_EDGE_FALLING = 3  /**< Interupt on falling only */
  84 } gpio_edge_t;
  85
  86 /**
  87  * Initialise gpio_context, based on board number
  88  *
  89  *  @param pin Pin number read from the board, i.e IO3 is 3
  90  *  @returns gpio context or NULL
  91  */
  92 maa_gpio_context maa_gpio_init(int pin);
  93
  94 /**
  95  * Initialise gpio context without any mapping to a pin
  96  *
  97  * @param gpiopin gpio pin as listed in SYSFS
  98  * @return gpio context or NULL
  99  */
 100 maa_gpio_context maa_gpio_init_raw(int gpiopin);
 101
 102 /**
 103  * Set the edge mode on the gpio
 104  *
 105  * @param dev The Gpio context
 106  * @param mode The edge mode to set the gpio into
 107  * @return Result of operation
 108  */
 109 maa_result_t maa_gpio_edge_mode(maa_gpio_context dev, gpio_edge_t mode);
 110
 111 /**
 112  * Set an interupt on pin
 113  *
 114  * @param dev The Gpio context
 115  * @param edge The edge mode to set the gpio into
 116  * @param fptr Function pointer to function to be called when interupt is
 117  * triggered
 118  * @param args Arguments passed to the interrupt handler (fptr)
 119  * @return Result of operation
 120  */
 121 maa_result_t maa_gpio_isr(maa_gpio_context dev, gpio_edge_t edge, void (*fptr)(void *), void * args);
 122
 123 /**
 124  * Stop the current interupt watcher on this Gpio, and set the Gpio edge mode
 125  * to MAA_GPIO_EDGE_NONE
 126  *
 127  * @param dev The Gpio context
 128  * @return Result of operation
 129  */
 130 maa_result_t maa_gpio_isr_exit(maa_gpio_context dev);
 131
 132 /**
 133  * Set Gpio Output Mode,
 134  *
 135  * @param dev The Gpio context
 136  * @param mode The Gpio Output Mode
 137  * @return Result of operation
 138  */
 139 maa_result_t maa_gpio_mode(maa_gpio_context dev, gpio_mode_t mode);
 140
 141 /**
 142  * Set Gpio direction
 143  *
 144  * @param dev The Gpio context
 145  * @param dir The direction of the Gpio
 146  * @return Result of operation
 147  */
 148 maa_result_t maa_gpio_dir(maa_gpio_context dev, gpio_dir_t dir);
 149
 150 /**
 151  * Close the Gpio context
 152  * - Will free the memory for the context and unexport the Gpio
 153  *
 154  * @param dev The Gpio context
 155  * @return Result of operation
 156  */
 157 maa_result_t maa_gpio_close(maa_gpio_context dev);
 158
 159 /**
 160  * Read the Gpio value.
 161  *
 162  * @param dev The Gpio context
 163  * @return Result of operation
 164  */
 165 int maa_gpio_read(maa_gpio_context dev);
 166
 167 /**
 168  * Write to the Gpio Value.
 169  *
 170  * @param dev The Gpio context
 171  * @param value Integer value to write
 172  * @return Result of operation
 173  */
 174 maa_result_t maa_gpio_write(maa_gpio_context dev, int value);
 175
 176 /**
 177  * Change ownership of the context.
 178  *
 179  * @param dev The Gpio context
 180  * @param owner Does this context own the pin
 181  * @return Result of operation
 182  */
 183 maa_result_t maa_gpio_owner(maa_gpio_context dev, maa_boolean_t owner);
 184
 185 /**
 186  * Enable using memory mapped io instead of sysfs
 187  *
 188  * @param dev The Gpio context
 189  * @param mmap Use mmap instead of sysfs
 190  * @return Result of operation
 191  */
 192 maa_result_t maa_gpio_use_mmaped(maa_gpio_context dev, maa_boolean_t mmap);
 193
 194 #ifdef __cplusplus
 195 }
 196 #endif