| ISF 2.1 Intelligent Sensing Framework for Kinetis with Processor Expert

- Main Page
- Modules
- Data Structures
- Files

- File List
- Globals

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Modules Pages
isf_ci.h
Go to the documentation of this file.
1 /*!
2 *
3 * Copyright (c) 2013, Freescale Semiconductor, Inc.
4 *
5 */
6
7 /*!
8 * @file isf_ci.h
9 *
10 * @brief API definitions, types, and macros for the Intelligent Sensing
11 * Framework (ISF) Command Interpreter (CI).
12 *
13 */
14
15 #ifndef ISF_CI_H_
16 #define ISF_CI_H_
17
18
19 #include "isf_types.h"
20
21
22
23 /**************
24 ** Enumerations
25 */
26
27
28 /*!
29 * @brief ISF CI return status type.
30 */
31 typedef enum
32 {
33 /*! This error indicates a general failure status. */
34 ISF_CI_FAILURE = 1,
35
36 /*! This error indicates at least one of the parameter is invalid. */
37 ISF_CI_FAILURE_INVALID_PARAMETERS = 2
38
39 } ci_status_enum;
40
41
42 /*!
43 * @brief CI read or write operation.
44 */
45 typedef enum
46 {
47
48 /*! CI NULL operation. */
49 CI_RW_NULL = 0,
50
51 /*! CI read operation. */
52 CI_RW_READ,
53
54 /*! CI write operation. */
55 CI_RW_WRITE
56
57 } ci_rw_enum;
58
59
60 /*!
61 * @brief CI host command instructions.
62 *
63 * @details The host indicates which command the Command Interpreter runs.
64 * ::ci_commands_enum is used to identify this command. The maximum number of
65 * possible commands is 128 represented by 7 bits.
66 *
67 */
68 typedef enum
69 {
70 /*! The host reads version information from ROM, firmware, or hardware. */
71 CI_CMD_READ_VERSION = 0,
72
73 /*! The host reads configuration data written by a specific application. */
74 CI_CMD_READ_CONFIG,
75
76 /*! The host writes configuration data to a specific application. */
77 CI_CMD_WRITE_CONFIG,
78
79 /*! The host reads data written by a specific application. */
80 CI_CMD_READ_APP_DATA,
81
82 /*! The host requests the application to update the Quick-Read data. */
83 CI_CMD_UPDATE_QUICKREAD,
84
85 /*! The host reads the application status. */
86 CI_CMD_READ_APP_STATUS,
87
88 /*! The host is requesting the application to reset. */
89 CI_CMD_RESET_APP,
90
91 /*! Maximum number of possible CI commands. */
92 CI_CMD_MAX = 128
93
94 } ci_commands_enum;
95
96
97
98
99
100 /*! @brief These are the CI errors provided to the host.
101 *
102 * @details Any errors identified by the Command Interpreter are returned
103 * to the host. Any of these errors may be passed back to the host from
104 * the application. There are 7 bits allocated to contain error status
105 * resulting in 128 possible different status values.
106 */
107 typedef enum
108 {
109
110 /*! The CI command completed without any errors. */
111 CI_ERROR_NONE = 0,
112
113 /*! This error indicates one or more parameters is incorrect. Specific
114 * reasons are an unrecognized application ID, an incomplete command,
115 * or an incorrect offset.
116 */
117 CI_ERROR_PARAM = 0x04,
118
119 /*! This error indicates that the byte count parameter is greater than
120 * the output structure size.
121 */
122 CI_INVALID_COUNT = 0x19,
123
124 /*! This error indicates that the command code is not recognized. */
125 CI_ERROR_COMMAND = 0x1c,
126
127 /*! This error indicates that the byte length parameter is invalid. */
128 CI_ERROR_INVALID_LENGTH = 0x21,
129
130 /*! This error indicates that the FIFO is busy performing a push operation
131 * and it is not possible to execute any other functions.
132 */
133 CI_ERROR_FIFO_BUSY = 0x22,
134
135 /*! This error indicates an error in the FIFO allocation. */
136 CI_ERROR_FIFO_ALLOCATED = 0x23,
137
138 /*! This error indicates that the host is trying to set a FIFO buffer size
139 * outside the memory boundary of the device.
140 */
141 CI_ERROR_FIFO_OVERSIZE = 0x24,
142
143 /*! This error indicates there is no callback registered for the given
144 * application ID.
145 */
146 CI_ERROR_CB_NOT_REGISTERED = 0x25,
147
148
149 /*! This status means the packet is a Quick Read response packet. */
150 CI_RESP_QUICKREAD = 0x40,
151
152 /*! The maximum possible error value. */
153 CI_ERROR_MAX = 0x80
154
155 } ci_response_enum;
156
157
158
159
160 /*******************
161 ** Macro Definitions
162 */
163
164 /*! @brief The maximum enumeration value implemented as a valid CI
165 * command.
166 */
167 #define CI_CMD_LAST CI_CMD_MAX
168
169
170
171 /*********************
172 ** Struct and Typedefs
173 */
174
175 /*! @brief Type definition for the CI status values. */
176 typedef ci_status_enum ci_status_t;
177
178
179
180 /*! @brief This structure contains host command information.
181 *
182 * @details This structure contains the host command and parameters
183 * passed to the embedded application for processing.
184 *
185 */
186 typedef struct
187 {
188 /*! Application ID */
189 uint8 appId;
190
191 /*! Host command */
192 uint8 cmd;
193
194 /*! Offset into the application's data */
195 uint16 offset;
196
197 /*! Number of bytes to read/write */
198 uint8 byte_cnt;
199
200 } ci_host_cmd_packet_t;
201
202
203
204 /*! @brief This structure enables an application to read from or write to
205 * the host.
206 *
207 * @details This structure is updated by the application's CI callback as
208 * a result of handling a command from the host.
209 */
210 typedef struct
211 {
212
213 /*! Application read from or write to the host:
214 * @li CI_RW_READ - application reads from the host.
215 * @li CI_RW_WRITE - application writes to the host.
216 */
217 ci_rw_enum rw;
218
219 /*! Number of bytes actually read from or written to the host via the
220 * mailboxes.
221 */
222 uint8 bytes_xfer;
223
224 /*! Number of bytes left to read from or write to the host via the
225 * mailboxes.
226 */
227 uint8 bytes_left;
228 } ci_app_resp_packet_t;
229
230
231
232 /*! @brief Type definition for the CI response values. */
233 typedef ci_response_enum ci_response_t;
234
235
236
237 /*! @brief This is a CI callback function pointer.
238 *
239 * @details Any application that responds to the host must have a CI
240 * callback defined.
241 */
242 typedef ci_response_t (*ci_funcp_t)(ci_host_cmd_packet_t *, ci_app_resp_packet_t *);
243
244
245
246 /*********************
247 ** Function Prototypes
248 */
249
250
251
252 /*!
253 *
254 * @brief This function is the mailbox application callback.
255 *
256 * @details This mailbox function is referred to as the mailbox application.
257 * This callback function is invoked when the host sends commands to the
258 * mailbox application via the mailboxes. This is the mechanism whereby
259 * the host reads or writes to the mailbox configuration data to configure
260 * the mailboxes for Quick-Read or the interrupt output (INT_O) behavior.
261 *
262 * @param [in] apHostPacket Host command packet pointer that points to
263 * a data structure of type ::ci_host_cmd_packet_t. The
264 * data structure contains the host command and
265 * parameters for the mailbox application to process.
266 *
267 * @param [in,out] apAppPacket An application response packet pointer that
268 * points to a data structure of type
269 * ::ci_app_resp_packet_t. The mailbox application
270 * fills this data structure with data as a result of
271 * handling the host command.
272 *
273 * @return isf_app_callback_mbox() returns a
274 * value of type ::ci_response_t indicating the status of
275 * the callback operation.
276 *
277 * @retval ::CI_ERROR_NONE The host command completed
278 * successfully.
279 *
280 * @retval ::CI_ERROR_COMMAND The host command in apHostPacket->cmd
281 * is not recognized.
282 *
283 * @retval ::CI_INVALID_COUNT The byte count in
284 * apHostPacket->byte_cnt is invalid because it is zero
285 * or it exceeds the mailbox configuration data size.
286 *
287 * @retval ::CI_ERROR_INVALID_LENGTH The byte count
288 * apHostPacket->byte combined with apHostPacket->offset
289 * exceeds the mailbox configuration data size.
290 *
291 * @Constraints The following constraints must be observed when using
292 * this function. If these constraints are not met, this
293 * API returns an error.
294 * @li A valid host command must be supplied.
295 * @li The number of bytes plus the offset to read or
296 * write is within the mailbox data size.
297 *
298 * @Reentrant No
299 *
300 * @Libs isf_core.lib
301 *
302 * @see ci_funcp_t, ci_response_t
303 *
304 */
305 extern ci_response_t isf_app_callback_mbox(ci_host_cmd_packet_t *apHostPacket, ci_app_resp_packet_t *apAppPacket);
306
307 /*!
308 *
309 *
310 * @brief Callback function for the device info command, ISF_APP_ID_DEV_INFO.
311 *
312 * @param apHostPacket - host command packet
313 *
314 * @param apAppPacket - application response packet.
315 *
316 * @return See ci_response_enum type for possible return values
317 *
318 * @errors None
319 *
320 * @constraints If another application is using the mailboxes, then the
321 * current calling application must wait until the other
322 * application has completed its operation on the mailboxes.
323 *
324 * @reentrant Yes.
325 *
326 * @libs
327 *
328 * @see
329 *
330 */
331 extern ci_response_t isf_app_callback_dev_info(ci_host_cmd_packet_t *apHostPacket, ci_app_resp_packet_t *apAppPacket);
332
333 /*! @brief This API writes data to the host via the mailboxes.
334 *
335 * @details This API function is called by an application that sends
336 * data to the host in response to a host command. Data is sent to the
337 * host via the mailboxes.
338 *
339 * @param [in] aAppId ID of application writing data to the host.
340 *
341 * @param [in] anumBytes The number of bytes to write to the mailboxes.
342 * The range is 1 to 28.
343 *
344 * @param [in] apSrc Pointer to the source of the data to write to
345 * the host.
346 *
347 * @return isf_ci_app_write() returns a value of type uint32
348 * which is the number of bytes written to the mailboxes
349 * for the host to retrieve.
350 *
351 * @Constraints The following constraints must be observed when using
352 * this function. If these constraints are not met, this
353 * API returns a zero for the number of bytes read from
354 * the mailboxes.
355 * @li anumBytes must be within the valid range of 1 to 28.
356 * @li apSrc cannot be NULL.
357 *
358 * @Reentrant Yes
359 *
360 * @Libs isf_core.lib
361 *
362 * @see isf_ci_app_read()
363 *
364 */
365 extern uint32 isf_ci_app_write(uint8 aAppId, uint32 anumBytes, uint8 *apSrc);
366
367
368 /*! @brief This API reads data from the host via the mailboxes.
369 *
370 * @details This API function is called by an application that reads data
371 * from the host in response to a host command.
372 *
373 * @param [in] aAppId ID of the application reading data from the host.
374 *
375 * @param [in] anumBytes The number of bytes to read from the
376 * mailboxes. The range is 1 to 28.
377 *
378 * @param [in] apDst Pointer to the destination where the data is to be
379 * stored.
380 *
381 * @return isf_ci_app_read() returns a value of type uint32
382 * containing the number of bytes read from the mailboxes
383 * written by the host.
384 *
385 * @Constraints The following constraints must be observed when using
386 * this function. If these constraints are not met, this
387 * API returns a zero for the number of bytes read from the
388 * mailboxes.
389 * @li anumBytes must be within the valid range of 1 to 28.
390 * @li apDst cannot be NULL.
391 *
392 * @Reentrant Yes
393 *
394 * @Libs isf_core.lib
395 *
396 * @see isf_ci_app_write()
397 */
398 extern uint32 isf_ci_app_read(uint8 aAppId, uint32 anumBytes, uint8 *apDst);
399
400
401
402 /*! @brief This API updates the Quick-Read mailboxes.
403 *
404 * @details This API function is called by an application to write data to
405 * the host via the mailboxes designated as Quick-Read for that application.
406 * The host must configure the mailboxes for Quick-Read by configuring the
407 * mailbox application. The host reads these Quick-Read mailboxes
408 * directly without sending a command to the CI.
409 *
410 * @param [in] aAppId ID of the application writing data to the
411 * mailboxes for the host.
412 *
413 * @param [in] anumBytes The number of bytes to write to the mailboxes.
414 * The range is 1 to 28.
415 *
416 * @param [in] apSrc Pointer to the source of the data to write to the
417 * mailboxes designated as Quick-Read for the application
418 * specified in appId.
419 *
420 * @return isf_ci_qr_update() returns a value of type
421 * ::ci_status_t providing the status of the
422 * Quick-Read operation.
423 *
424 * @retval ::ISF_SUCCESS The Quick-Read update completed
425 * successfully.
426 *
427 * @retval ::ISF_CI_FAILURE A timeout error occurred while waiting
428 * for the mailboxes to be free for updates.
429 *
430 * @Constraints The following constraints must be observed when using
431 * this function. If these constraints are not met, this
432 * API returns an error.
433 * @li anumbytes must be within the valid range of 1 to 28.
434 * @li apSrc cannot be NULL.
435 *
436 * @Reentrant Yes
437 *
438 * @Libs isf_core.lib
439 *
440 * @see ci_status_t
441 */
442 extern ci_status_t isf_ci_qr_update(uint8 aAppId, int8 anumBytes, uint8 *apSrc);
443
444
445
446
447
448 /**
449 * @brief This API initializes the Command Interpreter.
450 *
451 * @details The Command Interpreter requires a one time initialization at
452 * system startup performed by this API call. It creates and initializes
453 * internal variables. In addition, it installs an interrupt service
454 * routine for the slave-port interrupt.
455 *
456 * @return ci_init() returns a value of type
457 * ::isf_status_t providing the status of the
458 * initialization operation.
459 *
460 * @retval ::ISF_SUCCESS The initialization completed
461 * successfully.
462 *
463 * @retval ::ISF_ERR_LIB_INIT The interrupt service routine for
464 * the uart channel used by the Command Interpereter
465 * could not installed.
466 *
467 * @Constraints The following constraints must be observed when using
468 * this function. If these constraints are not met, this
469 * API returns an error.
470 * @li An interrupt routine for the uart channel used by
471 * the Command Interpereter has not been installed.
472 *
473 * @Reentrant No
474 *
475 * @Libs isf_core.lib
476 *
477 * @see ci_status_t
478 */
479 isf_status_t ci_init(void);
480
481
482
483
484 #endif /* ISF_CI_H_ */
485
ci_response_t
ci_response_enum ci_response_t
Type definition for the CI response values.
Definition: isf_ci.h:233
uint8
unsigned char uint8
This defines uint8 as unsigned char.
Definition: isf_types.h:18
CI_RW_WRITE
Definition: isf_ci.h:55
CI_CMD_READ_CONFIG
Definition: isf_ci.h:74
ci_host_cmd_packet_t::byte_cnt
uint8 byte_cnt
Definition: isf_ci.h:198
ci_host_cmd_packet_t::offset
uint16 offset
Definition: isf_ci.h:195
ISF_CI_FAILURE
Definition: isf_ci.h:34
ci_status_t
ci_status_enum ci_status_t
Type definition for the CI status values.
Definition: isf_ci.h:176
isf_ci_app_write
uint32 isf_ci_app_write(uint8 aAppId, uint32 anumBytes, uint8 *apSrc)
This API writes data to the host via the mailboxes.
Definition: ci_protocol_mbox.c:268
ci_rw_enum
ci_rw_enum
CI read or write operation.
Definition: isf_ci.h:45
CI_ERROR_INVALID_LENGTH
Definition: isf_ci.h:128
CI_ERROR_COMMAND
Definition: isf_ci.h:125
CI_ERROR_FIFO_OVERSIZE
Definition: isf_ci.h:141
CI_CMD_UPDATE_QUICKREAD
Definition: isf_ci.h:83
int8
signed char int8
Definition: basic_types.h:12
isf_app_callback_dev_info
ci_response_t isf_app_callback_dev_info(ci_host_cmd_packet_t *apHostPacket, ci_app_resp_packet_t *apAppPacket)
Callback function for the device info command, ISF_APP_ID_DEV_INFO.
Definition: ci_protocol_mbox.c:767
uint32
unsigned long uint32
This defines uint32 as unsigned long.
Definition: isf_types.h:36
ci_host_cmd_packet_t::cmd
uint8 cmd
Definition: isf_ci.h:192
CI_RESP_QUICKREAD
Definition: isf_ci.h:150
ci_app_resp_packet_t::rw
ci_rw_enum rw
Definition: isf_ci.h:217
ci_app_resp_packet_t::bytes_xfer
uint8 bytes_xfer
Definition: isf_ci.h:222
CI_ERROR_FIFO_BUSY
Definition: isf_ci.h:133
CI_CMD_MAX
Definition: isf_ci.h:92
CI_RW_NULL
Definition: isf_ci.h:49
isf_types.h
The isf_types.h file contains the ISF data type definitions and some of the globally used macros...
isf_ci_app_read
uint32 isf_ci_app_read(uint8 aAppId, uint32 anumBytes, uint8 *apDst)
This API reads data from the host via the mailboxes.
Definition: ci_protocol_mbox.c:211
CI_RW_READ
Definition: isf_ci.h:52
CI_ERROR_CB_NOT_REGISTERED
Definition: isf_ci.h:146
CI_CMD_READ_APP_DATA
Definition: isf_ci.h:80
CI_CMD_READ_APP_STATUS
Definition: isf_ci.h:86
CI_INVALID_COUNT
Definition: isf_ci.h:122
isf_ci_qr_update
ci_status_t isf_ci_qr_update(uint8 aAppId, int8 anumBytes, uint8 *apSrc)
This API updates the Quick-Read mailboxes.
Definition: ci_protocol_mbox.c:80
CI_ERROR_FIFO_ALLOCATED
Definition: isf_ci.h:136
ci_app_resp_packet_t::bytes_left
uint8 bytes_left
Definition: isf_ci.h:227
ISF_CI_FAILURE_INVALID_PARAMETERS
Definition: isf_ci.h:37
CI_ERROR_PARAM
Definition: isf_ci.h:117
ci_status_enum
ci_status_enum
ISF CI return status type.
Definition: isf_ci.h:31
ci_funcp_t
ci_response_t(* ci_funcp_t)(ci_host_cmd_packet_t *, ci_app_resp_packet_t *)
This is a CI callback function pointer.
Definition: isf_ci.h:242
CI_CMD_READ_VERSION
Definition: isf_ci.h:71
uint16
unsigned short uint16
This defines uint16 as unsigned short.
Definition: isf_types.h:27
ci_app_resp_packet_t
This structure enables an application to read from or write to the host.
Definition: isf_ci.h:210
isf_status_t
int32 isf_status_t
ISF return status type.
Definition: isf.h:51
ci_commands_enum
ci_commands_enum
CI host command instructions.
Definition: isf_ci.h:68
isf_app_callback_mbox
ci_response_t isf_app_callback_mbox(ci_host_cmd_packet_t *apHostPacket, ci_app_resp_packet_t *apAppPacket)
This function is the mailbox application callback.
Definition: ci_protocol_mbox.c:626
ci_host_cmd_packet_t
This structure contains host command information.
Definition: isf_ci.h:186
CI_ERROR_MAX
Definition: isf_ci.h:153
ci_init
isf_status_t ci_init(void)
This API initializes the Command Interpreter.
Definition: task_ci.c:584
CI_ERROR_NONE
Definition: isf_ci.h:111
ci_host_cmd_packet_t::appId
uint8 appId
Definition: isf_ci.h:189
ci_response_enum
ci_response_enum
These are the CI errors provided to the host.
Definition: isf_ci.h:107
CI_CMD_RESET_APP
Definition: isf_ci.h:89
CI_CMD_WRITE_CONFIG
Definition: isf_ci.h:77
- © Freescale Semiconductor, Inc. 2015. All Rights Reserved.