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

- Main Page
- Modules
- Data Structures
- Files

- File List
- Globals

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