ISF  1.1
Intelligent Sensing Framework
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines
Include/isf_ci.h File Reference

API definitions, types, and macros for the Intelligent Sensing Framework (ISF) Command Interpreter (CI). More...

#include "isf_types.h"

Go to the source code of this file.

Data Structures

struct  ci_host_cmd_packet_t
 This structure contains host command information. More...
struct  ci_app_resp_packet_t
 This structure enables an application to read from or write to the host. More...

Defines

#define CI_CMD_LAST   CI_CMD_MAX
 The maximum enumeration value implemented as a valid CI command.

Typedefs

typedef ci_status_enum ci_status_t
 Type definition for the CI status values.
typedef ci_response_enum ci_response_t
 Type definition for the CI response values.
typedef ci_response_t(* ci_funcp_t )(ci_host_cmd_packet_t *, ci_app_resp_packet_t *)
 This is a CI callback function pointer.

Enumerations

enum  ci_status_enum { ISF_CI_FAILURE = 1, ISF_CI_FAILURE_INVALID_PARAMETERS = 2 }
 ISF CI return status type. More...
enum  ci_rw_enum { CI_RW_NULL = 0, CI_RW_READ, CI_RW_WRITE }
 CI read or write operation. More...
enum  ci_commands_enum {
  CI_CMD_READ_VERSION = 0, CI_CMD_READ_CONFIG, CI_CMD_WRITE_CONFIG, CI_CMD_READ_APP_DATA,
  CI_CMD_UPDATE_QUICKREAD, CI_CMD_READ_APP_STATUS, CI_CMD_MAX = 128
}
 CI host command instructions. More...
enum  ci_response_enum {
  CI_ERROR_NONE = 0, CI_ERROR_PARAM = 0x04, CI_INVALID_COUNT = 0x19, CI_ERROR_COMMAND = 0x1c,
  CI_ERROR_INVALID_LENGTH = 0x21, CI_ERROR_FIFO_BUSY = 0x22, CI_ERROR_FIFO_ALLOCATED = 0x23, CI_ERROR_FIFO_OVERSIZE = 0x24,
  CI_ERROR_CB_NOT_REGISTERED = 0x25, CI_ERROR_MAX = 0x80
}
 These are the CI errors provided to the host. More...

Functions

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.
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.
uint32 isf_ci_app_write (uint8 aAppId, uint32 anumBytes, uint8 *apSrc)
 This API writes data to the host via the mailboxes.
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.
isf_status_t ci_init (void)
 This API initializes the Command Interpreter.
void isf_ci_assert_int_o (void)
 This API asserts the FXLC95000 INT_O pin.
void isf_ci_enable_int_o (uint8 enable)
 This API enables the Command Interpreter to assert INT_O whenever response data is written to the mailboxes.
void isf_ci_set_int_o_polarity (uint8 pol)
 This API sets the interrupt output pin polarity.

Detailed Description

API definitions, types, and macros for the Intelligent Sensing Framework (ISF) Command Interpreter (CI).

Copyright (c) 2012, Freescale Semiconductor, Inc.

Definition in file isf_ci.h.


Define Documentation

#define CI_CMD_LAST   CI_CMD_MAX

The maximum enumeration value implemented as a valid CI command.

Definition at line 172 of file isf_ci.h.


Typedef Documentation

This is a CI callback function pointer.

Any application that responds to the host must have a CI callback defined.

Definition at line 247 of file isf_ci.h.

Type definition for the CI response values.

Definition at line 238 of file isf_ci.h.

Type definition for the CI status values.

Definition at line 181 of file isf_ci.h.


Enumeration Type Documentation

CI host command instructions.

The host indicates which command the Command Interpreter runs. ci_commands_enum is used to identify this command. The maximum number of possible commands is 128 represented by 7 bits.

Enumerator:
CI_CMD_READ_VERSION 

The host reads version information from ROM, firmware, or hardware.

CI_CMD_READ_CONFIG 

The host reads configuration data written by a specific application.

CI_CMD_WRITE_CONFIG 

The host writes configuration data to a specific application.

CI_CMD_READ_APP_DATA 

The host reads data written by a specific application.

CI_CMD_UPDATE_QUICKREAD 

The host requests the application to update the Quick-Read data.

CI_CMD_READ_APP_STATUS 

The host reads the application status.

CI_CMD_MAX 

Maximum number of possible CI commands.

Definition at line 80 of file isf_ci.h.

These are the CI errors provided to the host.

Any errors identified by the Command Interpreter are returned to the host. Any of these errors may be passed back to the host from the application. There are 7 bits allocated to contain error status resulting in 128 possible different status values.

Enumerator:
CI_ERROR_NONE 

The CI command completed without any errors.

CI_ERROR_PARAM 

This error indicates one or more parameters is incorrect. Specific reasons are an unrecognized application ID, an incomplete command, or an incorrect offset.

CI_INVALID_COUNT 

This error indicates that the byte count parameter is greater than the output structure size.

CI_ERROR_COMMAND 

This error indicates that the command code is not recognized.

CI_ERROR_INVALID_LENGTH 

This error indicates that the byte length parameter is invalid.

CI_ERROR_FIFO_BUSY 

This error indicates that the FIFO is busy performing a push operation and it is not possible to execute any other functions.

CI_ERROR_FIFO_ALLOCATED 

This error indicates an error in the FIFO allocation.

CI_ERROR_FIFO_OVERSIZE 

This error indicates that the host is trying to set a FIFO buffer size outside the memory boundary of the device.

CI_ERROR_CB_NOT_REGISTERED 

This error indicates there is no callback registered for the given application ID.

CI_ERROR_MAX 

The maximum possible error value.

Definition at line 116 of file isf_ci.h.

enum ci_rw_enum

CI read or write operation.

Enumerator:
CI_RW_NULL 

CI NULL operation.

CI_RW_READ 

CI read operation.

CI_RW_WRITE 

CI write operation.

Definition at line 57 of file isf_ci.h.

ISF CI return status type.

Enumerator:
ISF_CI_FAILURE 

This error indicates a general failure status.

ISF_CI_FAILURE_INVALID_PARAMETERS 

This error indicates at least one of the parameter is invalid.

Definition at line 43 of file isf_ci.h.


Function Documentation

isf_status_t ci_init ( void  )

This API initializes the Command Interpreter.

The Command Interpreter requires a one time initialization at system startup performed by this API call. It creates and initializes internal variables. In addition, it installs an interrupt service routine for the slave-port interrupt.

Returns:
ci_init() returns a value of type isf_status_t providing the status of the initialization operation.
Return values:
ISF_SUCCESSThe initialization completed successfully.
ISF_ERR_LIB_INITThe interrupt service routine for the FXLC95000 slave-port mailboxes could not installed.
Constraints:
The following constraints must be observed when using this function. If these constraints are not met, this API returns an error.
  • An interrupt routine for the FXLC95000 slave-port has not been installed.
Reentrant: No
Link Libraries:
isf_core.lib
See also:
ci_status_t

Referenced by isf_lib_init().

Callback function for the device info command, ISF_APP_ID_DEV_INFO.

Parameters:
apHostPacket- host command packet
apAppPacket- pointer to first mailbox address containing
data.
Returns:
See ci_response_enum type for possible return values
Errors:
None
Constraints:
If another application is using the mailboxes, then the current calling application must wait until the other application has completed its operation on the mailboxes.
Reentrant: Yes.
Link Libraries:
isf_core.lib
See also:
None

This function is the mailbox application callback.

This mailbox function is referred to as the mailbox application. This callback function is invoked when the host sends commands to the mailbox application via the mailboxes. This is the mechanism whereby the host reads or writes to the mailbox configuration data to configure the mailboxes for Quick-Read or the interrupt output (INT_O) behavior.

Parameters:
[in]apHostPacketHost command packet pointer that points to a data structure of type ci_host_cmd_packet_t. The data structure contains the host command and parameters for the mailbox application to process.
[in,out]apAppPacketAn application response packet pointer that points to a data structure of type ci_app_resp_packet_t. The mailbox application fills this data structure with data as a result of handling the host command.
Returns:
isf_app_callback_mbox() returns a value of type ci_response_t indicating the status of the callback operation.
Return values:
CI_ERROR_NONEThe host command completed successfully.
CI_ERROR_COMMANDThe host command in apHostPacket->cmd is not recognized.
CI_INVALID_COUNTThe byte count in apHostPacket->byte_cnt is invalid because it is zero or it exceeds the mailbox configuration data size.
CI_ERROR_INVALID_LENGTHThe byte count apHostPacket->byte combined with apHostPacket->offset exceeds the mailbox configuration data size.
Constraints:
The following constraints must be observed when using this function. If these constraints are not met, this API returns an error.
  • A valid host command must be supplied.
  • The number of bytes plus the offset to read or write is within the mailbox data size.
Reentrant: No
Link Libraries:
isf_core.lib
See also:
ci_funcp_t, ci_response_t
uint32 isf_ci_app_read ( uint8  aAppId,
uint32  anumBytes,
uint8 apDst 
)

This API reads data from the host via the mailboxes.

This API function is called by an application that reads data from the host in response to a host command.

Parameters:
[in]aAppIdID of the application reading data from the host.
[in]anumBytesThe number of bytes to read from the mailboxes. The range is 1 to 28.
[in]apDstPointer to the destination where the data is to be stored.
Returns:
isf_ci_app_read() returns a value of type uint32 containing the number of bytes read from the mailboxes written by the host.
Constraints:
The following constraints must be observed when using this function. If these constraints are not met, this API returns a zero for the number of bytes read from the mailboxes.
  • anumBytes must be within the valid range of 1 to 28.
  • apDst cannot be NULL.
Reentrant: Yes
Link Libraries:
isf_core.lib
See also:
isf_ci_app_write()
uint32 isf_ci_app_write ( uint8  aAppId,
uint32  anumBytes,
uint8 apSrc 
)

This API writes data to the host via the mailboxes.

This API function is called by an application that sends data to the host in response to a host command. Data is sent to the host via the mailboxes.

Parameters:
[in]aAppIdID of application writing data to the host.
[in]anumBytesThe number of bytes to write to the mailboxes. The range is 1 to 28.
[in]apSrcPointer to the source of the data to write to the host.
Returns:
isf_ci_app_write() returns a value of type uint32 which is the number of bytes written to the mailboxes for the host to retrieve.
Constraints:
The following constraints must be observed when using this function. If these constraints are not met, this API returns a zero for the number of bytes read from the mailboxes.
  • anumBytes must be within the valid range of 1 to 28.
  • apSrc cannot be NULL.
Reentrant: Yes
Link Libraries:
isf_core.lib
See also:
isf_ci_app_read()
void isf_ci_assert_int_o ( void  )

This API asserts the FXLC95000 INT_O pin.

The FXLC95000CL has the ability to notify the host when data is written to the mailboxes by asserting the INT_O output pin of the FXLC95000CL device. This API asserts the INT_O pin to notify the host that data is ready in the mailboxes by writing a 1 to the SP_OIC[SET] register bit.

Constraints:
The following constraints must be observed when using this function. In order for the INT_O pin to be asserted properly, the following registers must be set up as described in the FXLC95000 Hardware Reference Manual.
  • The PMCR2 register must have RGPIO5 configured for INT_O functionality.
  • The slave-port peripheral clock must be enabled for INT_O to be asserted.
  • SP_OIC[POL] is set for the desired INT_O polarity.
Reentrant: Yes.
Link Libraries:
isf_core.lib
void isf_ci_enable_int_o ( uint8  enable)

This API enables the Command Interpreter to assert INT_O whenever response data is written to the mailboxes.

The FXLC95000CL has the ability to notify the host when data is written to the mailboxes by asserting the INT_O output pin of the FXLC95000CL device. This API sets the Command Interpreter configuration to enable this functionality.

Constraints:
The following constraints must be observed when using this function. In order for the INT_O pin to be asserted properly, the following registers must be set up as described in the FXLC95000 Hardware Reference Manual.
  • The PMCR2 register must have RGPIO5 configured for INT_O functionality.
  • The slave-port peripheral clock must be enabled for INT_O to be asserted.
  • SP_OIC[POL] is set for the desired INT_O polarity.
Parameters:
[in]enableValue used to determine whether the INT_O function is enabled (1) or disabled (0).
Reentrant: Yes.
Link Libraries:
isf_core.lib
ci_status_t isf_ci_qr_update ( uint8  aAppId,
int8  anumBytes,
uint8 apSrc 
)

This API updates the Quick-Read mailboxes.

This API function is called by an application to write data to the host via the mailboxes designated as Quick-Read for that application. The host must configure the mailboxes for Quick-Read by configuring the mailbox application. The host reads these Quick-Read mailboxes directly without sending a command to the CI.

Parameters:
[in]aAppIdID of the application writing data to the mailboxes for the host.
[in]anumBytesThe number of bytes to write to the mailboxes. The range is 1 to 28.
[in]apSrcPointer to the source of the data to write to the mailboxes designated as Quick-Read for the application specified in appId.
Returns:
isf_ci_qr_update() returns a value of type ci_status_t providing the status of the Quick-Read operation.
Return values:
ISF_SUCCESSThe Quick-Read update completed successfully.
ISF_CI_FAILUREA timeout error occurred while waiting for the mailboxes to be free for updates.
Constraints:
The following constraints must be observed when using this function. If these constraints are not met, this API returns an error.
  • anumbytes must be within the valid range of 1 to 28.
  • apSrc cannot be NULL.
Reentrant: Yes
Link Libraries:
isf_core.lib
See also:
ci_status_t

This API sets the interrupt output pin polarity.


Parameters:
[in]polPolarity. 1 - INT_O is configured to be active low. 0 - INT_O is configured to be active high.
Constraints:
The Slave Port peripheral clock must be enabled for this function to work properly.
Reentrant: Yes.
Link Libraries:

See also: