Device Control Shared API

The following structures and functions are common to the control instance on the xcore device and the host.

typedef uint8_t control_resid_t

These types are used in control functions to identify the resource id, command, version, and status.

typedef uint8_t control_cmd_t

typedef uint8_t control_version_t

typedef uint8_t control_status_t

enum control_ret_t

This type enumerates the possible outcomes from a control transaction.

Values:

enumerator CONTROL_SUCCESS

enumerator CONTROL_REGISTRATION_FAILED

enumerator CONTROL_BAD_COMMAND

enumerator CONTROL_DATA_LENGTH_ERROR

enumerator CONTROL_OTHER_TRANSPORT_ERROR

enumerator CONTROL_BAD_RESOURCE

enumerator CONTROL_MALFORMED_PACKET

enumerator CONTROL_COMMAND_IGNORED_IN_DEVICE

enumerator CONTROL_ERROR

enumerator SERVICER_COMMAND_RETRY

enumerator SERVICER_WRONG_COMMAND_ID

enumerator SERVICER_WRONG_COMMAND_LEN

enumerator SERVICER_WRONG_PAYLOAD

enumerator SERVICER_QUEUE_FULL

enumerator SERVICER_SPECIAL_COMMAND_ALREADY_ONGOING

enumerator SERVICER_SPECIAL_COMMAND_BUFFER_OVERFLOW

enumerator SERVICER_RESOURCE_ERROR

enumerator SERVICER_SPECIAL_COMMAND_WRONG_ORDER

enumerator SERVICER_SPECIAL_COMMAND_BUF_SIZE_ERROR

enum control_direction_t

This type is used to inform the control library the direction of a control transfer from the transport layer.

Values:

enumerator CONTROL_HOST_TO_DEVICE

enumerator CONTROL_DEVICE_TO_HOST

CONTROL_VERSION

This is the version of control protocol. Used to check compatibility

IS_CONTROL_CMD_READ(c)

Checks if the read bit is set in a command code.

Parameters:

• c – [in] The command code to check

Returns:

true if the read bit in the command is set

Returns:

false if the read bit is not set

CONTROL_CMD_SET_READ(c)

Sets the read bit on a command code

Parameters:

• c – [inout] The command code to set the read bit on.

CONTROL_CMD_SET_WRITE(c)

Clears the read bit on a command code

Parameters:

• c – [inout] The command code to clear the read bit on.

CONTROL_SPECIAL_RESID

This is the special resource ID owned by the control library. It can be used to check the version of the control protocol. Servicers may not register this resource ID.

CONTROL_MAX_RESOURCE_ID

The maximum resource ID. IDs greater than this cannot be registered.

CONTROL_GET_VERSION

The command to read the version of the control protocol. It must be sent to resource ID CONTROL_SPECIAL_RESID.

CONTROL_GET_LAST_COMMAND_STATUS

The command to read the return status of the last command. It must be sent to resource ID CONTROL_SPECIAL_RESID.

DEVICE_CONTROL_HOST_MODE

The mode value to use when initializing a device control instance that is on the same tile as its associated transport layer. These may be connected to device control instances on other tiles that have been initialized with DEVICE_CONTROL_CLIENT_MODE.

DEVICE_CONTROL_CLIENT_MODE

The mode value to use when initializing a device control instance that is not on the same tile as its associated transport layer. These must be connected to a device control instance on another tile that has been initialized with DEVICE_CONTROL_HOST_MODE.

DEVICE_CONTROL_CALLBACK_ATTR

This attribute must be specified on all device control command handler callback functions provided by the application.