| 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
Data Structures | Defines | Typedefs | Enumerations | Functions
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

typedef ci_response_t(* ci_funcp_t)(ci_host_cmd_packet_t *, ci_app_resp_packet_t *)

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.

typedef ci_response_enum ci_response_t

Type definition for the CI response values.

Definition at line 238 of file isf_ci.h.

typedef ci_status_enum ci_status_t

Type definition for the CI status values.

Definition at line 181 of file isf_ci.h.

## Enumeration Type Documentation

enum ci_commands_enum

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.

enum ci_response_enum

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.

enum ci_status_enum

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_SUCCESS | The initialization completed successfully.
  ISF_ERR_LIB_INIT | The 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().

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.

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

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 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] | apHostPacket | Host 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] | apAppPacket | An 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_NONE | The host command completed successfully.
  CI_ERROR_COMMAND | The host command in apHostPacket->cmd is not recognized.
  CI_INVALID_COUNT | The byte count in apHostPacket->byte_cnt is invalid because it is zero or it exceeds the mailbox configuration data size.
  CI_ERROR_INVALID_LENGTH | The 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] | aAppId | ID of the application reading data from the host.
  [in] | anumBytes | The number of bytes to read from the mailboxes. The range is 1 to 28.
  [in] | apDst | Pointer 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] | aAppId | ID of application writing data to the host.
  [in] | anumBytes | The number of bytes to write to the mailboxes. The range is 1 to 28.
  [in] | apSrc | Pointer 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] | enable | Value 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] | aAppId | ID of the application writing data to the mailboxes for the host.
  [in] | anumBytes | The number of bytes to write to the mailboxes. The range is 1 to 28.
  [in] | apSrc | Pointer 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_SUCCESS | The Quick-Read update completed successfully.
  ISF_CI_FAILURE | A 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

void isf_ci_set_int_o_polarity | ( | uint8 | pol | ) |

This API sets the interrupt output pin polarity.

Parameters:

  [in] | pol | Polarity. 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: