The AWEInstance API Header File. More...

#include <stdlib.h>
#include <string.h>
#include <stddef.h>
#include "TargetProcessor.h"
#include "AWELoggingDefs.h"

Data Structures
struct	_AWEInstance
	The AWE instance. More...

struct	AWEBuildVersionInfo
	Build versioning structure returned by awe_getBuildVersionInfo. More...

Typedefs
typedef void(*	cbAweLogging_t) (struct _AWEInstance pAWE, INT32 level, UINT32 type, void payload, INT32 payloadSizeInBytes)
	OPTIONAL This callback is invoked from multiple places in the AWE framework to log any message to the BSP. More...

typedef INT32(*	cbAweEventTrigger_t) (struct _AWEInstance pAWE, INT32 eventType, UINT32 moduleObjId, void payload, INT32 payloadSizeInBytes, void *userHandle)
	OPTIONAL These callback are invoked only from the Event Module. More...

typedef INT32(*	cbAweEventRegister_t) (struct _AWEInstance pAWE, INT32 eventType, UINT32 moduleObjId, INT32 payloadSizeInBytes, void *userHandle)
	The Event Register callback is called by an Event Module when it is constructed. More...

typedef INT32(*	cbAweEventDeregister_t) (struct _AWEInstance pAWE, INT32 eventType, UINT32 moduleObjId, void *userHandle)
	The Event Deregister callback is called by the Event Module when it is destroyed. More...

typedef struct _AWEInstance	AWEInstance
	The AWE instance. More...

typedef struct AWEBuildVersionInfo	AWEBuildVersionInfo_t
	Build versioning structure returned by awe_getBuildVersionInfo.

typedef INT32	packetProcessFunction(AWEInstance *pAWE)

Functions
INT32	awe_init (AWEInstance *pAWE)
	Initialize the instance. More...

INT32	awe_initPin (IOPinDescriptor pPin, UINT32 channels, const char name)
	Initialize an input or output pin. More...

void	awe_initFlashFS (AWEInstance pAWE, AWEFlashFSInstance pAWEFlashFSInstance)
	Initialize the file system. More...

INT32	awe_packetProcess (AWEInstance *pAWE)
	Process an AWEInstance's newly received tuning packet. More...

INT32	awe_packetProcessMulti (AWEInstance *pAWE, BOOL isTuningInstance)
	Multi-instance Wrapper for tuning packet processing. More...

INT32	awe_audioPump (AWEInstance *pAWE, UINT32 layoutIndex)
	Audio pump function. More...

INT32	awe_audioImportSamples (const AWEInstance pAWE, const void inSamples, INT32 inStride, INT32 channel, SampleType inType)
	Import samples from a user buffer to a channel. More...

INT32	awe_audioExportSamples (const AWEInstance pAWE, void outSamples, INT32 outStride, INT32 channel, SampleType outType)
	Export samples to a user buffer from a channel. More...

INT32	awe_audioIsStarted (const AWEInstance *pAWE)
	Check if this instance is running. More...

INT32	awe_audioGetPumpMask (AWEInstance *pAWE)
	Test if AWE is ready to run. More...

INT32	awe_audioIsReadyToPumpMulti (AWEInstance *pAWE, UINT32 instanceID)
	Test if AWE is ready to run on secondary instances (ID > 0). More...

UINT32	awe_audioStartPreemption (AWEInstance *pAWE, INT32 coreAffinity)
	Function to correct overhead outside of the Audio Weaver, like Audio DMA ISR. More...

UINT32	awe_audioEndPreemption (AWEInstance *pAWE, UINT32 start_time, INT32 coreAffinity)
	Function to correct overhead outside of the Audio Weaver, like Audio DMA ISR. More...

INT32	awe_deferredSetCall (AWEInstance *pAWE)
	Perform deferred awe set on a module. More...

INT32	awe_loadAWBfromArray (AWEInstance pAWE, const UINT32 pCommands, UINT32 arraySize, UINT32 *pPos)
	Executes packet commands from an in-memory array. More...

INT32	awe_loadAWBfromFile (AWEInstance pAWE, const char binaryFile, UINT32 *pPos)
	Load an AWB file from stdio. More...

INT32	awe_loadAWBfromFlash (AWEInstance pAWE, const char binaryFile, UINT32 *pPos)
	Load an AWB file from the flash. More...

void	awe_layoutGetChannelCount (const AWEInstance pAWE, UINT32 pinIdx, UINT32 inCount, UINT32 *outCount)
	Returns the number of channels in the Layout's input and output pins. More...

INT32	awe_layoutGetInputBlockSize (const AWEInstance pAWE, UINT32 pinIdx, UINT32 blockSize)
	Returns the block size of a pin. More...

INT32	awe_layoutGetInputSampleRate (const AWEInstance pAWE, UINT32 pinIdx, FLOAT32 sampleRate)
	Returns the sample rate of an input pin. More...

INT32	awe_layoutIsValid (const AWEInstance *pAWE)
	Determines if a layout is loaded and valid. More...

INT32	awe_ctrlSetValue (const AWEInstance pAWE, UINT32 handle, const void value, INT32 arrayOffset, UINT32 length)
	Set a scalar or array value of a module variable by handle. More...

INT32	awe_ctrlGetValue (const AWEInstance pAWE, UINT32 handle, void value, INT32 arrayOffset, UINT32 length)
	Get a scalar or array value of a module variable by handle. More...

INT32	awe_ctrlSetStatus (const AWEInstance *pAWE, UINT32 handle, UINT32 status)
	Set the runtime status of a module. More...

INT32	awe_ctrlGetStatus (const AWEInstance pAWE, UINT32 handle, UINT32 status)
	Get the runtime status of a module. More...

INT32	awe_ctrlSetValueMask (const AWEInstance pAWE, UINT32 handle, const void value, INT32 arrayOffset, UINT32 length, UINT32 mask)
	Set a scalar or array value of a module variable by handle with mask. More...

INT32	awe_ctrlGetValueMask (const AWEInstance pAWE, UINT32 handle, void value, INT32 arrayOffset, UINT32 length, UINT32 mask)
	Get a scalar or array value of a module variable by handle with mask. More...

INT32	awe_ctrlGetModuleClass (const AWEInstance pAWE, UINT32 handle, UINT32 pClassID)
	Get an object class from its handle. More...

INT32	awe_setProfilingStatus (AWEInstance *pAWE, UINT32 status)
	Enable or disable the profiling ability of the AWE Core. More...

INT32	awe_getAverageLayoutCycles (AWEInstance pAWE, UINT32 layoutIdx, UINT32 averageCycles)
	Get the average cycles of a running layout, in units of cycles at profileSpeed. More...

void	awe_setInstancesInfo (AWEInstance **pInstances, INT32 numAweInstancesOnCore)
	Setup function only intended for systems with multiple AWE Instances in a single core. More...

INT32	awe_fwSetLayoutCoreAffinity (AWEInstance *pAWE, INT32 layoutNumber, INT32 coreAffinity)
	Set the core affinity of the layout in layoutNumber. More...

INT32	awe_fwGetLayoutCoreAffinity (AWEInstance *pAWE, INT32 layoutNumber)
	Get the core affinity of the layout in layoutNumber, initializes to 0 and can be set with awe_fwSetLayoutCoreAffinity. More...

INT32	awe_getBuildVersionInfo (AWEBuildVersionInfo_t *pBuildVersionInfo)
	Get the AWECore build number and version information. More...

INT32	awe_setInstanceStandaloneAWBLoad (AWEInstance *pAWE, INT32 status)
	This function can be used to achieve Progressive Loading on a multi-instance system. More...

INT32	awe_registerLoggingCallback (AWEInstance *pAWE, cbAweLogging_t cbAweLogging, INT32 logLevel, UINT32 logTypeMask)
	Register the logging callback with required logging level and logging type mask. More...

INT32	awe_registerEventCallbacks (AWEInstance *pAWE, cbAweEventTrigger_t cbAweEventTrigger, cbAweEventRegister_t cbAweEventRegister, cbAweEventDeregister_t cbAweEventDeregister)
	Register the event callbacks used by the Event Module. More...

Detailed Description

The AWEInstance API Header File.

Typedef Documentation

◆ cbAweLogging_t

typedef void(* cbAweLogging_t) (struct _AWEInstance *pAWE, INT32 level, UINT32 type, void *payload, INT32 payloadSizeInBytes)

OPTIONAL This callback is invoked from multiple places in the AWE framework to log any message to the BSP.

User should register the callback via awe_registerLoggingCallback, which requires logging level and type mask. type is a 32-bit bitfield, with each bit representing a type of message. These types are defined in the framework and provide information about where the logging messages come from.

◆ cbAweEventTrigger_t

typedef INT32(* cbAweEventTrigger_t) (struct _AWEInstance *pAWE, INT32 eventType, UINT32 moduleObjId, void *payload, INT32 payloadSizeInBytes, void *userHandle)

OPTIONAL These callback are invoked only from the Event Module.

Use the awe_registerEventCallbacks to register them The Event Trigger callback is called when an Event Module is triggered in the layout. Depending on the Event Module configuration, this may happen inline in the module processing, or it may happen during deferred processing. In the latter case, there may be a delay between the actual event trigger and calling this Event Trigger callback. If this returns a negative number, then it is assumed that the Event Trigger was not successfully processed and the module's numFailedTriggers parameter will increment. If there is no Event Trigger callback registered, then the Event Module can never generate an event.

◆ cbAweEventRegister_t

typedef INT32(* cbAweEventRegister_t) (struct _AWEInstance *pAWE, INT32 eventType, UINT32 moduleObjId, INT32 payloadSizeInBytes, void **userHandle)

The Event Register callback is called by an Event Module when it is constructed.

The userHandle is free to use for whatever custom purpose is required. The user is responsible for managing any memory allocated to the userHandle. The user must not define a Event Register callback if no preparation is necessary to handle an Event. If a negative value is returned, then the module will fail to initialize and the layout will fail to load.

◆ cbAweEventDeregister_t

typedef INT32(* cbAweEventDeregister_t) (struct _AWEInstance *pAWE, INT32 eventType, UINT32 moduleObjId, void **userHandle)

The Event Deregister callback is called by the Event Module when it is destroyed.

When this is called, the user is responsible for freeing any memory allocated to the userHandle in the Event Register callback. The return value from this function is ignored.

◆ AWEInstance

typedef struct _AWEInstance AWEInstance

The AWE instance.

The AWE Instance struct must have its members/pointers assigned at init time. The AWEInstance is the most important structure, and it must be initialized properly. After assigning all of the required members, the BSP author will call the awe_init() function. All members are required to be assigned unless they are marked optional in the detailed description below..

Function Documentation

◆ awe_init()

INT32 awe_init ( AWEInstance * pAWE )

Initialize the instance.

Call this once you have assigned all of the required members/pointers of the AWE Instance, and after calling awe_InitPin on both input and output pins. Calling awe_init before assigning all members of the instance structure or initializing the pins will result in crashes/erratic behavior.

Parameters

pAWE	instance to initialize

Returns: E_SUCCESS, E_NULL_PACKET_BUFFER_POINTER, E_NULL_REPLY_BUFFER_POINTER, E_ZERO_PACKET_BUFFER_LENGTH, E_EXCEPTION, E_PARAMETER_ERROR, E_NOT_CREATED

Examples: ControlApp.c, LinuxApp.c, LinuxAppMulti.c, bare_metal_example.c, and singleinstance_simple.c.

◆ awe_initPin()

INT32 awe_initPin	(	IOPinDescriptor *	pPin,
		UINT32	channels,
		const char *	name
	)

Initialize an input or output pin.

This function must be called for both the input and output pins. Must be called BEFORE the awe_init API function.

Parameters

[in]	pPin	the pin instance to initialize
[in]	channels	number of channels
[in]	name	optional pin name

Returns: E_SUCCESS, E_NOT_OBJECT

Examples: ControlApp.c, LinuxApp.c, LinuxAppMulti.c, bare_metal_example.c, and singleinstance_simple.c.

◆ awe_initFlashFS()

void awe_initFlashFS	(	AWEInstance *	pAWE,
		AWEFlashFSInstance *	pAWEFlashFSInstance
	)

Initialize the file system.

Parameters

pAWE	instance to initialize
pAWEFlashFSInstance	the file system instance

Examples: LinuxAppMulti.c.

◆ awe_packetProcess()

INT32 awe_packetProcess ( AWEInstance * pAWE )

Process an AWEInstance's newly received tuning packet.

Parameters

[in] pAWE The AWE instance pointer to process

Returns: error E_SUCCESS, E_COMMAND_NOT_IMPLEMENTED, E_MESSAGE_LENGTH_TOO_LONG, E_CRC_ERROR, E_BADPACKET

Examples: LinuxApp.c, bare_metal_example.c, and singleinstance_simple.c.

◆ awe_packetProcessMulti()

INT32 awe_packetProcessMulti	(	AWEInstance *	pAWE,
		BOOL	isTuningInstance
	)

Multi-instance Wrapper for tuning packet processing.

If called by the tuning instance, call whenever a complete packet is received. Wait until the return value is not E_MULTI_PACKET_WAITING to forward reply back to the tuning interface. If called by a non-tuning instance, poll continuously in a low-priority task.

Parameters

[in]	pAWE	The AWE instance pointer to process
[in]	isTuningInstance	Boolean marking if the instance calling this API implements the tuning interface

Returns: error E_SUCCESS, E_MULTI_PACKET_WAITING, E_COMMAND_NOT_IMPLEMENTED,
E_MESSAGE_LENGTH_TOO_LONG, E_CRC_ERROR, E_BADPACKET

Examples: LinuxAppMulti.c.

◆ awe_audioPump()

INT32 awe_audioPump	(	AWEInstance *	pAWE,
		UINT32	layoutIndex
	)

Audio pump function.

Call this in your audio thread once you have imported the data you wish to process. Before pumping, you must also check that the AudioWeaver buffers have been filled (awe_getPumpMask) and that audio has been started (awe_audioIsStarted). This function will return 1 if awe_deferredSetCall needs to be called. This is for modules that need to do more time consuming calculations, like calculating filter coefficients. For example, a SOF Control module needs to calculate new coeffs when the frequency is modified by the control input.

Parameters

[in]	pAWE	AWE instance pointer
[in]	layoutIndex	the layout index to pump

Returns: E_SUCCESS, E_NO_LAYOUTS, or 1 (indicating that deferred set is needed, see documentation)

Examples: ControlApp.c, LinuxApp.c, LinuxAppMulti.c, and bare_metal_example.c.

◆ awe_audioImportSamples()

INT32 awe_audioImportSamples	(	const AWEInstance *	pAWE,
		const void *	inSamples,
		INT32	inStride,
		INT32	channel,
		SampleType	inType
	)

Import samples from a user buffer to a channel.

The value of the fundamentalBlockSize member of the AWEInstance determines the number of samples that are imported with each call. Call this function once for each audio input channel on the hardware. Channel matching between hardware capabilities and layout will be done automatically. For example, if the target has only 1 audio input channel, and if a layout with 3 input channels is loaded, the second and third channels of the layout input will be all zeros. Inversely, if there are more HW input channels than the layout expects, then they are ignored.

The value of inStride defines the number of samples to skip between each read, and should be the number of interleaved channels in the inSamples buffer being read from. A typical usage for a single source, interleaved stereo input could look like:

awe_audioImportSamples(pAWE, inSamples + 0, 2, 0, Sample32bit);

awe_audioImportSamples(pAWE, inSamples + 1, 2, 1, Sample32bit);

awe_audioImportSamples

INT32 awe_audioImportSamples(const AWEInstance *pAWE, const void *inSamples, INT32 inStride, INT32 channel, SampleType inType)

Import samples from a user buffer to a channel.

Sample32bit

@ Sample32bit

Data is 32 bit PCM .

Definition: StandardDefs.h:231

Parameters

[in]	pAWE	AWE instance
[in]	inSamples	pointer to first sample in buffer to import for current channel
[in]	inStride	input buffer import stride
[in]	channel	channel to write to
[in]	inType	type of input data

Returns: E_SUCCESS, E_AUDIO_NOT_STARTED, E_PARAMETER_ERROR

Examples: ControlApp.c, LinuxApp.c, LinuxAppMulti.c, and bare_metal_example.c.

◆ awe_audioExportSamples()

INT32 awe_audioExportSamples	(	const AWEInstance *	pAWE,
		void *	outSamples,
		INT32	outStride,
		INT32	channel,
		SampleType	outType
	)

Export samples to a user buffer from a channel.

The value of the fundamentalBlockSize member of the AWEInstance determines the number of samples that are exported with each call. Call this function once for each audio output channel on the hardware. Like awe_audioImportSamples, this will do channel matching automatically. For example, if the target has 3 audio output channels, and if a layout with 1 output channel is loaded, the second and third channels of the exported output will be all zeros. Inversely, if the layout has more output channels than the target supports, they are ignored.

The value of outStride defines the number of samples to skip between each write. It should be equal to the number of interleaved channels in the outSamples buffer being written to. A typical usage for exporting to an interleaved 3 channel output could look like:

awe_audioExportSamples(pAWE, &outSamples[0], 3, 0, Sample32bit);
awe_audioExportSamples(pAWE, &outSamples[1], 3, 1, Sample32bit);
awe_audioExportSamples(pAWE, &outSamples[2], 3, 2, Sample32bit);

Parameters

[in]	pAWE	AWE instance
[out]	outSamples	pointer to first sample in buffer to export to
[in]	outStride	output buffer export stride
[in]	channel	channel to read from
[in]	outType	type of output data

Returns: E_SUCCESS, E_AUDIO_NOT_STARTED, E_PARAMETER_ERROR

Examples: ControlApp.c, LinuxApp.c, LinuxAppMulti.c, and bare_metal_example.c.

◆ awe_audioIsStarted()

INT32 awe_audioIsStarted ( const AWEInstance * pAWE )

Check if this instance is running.

A BSP author can use this to determine if the instance is already running to avoid pumping audio through a dead layout.

Parameters

pAWE	instance pointer

Returns: 0 if audio is not started, 1 if audio is started. No error conditions

Examples: ControlApp.c, LinuxApp.c, LinuxAppMulti.c, and bare_metal_example.c.

◆ awe_audioGetPumpMask()

INT32 awe_audioGetPumpMask ( AWEInstance * pAWE )

Test if AWE is ready to run.

This will return the "layout mask" which is a bit vector of threads to run. For a simple, single threaded system, the bitvector will be 0x1. If a previous pump is not complete and the layout is ready to pump again, an overflow is detected by this function. In this condition, the layoutMask bit for the overflowed layout will be zero, which prevents the layout from being pumped again. Example: int layoutMask = awe_audioGetPumpMask(&g_AWEInstance); if (layoutMask > 0) { if (layoutMask & 0x1) { int ret = awe_audioPump(&g_AWEInstance, 0); } }

Parameters

pAWE	AWE instance

Returns: bit vector of threads to run, 0 if no threads, E_AUDIO_NOT_STARTED

Examples: ControlApp.c, LinuxApp.c, LinuxAppMulti.c, and bare_metal_example.c.

◆ awe_audioIsReadyToPumpMulti()

INT32 awe_audioIsReadyToPumpMulti	(	AWEInstance *	pAWE,
		UINT32	instanceID
	)

Test if AWE is ready to run on secondary instances (ID > 0).

This must be used in multi-instance applications to determine when to trigger secondary instances. Failure to do so can result in pumping at the wrong rates. This avoids unneccessary interrupts on secondary instances where layout block size is higher than the fundamental block size. This function returns TRUE or FALSE. When it returns TRUE, corresponding secondary instance is ready to signal. When this function is called with instance ID 0 or invalid ID, then always False is returned. Example: int pumpSlaveInstance = awe_audioIsReadyToPumpMulti(&g_AWEInstance, 1); if (pumpSlaveInstance) { Signal slave core to get pump mask raise(); }

Parameters

pAWE	AWE instance
instanceID	AWE instance ID

Returns: true or false

Examples: LinuxAppMulti.c.

◆ awe_audioStartPreemption()

UINT32 awe_audioStartPreemption	(	AWEInstance *	pAWE,
		INT32	coreAffinity
	)

Function to correct overhead outside of the Audio Weaver, like Audio DMA ISR.

Call this function at the very beginning of the DMA ISR and store the returned value, which is an argument to following end function call. For the use case where multiple instances exists on the same core, this function can be called with any instance's AWEInstance pointer, provided that the user called awe_setInstancesInfo during the startup. Example: UINT32 start_time = awe_audioStartPreemption(&g_AWEInstance, coreAffinity);

Parameters

pAWE	AWE instance
coreAffinity	Core affinity from which this function is called

Returns: start time stamp in cycles at profiling clock

◆ awe_audioEndPreemption()

UINT32 awe_audioEndPreemption	(	AWEInstance *	pAWE,
		UINT32	start_time,
		INT32	coreAffinity
	)

Function to correct overhead outside of the Audio Weaver, like Audio DMA ISR.

Call this function at the end in the DMA ISR with start_time returned by awe_audioStartPreemption(). If the DMA ISR has low latency audio pump calls, then this function must be called before the audio pump and call awe_audioStartPreemption() again after pump. Note that the funtion awe_audioStartPreemption() must be called first, before calling awe_audioEndPreemption(). For the use case where multiple instances exists on the same core, this function can be called with any instance's AWEInstance pointer, provided that the user called awe_setInstancesInfo during the startup. Example: awe_audioEndPreemption(&g_AWEInstance, start_time, coreAffinity);

Parameters

pAWE	AWE instance
start_time	Start time returned by the corresponding start function "awe_audioStartPreemption"
coreAffinity	Core affinity from which this function is called

Returns: Elapsed time between start preempt and this function

◆ awe_deferredSetCall()

INT32 awe_deferredSetCall ( AWEInstance * pAWE )

Perform deferred awe set on a module.

Each call to awe_deferredSetCall processes a single module. Usually this function would be called repeatedly until the return value is 0.

Parameters

[in] pAWE AWE instance pointer

Returns: finishedProcessing Will return 1 when processing is incomplete, 0 when complete. No error codes.

Examples: LinuxApp.c, LinuxAppMulti.c, and bare_metal_example.c.

◆ awe_loadAWBfromArray()

INT32 awe_loadAWBfromArray	(	AWEInstance *	pAWE,
		const UINT32 *	pCommands,
		UINT32	arraySize,
		UINT32 *	pPos
	)

Executes packet commands from an in-memory array.

Designer can generate AWB arrays directly from a layout.

Parameters

[in]	pAWE	AWE instance pointer
[in]	pCommands	Buffer with commands to execute
[in]	arraySize	Number of DWords in command buffer
[out]	pPos	Report failing word index

Returns: E_SUCCESS E_EXCEPTION E_UNEXPECTED_EOF E_END_OF_FILE E_MESSAGE_LENGTH_TOO_LONG E_BADPACKET

Examples: ControlApp.c, and LinuxAppMulti.c.

◆ awe_loadAWBfromFile()

INT32 awe_loadAWBfromFile	(	AWEInstance *	pAWE,
		const char *	binaryFile,
		UINT32 *	pPos
	)

Load an AWB file from stdio.

Parameters

[in]	pAWE	AWE instance pointer
[in]	binaryFile	AWB file to be loaded
[out]	pPos	Report failing word index

Returns: E_SUCCESS E_EXCEPTION E_UNEXPECTED_EOF E_END_OF_FILE E_MESSAGE_LENGTH_TOO_LONG E_BADPACKET E_CANTOPEN

Examples: LinuxApp.c.

◆ awe_loadAWBfromFlash()

INT32 awe_loadAWBfromFlash	(	AWEInstance *	pAWE,
		const char *	binaryFile,
		UINT32 *	pPos
	)

Load an AWB file from the flash.

Parameters

[in]	pAWE	AWE instance pointer
[in]	binaryFile	AWB file to be loaded
[out]	pPos	Report failing word index

Returns: E_SUCCESS E_EXCEPTION E_UNEXPECTED_EOF E_END_OF_FILE E_MESSAGE_LENGTH_TOO_LONG E_BADPACKET E_CANTOPEN

◆ awe_layoutGetChannelCount()

void awe_layoutGetChannelCount	(	const AWEInstance *	pAWE,
		UINT32	pinIdx,
		UINT32 *	inCount,
		UINT32 *	outCount
	)

Returns the number of channels in the Layout's input and output pins.

Parameters

[in]	pAWE	AWE instance pointer
[in]	pinIdx	which input pin (always 0)
[out]	inCount	channels in primary input pin
[out]	outCount	channels in primary output pin

Examples: ControlApp.c.

◆ awe_layoutGetInputBlockSize()

INT32 awe_layoutGetInputBlockSize	(	const AWEInstance *	pAWE,
		UINT32	pinIdx,
		UINT32 *	blockSize
	)

Returns the block size of a pin.

Because the block size of the output pin is inherited from the input pin, the user only needs to check the input pin.

Parameters

[in]	pAWE	The AWE Instance
[in]	pinIdx	which input pin (always 0)
[out]	blockSize	block size of input pin

Returns: E_SUCCESS, E_NO_LAYOUTS, E_PIN_ID_NOT_FOUND

Examples: ControlApp.c.

◆ awe_layoutGetInputSampleRate()

INT32 awe_layoutGetInputSampleRate	(	const AWEInstance *	pAWE,
		UINT32	pinIdx,
		FLOAT32 *	sampleRate
	)

Returns the sample rate of an input pin.

Because the sample rate of the output pin is inherited from the input pin, the user only needs to check the input pin.

Parameters

[in]	pAWE	The AWE Instance
[in]	pinIdx	which input pin (always 0)
[out]	sampleRate	the input pin sample rate

Returns: E_SUCCESS, E_NO_LAYOUTS, E_PIN_ID_NOT_FOUND

◆ awe_layoutIsValid()

INT32 awe_layoutIsValid ( const AWEInstance * pAWE )

Determines if a layout is loaded and valid.

Parameters

[in] pAWE The AWE Instance

Returns: 0 if layout is not valid/loaded, 1 if layout is valid. No error codes.

Examples: ControlApp.c, LinuxApp.c, LinuxAppMulti.c, and bare_metal_example.c.

◆ awe_ctrlSetValue()

INT32 awe_ctrlSetValue	(	const AWEInstance *	pAWE,
		UINT32	handle,
		const void *	value,
		INT32	arrayOffset,
		UINT32	length
	)

Set a scalar or array value of a module variable by handle.

Parameters

[in]	pAWE	instance pointer
[in]	handle	packed object handle
[in]	value	value(s) to set
[in]	arrayOffset	array index if array
[in]	length	number of elements. 1 if scaler

Returns: E_SUCCESS, E_ARGUMENT_ERROR, E_BAD_MEMBER_INDEX, E_CLASS_NOT_SUPPORTED, E_LINKEDLIST_CORRUPT, E_NO_MORE_OBJECTS

Examples: ControlApp.c, and bare_metal_example.c.

◆ awe_ctrlGetValue()

INT32 awe_ctrlGetValue	(	const AWEInstance *	pAWE,
		UINT32	handle,
		void *	value,
		INT32	arrayOffset,
		UINT32	length
	)

Get a scalar or array value of a module variable by handle.

Parameters

[in]	pAWE	instance pointer
[in]	handle	packed object handle
[out]	value	value(s) to get
[in]	arrayOffset	array index if array
[in]	length	number of elements. 1 if scaler

Returns: E_SUCCESS, E_ARGUMENT_ERROR, E_BAD_MEMBER_INDEX, E_CLASS_NOT_SUPPORTED, E_LINKEDLIST_CORRUPT, E_NO_MORE_OBJECTS

Examples: ControlApp.c, and bare_metal_example.c.

◆ awe_ctrlSetStatus()

INT32 awe_ctrlSetStatus	(	const AWEInstance *	pAWE,
		UINT32	handle,
		UINT32	status
	)

Set the runtime status of a module.

0 = Active, 1 = Bypass, 2 = Mute, 3 = Inactive

Parameters

[in]	pAWE	instance pointer
[in]	handle	packed object handle
[in]	status	status to set

Returns: E_SUCCESS, E_NOT_MODULE, E_LINKEDLIST_CORRUPT, E_NO_MORE_OBJECTS

◆ awe_ctrlGetStatus()

INT32 awe_ctrlGetStatus	(	const AWEInstance *	pAWE,
		UINT32	handle,
		UINT32 *	status
	)

Get the runtime status of a module.

0 = Active, 1 = Bypass, 2 = Mute, 3 = Inactive

Parameters

[in]	pAWE	instance pointer
[in]	handle	packed object handle
[out]	status	pointer to return status value

Returns: E_SUCCESS, E_NOT_MODULE, E_LINKEDLIST_CORRUPT, E_NO_MORE_OBJECTS, E_PARAMETER_ERROR

◆ awe_ctrlSetValueMask()

INT32 awe_ctrlSetValueMask	(	const AWEInstance *	pAWE,
		UINT32	handle,
		const void *	value,
		INT32	arrayOffset,
		UINT32	length,
		UINT32	mask
	)

Set a scalar or array value of a module variable by handle with mask.

A mask allows you to only call module's set function for a single variable.

Parameters

[in]	pAWE	instance pointer
[in]	handle	packed object handle
[in]	value	value(s) to set
[in]	arrayOffset	array index if array
[in]	length	number of elements if array. 1 if scaler
[in]	mask	mask to use - 0 to not call set function

Returns: E_SUCCESS, E_ARGUMENT_ERROR, E_BAD_MEMBER_INDEX, E_CLASS_NOT_SUPPORTED, E_OBJECT_ID_NOT_FOUND, E_NOT_MODULE

◆ awe_ctrlGetValueMask()

INT32 awe_ctrlGetValueMask	(	const AWEInstance *	pAWE,
		UINT32	handle,
		void *	value,
		INT32	arrayOffset,
		UINT32	length,
		UINT32	mask
	)

Get a scalar or array value of a module variable by handle with mask.

A mask allows you to only call module's set function for a single variable.

Parameters

[in]	pAWE	instance pointer
[in]	handle	packed object handle
[out]	value	value(s) to get
[in]	arrayOffset	array index if array
[in]	length	number of elements if array. 1 if scaler
[in]	mask	mask to use - 0 to not call get function

Returns: E_SUCCESS, E_ARGUMENT_ERROR, E_BAD_MEMBER_INDEX, E_CLASS_NOT_SUPPORTED, E_OBJECT_ID_NOT_FOUND, E_NOT_MODULE

◆ awe_ctrlGetModuleClass()

INT32 awe_ctrlGetModuleClass	(	const AWEInstance *	pAWE,
		UINT32	handle,
		UINT32 *	pClassID
	)

Get an object class from its handle.

Parameters

	pAWE	instance pointer
[in]	handle	handle of object to find
[out]	pClassID	pointer to found object class

Returns: E_SUCCESS, E_NO_MORE_OBJECTS, E_LINKEDLIST_CORRUPT

Examples: ControlApp.c, and bare_metal_example.c.

◆ awe_setProfilingStatus()

INT32 awe_setProfilingStatus	(	AWEInstance *	pAWE,
		UINT32	status
	)

Enable or disable the profiling ability of the AWE Core.

Both top and module level profiling and preemption overhead correction enabled by default at awe_init. Use this function if you wish to selectively enable or disable per pump profiling during runtime. Disabling profiling saves a small amount of cycles per pump. User can also enable or disable independently module level profiling and top level profiling and overhead correction due to preemption.

Parameters

pAWE	instance pointer
status	0 to disable both, 1 to enable both, 2 to enable module level only, 3 to enable top level only, 4 to enable preemption overhead correction and 5 to disable preemption overhead correction

Returns: E_SUCCESS, E_NOT_OBJECT, E_PARAMETER_ERROR

Examples: ControlApp.c, LinuxApp.c, and LinuxAppMulti.c.

◆ awe_getAverageLayoutCycles()

INT32 awe_getAverageLayoutCycles	(	AWEInstance *	pAWE,
		UINT32	layoutIdx,
		UINT32 *	averageCycles
	)

Get the average cycles of a running layout, in units of cycles at profileSpeed.

Returns cycles in 24.8 format, so shift right by 8 bits for integer value. To get CPU cycles, multiply by target cpuSpeed / profileSpeed. If a previous pump is not complete and the layout is ready to pump again, an overflow is detected. When in this state, the awe_getAverageLayoutCycles api will return the averageCycles = AWE_PUMP_OVF_MAX_AVG_CYCLES (0xFFFFFFFF).

Parameters

pAWE	instance pointer
layoutIdx	Layout index (typically 0, except in advanced use cases)
averageCycles	Pointer the output (average layout cycles)

Returns: E_SUCCESS, E_PARAMETER_ERROR, E_NO_LAYOUTS

Examples: LinuxAppMulti.c.

◆ awe_setInstancesInfo()

void awe_setInstancesInfo	(	AWEInstance **	pInstances,
		INT32	numAweInstancesOnCore
	)

Setup function only intended for systems with multiple AWE Instances in a single core.

Call this function at startup after awe_init is done in the sequence. Enables both accurate profiling and loading of multi-instance designs.

Parameters

[in]	pInstances	Array of AWE Instance pointers that process on one core. Array must exist as long as the system is active.
[in]	numAweInstancesOnCore	Number of AWE Instances in pInstances array.

Examples: LinuxAppMulti.c.

◆ awe_fwSetLayoutCoreAffinity()

INT32 awe_fwSetLayoutCoreAffinity	(	AWEInstance *	pAWE,
		INT32	layoutNumber,
		INT32	coreAffinity
	)

Set the core affinity of the layout in layoutNumber.

Used to get more accurate profiling in multithreaded systems.

Parameters

[in]	pAWE	AWE instance pointer (this)
[in]	layoutNumber	the layout index to set the core affinity.
[in]	coreAffinity	core affinity to set in the layout.

Returns: E_SUCCESS or E_INVALID_LAYOUT_INDEX if no layout

◆ awe_fwGetLayoutCoreAffinity()

INT32 awe_fwGetLayoutCoreAffinity	(	AWEInstance *	pAWE,
		INT32	layoutNumber
	)

Get the core affinity of the layout in layoutNumber, initializes to 0 and can be set with awe_fwSetLayoutCoreAffinity.

Parameters

[in]	pAWE	AWE instance pointer (this)
[in]	layoutNumber	the layout index to get the core affinity.

Returns: the core affinity of the requested layout, or E_INVALID_LAYOUT_INDEX if no layout

◆ awe_getBuildVersionInfo()

INT32 awe_getBuildVersionInfo ( AWEBuildVersionInfo_t * pBuildVersionInfo )

Get the AWECore build number and version information.

Parameters

[in,out] pBuildVersionInfo Pointer of type AWEBuildVersionInfo_t to return build version information

Returns: Return E_SUCCESS up on success. If pBuildVersionInfo is NULL, E_NOT_OBJECT returned.

Examples: LinuxApp.c.

◆ awe_setInstanceStandaloneAWBLoad()

INT32 awe_setInstanceStandaloneAWBLoad	(	AWEInstance *	pAWE,
		INT32	status
	)

This function can be used to achieve Progressive Loading on a multi-instance system.

Indicates this instance loads AWB in standalone mode.

Parameters

[in]	pAWE	AWE instance pointer (this)
[in]	status	Boolean flag indicates to enable or disable standalone loading. 1 - to enable standalone mode, 0 - to disable standalone mode. Default disabled.

Returns: E_NO_HEAP_MEMORY if no shared memory exists and E_SUCCESS otherwise.

◆ awe_registerLoggingCallback()

INT32 awe_registerLoggingCallback	(	AWEInstance *	pAWE,
		cbAweLogging_t	cbAweLogging,
		INT32	logLevel,
		UINT32	logTypeMask
	)

Register the logging callback with required logging level and logging type mask.

The type mask is used to filter out undesired event types

Parameters

[in]	pAWE	AWE instance pointer
[in]	cbAweLogging	Function pointer of the logging callback.
[in]	logLevel	Logging level. 0 = AWE_LOG_LEVEL_NONE (DISABLED), 1 = AWE_LOG_LEVEL_ERROR, 2 = AWE_LOG_LEVEL_WARNING, 3 = AWE_LOG_LEVEL_INFO, 4 = AWE_LOG_LEVEL_DEBUG
[in]	logTypeMask	Logging type mask. Combination of any logging type like AWE_LOG_SYSTEM_MSG \| AWE_LOG_CPU_OVERFLOW_MSG. Use AWE_LOG_ALL_TYPE_MASK to subscribe to all logging message types Please note that logging messages never end with a newline so the user callback has to apply that as desired.

Returns: E_SUCCESS or E_NOT_OBJECT if invalid pAWE or E_PARAMETER_ERROR if invalid cbAweLogging.

Examples: LinuxApp.c.

◆ awe_registerEventCallbacks()

INT32 awe_registerEventCallbacks	(	AWEInstance *	pAWE,
		cbAweEventTrigger_t	cbAweEventTrigger,
		cbAweEventRegister_t	cbAweEventRegister,
		cbAweEventDeregister_t	cbAweEventDeregister
	)

Register the event callbacks used by the Event Module.

cbAweEventTrigger must be non-null. The cbAweEventRegister and cbAweEventDeregister can be null.

Parameters

[in]	pAWE	AWE instance pointer
[in]	cbAweEventTrigger	Function pointer of the event trigger callback
[in]	cbAweEventRegister	Function pointer of the event register callback (optional)
[in]	cbAweEventDeregister	Function pointer of the event deregister callback (optional)

Returns: E_SUCCESS on success, or E_NOT_OBJECT if invalid pAWE, or E_PARAMETER_ERROR if invalid cbAweEventTrigger.

Examples: LinuxApp.c.

Data Structures

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ cbAweLogging_t

◆ cbAweEventTrigger_t

◆ cbAweEventRegister_t

◆ cbAweEventDeregister_t

◆ AWEInstance

Function Documentation

◆ awe_init()

◆ awe_initPin()

◆ awe_initFlashFS()

◆ awe_packetProcess()

◆ awe_packetProcessMulti()

◆ awe_audioPump()

◆ awe_audioImportSamples()

◆ awe_audioExportSamples()

◆ awe_audioIsStarted()

◆ awe_audioGetPumpMask()

◆ awe_audioIsReadyToPumpMulti()

◆ awe_audioStartPreemption()

◆ awe_audioEndPreemption()

◆ awe_deferredSetCall()

◆ awe_loadAWBfromArray()

◆ awe_loadAWBfromFile()

◆ awe_loadAWBfromFlash()

◆ awe_layoutGetChannelCount()

◆ awe_layoutGetInputBlockSize()

◆ awe_layoutGetInputSampleRate()

◆ awe_layoutIsValid()

◆ awe_ctrlSetValue()

◆ awe_ctrlGetValue()

◆ awe_ctrlSetStatus()

◆ awe_ctrlGetStatus()

◆ awe_ctrlSetValueMask()

◆ awe_ctrlGetValueMask()

◆ awe_ctrlGetModuleClass()

◆ awe_setProfilingStatus()

◆ awe_getAverageLayoutCycles()

◆ awe_setInstancesInfo()

◆ awe_fwSetLayoutCoreAffinity()

◆ awe_fwGetLayoutCoreAffinity()

◆ awe_getBuildVersionInfo()

◆ awe_setInstanceStandaloneAWBLoad()

◆ awe_registerLoggingCallback()

◆ awe_registerEventCallbacks()