| ISF 2.2 rev 5 Intelligent Sensing Framework for Kinetis with Processor Expert

- Main Page
- Modules
- Data Structures
- Files

- File List
- Globals

isf_bm.h
Go to the documentation of this file.
1 /*
2 *
3 * Copyright (c) 2015, 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 */
79 typedef uint32 bm_callback_token_t;
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
176 bm_callback_token_t bm_register_periodic_callback(
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 */
223 isf_status_t bm_unregister_callback( bm_callback_token_t aTokens );
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 */
321 isf_status_t bm_stop(bm_callback_token_t aTokens);
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 */
342 uint32 bm_get_num_callback(void);
343
344
345 /*
346 * ! @brief This API exposes the ISF BM ISR routine.
347 */
348 void isr_bm_callback_tmr (void* dummy);
349
350 #endif /* BUS_MANAGEMENT_H */
351
bm_register_periodic_callback
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.
Definition: bus_management.c:94
bm_get_num_callback
uint32 bm_get_num_callback(void)
This API returns the number of callbacks registered.
Definition: bus_management.c:252
bm_callback_token_t
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
bm_unregister_callback
isf_status_t bm_unregister_callback(bm_callback_token_t aTokens)
This API unregisters one or more callbacks.
Definition: bus_management.c:178
bm_start
isf_status_t bm_start(boolean aSync, bm_callback_token_t aTokens)
This API sets one or more callback(s) to the active state.
Definition: bus_management.c:278
bm_init
isf_status_t bm_init(void)
This API initializes the Bus Manager.
Definition: bus_management.c:445
bm_stop
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.
Definition: bus_management.c:349
isr_bm_callback_tmr
void isr_bm_callback_tmr(void *dummy)
Definition: bus_management.c:570
isf_duration_t
uint32 isf_duration_t
ISF time duration in microseconds.
Definition: isf.h:84
bm_callback_t
void( bm_callback_t)(void *)
Type for the prototype for a Bus Manager periodic callback function.
Definition: isf_bm.h:71
isf_status_t
int32 isf_status_t
ISF return status type.
Definition: isf.h:76
uint32
unsigned long int uint32
Definition: isf_types.h:78
- © Freescale Semiconductor, Inc. 2016. All Rights Reserved.