ISF  2.2 rev 5
Intelligent Sensing Framework for Kinetis with Processor Expert
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. */
35 
36  /*! This error indicates at least one of the parameter is invalid. */
38 
40 
41 
42 /*!
43  * @brief CI read or write operation.
44 */
45 typedef enum
46 {
47 
48  /*! CI NULL operation. */
50 
51  /*! CI read operation. */
53 
54  /*! CI write operation. */
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. */
72 
73  /*! The host reads configuration data written by a specific application. */
75 
76  /*! The host writes configuration data to a specific application. */
78 
79  /*! The host reads data written by a specific application. */
81 
82  /*! The host requests the application to update the Quick-Read data. */
84 
85  /*! The host reads the application status. */
87 
88  /*! The host is requesting the application to reset. */
90 
91  /*! The host is requesting to write to a slave device (RLI command) */
93 
94  /*! The host is requesting to read from a slave device (RLI Command) */
96 
97  /*! The host is requesting to get application sensor subscriptions info. */
99 
100  /*! The host is writing SREC Flash data to be sent to a specific subscription. */
102 
103  /*! Maximum number of possible CI commands. */
105 
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. */
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  */
135 
136  /*! This error indicates that the command code is not recognized. */
138 
139  /*! This error indicates that the byte length parameter is invalid. */
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  */
146 
147  /*! This error indicates an error in the FIFO allocation. */
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  */
154 
155  /*! This error indicates there is no callback registered for the given
156  * application ID.
157  */
159 
160 
161  /*! This status means the packet is a Quick Read response packet. */
163 
164  /*! The maximum possible error value. */
165  CI_ERROR_MAX = 0x80
166 
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. */
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 */
201 
202  /*! Host command */
204 
205  /*! Offset into the application's data */
207 
208  /*! Number of bytes to read/write */
210 
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  */
229 
230  /*! Number of bytes actually read from or written to the host via the
231  * mailboxes.
232  */
234 
235  /*! Number of bytes left to read from or write to the host via the
236  * mailboxes.
237  */
240 
241 
242 
243 /*! @brief Type definition for the CI response values. */
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  */
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  */
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 */
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_enum ci_response_t
Type definition for the CI response values.
Definition: isf_ci.h:244
unsigned char uint8
Definition: isf_types.h:76
ci_status_enum ci_status_t
Type definition for the CI status values.
Definition: isf_ci.h:187
uint32 isf_ci_app_write(uint8 aAppId, uint32 anumBytes, uint8 *apSrc)
This API writes data to the host via the mailboxes.
ci_rw_enum
CI read or write operation.
Definition: isf_ci.h:45
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.
ci_rw_enum rw
Definition: isf_ci.h:228
The isf_types.h file contains the ISF data type definitions and some of the globally used macros...
uint32 isf_ci_app_read(uint8 aAppId, uint32 anumBytes, uint8 *apDst)
This API reads data from the host via the mailboxes.
ci_status_t isf_ci_qr_update(uint8 aAppId, int8 anumBytes, uint8 *apSrc)
This API updates the Quick-Read mailboxes.
unsigned short int uint16
Definition: isf_types.h:77
ci_status_enum
ISF CI return status type.
Definition: isf_ci.h:31
This structure enables an application to read from or write to the host.
Definition: isf_ci.h:221
int32 isf_status_t
ISF return status type.
Definition: isf.h:76
ci_commands_enum
CI host command instructions.
Definition: isf_ci.h:68
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.
This structure contains host command information.
Definition: isf_ci.h:197
isf_status_t ci_init(void)
This API initializes the Command Interpreter.
Definition: task_ci.c:580
unsigned long int uint32
Definition: isf_types.h:78
ci_response_enum
These are the CI errors provided to the host.
Definition: isf_ci.h:119
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
signed char int8
Definition: isf_types.h:72