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 <stdint.h>
  28 #include "types.h"
  29
  30 #define MRAA_PLATFORM_NAME_MAX_SIZE 64
  31 #define MRAA_PIN_NAME_SIZE 12
  32
  33 #define MRAA_SUB_PLATFORM_BIT_SHIFT 9
  34 #define MRAA_SUB_PLATFORM_MASK (1<<MRAA_SUB_PLATFORM_BIT_SHIFT)
  35
  36 #define MRAA_MAIN_PLATFORM_OFFSET 0
  37 #define MRAA_SUB_PLATFORM_OFFSET 1
  38
  39 /** Executes function func and returns its result in case of error
  40  */
  41 #define MRAA_RETURN_FOR_ERROR(func) do { \
  42                                       mraa_result_t res; \
  43                                       res = func; \
  44                                       if (res != MRAA_SUCCESS) \
  45                                       return res;} while(0)
  46
  47 /** @file
  48  *
  49  * This file defines the basic shared values for libmraa
  50  */
  51
  52 #ifdef __cplusplus
  53 extern "C" {
  54 #endif
  55
  56 /**
  57  * MRAA boolean type
  58  * 1 For TRUE
  59  */
  60 typedef unsigned int mraa_boolean_t;
  61
  62 /**
  63  * Initialise MRAA
  64  *
  65  * Detects running platform and attempts to use included pinmap, this is run on
  66  * module/library init/load but is handy to rerun to check board initialised
  67  * correctly. MRAA_SUCCESS inidicates correct (first time) initialisation
  68  * whilst MRAA_ERROR_PLATFORM_ALREADY_INITIALISED indicates the board is
  69  * already initialised correctly
  70  *
  71  * @return Result of operation
  72  */
  73 #if (defined SWIGPYTHON) || (defined SWIG)
  74 mraa_result_t mraa_init();
  75 #else
  76 // this sets a compiler attribute (supported by GCC & clang) to have mraa_init()
  77 // be called as a constructor make sure your libc supports this!  uclibc needs
  78 // to be compiled with UCLIBC_CTOR_DTOR
  79 mraa_result_t mraa_init() __attribute__((constructor));
  80 #endif
  81
  82 /**
  83  * De-Initilise MRAA
  84  *
  85  * This is not a strict requirement but useful to test memory leaks and for
  86  * people who like super clean code. If dynamically loading & unloading
  87  * libmraa you need to call this before unloading the library.
  88  */
  89 void mraa_deinit();
  90
  91 /**
  92  * Checks if a pin is able to use the passed in mode.
  93  *
  94  * @param pin Physical Pin to be checked.
  95  * @param mode the mode to be tested.
  96  * @return boolean if the mode is supported, 0=false.
  97  */
  98 mraa_boolean_t mraa_pin_mode_test(int pin, mraa_pinmodes_t mode);
  99
 100 /**
 101  * Check the board's  bit size when reading the value
 102  *
 103  * @return raw bits being read from kernel module. zero if no ADC
 104  */
 105 unsigned int mraa_adc_raw_bits();
 106
 107 /**
 108  * Check the specified board's bit size when reading the value
 109  *
 110  * @param specified platform offset; 0 for main platform, 1 foor sub platform
 111  * @return raw bits being read from kernel module. zero if no ADC
 112  */
 113 unsigned int mraa_get_platform_adc_raw_bits(uint8_t platform_offset);
 114
 115 /**
 116  * Return value that the raw value should be shifted to. Zero if no ADC
 117  *
 118  * @return return actual bit size the adc value should be understood as.
 119  */
 120 unsigned int mraa_adc_supported_bits();
 121
 122 /**
 123  * Return value that the raw value should be shifted to. Zero if no ADC
 124  *
 125  * @param specified platform offset; 0 for main platform, 1 foor sub platform
 126  * @return return actual bit size the adc value should be understood as.
 127  */
 128 unsigned int mraa_get_platform_adc_supported_bits(int platform_offset);
 129
 130 /**
 131  * Sets the log level to use from 0-7 where 7 is very verbose. These are the
 132  * syslog log levels, see syslog(3) for more information on the levels.
 133  *
 134  * @return Result of operation
 135  */
 136 mraa_result_t mraa_set_log_level(int level);
 137
 138 /**
 139  * Return the Platform's Name, If no platform detected return NULL
 140  *
 141  * @return platform name
 142  */
 143 char* mraa_get_platform_name();
 144
 145 /**
 146  * This function attempts to set the mraa process to a given priority and the
 147  * scheduler to SCHED_RR. Highest * priority is typically 99 and minimum is 0.
 148  * This function * will set to MAX if * priority is > MAX. Function will return
 149  * -1 on failure.
 150  *
 151  * @param priority Value from typically 0 to 99
 152  * @return The priority value set
 153  */
 154 int mraa_set_priority(const unsigned int priority);
 155
 156 /** Get the version string of mraa autogenerated from git tag
 157  *
 158  * The version returned may not be what is expected however it is a reliable
 159  * number associated with the git tag closest to that version at build time
 160  *
 161  * @return version string from version.h
 162  */
 163 const char* mraa_get_version();
 164
 165 /**
 166  * Print a textual representation of the mraa_result_t
 167  *
 168  * @param result the result to print
 169  */
 170 void mraa_result_print(mraa_result_t result);
 171
 172 /**
 173  * Get platform type, board must be initialised.
 174  *
 175  * @return mraa_platform_t Platform type enum
 176  */
 177 mraa_platform_t mraa_get_platform_type();
 178
 179 /**
 180  * Get combined platform type, board must be initialised.
 181  * The combined type is represented as
 182  * (sub_platform_type << 8) | main_platform_type
 183  *
 184  * @return int combined platform type
 185  */
 186 int mraa_get_platform_combined_type();
 187
 188 /**
 189  * Get platform pincount, board must be initialised.
 190  *
 191  * @return uint of physical pin count on the in-use platform
 192  */
 193 unsigned int mraa_get_pin_count();
 194
 195 /**
 196  * Get platform usable I2C bus count, board must be initialised.
 197  *
 198  * @return number f usable I2C bus count on the current platform. Function will
 199  * return -1 on failure
 200  */
 201 int mraa_get_i2c_bus_count();
 202
 203 /**
 204  * Get I2C adapter number in sysfs.
 205  *
 206  * @param i2c_bus the logical I2C bus number
 207  * @return I2C adapter number in sysfs. Function will return -1 on failure
 208  */
 209 int mraa_get_i2c_bus_id(unsigned int i2c_bus);
 210
 211 /**
 212  * Get specified platform pincount, board must be initialised.
 213  *
 214  * @param specified platform offset; 0 for main platform, 1 foor sub platform
 215  * @return uint of physical pin count on the in-use platform
 216  */
 217 unsigned int mraa_get_platform_pin_count(uint8_t platform_offset);
 218
 219 /**
 220 * Get name of pin, board must be initialised.
 221 *
 222 * @param pin number
 223 * @return char* of pin name
 224 */
 225 char* mraa_get_pin_name(int pin);
 226
 227 /**
 228  * Get default i2c bus, board must be initialised.
 229  *
 230  * @return int default i2c bus index
 231  */
 232 int mraa_get_default_i2c_bus(uint8_t platform_offset);
 233
 234 /**
 235  * Detect presence of sub platform.
 236  *
 237  * @return mraa_boolean_t 1 if sub platform is present and initialized, 0 otherwise
 238  */
 239 mraa_boolean_t mraa_has_sub_platform();
 240
 241
 242 /**
 243  * Check if pin or bus id includes sub platform mask.
 244  *
 245  * @param int pin or bus number
 246  *
 247  * @return mraa_boolean_t 1 if pin or bus is for sub platform, 0 otherwise
 248  */
 249 mraa_boolean_t mraa_is_sub_platform_id(int pin_or_bus_id);
 250
 251 /**
 252  * Convert pin or bus index to corresponding sub platform id.
 253  *
 254  * @param int pin or bus index
 255  *
 256  * @return int sub platform pin or bus number
 257  */
 258 int mraa_get_sub_platform_id(int pin_or_bus_index);
 259
 260 /**
 261  * Convert pin or bus sub platform id to index.
 262  *
 263  * @param int sub platform pin or bus id
 264  *
 265  * @return int pin or bus index
 266  */
 267 int mraa_get_sub_platform_index(int pin_or_bus_id);
 268
 269
 270
 271 #ifdef __cplusplus
 272 }
 273 #endif