![]() |
ISF
1.1
Intelligent Sensing Framework
|
00001 /* 00002 * 00003 * Copyright (c) 2012, Freescale Semiconductor, Inc. 00004 * 00005 */ 00006 00007 00008 /*! 00009 * @file isf_bm.h 00010 * 00011 * @brief API definitions, types, and macros for the Intelligent Sensing 00012 * Framework (ISF) Bus Manager (BM). 00013 * 00014 */ 00015 00016 #ifndef BUS_MANAGEMENT_H 00017 #define BUS_MANAGEMENT_H 00018 00019 00020 00021 // Use byte alignment for structures 00022 #pragma pack(push) 00023 #pragma pack(1) 00024 00025 00026 00027 /******************* 00028 ** Macro Definitions 00029 */ 00030 00031 00032 /*! @brief The maximum number of callbacks registered with the Bus Manager. 00033 */ 00034 #define MAX_BM_CALLBACKS (8) 00035 00036 /*! @brief The maximum period of a callback is provided in microseconds. 00037 * Attempting to register a callback period greater than this value results 00038 * in an error. 00039 */ 00040 #define MAX_BM_PERIOD_USEC (60 * 1000 * 1000) // 60 seconds => 0.0167 Hz 00041 00042 /*! @brief The minimum period of a callback is provided in microseconds. 00043 * Attempting to register a callback period less than this value results 00044 * in an error. 00045 */ 00046 #define MIN_BM_PERIOD_USEC (200) // 200 usec => 5000 Hz 00047 00048 00049 /*! @brief The largest token value assigned to a bus management callback. 00050 */ 00051 #define BM_TOKEN_VAL_MAX ((bm_callback_token_t)(1 << (MAX_BM_CALLBACKS-1))) 00052 00053 /*! @brief This value is returned when the token value for the BM callback 00054 * is incorrect. 00055 */ 00056 #define BM_TOKEN_VAL_ERROR ((bm_callback_token_t)(1 << ((sizeof(bm_callback_token_t)*8)-1))) // Set msb bit to indicate error 00057 00058 /*! @brief This value specifies a general Bus Manager error. If an error 00059 * occurs in registering a callback, this token error value is logically 00060 * OR'd with the specific nature of the error and returned. 00061 */ 00062 #define BM_ERROR BM_TOKEN_VAL_ERROR 00063 00064 /*! @brief This value specifies an action to be taken on all callbacks 00065 * registered with the Bus Manager. 00066 */ 00067 #define BM_ALL_TOKENS ((bm_callback_token_t)((1 << MAX_BM_CALLBACKS)-1)) 00068 00069 00070 /************** 00071 ** Type Definitions 00072 */ 00073 00074 /*! @brief Type for the prototype for a Bus Manager periodic callback function. 00075 */ 00076 typedef void (bm_callback_t)(void *); 00077 00078 00079 /*! @brief This type defines the Bus Manager token. Each callback registered 00080 * with the Bus Manager receives a unique token value of this type. Certain Bus 00081 * Manager API calls require the token value as an input parameter such as 00082 * bm_start(), bm_stop(), and bm_unregister_callback(). 00083 */ 00084 typedef uint32 bm_callback_token_t; 00085 00086 00087 00088 /********************* 00089 ** Function Prototypes 00090 */ 00091 00092 00093 /*! @brief This API initializes the Bus Manager. 00094 * 00095 * 00096 * @details The Bus Manager requires a one time initialization at system 00097 * startup performed by this API call. It creates and initializes internal 00098 * variables. In addition, it installs an interrupt service routine for a 00099 * hardware timer to be used by the Bus Manager to schedule callbacks. 00100 * 00101 * @return ::isf_status_t bm_init() returns a value of type 00102 * ::isf_status_t providing the status of the 00103 * initialization operation. 00104 * 00105 * @retval ::ISF_SUCCESS This value is returned if the 00106 * initialization completed successfully. 00107 * 00108 * @retval ::ISF_ERR_LIB_INIT This value is returned if the 00109 * interrupt service routine for the FXLC95000 MTIM timer 00110 * could not be installed. 00111 * 00112 * @Constraints The following constraints must be observed when using 00113 * this function. If these constraints are not met, this 00114 * API returns an error. 00115 * @li There must not be any installed interrupt routines 00116 * for the FXLC95000 MTIM timer. 00117 * 00118 * @Reentrant No 00119 * 00120 * @Libs isf_core.lib 00121 * 00122 */ 00123 isf_status_t bm_init(void); 00124 00125 00126 00127 00128 /*! @brief This API schedules a callback at the specified period. 00129 * 00130 * @details The Bus Manager schedules periodic sensor data automatically. 00131 * It allows a registered callback to be automatically invoked at the 00132 * specified period. Multiple callbacks registered for the same frequency 00133 * are executed serially by the Bus Manager. If registration of the 00134 * callback is successful, the callback is set to the inactive state. 00135 * The API function bm_start() can be called to make the callback active. 00136 * 00137 * @param [in] aPeriod The period (1/frequency) between successive 00138 * callback invocations in microseconds. 00139 * 00140 * @param [in] apCallback The pointer to the callback function to be 00141 * registered. 00142 * 00143 * @param [in] apCbData The pointer passed to the callback function 00144 * each time it is invoked. This pointer may be used 00145 * to pass specific data to the callback function. 00146 * 00147 * @return bm_register_periodic_callback() 00148 * returns a token of type ::bm_callback_token_t if the 00149 * callback registration is successful. 00150 * 00151 * @retval ::COMM_ERROR_NULL_PTR This error value and the most 00152 * significant bit of the macro ::BM_ERROR is 00153 * returned if the callback function pointer is NULL. 00154 * 00155 * @retval ::COMM_ERROR_NOEXIST This error value and the most 00156 * significant bit of the macro ::BM_ERROR is returned 00157 * if either of the following conditions are true: 00158 * @li The callback period is longer than 00159 * ::MAX_BM_PERIOD_USEC or shorter than 00160 * ::MIN_BM_PERIOD_USEC. 00161 * @li The callback under registration exceeds the maximum 00162 * number of callbacks allowed. 00163 * 00164 * @Constraints The following constraints must be observed when using 00165 * this function. If these constraints are not met, this 00166 * API returns an error. 00167 * @li aPeriod must be within the valid range of 00168 * ::MIN_BM_PERIOD_USEC to ::MAX_BM_PERIOD_USEC for the 00169 * bus being initialized. 00170 * @li apCallback callback function pointer must not 00171 * be NULL. 00172 * @li The number of callbacks registered must not 00173 * exceed the maximum specified by ::MAX_BM_CALLBACKS. 00174 * 00175 * @Reentrant Yes 00176 * 00177 * @Libs isf_core.lib 00178 * 00179 */ 00180 00181 bm_callback_token_t bm_register_periodic_callback( 00182 isf_duration_t aPeriod, 00183 bm_callback_t *apCallback, 00184 void *apCbData 00185 ); 00186 00187 00188 /*! @brief This API unregisters one or more callbacks. 00189 * 00190 * @details The Bus Manager allows the removal of a registered callback. 00191 * After a call to this function, unregistered callbacks no longer exist. 00192 * To specify the callback to be unregistered, the token returned by 00193 * bm_register_periodic_callback() is passed to bm_unregister_callback(). 00194 * Multiple callbacks can be specified by performing a logical OR of the 00195 * token values. The callback can be in the active or inactive state when 00196 * it is unregistered. 00197 * 00198 * @param [in] aTokens This parameter specifies the token value(s) of 00199 * the callback(s) that are to be unregistered. More 00200 * than one callback is specified by performing a logical 00201 * OR of the token values associated with the registered 00202 * callbacks. 00203 * 00204 * @return bm_unregister_callback() returns a value of type 00205 * ::isf_status_t indicating the status of the 00206 * unregister operation. 00207 * 00208 * @retval ::ISF_SUCCESS This value is returned if the callbacks 00209 * unregistered successfully. 00210 * 00211 * @retval ::COMM_ERROR_NOEXIST This value is returned if at least 00212 * one of the token values specified in aTokens is invalid 00213 * because it is not associated with a registered callback. 00214 * 00215 * @Constraints The following constraints must be observed when using this 00216 * function. If these constraints are not met, this API returns 00217 * an error. 00218 * @li aTokens value must be associated with registered 00219 * callback(s). 00220 * 00221 * @Reentrant Yes 00222 * 00223 * @Libs isf_core.lib 00224 * 00225 * @see bm_register_periodic_callback() 00226 * 00227 */ 00228 isf_status_t bm_unregister_callback( bm_callback_token_t aTokens ); 00229 00230 00231 00232 00233 /*! @brief This API sets one or more callback(s) to the active state. 00234 * 00235 * @details The start operation sets the callback(s) associated with 00236 * the specified token values to the active state. A callback in the 00237 * active state is invoked at its specified period. Multiple callbacks 00238 * are specified by performing a logical OR of the token values. Any 00239 * callbacks specified by this API call already in the active state, 00240 * remain in the active state and their current timings are not 00241 * affected. In addition to setting callbacks to the active state, 00242 * this API can also synchronize the callback timings. The timings 00243 * of all the active callbacks are reset to start running at the same 00244 * time reference. The bm_stop() API call changes a callback to the 00245 * inactive state. 00246 * 00247 * @param[in] aSync The parameter is set to TRUE to reset the timings 00248 * of the active callbacks and start them running at the 00249 * same time reference. The parameter is set to FALSE 00250 * to leave all active callback timings as they are. 00251 * 00252 * @param[in] aTokens This parameter specifies the token value(s) 00253 * of callback(s) to be set to the active state. 00254 * More than one callback is specified by performing 00255 * a logical OR of the token values associated with the 00256 * registered callbacks. 00257 * 00258 * @return ::isf_status_t bm_start() returns a value of type 00259 * ::isf_status_t providing the status of the start 00260 * operation. 00261 * 00262 * @retval ::ISF_SUCCESS This value is returned if the callback(s) 00263 * is set to the active state successfully. 00264 * 00265 * @retval ::COMM_ERROR_NOEXIST This value is returned if at least 00266 * one of the token values specified is invalid because 00267 * it is not associated with a registered callback. 00268 * 00269 * @Constraints The following constraints must be observed when using 00270 * this function. If these constraints are not met, this 00271 * API returns an error. 00272 * @li aTokens value must be associated with the registered 00273 * callback(s). 00274 * 00275 * @Reentrant Yes 00276 * 00277 * @Libs isf_core.lib 00278 * 00279 * @see bm_stop() 00280 * 00281 */ 00282 isf_status_t bm_start(boolean aSync, bm_callback_token_t aTokens); 00283 00284 00285 00286 /*! @brief This API stops one or more callback(s) by setting them to 00287 * the inactive state. 00288 * 00289 * @details The stop operation sets the the callback(s) associated 00290 * with the specified token values to the inactive state. A callback 00291 * in the inactive state is not invoked. Multiple callbacks are 00292 * specified by performing a logical OR of the token values. Any 00293 * callbacks specified by this API call already inactive will remain 00294 * in the inactive state. To change a callback to the active state, 00295 * the bm_start() API call is used. 00296 * 00297 * @param [in] aTokens This parameter specifies the token value(s) of 00298 * callback(s) to be set to the inactive state. More 00299 * than one callback is specified by performing a 00300 * logical OR of the token values associated with the 00301 * registered callbacks. 00302 * 00303 * @return ::isf_status_t bm_stop()returns a value of type 00304 * ::isf_status_t providing the status of the stop 00305 * operation. 00306 * 00307 * @retval ::ISF_SUCCESS The callback(s) stopped successfully. 00308 * 00309 * @retval ::COMM_ERROR_NOEXIST At least one of the token 00310 * values specified is invalid because it is not 00311 * associated with a registered callback. 00312 * 00313 * @Constraints The following constraints must be observed when using 00314 * this function. If these constraints are not met, this 00315 * API returns an error. 00316 * @li aTokens value must be associated with registered 00317 * callback(s). 00318 * 00319 * @Reentrant Yes 00320 * 00321 * @Libs isf_core.lib 00322 * 00323 * @see bm_start() 00324 * 00325 */ 00326 isf_status_t bm_stop(bm_callback_token_t aTokens); 00327 00328 00329 00330 /*! @brief This API returns the number of callbacks registered. 00331 * 00332 * @details The number of registered callbacks is returned regardless of 00333 * their state, active or inactive. 00334 * 00335 * @return bm_get_num_callback() returns a value of type uint32 00336 * providing the number of callbacks currently 00337 * registered with the Bus Manager whether they are 00338 * in the active or inactive state. 00339 * 00340 * @Constraints None 00341 * 00342 * @Reentrant Yes 00343 * 00344 * @Libs isf_core.lib 00345 * 00346 */ 00347 uint32 bm_get_num_callback(void); 00348 00349 00350 00351 #pragma pack(pop) 00352 00353 00354 #endif /* BUS_MANAGEMENT_H */