| ISF 2.1 Intelligent Sensing Framework for Kinetis with Processor Expert

- Main Page
- Modules
- Data Structures
- Files

- File List
- Globals

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Modules Pages
Data Structures | Macros | Typedefs | Enumerations | Functions
isf_ci.h File Reference

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

`#include "isf_types.h"`
Include dependency graph for isf_ci.h:
This graph shows which files directly or indirectly include this file:

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...

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

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

## 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_RESET_APP, 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_RESP_QUICKREAD = 0x40, 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. More...
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. More...
uint32 | isf_ci_app_write (uint8 aAppId, uint32 anumBytes, uint8 *apSrc)
| This API writes data to the host via the mailboxes. More...
uint32 | isf_ci_app_read (uint8 aAppId, uint32 anumBytes, uint8 *apDst)
| This API reads data from the host via the mailboxes. More...
ci_status_t | isf_ci_qr_update (uint8 aAppId, int8 anumBytes, uint8 *apSrc)
| This API updates the Quick-Read mailboxes. More...
isf_status_t | ci_init (void)
| This API initializes the Command Interpreter. More...

## Detailed Description

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

Copyright (c) 2013, Freescale Semiconductor, Inc.

Definition in file isf_ci.h.

## Macro Definition Documentation

#define CI_CMD_LAST CI_CMD_MAX

The maximum enumeration value implemented as a valid CI command.

Definition at line 167 of file isf_ci.h.

Referenced by ci_protocol_CB_mbox().

## 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 242 of file isf_ci.h.

typedef ci_response_enum ci_response_t

Type definition for the CI response values.

Definition at line 233 of file isf_ci.h.

typedef ci_status_enum ci_status_t

Type definition for the CI status values.

Definition at line 176 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_RESET_APP | The host is requesting the application to reset.
CI_CMD_MAX | Maximum number of possible CI commands.

Definition at line 68 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_RESP_QUICKREAD | This status means the packet is a Quick Read response packet.
CI_ERROR_MAX | The maximum possible error value.

Definition at line 107 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 45 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 31 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 uart channel used by the Command Interpereter 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 uart channel used by the Command Interpereter has not been installed.

Reentrant: No

Link Libraries:
  isf_core.lib

See also
  ci_status_t

Definition at line 584 of file task_ci.c.

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 | - application response packet.

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:

See also

Parameters

  packet_ptr | - host command packet
  mb_data_ptr | - 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:

See also

Definition at line 767 of file ci_protocol_mbox.c.

References _fw_device_info_get(), ci_host_cmd_packet_t::appId, ci_app_resp_packet_t::bytes_left, ci_app_resp_packet_t::bytes_xfer, CI_ERROR_NONE, CI_RW_WRITE, isf_ci_app_write(), and ci_app_resp_packet_t::rw.

Here is the call graph for this function:

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

This function is the mailbox application callback.

Parameters

  packet_ptr | - host command packet
  mb_data_ptr | - 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:

See also

Definition at line 626 of file ci_protocol_mbox.c.

References ci_host_cmd_packet_t::appId, ci_host_cmd_packet_t::byte_cnt, ci_app_resp_packet_t::bytes_left, ci_app_resp_packet_t::bytes_xfer, CI_CMD_READ_APP_DATA, CI_CMD_READ_CONFIG, CI_CMD_RESET_APP, CI_CMD_UPDATE_QUICKREAD, CI_CMD_WRITE_CONFIG, CI_ERROR_COMMAND, CI_ERROR_INVALID_LENGTH, CI_ERROR_NONE, CI_INVALID_COUNT, ci_qr_update(), CI_RW_NULL, CI_RW_READ, CI_RW_WRITE, ci_update_first_data_mb(), ci_regs_t::ciCtrlReg, ci_host_cmd_packet_t::cmd, isf_ci_app_read(), isf_ci_app_write(), ci_host_cmd_packet_t::offset, ci_regs_t::qr_config, qr_config_clear, ci_ctrl_reg_t::reg, and ci_app_resp_packet_t::rw.

Here is the call graph for this function:

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()

Definition at line 211 of file ci_protocol_mbox.c.

Referenced by App1_ci_app_callback(), isf_app_callback_mbox(), and rli_ci_app_callback().

Here is the caller graph for this function:

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()

Definition at line 268 of file ci_protocol_mbox.c.

Referenced by App1_ci_app_callback(), ci_mbox_init(), isf_app_callback_dev_info(), isf_app_callback_mbox(), and rli_ci_app_callback().

Here is the caller graph for this function:

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

Definition at line 80 of file ci_protocol_mbox.c.

References qr_config_t::appId, ci_ctrl_reg_t::Bits, ci_ctrl_reg_t::blockTransferMode, qr_config_t::byte_id, ccitt_crc16_cal(), ci_insert_crc, CI_PROTOCOL_DATA_OFFSET, CI_PROTOCOL_ID_SIZE, CI_RESP_QUICKREAD, ci_send_packet(), CI_STREAMING_MODE, ci_regs_t::ciCtrlReg, FIRST_QR_MAILBOX_NUM, ISF_CI_FAILURE, ISF_SUCCESS, MAX_NUM_MAILBOXES, MB_APP_RESP_SIZE, MB_RESP_INDEX_APP_ID, MB_RESP_INDEX_BYTES_XFER, MB_RESP_INDEX_COUNT, MB_RESP_INDEX_STATUS_CC, MBOX_CRC_BYTE_SIZE, NUM_QR_MAILBOXES, and ci_regs_t::qr_config.

Referenced by App1_ci_app_callback(), App1_MainTask(), and rli_ci_app_callback().

Here is the call graph for this function:

Here is the caller graph for this function:
- © Freescale Semiconductor, Inc. 2015. All Rights Reserved.