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