Device Control XCORE API¶

The following structures and functions are used to initialize and start a control instance on the xcore device.

typedef control_ret_t (*device_control_read_cmd_cb_t)(control_resid_t resid, control_cmd_t cmd, uint8_t *payload, size_t payload_len, void *app_data)¶

Function pointer type for application provided device control read command handler callback functions.

Called by device_control_servicer_cmd_recv() when a read command is received from the transport layer. The command consists of a resource ID, command value, and a payload_len. This handler must respond with a payload of the requested length.

Parameters

resid – [in] Resource ID. Indicates which resource the command is intended for.
cmd – [in] Command code. Note that this will be in the range 0x80 to 0xFF because bit 7 set indicates a read command.
payload – [out] Payload bytes of length payload_len that will be sent back over the transport layer in response to this read command.
payload_len – [in] Requested size of the payload in bytes.
app_data – [inout] A pointer to application specific data provided to device_control_servicer_cmd_recv(). How and if this is used is entirely up to the application.

Returns

CONTROL_SUCCESS if the handling of the read data by the device was successful. An error code otherwise.

typedef control_ret_t (*device_control_write_cmd_cb_t)(control_resid_t resid, control_cmd_t cmd, const uint8_t *payload, size_t payload_len, void *app_data)¶

Function pointer type for application provided device control write command handler callback functions.

Called by device_control_servicer_cmd_recv() when a write command is received from the transport layer. The command consists of a resource ID, command value, payload, and the payload’s length.

Parameters

resid – [in] Resource ID. Indicates which resource the command is intended for.
cmd – [in] Command code. Note that this will be in the range 0x80 to 0xFF because bit 7 set indicates a read command.
payload – [in] Payload bytes of length payload_len.
payload_len – [in] The number of bytes in payload.
app_data – [inout] A pointer to application specific data provided to device_control_servicer_cmd_recv(). How and if this is used is entirely up to the application.

Returns

CONTROL_SUCCESS if the handling of the read data by the device was successful. An error code otherwise.

control_ret_t device_control_request(device_control_t *ctx, control_resid_t resid, control_cmd_t cmd, size_t payload_len)¶

Must be called by the transport layer when a new request is received.

Precisely how each of the three command parameters resid, cmd, and payload_len are received is specific to the transport layer and not defined by this library.

Parameters

ctx – A pointer to the associated device control instance.
resid – The received resource ID.
cmd – The received command value.
payload_len – The length in bytes of the payload that will follow.

Returns

CONTROL_SUCCESS – if resid has been registered by a servicer.
CONTROL_BAD_COMMAND – if resid has not been registered by a servicer.

control_ret_t device_control_payload_transfer(device_control_t *ctx, uint8_t *payload_buf, size_t *buf_size, control_direction_t direction)¶

Must be called by the transport layer either when it receives a payload, or when it requires a payload to transmit.

Parameters

ctx – A pointer to the associated device control instance.
payload_buf – A pointer to the payload buffer.

buf_size – A pointer to a variable containing the size of payload_buf.

               When \p direction is CONTROL_HOST_TO_DEVICE, no more than this
               number of bytes will be read from it.

               When \p direction is CONTROL_DEVICE_TO_HOST, this will be updated
               to the number of bytes actually written to \p payload_buf.

direction – The direction of the payload transfer.

               This must be CONTROL_HOST_TO_DEVICE when a payload has already
               been received and is inside \p payload_buf.

               This must be CONTROL_DEVICE_TO_HOST when a payload needs to be
               written into \p payload_buf by device_control_payload_transfer()
               before sending it.

Returns

CONTROL_SUCCESS if everything works and the command is successfully handled by a registered servicer. An error code otherwise.

control_ret_t device_control_servicer_cmd_recv(device_control_servicer_t *ctx, device_control_read_cmd_cb_t read_cmd_cb, device_control_write_cmd_cb_t write_cmd_cb, void *app_data, unsigned timeout)¶

This is called by servicers to wait for and receive any commands received by the transport layer contain one of the resource IDs registered by the servicer. This is also responsible for responding to read commands.

Parameters

ctx – A pointer to the device control servicer context to receive commands for.
read_cmd_cb – The callback function to handle read commands for all resource IDs associated with the given servicer.
write_cmd_cb – The callback function to handle write commands for all resource IDs associated with the given servicer.
app_data – A pointer to application specific data to pass along to the provided callback functions. How and if this is used is entirely up to the application.
timeout – The number of RTOS ticks to wait before returning if no command is received.

Returns

CONTROL_SUCCESS – if a command successfully received and responded to.
CONTROL_ERROR – if no command is received before the function times out, or if there was a problem communicating back to the transport layer thread.

control_ret_t device_control_resources_register(device_control_t *ctx, unsigned timeout)¶

This must be called on the tile that runs the transport layer for the device control instance, and has initialized it with DEVICE_CONTROL_HOST_MODE. This must be called after calling device_control_start() and before the transport layer is started. It is to be run simultaneously with device_control_servicer_register() from other threads on any tiles associated with the device control instance. The number of servicers that must register is specified by the servicer_count parameter of device_control_init().

Parameters

ctx – A pointer to the device control instance to register resources for.
timeout – The amount of time in RTOS ticks to wait before all servicers register their resource IDs with device_control_servicer_register().

Returns

CONTROL_SUCCESS – if all servicers successfully register their resource IDs before the timeout.
CONTROL_REGISTRATION_FAILED – otherwise.

control_ret_t device_control_servicer_register(device_control_servicer_t *ctx, device_control_t *device_control_ctx[], size_t device_control_ctx_count, const control_resid_t resources[], size_t num_resources)¶

Registers a servicer for a device control instance. Each servicer is responsible for handling any number of resource IDs. All commands received from the transport layer will be forwarded to the servicer that has registered the resource ID that is found in the command.

Servicers may be registered on any tile that has initialized a device control instance. This must be called after calling device_control_start().

Parameters

ctx – A pointer to the device control servicer context to initialize.
device_control_ctx – An array of pointers to the device control instance to register the servicer with.
device_control_ctx_count – The number of device control instances to register the servicer with.
resources – Array of resource IDs to associate with this servicer.
num_resources – The number of resource IDs within resources.

control_ret_t device_control_start(device_control_t *ctx, uint8_t intertile_port, unsigned priority)¶

Starts a device control instance. This must be called by all tiles that have called device_control_init(). It may be called either before or after starting the RTOS, but must be called before registering the resources and servicers for this instance.

device_control_init() must be called on this device control instance prior to calling this.

Parameters

ctx – A pointer to the device control instance to start.
intertile_port – The port to use with any and all associated intertile instances associated with this device control instance. If this device control instance is only used by one tile then this is unused.
priority – The priority of the task that will be created if the device control instance was initialized with DEVICE_CONTROL_CLIENT_MODE. This is unused on the tiles where this has been initialized with DEVICE_CONTROL_HOST_MODE. This task is used to listen for commands for a resource ID registered by a servicer running on this tile, but received by the transport layer that is running on another.

control_ret_t device_control_init(device_control_t *ctx, int mode, size_t servicer_count, rtos_intertile_t *intertile_ctx[], size_t intertile_count)¶

Initializes a device control instance.

This must be called by the tile that runs the transport layer (I2C, USB, etc) for the device control instance, as well as all tiles that will register device control servicers for it. It may be called either before or after starting the RTOS, but must be called before calling device_control_start().

Parameters

ctx – A pointer to the device control context to initialize.
mode – Set to DEVICE_CONTROL_HOST_MODE if the command transport layer is on the same tile. Set to DEVICE_CONTROL_CLIENT_MODE if the command transport layer is on another tile.
servicer_count – The number of servicers that will be associated with this device control instance.
intertile_ctx – An array of intertile contexts used to communicate with other tiles.

intertile_count – The number of intertile contexts in the intertile_ctx array.

                   When \p mode is DEVICE_CONTROL_HOST_MODE, this may be 0 if there are
                   no servicers on other tiles, up to one per device control instance that
                   has been initialized with DEVICE_CONTROL_CLIENT_MODE on other tiles.

                   When \p mode is DEVICE_CONTROL_CLIENT_MODE then this must be 1,
                   and the intertile context must connect to a device control instance
                   on another tile that has been initialized with DEVICE_CONTROL_HOST_MODE.

Returns

CONTROL_SUCCESS if the initialization was successful. An error status otherwise.

struct device_control_t¶

#include <device_control.h>

Struct representing a device control instance.

The members in this struct should not be accessed directly.

struct device_control_client_t¶: #include <device_control.h>

A device_control_t pointer may be cast to a pointer to this structure type and used with the device control API, provided it is initialized with DEVICE_CONTROL_CLIENT_MODE. This is not necessary to do, but will save a small amount of memory.

struct device_control_servicer_t¶

#include <device_control.h>

Struct representing a device control servicer instance.

The members in this struct should not be accessed directly.