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  * A bitfield representing the capabilities of a pin.
  66  */
  67 typedef struct {
  68     /*@{*/
  69     maa_boolean_t valid:1;     /**< Is the pin valid at all */
  70     maa_boolean_t gpio:1;      /**< Is the pin gpio capable */
  71     maa_boolean_t pwm:1;       /**< Is the pin pwm capable */
  72     maa_boolean_t fast_gpio:1; /**< Is the pin fast gpio capable */
  73     maa_boolean_t spi:1;       /**< Is the pin spi capable */
  74     maa_boolean_t i2c:1;       /**< Is the pin i2c capable */
  75     maa_boolean_t aio:1;       /**< Is the pin analog input capable */
  76     /*@}*/
  77 } maa_pincapabilities_t;
  78
  79 /**
  80  * A Structure representing a multiplexer and the required value
  81  */
  82 typedef struct {
  83     /*@{*/
  84     unsigned int pin;   /**< Raw GPIO pin id */
  85     unsigned int value; /**< Raw GPIO value */
  86 } maa_mux_t;
  87
  88 /**
  89  * A Strucutre representing a singular I/O pin. i.e GPIO/PWM
  90  */
  91 typedef struct {
  92     /*@{*/
  93     unsigned int pinmap;
  94     unsigned int parent_id;
  95     unsigned int mux_total;
  96     maa_mux_t mux[6];
  97     /*@}*/
  98 } maa_pin_t;
  99
 100 /**
 101  * A Structure representing a physical Pin.
 102  */
 103 typedef struct {
 104     /*@{*/
 105     char name[8];                      /**< Pin's real world name */
 106     maa_pincapabilities_t capabilites; /**< Pin Capabiliites */
 107     maa_pin_t gpio; /**< GPIO structure */
 108     maa_pin_t pwm;  /**< PWM structure */
 109     maa_pin_t aio;  /**< Anaglog Pin */
 110     maa_pin_t fast_gpio; /**< Fast GPIO */
 111     maa_pin_t i2c;  /**< i2c bus/pin */
 112     maa_pin_t spi;  /**< spi bus/pin */
 113     /*@}*/
 114 } maa_pininfo_t;
 115
 116 /**
 117  * A Structure representing the physical properties of a i2c bus.
 118  */
 119 typedef struct {
 120     /*@{*/
 121     unsigned int bus_id; /**< ID as exposed in the system */
 122     unsigned int scl; /**< i2c SCL */
 123     unsigned int sda; /**< i2c SDA */
 124     /*@}*/
 125 } maa_i2c_bus_t;
 126
 127 /**
 128  * A Structure representing the physical properties of a spi bus.
 129  */
 130 typedef struct {
 131     /*@{*/
 132     double bus_id; /**< The Bus ID as exposed to the system. */
 133     maa_boolean_t three_wire; /**< Is the bus only a three wire system */
 134     unsigned int sclk; /**< Serial Clock */
 135     unsigned int mosi; /**< Master Out, Slave In. */
 136     unsigned int miso; /**< Master In, Slave Out. */
 137     unsigned int cs; /**< Chip Select, used when the board is a spi slave */
 138     /*@}*/
 139 } maa_spi_bus_t;
 140
 141 /**
 142  * A Structure representing a platform/board.
 143  */
 144 typedef struct {
 145     /*@{*/
 146     unsigned int phy_pin_count; /**< The Total IO pins on board */
 147     unsigned int gpio_count; /**< GPIO Count */
 148     unsigned int aio_count;  /**< Analog side Count */
 149     unsigned int i2c_bus_count; /**< Usable i2c Count */
 150     maa_i2c_bus_t  i2c_bus[6]; /**< Array of i2c */
 151     unsigned int def_i2c_bus; /**< Position in array of default i2c bus */
 152     unsigned int spi_bus_count; /**< Usable spi Count */
 153     maa_spi_bus_t spi_bus[6];       /**< Array of spi */
 154     unsigned int def_spi_bus; /**< Position in array of defult spi bus */
 155     maa_pininfo_t* pins;     /**< Pointer to pin array */
 156     /*@}*/
 157 } maa_board_t;
 158
 159 /** Initialise MAA
 160  *
 161  * Detects running platform and attempts to use included pinmap
 162  * @return maa_result_t maa result
 163  */
 164 maa_result_t maa_init();
 165
 166 /** Check GPIO
 167  *
 168  * Will check input is valid for gpio and will also setup required multiplexers.
 169  * @param pin the pin as read from the board surface. i.e IO3 would be 3/
 170  * @return the pin as found in the pinmap
 171  */
 172 unsigned int maa_check_gpio(int pin);
 173
 174 /** Check AIO
 175  *
 176  * Will check input is valid for aio and will also setup required multiplexers.
 177  * @param pin the pin as read from the board surface. i.e A3 would be 3/
 178  * @return the pin as found in the pinmap
 179  */
 180 unsigned int maa_check_aio(int pin);
 181
 182 /** Check i2c interface, sets up multiplexer on device.
 183  *
 184  * @return unsigned int if using /dev/i2c-2 returned would be 2
 185  */
 186 unsigned int maa_check_i2c();
 187
 188 /** Get the version string of maa autogenerated from git tag
 189  *
 190  * The version returned may not be what is expected however it is a reliable
 191  * number associated with the git tag closest to that version at build time
 192  * @return version string from version.h
 193  */
 194 const char* maa_get_version();
 195
 196 #ifdef __cplusplus
 197 }
 198 #endif