XCORE SDK
XCORE Software Development Kit
Classes | Typedefs | Functions
Device_control_xcore

Classes

struct  device_control_t
 
struct  device_control_client_t
 
struct  device_control_servicer_t
 

Typedefs

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

Functions

control_ret_t device_control_request (device_control_t *ctx, control_resid_t resid, control_cmd_t cmd, size_t payload_len)
 
control_ret_t device_control_payload_transfer (device_control_t *ctx, uint8_t *payload_buf, size_t *buf_size, control_direction_t direction)
 
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)
 
control_ret_t device_control_resources_register (device_control_t *ctx, unsigned timeout)
 
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)
 
control_ret_t device_control_start (device_control_t *ctx, uint8_t intertile_port, unsigned priority)
 
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)
 

Detailed Description

The public API for using the device control library

Typedef Documentation

◆ device_control_read_cmd_cb_t

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
[in]residResource ID. Indicates which resource the command is intended for.
[in]cmdCommand code. Note that this will be in the range 0x80 to 0xFF because bit 7 set indicates a read command.
[out]payloadPayload bytes of length payload_len that will be sent back over the transport layer in response to this read command.
[in]payload_lenRequested size of the payload in bytes.
[in,out]app_dataA 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.

◆ device_control_write_cmd_cb_t

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
[in]residResource ID. Indicates which resource the command is intended for.
[in]cmdCommand code. Note that this will be in the range 0x80 to 0xFF because bit 7 set indicates a read command.
[in]payloadPayload bytes of length payload_len.
[in]payload_lenThe number of bytes in payload.
[in,out]app_dataA 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.

Function Documentation

◆ device_control_init()

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
ctxA pointer to the device control context to initialize.
modeSet 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_countThe number of servicers that will be associated with this device control instance.
intertile_ctxAn array of intertile contexts used to communicate with other tiles.
intertile_countThe 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.

◆ device_control_payload_transfer()

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
ctxA pointer to the associated device control instance.
payload_bufA pointer to the payload buffer.
buf_sizeA 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.
directionThe 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.

◆ device_control_request()

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
ctxA pointer to the associated device control instance.
residThe received resource ID.
cmdThe received command value.
payload_lenThe length in bytes of the payload that will follow.
Return values
CONTROL_SUCCESSif resid has been registered by a servicer.
CONTROL_BAD_COMMANDif resid has not been registered by a servicer.

◆ device_control_resources_register()

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
ctxA pointer to the device control instance to register resources for.
timeoutThe amount of time in RTOS ticks to wait before all servicers register their resource IDs with device_control_servicer_register().
Return values
CONTROL_SUCCESSif all servicers successfully register their resource IDs before the timeout.
CONTROL_REGISTRATION_FAILEDotherwise.

◆ device_control_servicer_cmd_recv()

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
ctxA pointer to the device control servicer context to receive commands for.
read_cmd_cbThe callback function to handle read commands for all resource IDs associated with the given servicer.
write_cmd_cbThe callback function to handle write commands for all resource IDs associated with the given servicer.
app_dataA 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.
timeoutThe number of RTOS ticks to wait before returning if no command is received.
Return values
CONTROL_SUCCESSif a command successfully received and responded to.
CONTROL_ERRORif no command is received before the function times out, or if there was a problem communicating back to the transport layer thread.

◆ device_control_servicer_register()

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
ctxA pointer to the device control servicer context to initialize.
device_control_ctxAn array of pointers to the device control instance to register the servicer with.
device_control_ctx_countThe number of device control instances to register the servicer with.
resourcesArray of resource IDs to associate with this servicer.
num_resourcesThe number of resource IDs within resources.

◆ device_control_start()

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
ctxA pointer to the device control instance to start.
intertile_portThe 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.
priorityThe 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.