api/maa.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 /** @file
  28  *
  29  * This file defines the basic shared values for libmaa
  30  *
  31  */
  32
  33 #ifdef __cplusplus
  34 extern "C" {
  35 #endif
  36
  37 /**
  38  * MAA return codes
  39  */
  40 typedef enum {
  41     MAA_SUCCESS                              =  0, /**< Expected response */
  42     MAA_ERROR_FEATURE_NOT_IMPLEMENTED        =  1, /**< Feature TODO */
  43     MAA_ERROR_FEATURE_NOT_SUPPORTED          =  2, /**< Feature not supported by HW */
  44     MAA_ERROR_INVALID_VERBOSITY_LEVEL        =  3, /**< Verbosity level wrong */
  45     MAA_ERROR_INVALID_PARAMETER              =  4, /**< Parameter invalid */
  46     MAA_ERROR_INVALID_HANDLE                 =  5, /**< Handle invalid */
  47     MAA_ERROR_NO_RESOURCES                   =  6, /**< No resource of that type avail */
  48     MAA_ERROR_INVALID_RESOURCE               =  7, /**< Resource invalid */
  49     MAA_ERROR_INVALID_QUEUE_TYPE             =  8, /**< Queue type incorrect */
  50     MAA_ERROR_NO_DATA_AVAILABLE              =  9, /**< No data available */
  51     MAA_ERROR_INVALID_PLATFORM               = 10, /**< Platform not recognised */
  52     MAA_ERROR_PLATFORM_NOT_INITIALISED       = 11, /**< Board information not initialised */
  53     MAA_ERROR_PLATFORM_ALREADY_INITIALISED   = 12, /**< Board is already initialised */
  54
  55     MAA_ERROR_UNSPECIFIED                    = 99 /**< Unknown Error */
  56 } maa_result_t;
  57
  58 /**
  59  * MAA boolean type
  60  * 1 For TRUE
  61  */
  62 typedef unsigned int maa_boolean_t;
  63
  64 /**
  65  * Enum representing different possible modes for a pin.
  66  */
  67 typedef enum {
  68     MAA_PIN_VALID       = 0, /**< Pin Valid */
  69     MAA_PIN_GPIO        = 1, /**< General Purpose IO */
  70     MAA_PIN_PWM         = 2, /**< Pulse Width Modulation */
  71     MAA_PIN_FAST_GPIO   = 3, /**< Faster GPIO */
  72     MAA_PIN_SPI         = 4, /**< SPI */
  73     MAA_PIN_I2C         = 5, /**< I2C */
  74     MAA_PIN_AIO         = 6  /**< Analog in */
  75 } maa_pinmodes_t;
  76
  77 /**
  78  * A bitfield representing the capabilities of a pin.
  79  */
  80 typedef struct {
  81     /*@{*/
  82     maa_boolean_t valid:1;     /**< Is the pin valid at all */
  83     maa_boolean_t gpio:1;      /**< Is the pin gpio capable */
  84     maa_boolean_t pwm:1;       /**< Is the pin pwm capable */
  85     maa_boolean_t fast_gpio:1; /**< Is the pin fast gpio capable */
  86     maa_boolean_t spi:1;       /**< Is the pin spi capable */
  87     maa_boolean_t i2c:1;       /**< Is the pin i2c capable */
  88     maa_boolean_t aio:1;       /**< Is the pin analog input capable */
  89     /*@}*/
  90 } maa_pincapabilities_t;
  91
  92 /**
  93  * A Structure representing a multiplexer and the required value
  94  */
  95 typedef struct {
  96     /*@{*/
  97     unsigned int pin;   /**< Raw GPIO pin id */
  98     unsigned int value; /**< Raw GPIO value */
  99 } maa_mux_t;
 100
 101 /**
 102  * A Strucutre representing a singular I/O pin. i.e GPIO/PWM
 103  */
 104 typedef struct {
 105     /*@{*/
 106     unsigned int pinmap;
 107     unsigned int parent_id;
 108     unsigned int mux_total;
 109     maa_mux_t mux[6];
 110     /*@}*/
 111 } maa_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     maa_pincapabilities_t capabilites; /**< Pin Capabiliites */
 120     maa_pin_t gpio; /**< GPIO structure */
 121     maa_pin_t pwm;  /**< PWM structure */
 122     maa_pin_t aio;  /**< Anaglog Pin */
 123     maa_pin_t fast_gpio; /**< Fast GPIO */
 124     maa_pin_t i2c;  /**< i2c bus/pin */
 125     maa_pin_t spi;  /**< spi bus/pin */
 126     /*@}*/
 127 } maa_pininfo_t;
 128
 129 /**
 130  * A Structure representing the physical properties of a i2c bus.
 131  */
 132 typedef struct {
 133     /*@{*/
 134     unsigned int bus_id; /**< ID as exposed in the system */
 135     unsigned int scl; /**< i2c SCL */
 136     unsigned int sda; /**< i2c SDA */
 137     /*@}*/
 138 } maa_i2c_bus_t;
 139
 140 /**
 141  * A Structure representing the physical properties of a spi bus.
 142  */
 143 typedef struct {
 144     /*@{*/
 145     unsigned int bus_id; /**< The Bus ID as exposed to the system. */
 146     unsigned int slave_s; /**< Slave select */
 147     maa_boolean_t three_wire; /**< Is the bus only a three wire system */
 148     unsigned int sclk; /**< Serial Clock */
 149     unsigned int mosi; /**< Master Out, Slave In. */
 150     unsigned int miso; /**< Master In, Slave Out. */
 151     unsigned int cs; /**< Chip Select, used when the board is a spi slave */
 152     /*@}*/
 153 } maa_spi_bus_t;
 154
 155 /**
 156  * A Structure representing a platform/board.
 157  */
 158 typedef struct {
 159     /*@{*/
 160     unsigned int phy_pin_count; /**< The Total IO pins on board */
 161     unsigned int gpio_count; /**< GPIO Count */
 162     unsigned int aio_count;  /**< Analog side Count */
 163     unsigned int i2c_bus_count; /**< Usable i2c Count */
 164     maa_i2c_bus_t  i2c_bus[6]; /**< Array of i2c */
 165     unsigned int def_i2c_bus; /**< Position in array of default i2c bus */
 166     unsigned int spi_bus_count; /**< Usable spi Count */
 167     maa_spi_bus_t spi_bus[6];       /**< Array of spi */
 168     unsigned int def_spi_bus; /**< Position in array of defult spi bus */
 169     maa_pininfo_t* pins;     /**< Pointer to pin array */
 170     /*@}*/
 171 } maa_board_t;
 172
 173 /** Initialise MAA
 174  *
 175  * Detects running platform and attempts to use included pinmap
 176  * @return maa_result_t maa result
 177  */
 178 #ifndef SWIG
 179 // this sets a compiler attribute (supported by GCC & clang) to have maa_init()
 180 // be called as a constructor make sure your libc supports this!  uclibc needs
 181 // to be compiled with UCLIBC_CTOR_DTOR
 182 maa_result_t maa_init() __attribute__((constructor));
 183 #else
 184 maa_result_t maa_init();
 185 #endif
 186
 187 /** Get the version string of maa autogenerated from git tag
 188  *
 189  * The version returned may not be what is expected however it is a reliable
 190  * number associated with the git tag closest to that version at build time
 191  * @return version string from version.h
 192  */
 193 const char* maa_get_version();
 194
 195 /** Print a textual representation of the maa_result_t
 196  *
 197  * @param result the result to print,
 198  */
 199 void maa_result_print(maa_result_t result);
 200
 201 /** Checks if a pin is able to use the passed in mode.
 202  *
 203  * @param pin Physical Pin to be checked.
 204  * @param mode the mode to be tested.
 205  * @return boolean if the mode is supported, 0=false.
 206  */
 207 maa_boolean_t maa_pin_mode_test(int pin, maa_pinmodes_t mode);
 208
 209 #ifdef __cplusplus
 210 }
 211 #endif