| ISF 1.1 Intelligent Sensing Framework

- Main Page
- Data Structures
- Files
- Sensor Adapters

- File List
- Globals

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_ */