api/mraa/common.h

   1 /*
   2  * Author: Brendan Le Foll <brendan.le.foll@intel.com>
   3  * Author: Thomas Ingleby <thomas.c.ingleby@intel.com>
   4  * Copyright © 2014 Intel Corporation
   5  *
   6  * Permission is hereby granted, free of charge, to any person obtaining a copy
   7  * of this software and associated documentation files (the "Software"), to
   8  * deal in the Software without restriction, including without limitation the
   9  * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
  10  * sell copies of the Software, and to permit persons to whom the Software is
  11  * furnished to do so, subject to the following conditions:
  12  *
  13  * The above copyright notice and this permission notice shall be included in
  14  * all copies or substantial portions of the Software.
  15  *
  16  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  17  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  18  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  19  * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  20  * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
  21  * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
  22  * IN THE SOFTWARE.
  23  */
  24
  25 #pragma once
  26
  27 #include "types.h"
  28
  29 /** @file
  30  *
  31  * This file defines the basic shared values for libmraa
  32  */
  33
  34 #ifdef __cplusplus
  35 extern "C" {
  36 #endif
  37
  38 /**
  39  * MRAA boolean type
  40  * 1 For TRUE
  41  */
  42 typedef unsigned int mraa_boolean_t;
  43
  44 /**
  45  * Enum representing different possible modes for a pin.
  46  */
  47 typedef enum {
  48     MRAA_PIN_VALID       = 0, /**< Pin Valid */
  49     MRAA_PIN_GPIO        = 1, /**< General Purpose IO */
  50     MRAA_PIN_PWM         = 2, /**< Pulse Width Modulation */
  51     MRAA_PIN_FAST_GPIO   = 3, /**< Faster GPIO */
  52     MRAA_PIN_SPI         = 4, /**< SPI */
  53     MRAA_PIN_I2C         = 5, /**< I2C */
  54     MRAA_PIN_AIO         = 6, /**< Analog in */
  55     MRAA_PIN_UART        = 7  /**< UART */
  56 } mraa_pinmodes_t;
  57
  58 /**
  59  * A bitfield representing the capabilities of a pin.
  60  */
  61 typedef struct {
  62     /*@{*/
  63     mraa_boolean_t valid:1;     /**< Is the pin valid at all */
  64     mraa_boolean_t gpio:1;      /**< Is the pin gpio capable */
  65     mraa_boolean_t pwm:1;       /**< Is the pin pwm capable */
  66     mraa_boolean_t fast_gpio:1; /**< Is the pin fast gpio capable */
  67     mraa_boolean_t spi:1;       /**< Is the pin spi capable */
  68     mraa_boolean_t i2c:1;       /**< Is the pin i2c capable */
  69     mraa_boolean_t aio:1;       /**< Is the pin analog input capable */
  70     mraa_boolean_t uart:1;       /**< Is the pin uart capable */
  71     /*@}*/
  72 } mraa_pincapabilities_t;
  73
  74 /**
  75  * A Structure representing a multiplexer and the required value
  76  */
  77 typedef struct {
  78     /*@{*/
  79     unsigned int pin;   /**< Raw GPIO pin id */
  80     unsigned int value; /**< Raw GPIO value */
  81     /*@}*/
  82 } mraa_mux_t;
  83
  84 typedef struct {
  85     mraa_boolean_t complex_pin:1;
  86     mraa_boolean_t output_en:1;
  87     mraa_boolean_t output_en_high:1;
  88     mraa_boolean_t pullup_en:1;
  89     mraa_boolean_t pullup_en_hiz:1;
  90 } mraa_pin_cap_complex_t;
  91
  92 typedef struct {
  93     /*@{*/
  94     unsigned int pinmap; /**< sysfs pin */
  95     unsigned int parent_id; /** parent chip id */
  96     unsigned int mux_total; /** Numfer of muxes needed for operation of pin */
  97     mraa_mux_t mux[6]; /** Array holding information about mux */
  98     unsigned int output_enable; /** Output Enable GPIO, for level shifting */
  99     unsigned int pullup_enable; /** Pull-Up enable GPIO, inputs */
 100     mraa_pin_cap_complex_t complex_cap;
 101     /*@}*/
 102 } mraa_pin_t;
 103
 104 typedef struct {
 105     /*@{*/
 106     char mem_dev[32]; /**< Memory device to use /dev/uio0 etc */
 107     unsigned int mem_sz; /** Size of memory to map */
 108     unsigned int bit_pos; /** Position of value bit */
 109     mraa_pin_t gpio; /** GPio context containing none mmap info */
 110     /*@}*/
 111 } mraa_mmap_pin_t;
 112
 113 /**
 114  * A Structure representing a physical Pin.
 115  */
 116 typedef struct {
 117     /*@{*/
 118     char name[8];                      /**< Pin's real world name */
 119     mraa_pincapabilities_t capabilites; /**< Pin Capabiliites */
 120     mraa_pin_t gpio; /**< GPIO structure */
 121     mraa_pin_t pwm;  /**< PWM structure */
 122     mraa_pin_t aio;  /**< Anaglog Pin */
 123     mraa_mmap_pin_t mmap; /**< GPIO through memory */
 124     mraa_pin_t i2c;  /**< i2c bus/pin */
 125     mraa_pin_t spi;  /**< spi bus/pin */
 126     mraa_pin_t uart;  /**< uart module/pin */
 127     /*@}*/
 128 } mraa_pininfo_t;
 129
 130 /**
 131  * A Structure representing the physical properties of a i2c bus.
 132  */
 133 typedef struct {
 134     /*@{*/
 135     unsigned int bus_id; /**< ID as exposed in the system */
 136     unsigned int scl; /**< i2c SCL */
 137     unsigned int sda; /**< i2c SDA */
 138     /*@}*/
 139 } mraa_i2c_bus_t;
 140
 141 /**
 142  * A Structure representing the physical properties of a spi bus.
 143  */
 144 typedef struct {
 145     /*@{*/
 146     unsigned int bus_id; /**< The Bus ID as exposed to the system. */
 147     unsigned int slave_s; /**< Slave select */
 148     mraa_boolean_t three_wire; /**< Is the bus only a three wire system */
 149     unsigned int sclk; /**< Serial Clock */
 150     unsigned int mosi; /**< Master Out, Slave In. */
 151     unsigned int miso; /**< Master In, Slave Out. */
 152     unsigned int cs; /**< Chip Select, used when the board is a spi slave */
 153     /*@}*/
 154 } mraa_spi_bus_t;
 155
 156 /**
 157  * A Structure representing a uart device.
 158  */
 159 typedef struct {
 160     /*@{*/
 161     unsigned int index; /**< ID as exposed in the system */
 162     int rx; /**< uart rx */
 163     int tx; /**< uart tx */
 164     /*@}*/
 165 } mraa_uart_dev_t;
 166
 167 /**
 168  * A Structure representing a platform/board.
 169  */
 170 typedef struct {
 171     /*@{*/
 172     unsigned int phy_pin_count; /**< The Total IO pins on board */
 173     unsigned int gpio_count; /**< GPIO Count */
 174     unsigned int aio_count;  /**< Analog side Count */
 175     unsigned int i2c_bus_count; /**< Usable i2c Count */
 176     mraa_i2c_bus_t  i2c_bus[6]; /**< Array of i2c */
 177     unsigned int def_i2c_bus; /**< Position in array of default i2c bus */
 178     unsigned int spi_bus_count; /**< Usable spi Count */
 179     mraa_spi_bus_t spi_bus[6];       /**< Array of spi */
 180     unsigned int def_spi_bus; /**< Position in array of defult spi bus */
 181     unsigned int adc_raw; /**< ADC raw bit value */
 182     unsigned int adc_supported; /**< ADC supported bit value */
 183     unsigned int def_uart_dev; /**< Position in array of defult uart */
 184     unsigned int uart_dev_count; /**< Usable spi Count */
 185     mraa_uart_dev_t uart_dev[6]; /**< Array of UARTs */
 186     mraa_pininfo_t* pins;     /**< Pointer to pin array */
 187     /*@}*/
 188 } mraa_board_t;
 189
 190 /**
 191  * Initialise MRAA
 192  *
 193  * Detects running platform and attempts to use included pinmap
 194  *
 195  * @return Result of operation
 196  */
 197 #if (defined SWIGPYTHON) || (defined SWIG)
 198 mraa_result_t mraa_init();
 199 #else
 200 // this sets a compiler attribute (supported by GCC & clang) to have mraa_init()
 201 // be called as a constructor make sure your libc supports this!  uclibc needs
 202 // to be compiled with UCLIBC_CTOR_DTOR
 203 mraa_result_t mraa_init() __attribute__((constructor));
 204 #endif
 205
 206 /**
 207  * De-Initilise MRAA
 208  *
 209  * This is not a strict requirement but useful to test memory leaks and for
 210  * people who like super clean code.
 211  */
 212 void mraa_deinit();
 213
 214 /**
 215  * Checks if a pin is able to use the passed in mode.
 216  *
 217  * @param pin Physical Pin to be checked.
 218  * @param mode the mode to be tested.
 219  * @return boolean if the mode is supported, 0=false.
 220  */
 221 mraa_boolean_t mraa_pin_mode_test(int pin, mraa_pinmodes_t mode);
 222
 223 /**
 224  * Check the board's  bit size when reading the value
 225  *
 226  * @return raw bits being read from kernel module. zero if no ADC
 227  */
 228 unsigned int mraa_adc_raw_bits();
 229
 230 /**
 231  * Return value that the raw value should be shifted to. Zero if no ADC
 232  *
 233  * @return return actual bit size the adc value should be understood as.
 234  */
 235 unsigned int mraa_adc_supported_bits();
 236
 237 #ifdef __cplusplus
 238 }
 239 #endif