Functions
dspqueue_create
Create a new queue to communicate with the DSP.
Queues can only be created on the host CPU.
This function cannot be used to create multi-domain queue. Refer ‘dspqueue_request’ for that.
int
DSP to communicate with (CDSP_DOMAIN_ID in remote.h for cDSP)
uint32_t
Queue creation flags
uint32_t
Total request queue memory size in bytes; use 0 for system default
uint32_t
Total response queue memory size in bytes; use 0 for system default
dspqueue_callback_t
Callback function called when there are new packets to read. The call will be done in a different thread’s context. NULL to disable the callback. Clients cannot use blocking read calls if a packet callback has been set.
dspqueue_callback_t
Callback function called on unrecoverable errors. NULL to disable.
void *
Context pointer for callback functions
dspqueue_t *
Queue handle
dspqueue_close
Close a queue and free all memory associated with it.
The function can be called on the host CPU with queue handles from dspqueue_create() or on the DSP with handles from dspqueue_import().
This function can be called on both single-domain and multi-domain queues.
dspqueue_t
Queue handle from dsp_queue_create() from dsp_queue_import().
dspqueue_export
Export a queue to the DSP.
The CPU-side client calls this function, passes the ID to the DSP, which can then call dspqueue_import() to access the queue.
This function is not required to be called on multi-domain queues.
dspqueue_t
Queue handle from dspqueue_create()
uint64_t *
Queue ID
dspqueue_import
Import a queue on the DSP based on an ID passed in from the host CPU.
The DSP client can use the returned queue handle to access the queue and communicate with its host CPU counterpart.
uint64_t
Queue ID from dspqueue_export().
dspqueue_callback_t
Callback function called when there are new packets to read. The call will be done in a different thread’s context. NULL to disable the callback.
dspqueue_callback_t
Callback function called on unrecoverable errors. NULL to disable.
void *
Context pointer fo callback functions
dspqueue_t *
Queue handle
dspqueue_request
Make dspqueue related requests - like creation of multi-domain queue.
dspqueue_request_payload *
: Request payload
dspqueue_write_noblock
Write a packet to a queue.
This variant of the function will not block, and will instead return AEE_EWOULDBLOCK if the queue does not have enough space for the packet.
With this function the client can pass separate pointers to the buffer references and message to include in the packet and the library copies the contents directly to the queue.
When this is called on a multi-domain queue, the packet will be shared with all remote domains the queue was created on. If any of the domains is unable to receive the packet, it means the queue is in a bad-state and is no longer usable. Client is expected to close the queue and reopen a new one.
dspqueue_t
Queue handle from dspqueue_create() or dspqueue_import()
uint32_t
Packet flags. See enum dspqueue_packet_flags
uint32_t
Number of buffer references to insert to the packet; zero if there are no buffer references
struct dspqueue_buffer *
Pointer to buffer references
uint32_t
Message length in bytes; zero if the packet contains no message
const uint8_t *
Pointer to packet message
dspqueue_write
Write a packet to a queue.
If the queue is full this function will block until space becomes available or the request times out.
With this function the client can pass separate pointers to the buffer references and message to include in the packet and the library copies the contents directly to the queue.
When this is called on a multi-domain queue, the packet will be shared with all remote domains the queue was created on. This call will block (for specified timeout or indefinitely) until the packet is shared with all domains. If any of the domains is unable to receive the packet, it means the queue is in a bad-state and is no longer usable. Client is expected to close the queue and reopen a new one.
dspqueue_t
Queue handle from dspqueue_create() or dspqueue_import()
uint32_t
Packet flags. See enum dspqueue_packet_flags
uint32_t
Number of buffer references to insert to the packet; zero if there are no buffer references
struct dspqueue_buffer *
Pointer to buffer references
uint32_t
Message length in bytes; zero if the packet contains no message
const uint8_t *
Pointer to packet message
uint32_t
Timeout in microseconds; use DSPQUEUE_TIMEOUT_NONE to block indefinitely until a space is available or zero for non-blocking behavior.
dspqueue_read_noblock
Read a packet from a queue.
This variant of the function will not block, and will instead return AEE_EWOULDBLOCK if the queue does not have enough space for the packet.
This function will read packet contents directly into client-provided buffers. The buffers must be large enough to fit contents from the packet or the call will fail.
When this is called on a multi-domain queue, it will return the response packet from the first domain where it finds one. If multiple domains have posted a response to the multi-domain queue, the client is expected to call this function as many times to consume the response packet from all domains.
dspqueue_t
Queue handle from dspqueue_create() or dspqueue_import()
uint32_t *
Packet flags. See enum dspqueue_packet_flags
uint32_t
The maximum number of buffer references that can fit in the “buffers” parameter
uint32_t *
The number of buffer references in the packet
struct dspqueue_buffer *
Buffer reference data from the packet
uint32_t
Maximum message length that can fit in the “message” parameter
uint32_t *
Message length in bytes
uint8_t *
Packet message
dspqueue_read
Read a packet from a queue.
If the queue is empty this function will block until a packet is available or the request times out. The queue must not have a packet callback set.
This function will read packet contents directly into client-provided buffers. The buffers must be large enough to fit contents from the packet or the call will fail.
This function is currently not supported on multi-domain queues.
dspqueue_t
Queue handle from dspqueue_create() or dspqueue_import()
uint32_t *
Packet flags. See enum dspqueue_packet_flags
uint32_t
The maximum number of buffer references that can fit in the “buffers” parameter
uint32_t *
The number of buffer references in the packet
struct dspqueue_buffer *
Buffer reference data from the packet
uint32_t
Maximum message length that can fit in the “message” parameter
uint32_t *
Message length in bytes
uint8_t *
Packet message
uint32_t
Timeout in microseconds; use DSPQUEUE_TIMEOUT_NONE to block indefinitely until a packet is available or zero for non-blocking behavior.
dspqueue_peek_noblock
Retrieve information for the next packet if available, without reading it from the queue and advancing the read pointer.
This function will not block, but will instead return an error if the queue is empty.
When this is called on a multi-domain queue, it will return the response packet info from the first domain where it finds one. If multiple domains have posted a response to the multi-domain queue, the client is expected to consume a peeked packet first before attempting to peek the next available packet from any of the domains.
dspqueue_t
Queue handle from dspqueue_create() or dspqueue_import().
uint32_t *
Packet flags. See enum dspqueue_packet_flags
uint32_t *
Number of buffer references in packet
uint32_t *
Packet message length in bytes
dspqueue_peek
Retrieve information for the next packet, without reading it from the queue and advancing the read pointer.
If the queue is empty this function will block until a packet is available or the request times out.
This function is currently not supported on multi-domain queues.
dspqueue_t
Queue handle from dspqueue_create() or dspqueue_import().
uint32_t *
Packet flags. See enum dspqueue_packet_flags
uint32_t *
Number of buffer references in packet
uint32_t *
Packet message length in bytes
uint32_t
Timeout in microseconds; use DSPQUEUE_TIMEOUT_NONE to block indefinitely until a packet is available or zero for non-blocking behavior.
dspqueue_write_early_wakeup_noblock
Write an early wakeup packet to the queue.
Early wakeup packets are used to bring the recipient out of a low-power state in anticipation of a real message packet being availble shortly, and are typically used from the DSP to signal that an operation is almost complete.
This function will return immediately if the queue is full. There is no blocking variant of this function; if the queue is full the other endpoint should already be processing data and an early wakeup would not be useful.
When this function is called on a multi-domain queue, early wakeup is done on all the domains that the queue was created on.
dspqueue_t
Queue handle from dspqueue_create() or dspqueue_import()
uint32_t
Wakeup time in microseconds; this indicates how soon the real message packet should be available. Zero if not known. The recipient can use this information to determine how to wait for the packet.
uint32_t
Flags for the upcoming packet if known. The recipient can use this information to determine how to wait for the packet. See enum dspqueue_packet_flags
dspqueue_get_stat
Retrieve statistics from a queue.
Statistics are relative to the queue as viewed from the current endpoint (e.g. “read queue” refers to the queue as being read by the current endpoint).
Reading an accumulating statistic (such as early wakeup wait time) will reset it to zero.
Note that statistics values are only valid at the time when they’re read. By the time this function returns the values may have changed due to actions from another thread or the other queue endpoint.
This function is currently not supported on multi-domain queues.
dspqueue_t
Queue handle from dspqueue_create() or dspqueue_import()
enum dspqueue_stat
Statistic to read, see enum dspqueue_stat
uint64_t *
Statistic value. Reading a statistic will reset it to zero