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 const char* mraa_get_platform_name(); 144 145 /** 146 * Return the platform's versioning info, the information given depends per 147 * platform and can be NULL. platform_offset has to be given. Do not modify 148 * this pointer 149 * 150 * @param specified platform offset; 0 for main platform, 1 for sub platform 151 * @return platform's versioning string 152 */ 153 const char* mraa_get_platform_version(int platform_offset); 154 155 /** 156 * This function attempts to set the mraa process to a given priority and the 157 * scheduler to SCHED_RR. Highest * priority is typically 99 and minimum is 0. 158 * This function * will set to MAX if * priority is > MAX. Function will return 159 * -1 on failure. 160 * 161 * @param priority Value from typically 0 to 99 162 * @return The priority value set 163 */ 164 int mraa_set_priority(const unsigned int priority); 165 166 /** Get the version string of mraa autogenerated from git tag 167 * 168 * The version returned may not be what is expected however it is a reliable 169 * number associated with the git tag closest to that version at build time 170 * 171 * @return version string from version.h 172 */ 173 const char* mraa_get_version(); 174 175 /** 176 * Print a textual representation of the mraa_result_t 177 * 178 * @param result the result to print 179 */ 180 void mraa_result_print(mraa_result_t result); 181 182 /** 183 * Get platform type, board must be initialised. 184 * 185 * @return mraa_platform_t Platform type enum 186 */ 187 mraa_platform_t mraa_get_platform_type(); 188 189 /** 190 * Get combined platform type, board must be initialised. 191 * The combined type is represented as 192 * (sub_platform_type << 8) | main_platform_type 193 * 194 * @return int combined platform type 195 */ 196 int mraa_get_platform_combined_type(); 197 198 /** 199 * Get platform pincount, board must be initialised. 200 * 201 * @return uint of physical pin count on the in-use platform 202 */ 203 unsigned int mraa_get_pin_count(); 204 205 /** 206 * Get platform usable I2C bus count, board must be initialised. 207 * 208 * @return number f usable I2C bus count on the current platform. Function will 209 * return -1 on failure 210 */ 211 int mraa_get_i2c_bus_count(); 212 213 /** 214 * Get I2C adapter number in sysfs. 215 * 216 * @param i2c_bus the logical I2C bus number 217 * @return I2C adapter number in sysfs. Function will return -1 on failure 218 */ 219 int mraa_get_i2c_bus_id(unsigned int i2c_bus); 220 221 /** 222 * Get specified platform pincount, board must be initialised. 223 * 224 * @param specified platform offset; 0 for main platform, 1 foor sub platform 225 * @return uint of physical pin count on the in-use platform 226 */ 227 unsigned int mraa_get_platform_pin_count(uint8_t platform_offset); 228 229 /** 230 * Get name of pin, board must be initialised. 231 * 232 * @param pin number 233 * @return char* of pin name 234 */ 235 char* mraa_get_pin_name(int pin); 236 237 /** 238 * Get default i2c bus, board must be initialised. 239 * 240 * @return int default i2c bus index 241 */ 242 int mraa_get_default_i2c_bus(uint8_t platform_offset); 243 244 /** 245 * Detect presence of sub platform. 246 * 247 * @return mraa_boolean_t 1 if sub platform is present and initialized, 0 otherwise 248 */ 249 mraa_boolean_t mraa_has_sub_platform(); 250 251 252 /** 253 * Check if pin or bus id includes sub platform mask. 254 * 255 * @param int pin or bus number 256 * 257 * @return mraa_boolean_t 1 if pin or bus is for sub platform, 0 otherwise 258 */ 259 mraa_boolean_t mraa_is_sub_platform_id(int pin_or_bus_id); 260 261 /** 262 * Convert pin or bus index to corresponding sub platform id. 263 * 264 * @param int pin or bus index 265 * 266 * @return int sub platform pin or bus number 267 */ 268 int mraa_get_sub_platform_id(int pin_or_bus_index); 269 270 /** 271 * Convert pin or bus sub platform id to index. 272 * 273 * @param int sub platform pin or bus id 274 * 275 * @return int pin or bus index 276 */ 277 int mraa_get_sub_platform_index(int pin_or_bus_id); 278 279 280 281 #ifdef __cplusplus 282 } 283 #endif 284