> ## Documentation Index
> Fetch the complete documentation index at: https://dragonwingdocs-staging.qualcomm.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Asynchronous DSP Packet Queue API Functions

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

```cpp theme={null}
AEEResult dspqueue_create(int domain, uint32_t flags, uint32_t req_queue_size, uint32_t resp_queue_size, dspqueue_callback_t packet_callback, dspqueue_callback_t error_callback, void *callback_context, dspqueue_t *queue)
```

**Parameters**

<ParamField path="domain" type="int">
  DSP to communicate with (CDSP\_DOMAIN\_ID in remote.h for cDSP)
</ParamField>

<ParamField path="flags" type="uint32_t">
  Queue creation flags
</ParamField>

<ParamField path="req_queue_size" type="uint32_t">
  Total request queue memory size in bytes; use 0 for system default
</ParamField>

<ParamField path="resp_queue_size" type="uint32_t">
  Total response queue memory size in bytes; use 0 for system default
</ParamField>

<ParamField path="packet_callback" type="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.
</ParamField>

<ParamField path="error_callback" type="dspqueue_callback_t">
  Callback function called on unrecoverable errors. NULL to disable.
</ParamField>

<ParamField path="callback_context" type="void *">
  Context pointer for callback functions
</ParamField>

<ParamField path="queue" type="dspqueue_t *">
  Queue handle
</ParamField>

**Returns**

0 on success, error code on failure.
AEE\_ENOMEMORY: Not enough memory available
AEE\_EUNSUPPORTED: Message queue not supported on the given DSP
AEE\_EBADPARM: Bad parameters, e.g. Invalid domain (use CDSP\_DOMAIN\_ID for cDSP)
AEE\_ERPC: Internal RPC error, e.g. Queue list corrupt

### `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.

```cpp theme={null}
AEEResult dspqueue_close(dspqueue_t queue)
```

**Parameters**

<ParamField path="queue" type="dspqueue_t">
  Queue handle from dsp\_queue\_create() from dsp\_queue\_import().
</ParamField>

**Returns**

0 on success, error code on failure.
AEE\_ERPC: Internal RPC error, e.g. The queue is open on the DSP when attempting to close it on the host CPU

### `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.

```cpp theme={null}
AEEResult dspqueue_export(dspqueue_t queue, uint64_t *queue_id)
```

**Parameters**

<ParamField path="queue" type="dspqueue_t">
  Queue handle from dspqueue\_create()
</ParamField>

<ParamField path="queue_id" type="uint64_t *">
  Queue ID
</ParamField>

**Returns**

0 on success, error code on failure.

### `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.

```cpp theme={null}
AEEResult dspqueue_import(uint64_t queue_id, dspqueue_callback_t packet_callback, dspqueue_callback_t error_callback, void *callback_context, dspqueue_t *queue)
```

**Parameters**

<ParamField path="queue_id" type="uint64_t">
  Queue ID from dspqueue\_export().
</ParamField>

<ParamField path="packet_callback" type="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.
</ParamField>

<ParamField path="error_callback" type="dspqueue_callback_t">
  Callback function called on unrecoverable errors. NULL to disable.
</ParamField>

<ParamField path="callback_context" type="void *">
  Context pointer fo callback functions
</ParamField>

<ParamField path="queue" type="dspqueue_t *">
  Queue handle
</ParamField>

**Returns**

0 on success, error code on failure.
AEE\_EITEMBUSY: The queue has already been imported
AEE\_EQURTTHREADCREATE: Unable to create callback thread; the system may have reached its thread limit.
AEE\_EBADSTATE: Bad internal state

### `dspqueue_request`

Make dspqueue related requests - like creation of multi-domain queue.

```cpp theme={null}
int dspqueue_request(dspqueue_request_payload *req)
```

**Parameters**

<ParamField path="req" type="dspqueue_request_payload *">
  : Request payload
</ParamField>

**Returns**

0 on success, error code on failure.
AEE\_ENOMEMORY : Not enough memory available
AEE\_EUNSUPPORTED : Not supported on given domains
AEE\_EBADPARM : Bad parameters, e.g. invalid context
AEE\_ERPC : Internal RPC error

### `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.

```cpp theme={null}
AEEResult dspqueue_write_noblock(dspqueue_t queue, uint32_t flags, uint32_t num_buffers, struct dspqueue_buffer *buffers, uint32_t message_length, const uint8_t *message)
```

**Parameters**

<ParamField path="queue" type="dspqueue_t">
  Queue handle from dspqueue\_create() or dspqueue\_import()
</ParamField>

<ParamField path="flags" type="uint32_t">
  Packet flags. See enum dspqueue\_packet\_flags
</ParamField>

<ParamField path="num_buffers" type="uint32_t">
  Number of buffer references to insert to the packet; zero if there are no buffer references
</ParamField>

<ParamField path="buffers" type="struct dspqueue_buffer *">
  Pointer to buffer references
</ParamField>

<ParamField path="message_length" type="uint32_t">
  Message length in bytes; zero if the packet contains no message
</ParamField>

<ParamField path="message" type="const uint8_t *">
  Pointer to packet message
</ParamField>

**Returns**

0 on success, error code on failure.
AEE\_EWOULDBLOCK: The queue is full
AEE\_EBADPARM: Bad parameters, e.g. buffers is NULL when num\_buffers > 0
AEE\_ENOSUCHMAP: Attempt to refer to an unmapped buffer. Buffers must be mapped to the DSP with fastrpc\_mmap() before they can be used in queue packets.
AEE\_EBADSTATE: Queue is in bad-state and can no longer be used

### `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.

```cpp theme={null}
AEEResult dspqueue_write(dspqueue_t queue, uint32_t flags, uint32_t num_buffers, struct dspqueue_buffer *buffers, uint32_t message_length, const uint8_t *message, uint32_t timeout_us)
```

**Parameters**

<ParamField path="queue" type="dspqueue_t">
  Queue handle from dspqueue\_create() or dspqueue\_import()
</ParamField>

<ParamField path="flags" type="uint32_t">
  Packet flags. See enum dspqueue\_packet\_flags
</ParamField>

<ParamField path="num_buffers" type="uint32_t">
  Number of buffer references to insert to the packet; zero if there are no buffer references
</ParamField>

<ParamField path="buffers" type="struct dspqueue_buffer *">
  Pointer to buffer references
</ParamField>

<ParamField path="message_length" type="uint32_t">
  Message length in bytes; zero if the packet contains no message
</ParamField>

<ParamField path="message" type="const uint8_t *">
  Pointer to packet message
</ParamField>

<ParamField path="timeout_us" type="uint32_t">
  Timeout in microseconds; use DSPQUEUE\_TIMEOUT\_NONE to block indefinitely until a space is available or zero for non-blocking behavior.
</ParamField>

**Returns**

0 on success, error code on failure.
AEE\_EBADPARM: Bad parameters, e.g. buffers is NULL when num\_buffers > 0
AEE\_ENOSUCHMAP: Attempt to refer to an unmapped buffer. Buffers must be mapped to the DSP with fastrpc\_mmap() before they can be used in queue packets.
AEE\_EEXPIRED: Request timed out
AEE\_EINTERRUPTED: The request was canceled
AEE\_EBADSTATE: Queue is in bad-state and can no longer be used

### `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.

```cpp theme={null}
AEEResult dspqueue_read_noblock(dspqueue_t queue, uint32_t *flags, uint32_t max_buffers, uint32_t *num_buffers, struct dspqueue_buffer *buffers, uint32_t max_message_length, uint32_t *message_length, uint8_t *message)
```

**Parameters**

<ParamField path="queue" type="dspqueue_t">
  Queue handle from dspqueue\_create() or dspqueue\_import()
</ParamField>

<ParamField path="flags" type="uint32_t *">
  Packet flags. See enum dspqueue\_packet\_flags
</ParamField>

<ParamField path="max_buffers" type="uint32_t">
  The maximum number of buffer references that can fit in the "buffers" parameter
</ParamField>

<ParamField path="num_buffers" type="uint32_t *">
  The number of buffer references in the packet
</ParamField>

<ParamField path="buffers" type="struct dspqueue_buffer *">
  Buffer reference data from the packet
</ParamField>

<ParamField path="max_message_length" type="uint32_t">
  Maximum message length that can fit in the "message" parameter
</ParamField>

<ParamField path="message_length" type="uint32_t *">
  Message length in bytes
</ParamField>

<ParamField path="message" type="uint8_t *">
  Packet message
</ParamField>

**Returns**

0 on success, error code on failure.
AEE\_ENOSUCHMAP: The packet refers to an unmapped buffer. Buffers must be mapped to the DSP with fastrpc\_mmap() before they can be used in queue packets.
AEE\_EWOULDBLOCK: The queue is empty; try again later
AEE\_EBADITEM: The queue contains a corrupted packet. Internal error.

### `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.

```cpp theme={null}
AEEResult dspqueue_read(dspqueue_t queue, uint32_t *flags, uint32_t max_buffers, uint32_t *num_buffers, struct dspqueue_buffer *buffers, uint32_t max_message_length, uint32_t *message_length, uint8_t *message, uint32_t timeout_us)
```

**Parameters**

<ParamField path="queue" type="dspqueue_t">
  Queue handle from dspqueue\_create() or dspqueue\_import()
</ParamField>

<ParamField path="flags" type="uint32_t *">
  Packet flags. See enum dspqueue\_packet\_flags
</ParamField>

<ParamField path="max_buffers" type="uint32_t">
  The maximum number of buffer references that can fit in the "buffers" parameter
</ParamField>

<ParamField path="num_buffers" type="uint32_t *">
  The number of buffer references in the packet
</ParamField>

<ParamField path="buffers" type="struct dspqueue_buffer *">
  Buffer reference data from the packet
</ParamField>

<ParamField path="max_message_length" type="uint32_t">
  Maximum message length that can fit in the "message" parameter
</ParamField>

<ParamField path="message_length" type="uint32_t *">
  Message length in bytes
</ParamField>

<ParamField path="message" type="uint8_t *">
  Packet message
</ParamField>

<ParamField path="timeout_us" type="uint32_t">
  Timeout in microseconds; use DSPQUEUE\_TIMEOUT\_NONE to block indefinitely until a packet is available or zero for non-blocking behavior.
</ParamField>

**Returns**

0 on success, error code on failure.
AEE\_ENOSUCHMAP: The packet refers to an unmapped buffer. Buffers must be mapped to the DSP with fastrpc\_mmap() before they can be used in queue packets.
AEE\_EBADITEM: The queue contains a corrupted packet. Internal error.
AEE\_EEXPIRED: Request timed out
AEE\_EINTERRUPTED: The request was canceled

### `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.

```cpp theme={null}
AEEResult dspqueue_peek_noblock(dspqueue_t queue, uint32_t *flags, uint32_t *num_buffers, uint32_t *message_length)
```

**Parameters**

<ParamField path="queue" type="dspqueue_t">
  Queue handle from dspqueue\_create() or dspqueue\_import().
</ParamField>

<ParamField path="flags" type="uint32_t *">
  Packet flags. See enum dspqueue\_packet\_flags
</ParamField>

<ParamField path="num_buffers" type="uint32_t *">
  Number of buffer references in packet
</ParamField>

<ParamField path="message_length" type="uint32_t *">
  Packet message length in bytes
</ParamField>

**Returns**

0 on success, error code on failure.
AEE\_EWOULDBLOCK: The queue is empty; try again later
AEE\_EBADITEM: The queue contains a corrupted packet. Internal error.

### `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.

```cpp theme={null}
AEEResult dspqueue_peek(dspqueue_t queue, uint32_t *flags, uint32_t *num_buffers, uint32_t *message_length, uint32_t timeout_us)
```

**Parameters**

<ParamField path="queue" type="dspqueue_t">
  Queue handle from dspqueue\_create() or dspqueue\_import().
</ParamField>

<ParamField path="flags" type="uint32_t *">
  Packet flags. See enum dspqueue\_packet\_flags
</ParamField>

<ParamField path="num_buffers" type="uint32_t *">
  Number of buffer references in packet
</ParamField>

<ParamField path="message_length" type="uint32_t *">
  Packet message length in bytes
</ParamField>

<ParamField path="timeout_us" type="uint32_t">
  Timeout in microseconds; use DSPQUEUE\_TIMEOUT\_NONE to block indefinitely until a packet is available or zero for non-blocking behavior.
</ParamField>

**Returns**

0 on success, error code on failure.
AEE\_EEXPIRED: Request timed out
AEE\_EINTERRUPTED: The request was canceled
AEE\_EBADITEM: The queue contains a corrupted packet. Internal error.

### `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.

```cpp theme={null}
AEEResult dspqueue_write_early_wakeup_noblock(dspqueue_t queue, uint32_t wakeup_delay, uint32_t packet_flags)
```

**Parameters**

<ParamField path="queue" type="dspqueue_t">
  Queue handle from dspqueue\_create() or dspqueue\_import()
</ParamField>

<ParamField path="wakeup_delay" type="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.
</ParamField>

<ParamField path="packet_flags" type="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
</ParamField>

**Returns**

0 on success, error code on failure.
AEE\_EWOULDBLOCK: The queue is full

### `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.

```cpp theme={null}
AEEResult dspqueue_get_stat(dspqueue_t queue, enum dspqueue_stat stat, uint64_t *value)
```

**Parameters**

<ParamField path="queue" type="dspqueue_t">
  Queue handle from dspqueue\_create() or dspqueue\_import()
</ParamField>

<ParamField path="stat" type="enum dspqueue_stat">
  Statistic to read, see enum dspqueue\_stat
</ParamField>

<ParamField path="value" type="uint64_t *">
  Statistic value. Reading a statistic will reset it to zero
</ParamField>

**Returns**

0 on success, error code on failure.
AEE\_EBADPARM: Invalid statistic