ISF  2.1
Intelligent Sensing Framework for Kinetis with Processor Expert
 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. */
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  /*! Maximum number of possible CI commands. */
92  CI_CMD_MAX = 128
93 
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. */
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  */
123 
124  /*! This error indicates that the command code is not recognized. */
126 
127  /*! This error indicates that the byte length parameter is invalid. */
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  */
134 
135  /*! This error indicates an error in the FIFO allocation. */
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  */
142 
143  /*! This error indicates there is no callback registered for the given
144  * application ID.
145  */
147 
148 
149  /*! This status means the packet is a Quick Read response packet. */
151 
152  /*! The maximum possible error value. */
153  CI_ERROR_MAX = 0x80
154 
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. */
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 */
190 
191  /*! Host command */
193 
194  /*! Offset into the application's data */
196 
197  /*! Number of bytes to read/write */
199 
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  */
218 
219  /*! Number of bytes actually read from or written to the host via the
220  * mailboxes.
221  */
223 
224  /*! Number of bytes left to read from or write to the host via the
225  * mailboxes.
226  */
229 
230 
231 
232 /*! @brief Type definition for the CI response values. */
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  */
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  */
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 */
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_enum ci_response_t
Type definition for the CI response values.
Definition: isf_ci.h:233
unsigned char uint8
This defines uint8 as unsigned char.
Definition: isf_types.h:18
ci_status_enum ci_status_t
Type definition for the CI status values.
Definition: isf_ci.h:176
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
signed char int8
Definition: basic_types.h:12
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.
unsigned long uint32
This defines uint32 as unsigned long.
Definition: isf_types.h:36
ci_rw_enum rw
Definition: isf_ci.h:217
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.
ci_status_enum
ISF CI return status type.
Definition: isf_ci.h:31
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
unsigned short uint16
This defines uint16 as unsigned short.
Definition: isf_types.h:27
This structure enables an application to read from or write to the host.
Definition: isf_ci.h:210
int32 isf_status_t
ISF return status type.
Definition: isf.h:51
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:186
isf_status_t ci_init(void)
This API initializes the Command Interpreter.
Definition: task_ci.c:584
ci_response_enum
These are the CI errors provided to the host.
Definition: isf_ci.h:107