ISF  1.1
Intelligent Sensing Framework
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines
Include/isf_bm.h
Go to the documentation of this file.
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 */