ISF  2.1
Intelligent Sensing Framework for Kinetis with Processor Expert
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Modules Pages
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

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.

Type definition for the CI response values.

Definition at line 233 of file isf_ci.h.

Type definition for the CI status values.

Definition at line 176 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_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.

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.

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_SUCCESSThe initialization completed successfully.
ISF_ERR_LIB_INITThe 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]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

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

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

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

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: