![]() |
ISF
1.1
Intelligent Sensing Framework
|
00001 /*! 00002 * 00003 * Copyright (c) 2012, Freescale Semiconductor, Inc. 00004 * 00005 */ 00006 00007 /*! 00008 * @file isf_ci.h 00009 * 00010 * @brief API definitions, types, and macros for the Intelligent Sensing 00011 * Framework (ISF) Command Interpreter (CI). 00012 * 00013 */ 00014 00015 #ifndef ISF_CI_H_ 00016 #define ISF_CI_H_ 00017 00018 00019 00020 #include "isf_types.h" 00021 00022 00023 00024 #ifdef __cplusplus 00025 extern "C" { 00026 #endif 00027 00028 00029 // Use byte alignment for structures 00030 #pragma pack(push) 00031 #pragma pack(1) 00032 00033 00034 00035 /************** 00036 ** Enumerations 00037 */ 00038 00039 00040 /*! 00041 * @brief ISF CI return status type. 00042 */ 00043 typedef enum 00044 { 00045 /*! This error indicates a general failure status. */ 00046 ISF_CI_FAILURE = 1, 00047 00048 /*! This error indicates at least one of the parameter is invalid. */ 00049 ISF_CI_FAILURE_INVALID_PARAMETERS = 2 00050 00051 } ci_status_enum; 00052 00053 00054 /*! 00055 * @brief CI read or write operation. 00056 */ 00057 typedef enum 00058 { 00059 00060 /*! CI NULL operation. */ 00061 CI_RW_NULL = 0, 00062 00063 /*! CI read operation. */ 00064 CI_RW_READ, 00065 00066 /*! CI write operation. */ 00067 CI_RW_WRITE 00068 00069 } ci_rw_enum; 00070 00071 00072 /*! 00073 * @brief CI host command instructions. 00074 * 00075 * @details The host indicates which command the Command Interpreter runs. 00076 * ::ci_commands_enum is used to identify this command. The maximum number of 00077 * possible commands is 128 represented by 7 bits. 00078 * 00079 */ 00080 typedef enum 00081 { 00082 /*! The host reads version information from ROM, firmware, or hardware. */ 00083 CI_CMD_READ_VERSION = 0, 00084 00085 /*! The host reads configuration data written by a specific application. */ 00086 CI_CMD_READ_CONFIG, 00087 00088 /*! The host writes configuration data to a specific application. */ 00089 CI_CMD_WRITE_CONFIG, 00090 00091 /*! The host reads data written by a specific application. */ 00092 CI_CMD_READ_APP_DATA, 00093 00094 /*! The host requests the application to update the Quick-Read data. */ 00095 CI_CMD_UPDATE_QUICKREAD, 00096 00097 /*! The host reads the application status. */ 00098 CI_CMD_READ_APP_STATUS, 00099 00100 /*! Maximum number of possible CI commands. */ 00101 CI_CMD_MAX = 128 00102 00103 } ci_commands_enum; 00104 00105 00106 00107 00108 00109 /*! @brief These are the CI errors provided to the host. 00110 * 00111 * @details Any errors identified by the Command Interpreter are returned 00112 * to the host. Any of these errors may be passed back to the host from 00113 * the application. There are 7 bits allocated to contain error status 00114 * resulting in 128 possible different status values. 00115 */ 00116 typedef enum 00117 { 00118 00119 /*! The CI command completed without any errors. */ 00120 CI_ERROR_NONE = 0, 00121 00122 /*! This error indicates one or more parameters is incorrect. Specific 00123 * reasons are an unrecognized application ID, an incomplete command, 00124 * or an incorrect offset. 00125 */ 00126 CI_ERROR_PARAM = 0x04, 00127 00128 /*! This error indicates that the byte count parameter is greater than 00129 * the output structure size. 00130 */ 00131 CI_INVALID_COUNT = 0x19, 00132 00133 /*! This error indicates that the command code is not recognized. */ 00134 CI_ERROR_COMMAND = 0x1c, 00135 00136 /*! This error indicates that the byte length parameter is invalid. */ 00137 CI_ERROR_INVALID_LENGTH = 0x21, 00138 00139 /*! This error indicates that the FIFO is busy performing a push operation 00140 * and it is not possible to execute any other functions. 00141 */ 00142 CI_ERROR_FIFO_BUSY = 0x22, 00143 00144 /*! This error indicates an error in the FIFO allocation. */ 00145 CI_ERROR_FIFO_ALLOCATED = 0x23, 00146 00147 /*! This error indicates that the host is trying to set a FIFO buffer size 00148 * outside the memory boundary of the device. 00149 */ 00150 CI_ERROR_FIFO_OVERSIZE = 0x24, 00151 00152 /*! This error indicates there is no callback registered for the given 00153 * application ID. 00154 */ 00155 CI_ERROR_CB_NOT_REGISTERED = 0x25, 00156 00157 /*! The maximum possible error value. */ 00158 CI_ERROR_MAX = 0x80 00159 00160 } ci_response_enum; 00161 00162 00163 00164 00165 /******************* 00166 ** Macro Definitions 00167 */ 00168 00169 /*! @brief The maximum enumeration value implemented as a valid CI 00170 * command. 00171 */ 00172 #define CI_CMD_LAST CI_CMD_MAX 00173 00174 00175 00176 /********************* 00177 ** Struct and Typedefs 00178 */ 00179 00180 /*! @brief Type definition for the CI status values. */ 00181 typedef ci_status_enum ci_status_t; 00182 00183 00184 00185 /*! @brief This structure contains host command information. 00186 * 00187 * @details This structure contains the host command and parameters 00188 * passed to the embedded application for processing. 00189 * 00190 */ 00191 typedef struct 00192 { 00193 /*! Application ID */ 00194 uint8 appId; 00195 00196 /*! Host command */ 00197 uint8 cmd; 00198 00199 /*! Offset into the application's data */ 00200 uint16 offset; 00201 00202 /*! Number of bytes to read/write */ 00203 uint8 byte_cnt; 00204 00205 } ci_host_cmd_packet_t; 00206 00207 00208 00209 /*! @brief This structure enables an application to read from or write to 00210 * the host. 00211 * 00212 * @details This structure is updated by the application's CI callback as 00213 * a result of handling a command from the host. 00214 */ 00215 typedef struct 00216 { 00217 00218 /*! Application read from or write to the host: 00219 * @li CI_RW_READ - application reads from the host. 00220 * @li CI_RW_WRITE - application writes to the host. 00221 */ 00222 ci_rw_enum rw; 00223 00224 /*! Number of bytes actually read from or written to the host via the 00225 * mailboxes. 00226 */ 00227 uint8 bytes_xfer; 00228 00229 /*! Number of bytes left to read from or write to the host via the 00230 * mailboxes. 00231 */ 00232 uint8 bytes_left; 00233 } ci_app_resp_packet_t; 00234 00235 00236 00237 /*! @brief Type definition for the CI response values. */ 00238 typedef ci_response_enum ci_response_t; 00239 00240 00241 00242 /*! @brief This is a CI callback function pointer. 00243 * 00244 * @details Any application that responds to the host must have a CI 00245 * callback defined. 00246 */ 00247 typedef ci_response_t (*ci_funcp_t)(ci_host_cmd_packet_t *, ci_app_resp_packet_t *); 00248 00249 00250 00251 /********************* 00252 ** Function Prototypes 00253 */ 00254 00255 00256 00257 /*! 00258 * 00259 * @brief This function is the mailbox application callback. 00260 * 00261 * @details This mailbox function is referred to as the mailbox application. 00262 * This callback function is invoked when the host sends commands to the 00263 * mailbox application via the mailboxes. This is the mechanism whereby 00264 * the host reads or writes to the mailbox configuration data to configure 00265 * the mailboxes for Quick-Read or the interrupt output (INT_O) behavior. 00266 * 00267 * @param [in] apHostPacket Host command packet pointer that points to 00268 * a data structure of type ::ci_host_cmd_packet_t. The 00269 * data structure contains the host command and 00270 * parameters for the mailbox application to process. 00271 * 00272 * @param [in,out] apAppPacket An application response packet pointer that 00273 * points to a data structure of type 00274 * ::ci_app_resp_packet_t. The mailbox application 00275 * fills this data structure with data as a result of 00276 * handling the host command. 00277 * 00278 * @return isf_app_callback_mbox() returns a 00279 * value of type ::ci_response_t indicating the status of 00280 * the callback operation. 00281 * 00282 * @retval ::CI_ERROR_NONE The host command completed 00283 * successfully. 00284 * 00285 * @retval ::CI_ERROR_COMMAND The host command in apHostPacket->cmd 00286 * is not recognized. 00287 * 00288 * @retval ::CI_INVALID_COUNT The byte count in 00289 * apHostPacket->byte_cnt is invalid because it is zero 00290 * or it exceeds the mailbox configuration data size. 00291 * 00292 * @retval ::CI_ERROR_INVALID_LENGTH The byte count 00293 * apHostPacket->byte combined with apHostPacket->offset 00294 * exceeds the mailbox configuration data size. 00295 * 00296 * @Constraints The following constraints must be observed when using 00297 * this function. If these constraints are not met, this 00298 * API returns an error. 00299 * @li A valid host command must be supplied. 00300 * @li The number of bytes plus the offset to read or 00301 * write is within the mailbox data size. 00302 * 00303 * @Reentrant No 00304 * 00305 * @Libs isf_core.lib 00306 * 00307 * @see ci_funcp_t, ci_response_t 00308 * 00309 */ 00310 extern ci_response_t isf_app_callback_mbox(ci_host_cmd_packet_t *apHostPacket, ci_app_resp_packet_t *apAppPacket); 00311 00312 /*! 00313 * 00314 * 00315 * @brief Callback function for the device info command, ISF_APP_ID_DEV_INFO. 00316 * 00317 * @param apHostPacket - host command packet 00318 * 00319 * @param apAppPacket - pointer to first mailbox address containing \n 00320 * data. 00321 * 00322 * @return See ci_response_enum type for possible return values 00323 * 00324 * @errors None 00325 * 00326 * @Constraints If another application is using the mailboxes, then the current calling application must wait until the other application 00327 * has completed its operation on the mailboxes. 00328 * 00329 * @reentrant Yes. 00330 * 00331 * @libs isf_core.lib 00332 * 00333 * @see None 00334 * 00335 */ 00336 extern ci_response_t isf_app_callback_dev_info(ci_host_cmd_packet_t *apHostPacket, ci_app_resp_packet_t *apAppPacket); 00337 00338 /*! @brief This API writes data to the host via the mailboxes. 00339 * 00340 * @details This API function is called by an application that sends 00341 * data to the host in response to a host command. Data is sent to the 00342 * host via the mailboxes. 00343 * 00344 * @param [in] aAppId ID of application writing data to the host. 00345 * 00346 * @param [in] anumBytes The number of bytes to write to the mailboxes. 00347 * The range is 1 to 28. 00348 * 00349 * @param [in] apSrc Pointer to the source of the data to write to 00350 * the host. 00351 * 00352 * @return isf_ci_app_write() returns a value of type uint32 00353 * which is the number of bytes written to the mailboxes 00354 * for the host to retrieve. 00355 * 00356 * @Constraints The following constraints must be observed when using 00357 * this function. If these constraints are not met, this 00358 * API returns a zero for the number of bytes read from 00359 * the mailboxes. 00360 * @li anumBytes must be within the valid range of 1 to 28. 00361 * @li apSrc cannot be NULL. 00362 * 00363 * @Reentrant Yes 00364 * 00365 * @Libs isf_core.lib 00366 * 00367 * @see isf_ci_app_read() 00368 * 00369 */ 00370 extern uint32 isf_ci_app_write(uint8 aAppId, uint32 anumBytes, uint8 *apSrc); 00371 00372 00373 /*! @brief This API reads data from the host via the mailboxes. 00374 * 00375 * @details This API function is called by an application that reads data 00376 * from the host in response to a host command. 00377 * 00378 * @param [in] aAppId ID of the application reading data from the host. 00379 * 00380 * @param [in] anumBytes The number of bytes to read from the 00381 * mailboxes. The range is 1 to 28. 00382 * 00383 * @param [in] apDst Pointer to the destination where the data is to be 00384 * stored. 00385 * 00386 * @return isf_ci_app_read() returns a value of type uint32 00387 * containing the number of bytes read from the mailboxes 00388 * written by the host. 00389 * 00390 * @Constraints The following constraints must be observed when using 00391 * this function. If these constraints are not met, this 00392 * API returns a zero for the number of bytes read from the 00393 * mailboxes. 00394 * @li anumBytes must be within the valid range of 1 to 28. 00395 * @li apDst cannot be NULL. 00396 * 00397 * @Reentrant Yes 00398 * 00399 * @Libs isf_core.lib 00400 * 00401 * @see isf_ci_app_write() 00402 */ 00403 extern uint32 isf_ci_app_read(uint8 aAppId, uint32 anumBytes, uint8 *apDst); 00404 00405 00406 00407 /*! @brief This API updates the Quick-Read mailboxes. 00408 * 00409 * @details This API function is called by an application to write data to 00410 * the host via the mailboxes designated as Quick-Read for that application. 00411 * The host must configure the mailboxes for Quick-Read by configuring the 00412 * mailbox application. The host reads these Quick-Read mailboxes 00413 * directly without sending a command to the CI. 00414 * 00415 * @param [in] aAppId ID of the application writing data to the 00416 * mailboxes for the host. 00417 * 00418 * @param [in] anumBytes The number of bytes to write to the mailboxes. 00419 * The range is 1 to 28. 00420 * 00421 * @param [in] apSrc Pointer to the source of the data to write to the 00422 * mailboxes designated as Quick-Read for the application 00423 * specified in appId. 00424 * 00425 * @return isf_ci_qr_update() returns a value of type 00426 * ::ci_status_t providing the status of the 00427 * Quick-Read operation. 00428 * 00429 * @retval ::ISF_SUCCESS The Quick-Read update completed 00430 * successfully. 00431 * 00432 * @retval ::ISF_CI_FAILURE A timeout error occurred while waiting 00433 * for the mailboxes to be free for updates. 00434 * 00435 * @Constraints The following constraints must be observed when using 00436 * this function. If these constraints are not met, this 00437 * API returns an error. 00438 * @li anumbytes must be within the valid range of 1 to 28. 00439 * @li apSrc cannot be NULL. 00440 * 00441 * @Reentrant Yes 00442 * 00443 * @Libs isf_core.lib 00444 * 00445 * @see ci_status_t 00446 */ 00447 extern ci_status_t isf_ci_qr_update(uint8 aAppId, int8 anumBytes, uint8 *apSrc); 00448 00449 00450 00451 00452 00453 /** 00454 * @brief This API initializes the Command Interpreter. 00455 * 00456 * @details The Command Interpreter requires a one time initialization at 00457 * system startup performed by this API call. It creates and initializes 00458 * internal variables. In addition, it installs an interrupt service 00459 * routine for the slave-port interrupt. 00460 * 00461 * @return ci_init() returns a value of type 00462 * ::isf_status_t providing the status of the 00463 * initialization operation. 00464 * 00465 * @retval ::ISF_SUCCESS The initialization completed 00466 * successfully. 00467 * 00468 * @retval ::ISF_ERR_LIB_INIT The interrupt service routine for 00469 * the FXLC95000 slave-port mailboxes could not 00470 * installed. 00471 * 00472 * @Constraints The following constraints must be observed when using 00473 * this function. If these constraints are not met, this 00474 * API returns an error. 00475 * @li An interrupt routine for the FXLC95000 slave-port 00476 * has not been installed. 00477 * 00478 * @Reentrant No 00479 * 00480 * @Libs isf_core.lib 00481 * 00482 * @see ci_status_t 00483 */ 00484 isf_status_t ci_init(void); 00485 00486 00487 00488 00489 /*! @brief This API asserts the FXLC95000 INT_O pin. 00490 * 00491 * @details The FXLC95000CL has the ability to notify the host when data 00492 * is written to the mailboxes by asserting the INT_O output pin of the 00493 * FXLC95000CL device. This API asserts the INT_O pin to notify the host 00494 * that data is ready in the mailboxes by writing a 1 to the SP_OIC[SET] 00495 * register bit. 00496 * 00497 * @Constraints The following constraints must be observed when using 00498 * this function. In order for the INT_O pin to be asserted 00499 * properly, the following registers must be set up as 00500 * described in the FXLC95000 Hardware Reference Manual. 00501 * @li The PMCR2 register must have RGPIO5 configured for 00502 * INT_O functionality. 00503 * @li The slave-port peripheral clock must be enabled for 00504 * INT_O to be asserted. 00505 * @li SP_OIC[POL] is set for the desired INT_O polarity. 00506 * 00507 * @Reentrant Yes. 00508 * 00509 * @Libs isf_core.lib 00510 */ 00511 void isf_ci_assert_int_o(void); 00512 00513 /*! @brief This API enables the Command Interpreter to assert INT_O whenever 00514 * response data is written to the mailboxes. 00515 * 00516 * @details The FXLC95000CL has the ability to notify the host when data 00517 * is written to the mailboxes by asserting the INT_O output pin of the 00518 * FXLC95000CL device. This API sets the Command Interpreter configuration 00519 * to enable this functionality. 00520 * 00521 * @Constraints The following constraints must be observed when using 00522 * this function. In order for the INT_O pin to be asserted 00523 * properly, the following registers must be set up as 00524 * described in the FXLC95000 Hardware Reference Manual. 00525 * @li The PMCR2 register must have RGPIO5 configured for 00526 * INT_O functionality. 00527 * @li The slave-port peripheral clock must be enabled for 00528 * INT_O to be asserted. 00529 * @li SP_OIC[POL] is set for the desired INT_O polarity. 00530 * 00531 * @param [in] enable Value used to determine whether the INT_O function 00532 * is enabled (1) or disabled (0). 00533 * 00534 * @Reentrant Yes. 00535 * 00536 * @Libs isf_core.lib 00537 */ 00538 void isf_ci_enable_int_o(uint8 enable); 00539 00540 /*! @brief This API sets the interrupt output pin polarity. 00541 * 00542 * @details \n 00543 * 00544 * @param[in] pol Polarity. 1 - INT_O is configured to be active low. 0 - INT_O is configured to be active high. 00545 * 00546 * @Constraints The Slave Port peripheral clock must be enabled for this function to work properly. 00547 * 00548 * @Reentrant Yes. 00549 * @Libs \n 00550 * @see \n 00551 */ 00552 void isf_ci_set_int_o_polarity(uint8 pol); 00553 00554 #pragma pack(pop) 00555 00556 00557 #ifdef __cplusplus 00558 } /* extern "C" */ 00559 #endif 00560 00561 00562 00563 00564 #endif /* ISF_CI_H_ */