ISF  1.1
Intelligent Sensing Framework
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines
Include/isf_ci.h
Go to the documentation of this file.
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_ */