ISF  2.1
Intelligent Sensing Framework for Kinetis with Processor Expert
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Modules Pages
isf_bm.h
Go to the documentation of this file.
1 /*
2  *
3  * Copyright (c) 2013, Freescale Semiconductor, Inc.
4  *
5 */
6 
7 
8 /*!
9  * @file isf_bm.h
10  *
11  * @brief API definitions, types, and macros for the Intelligent Sensing
12  * Framework (ISF) Bus Manager (BM).
13  *
14 */
15 
16 #ifndef BUS_MANAGEMENT_H
17 #define BUS_MANAGEMENT_H
18 
19 
20 
21 
22 /*******************
23 ** Macro Definitions
24 */
25 
26 
27 /*! @brief The maximum number of callbacks registered with the Bus Manager.
28  */
29 #define MAX_BM_CALLBACKS (8)
30 
31 /*! @brief The maximum period of a callback is provided in microseconds.
32  * Attempting to register a callback period greater than this value results
33  * in an error.
34  */
35 #define MAX_BM_PERIOD_USEC (60 * 1000 * 1000) // 60 seconds => 0.0167 Hz
36 
37 /*! @brief The minimum period of a callback is provided in microseconds.
38  * Attempting to register a callback period less than this value results
39  * in an error.
40  */
41 #define MIN_BM_PERIOD_USEC (100) // 100 usec => 10000 Hz
42 
43 
44 /*! @brief The largest token value assigned to a bus management callback.
45  */
46 #define BM_TOKEN_VAL_MAX ((bm_callback_token_t)(1 << (MAX_BM_CALLBACKS-1)))
47 
48 /*! @brief This value is returned when the token value for the BM callback
49  * is incorrect.
50  */
51 #define BM_TOKEN_VAL_ERROR ((bm_callback_token_t)(1 << ((sizeof(bm_callback_token_t)*8)-1))) // Set msb bit to indicate error
52 
53 /*! @brief This value specifies a general Bus Manager error. If an error
54  * occurs in registering a callback, this token error value is logically
55  * OR'd with the specific nature of the error and returned.
56  */
57 #define BM_ERROR BM_TOKEN_VAL_ERROR
58 
59 /*! @brief This value specifies an action to be taken on all callbacks
60  * registered with the Bus Manager.
61  */
62 #define BM_ALL_TOKENS ((bm_callback_token_t)((1 << MAX_BM_CALLBACKS)-1))
63 
64 
65 /**************
66 ** Type Definitions
67 */
68 
69 /*! @brief Type for the prototype for a Bus Manager periodic callback function.
70  */
71 typedef void (bm_callback_t)(void *);
72 
73 
74 /*! @brief This type defines the Bus Manager token. Each callback registered
75  * with the Bus Manager receives a unique token value of this type. Certain Bus
76  * Manager API calls require the token value as an input parameter such as
77  * bm_start(), bm_stop(), and bm_unregister_callback().
78  */
80 
81 
82 
83 /*********************
84 ** Function Prototypes
85 */
86 
87 
88 /*! @brief This API initializes the Bus Manager.
89  *
90  *
91  * @details The Bus Manager requires a one time initialization at system
92  * startup performed by this API call. It creates and initializes internal
93  * variables. In addition, it installs an interrupt service routine for a
94  * hardware timer to be used by the Bus Manager to schedule callbacks.
95  *
96  * @return ::isf_status_t bm_init() returns a value of type
97  * ::isf_status_t providing the status of the
98  * initialization operation.
99  *
100  * @retval ::ISF_SUCCESS This value is returned if the
101  * initialization completed successfully.
102  *
103  * @retval ::ISF_ERR_LIB_INIT This value is returned if the
104  * interrupt service routine for the TPM timer used by
105  * the Bus Manager could not be installed.
106  *
107  * @Constraints The following constraints must be observed when using
108  * this function. If these constraints are not met, this
109  * API returns an error.
110  * @li There must not be any installed interrupt routines
111  * for the TPM timer used by the Bus Manager.
112  *
113  * @Reentrant No
114  *
115  * @Libs isf_core.lib
116  *
117  */
118 isf_status_t bm_init(void);
119 
120 
121 
122 
123 /*! @brief This API schedules a callback at the specified period.
124  *
125  * @details The Bus Manager schedules periodic sensor data automatically.
126  * It allows a registered callback to be automatically invoked at the
127  * specified period. Multiple callbacks registered for the same frequency
128  * are executed serially by the Bus Manager. If registration of the
129  * callback is successful, the callback is set to the inactive state.
130  * The API function bm_start() can be called to make the callback active.
131  *
132  * @param [in] aPeriod The period (1/frequency) between successive
133  * callback invocations in microseconds.
134  *
135  * @param [in] apCallback The pointer to the callback function to be
136  * registered.
137  *
138  * @param [in] apCbData The pointer passed to the callback function
139  * each time it is invoked. This pointer may be used
140  * to pass specific data to the callback function.
141  *
142  * @return bm_register_periodic_callback()
143  * returns a token of type ::bm_callback_token_t if the
144  * callback registration is successful.
145  *
146  * @retval ::COMM_ERROR_NULL_PTR This error value and the most
147  * significant bit of the macro ::BM_ERROR is
148  * returned if the callback function pointer is NULL.
149  *
150  * @retval ::COMM_ERROR_NOEXIST This error value and the most
151  * significant bit of the macro ::BM_ERROR is returned
152  * if either of the following conditions are true:
153  * @li The callback period is longer than
154  * ::MAX_BM_PERIOD_USEC or shorter than
155  * ::MIN_BM_PERIOD_USEC.
156  * @li The callback under registration exceeds the maximum
157  * number of callbacks allowed.
158  *
159  * @Constraints The following constraints must be observed when using
160  * this function. If these constraints are not met, this
161  * API returns an error.
162  * @li aPeriod must be within the valid range of
163  * ::MIN_BM_PERIOD_USEC to ::MAX_BM_PERIOD_USEC for the
164  * bus being initialized.
165  * @li apCallback callback function pointer must not
166  * be NULL.
167  * @li The number of callbacks registered must not
168  * exceed the maximum specified by ::MAX_BM_CALLBACKS.
169  *
170  * @Reentrant Yes
171  *
172  * @Libs isf_core.lib
173  *
174  */
175 
177  isf_duration_t aPeriod,
178  bm_callback_t *apCallback,
179  void *apCbData
180 );
181 
182 
183 /*! @brief This API unregisters one or more callbacks.
184  *
185  * @details The Bus Manager allows the removal of a registered callback.
186  * After a call to this function, unregistered callbacks no longer exist.
187  * To specify the callback to be unregistered, the token returned by
188  * bm_register_periodic_callback() is passed to bm_unregister_callback().
189  * Multiple callbacks can be specified by performing a logical OR of the
190  * token values. The callback can be in the active or inactive state when
191  * it is unregistered.
192  *
193  * @param [in] aTokens This parameter specifies the token value(s) of
194  * the callback(s) that are to be unregistered. More
195  * than one callback is specified by performing a logical
196  * OR of the token values associated with the registered
197  * callbacks.
198  *
199  * @return bm_unregister_callback() returns a value of type
200  * ::isf_status_t indicating the status of the
201  * unregister operation.
202  *
203  * @retval ::ISF_SUCCESS This value is returned if the callbacks
204  * unregistered successfully.
205  *
206  * @retval ::COMM_ERROR_NOEXIST This value is returned if at least
207  * one of the token values specified in aTokens is invalid
208  * because it is not associated with a registered callback.
209  *
210  * @Constraints The following constraints must be observed when using this
211  * function. If these constraints are not met, this API returns
212  * an error.
213  * @li aTokens value must be associated with registered
214  * callback(s).
215  *
216  * @Reentrant Yes
217  *
218  * @Libs isf_core.lib
219  *
220  * @see bm_register_periodic_callback()
221  *
222  */
224 
225 
226 
227 
228 /*! @brief This API sets one or more callback(s) to the active state.
229  *
230  * @details The start operation sets the callback(s) associated with
231  * the specified token values to the active state. A callback in the
232  * active state is invoked at its specified period. Multiple callbacks
233  * are specified by performing a logical OR of the token values. Any
234  * callbacks specified by this API call already in the active state,
235  * remain in the active state and their current timings are not
236  * affected. In addition to setting callbacks to the active state,
237  * this API can also synchronize the callback timings. The timings
238  * of all the active callbacks are reset to start running at the same
239  * time reference. The bm_stop() API call changes a callback to the
240  * inactive state.
241  *
242  * @param[in] aSync The parameter is set to TRUE to reset the timings
243  * of the active callbacks and start them running at the
244  * same time reference. The parameter is set to FALSE
245  * to leave all active callback timings as they are.
246  *
247  * @param[in] aTokens This parameter specifies the token value(s)
248  * of callback(s) to be set to the active state.
249  * More than one callback is specified by performing
250  * a logical OR of the token values associated with the
251  * registered callbacks.
252  *
253  * @return ::isf_status_t bm_start() returns a value of type
254  * ::isf_status_t providing the status of the start
255  * operation.
256  *
257  * @retval ::ISF_SUCCESS This value is returned if the callback(s)
258  * is set to the active state successfully.
259  *
260  * @retval ::COMM_ERROR_NOEXIST This value is returned if at least
261  * one of the token values specified is invalid because
262  * it is not associated with a registered callback.
263  *
264  * @Constraints The following constraints must be observed when using
265  * this function. If these constraints are not met, this
266  * API returns an error.
267  * @li aTokens value must be associated with the registered
268  * callback(s).
269  *
270  * @Reentrant Yes
271  *
272  * @Libs isf_core.lib
273  *
274  * @see bm_stop()
275  *
276  */
277 isf_status_t bm_start(boolean aSync, bm_callback_token_t aTokens);
278 
279 
280 
281 /*! @brief This API stops one or more callback(s) by setting them to
282  * the inactive state.
283  *
284  * @details The stop operation sets the the callback(s) associated
285  * with the specified token values to the inactive state. A callback
286  * in the inactive state is not invoked. Multiple callbacks are
287  * specified by performing a logical OR of the token values. Any
288  * callbacks specified by this API call already inactive will remain
289  * in the inactive state. To change a callback to the active state,
290  * the bm_start() API call is used.
291  *
292  * @param [in] aTokens This parameter specifies the token value(s) of
293  * callback(s) to be set to the inactive state. More
294  * than one callback is specified by performing a
295  * logical OR of the token values associated with the
296  * registered callbacks.
297  *
298  * @return ::isf_status_t bm_stop()returns a value of type
299  * ::isf_status_t providing the status of the stop
300  * operation.
301  *
302  * @retval ::ISF_SUCCESS The callback(s) stopped successfully.
303  *
304  * @retval ::COMM_ERROR_NOEXIST At least one of the token
305  * values specified is invalid because it is not
306  * associated with a registered callback.
307  *
308  * @Constraints The following constraints must be observed when using
309  * this function. If these constraints are not met, this
310  * API returns an error.
311  * @li aTokens value must be associated with registered
312  * callback(s).
313  *
314  * @Reentrant Yes
315  *
316  * @Libs isf_core.lib
317  *
318  * @see bm_start()
319  *
320  */
322 
323 
324 
325 /*! @brief This API returns the number of callbacks registered.
326  *
327  * @details The number of registered callbacks is returned regardless of
328  * their state, active or inactive.
329  *
330  * @return bm_get_num_callback() returns a value of type uint32
331  * providing the number of callbacks currently
332  * registered with the Bus Manager whether they are
333  * in the active or inactive state.
334  *
335  * @Constraints None
336  *
337  * @Reentrant Yes
338  *
339  * @Libs isf_core.lib
340  *
341  */
343 
344 
345 /*
346  * ! @brief This API exposes the ISF BM ISR routine.
347  */
348 void isr_bm_callback_tmr (pointer dummy);
349 
350 #endif /* BUS_MANAGEMENT_H */
351 
bm_callback_token_t bm_register_periodic_callback(isf_duration_t aPeriod, bm_callback_t *apCallback, void *apCbData)
This API schedules a callback at the specified period.
uint32 bm_get_num_callback(void)
This API returns the number of callbacks registered.
unsigned long uint32
This defines uint32 as unsigned long.
Definition: isf_types.h:36
uint32 bm_callback_token_t
This type defines the Bus Manager token. Each callback registered with the Bus Manager receives a uni...
Definition: isf_bm.h:79
isf_status_t bm_unregister_callback(bm_callback_token_t aTokens)
This API unregisters one or more callbacks.
isf_status_t bm_start(boolean aSync, bm_callback_token_t aTokens)
This API sets one or more callback(s) to the active state.
void( bm_callback_t)(void *)
Type for the prototype for a Bus Manager periodic callback function.
Definition: isf_bm.h:71
isf_status_t bm_init(void)
This API initializes the Bus Manager.
isf_status_t bm_stop(bm_callback_token_t aTokens)
This API stops one or more callback(s) by setting them to the inactive state.
uint32 isf_duration_t
ISF time duration in microseconds.
Definition: isf.h:59
void isr_bm_callback_tmr(pointer dummy)
int32 isf_status_t
ISF return status type.
Definition: isf.h:51