| ISF 1.1 Intelligent Sensing Framework

- Main Page
- Data Structures
- Files
- Sensor Adapters

- File List
- Globals

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 */