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

AEEResult	dspqueue_close (dspqueue_t queue)

AEEResult	dspqueue_export (dspqueue_t queue, uint64_t *queue_id)

AEEResult	dspqueue_import (uint64_t queue_id, dspqueue_callback_t packet_callback, dspqueue_callback_t error_callback, void callback_context, dspqueue_t queue)

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)

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)

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)

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)

AEEResult	dspqueue_peek_noblock (dspqueue_t queue, uint32_t flags, uint32_t num_buffers, uint32_t *message_length)

AEEResult	dspqueue_peek (dspqueue_t queue, uint32_t flags, uint32_t num_buffers, uint32_t *message_length, uint32_t timeout_us)

AEEResult	dspqueue_write_early_wakeup_noblock (dspqueue_t queue, uint32_t wakeup_delay, uint32_t packet_flags)

AEEResult	dspqueue_get_stat (dspqueue_t queue, enum dspqueue_stat stat, uint64_t *value)

Detailed Description

Function Documentation

◆ dspqueue_close()

AEEResult dspqueue_close ( dspqueue_t queue )

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

Parameters

[in] queue Queue handle from dsp_queue_create() from dsp_queue_import().

Returns

0 on success, error code on failure.

AEE_EBADPARM: Bad parameters, e.g. The queue is open on the DSP when attempting to close it on the host CPU
AEE_EBADSTATE: Bad internal state

◆ dspqueue_create()

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
	)

Create a new queue to communicate with the DSP. Queues can only be created on the host CPU.

Parameters

[in]	domain	DSP to communicate with (CDSP_DOMAIN_ID in remote.h for cDSP)
[in]	flags	Queue creation flags
[in]	req_queue_size	Total request queue memory size in bytes; use 0 for system default
[in]	resp_queue_size	Total response queue memory size in bytes; use 0 for system default
[in]	packet_callback	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.
[in]	error_callback	Callback function called on unrecoverable errors. NULL to disable.
[in]	callback_context	Context pointer for callback functions
[out]	queue	Queue handle

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), Too many queues open for the DSP in this process
AEE_ERPC: Internal RPC error, e.g. Queue list corrupt
AEE_EBADSTATE: Bad internal state

◆ dspqueue_export()

AEEResult dspqueue_export	(	dspqueue_t	queue,
		uint64_t *	queue_id
	)

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.

Parameters

[in]	queue	Queue handle from dspqueue_create()
[out]	queue_id	Queue ID

Returns: 0 on success, error code on failure.

◆ dspqueue_get_stat()

AEEResult dspqueue_get_stat	(	dspqueue_t	queue,
		enum dspqueue_stat	stat,
		uint64_t *	value
	)

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.

Parameters

[in]	queue	Queue handle from dspqueue_create() or dspqueue_import()
[in]	stat	Statistic to read, see enum dspqueue_stat
[out]	value	Statistic value. Reading a statistic will reset it to zero

Returns

0 on success, error code on failure.

AEE_EBADPARM: Invalid statistic

◆ dspqueue_import()

AEEResult dspqueue_import	(	uint64_t	queue_id,
		dspqueue_callback_t	packet_callback,
		dspqueue_callback_t	error_callback,
		void *	callback_context,
		dspqueue_t *	queue
	)

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.

Parameters

[in]	queue_id	Queue ID from dspqueue_export().
[in]	packet_callback	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.
[in]	error_callback	Callback function called on unrecoverable errors. NULL to disable.
[in]	callback_context	Context pointer fo callback functions
[out]	queue	Queue handle

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

AEEResult dspqueue_peek	(	dspqueue_t	queue,
		uint32_t *	flags,
		uint32_t *	num_buffers,
		uint32_t *	message_length,
		uint32_t	timeout_us
	)

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.

Parameters

[in]	queue	Queue handle from dspqueue_create() or dspqueue_import().
[out]	flags	Packet flags. See enum dspqueue_packet_flags
[out]	num_buffers	Number of buffer references in packet
[out]	message_length	Packet message length in bytes
[out]	timeout_us	Timeout in microseconds; use DSPQUEUE_TIMEOUT_NONE to block indefinitely until a packet is available or zero for non-blocking behavior.

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.
AEE_EBADSTATE: Bad internal state

◆ dspqueue_peek_noblock()

AEEResult dspqueue_peek_noblock	(	dspqueue_t	queue,
		uint32_t *	flags,
		uint32_t *	num_buffers,
		uint32_t *	message_length
	)

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.

Parameters

[in]	queue	Queue handle from dspqueue_create() or dspqueue_import().
[out]	flags	Packet flags. See enum dspqueue_packet_flags
[out]	num_buffers	Number of buffer references in packet
[out]	message_length	Packet message length in bytes

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.
AEE_EBADSTATE: Bad internal state

◆ dspqueue_read()

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
	)

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.

Parameters

[in]	queue	Queue handle from dspqueue_create() or dspqueue_import()
[out]	flags	Packet flags. See enum dspqueue_packet_flags
[in]	max_buffers	The maximum number of buffer references that can fit in the "buffers" parameter
[out]	num_buffers	The number of buffer references in the packet
[out]	buffers	Buffer reference data from the packet
[in]	max_message_length	Maximum message length that can fit in the "message" parameter
[out]	message_length	Message length in bytes
[out]	message	Packet message
[in]	timeout_us	Timeout in microseconds; use DSPQUEUE_TIMEOUT_NONE to block indefinitely until a packet is available or zero for non-blocking behavior.

Returns

0 on success, error code on failure.

AEE_EBADPARM: Bad parameters, e.g. The packet is too large to fit in the provided buffers
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_EBADSTATE: Bad internal state
AEE_EEXPIRED: Request timed out
AEE_EINTERRUPTED: The request was canceled

◆ dspqueue_read_noblock()

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
	)

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.

Parameters

[in]	queue	Queue handle from dspqueue_create() or dspqueue_import()
[out]	flags	Packet flags. See enum dspqueue_packet_flags
[in]	max_buffers	The maximum number of buffer references that can fit in the "buffers" parameter
[out]	num_buffers	The number of buffer references in the packet
[out]	buffers	Buffer reference data from the packet
[in]	max_message_length	Maximum message length that can fit in the "message" parameter
[out]	message_length	Message length in bytes
[out]	message	Packet message

Returns

0 on success, error code on failure.

AEE_EBADPARM: Bad parameters, e.g. The packet is too large to fit in the provided buffers
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.
AEE_EBADSTATE: Bad internal state

◆ dspqueue_write()

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
	)

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.

Parameters

[in]	queue	Queue handle from dspqueue_create() or dspqueue_import()
[in]	flags	Packet flags. See enum dspqueue_packet_flags
[in]	num_buffers	Number of buffer references to insert to the packet; zero if there are no buffer references
[in]	buffers	Pointer to buffer references
[in]	message_length	Message length in bytes; zero if the packet contains no message
[in]	message	Pointer to packet message
[in]	timeout_us	Timeout in microseconds; use DSPQUEUE_TIMEOUT_NONE to block indefinitely until a space is available or zero for non-blocking behavior.

Returns

0 on success, error code on failure.

AEE_EBADPARM: Bad parameters, e.g. buffers is NULL when num_buffers > 0 The packet is too long to fit in the queue. The call will never succeed.
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: Bad internal state

◆ dspqueue_write_early_wakeup_noblock()

AEEResult dspqueue_write_early_wakeup_noblock	(	dspqueue_t	queue,
		uint32_t	wakeup_delay,
		uint32_t	packet_flags
	)

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.

Parameters

[in]	queue	Queue handle from dspqueue_create() or dspqueue_import()
[in]	wakeup_delay	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.
[in]	packet_flags	Flags for the upcoming packet if known. The framework can use this information to optimize its behavior if the flags match the upcoming packet; if not known set to zero. See enum dspqueue_packet_flags

Returns

0 on success, error code on failure.

AEE_EWOULDBLOCK: The queue is full
AEE_EBADSTATE: Bad internal state

◆ dspqueue_write_noblock()

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
	)

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.

Parameters

[in]	queue	Queue handle from dspqueue_create() or dspqueue_import()
[in]	flags	Packet flags. See enum dspqueue_packet_flags
[in]	num_buffers	Number of buffer references to insert to the packet; zero if there are no buffer references
[in]	buffers	Pointer to buffer references
[in]	message_length	Message length in bytes; zero if the packet contains no message
[in]	message	Pointer to packet message

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 , The packet is too long to fit in the queue. The call will never succeed.
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: Bad internal state

Functions

Detailed Description

Function Documentation

◆ dspqueue_close()

◆ dspqueue_create()

◆ dspqueue_export()

◆ dspqueue_get_stat()

◆ dspqueue_import()

◆ dspqueue_peek()

◆ dspqueue_peek_noblock()

◆ dspqueue_read()

◆ dspqueue_read_noblock()

◆ dspqueue_write()

◆ dspqueue_write_early_wakeup_noblock()

◆ dspqueue_write_noblock()