The AWECore API Header File. More...

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

Data Structures
struct	IOPinDescriptor
	AWE IO Pin type. More...

struct	AWEFlashFSInstance
	The DSPC Flash File System Instance Optional – SINGLE INSTANCE ONLY. More...

struct	AWEInstance
	The AWE instance. More...

Macros
#define	WORDSOF(x) (sizeof(x) / sizeof(INT32))

#define	NUMOF(x) (sizeof(x) / sizeof(*x))

#define	AWE_UNUSED_VARIABLE(x) ((void)(x))

Typedefs
typedef struct IOPinDescriptor	IOPinDescriptor
	AWE IO Pin type. More...

typedef struct AWEFlashFSInstance	AWEFlashFSInstance
	The DSPC Flash File System Instance Optional – SINGLE INSTANCE ONLY.

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

typedef enum _SampleType	SampleType
	Type of data for I/O. More...

Enumerations
enum	_SampleType { Sample16bit, Sample24bit_low, Sample24bit_high, Sample32bit }
	Type of data for I/O. More...

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_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 (const AWEInstance *pAWE)
	Test if AWE is ready to run. 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...

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_ctrlGetValue (const AWEInstance pAWE, UINT32 handle, const void value, INT32 arrayOffset, UINT32 length)
	Set a scalar or array value by handle. More...

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

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

INT32	awe_ctrlGetStatus (const AWEInstance pAWE, UINT32 handle, UINT32 status)
	Get the 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 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 by handle with mask. More...

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

Detailed Description

The AWECore API Header File.

Typedef Documentation

◆ IOPinDescriptor

typedef struct IOPinDescriptor IOPinDescriptor

AWE IO Pin type.

The AWE typedef for input/output pins. A BSP author will allocate their input/output pins of this type.

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

◆ SampleType

typedef enum _SampleType SampleType

Type of data for I/O.

Enumeration Type Documentation

◆ _SampleType

enum _SampleType

Type of data for I/O.

Enumerator
Sample16bit	Data is 16 bit PCM.
Sample24bit_low	Data is 24 bit PCM aligned to the low bit in 32 bit buffers.
Sample24bit_high	Data is 24 bit PCM aligned to the high bit in 32 bit buffers.
Sample32bit	Data is 32 bit PCM .

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: 0 or error code

Examples:: 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: 0 or error code

Examples:: 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

◆ 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/success 0 for success, negative on error

Examples:: bare_metal_example.c, and singleinstance_simple.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 (this)
[in]	layoutIndex	the layout index to pump

Returns: 0 for success, negative for error, 1 for deferred set needed

Examples:: 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.

This will perform channel matching implicitly. For example, if you have a BSP with one HW input and 2 HW outputs, call awe_audioImportSamples once for input channel 0. If you run a layout with 9 input channels, the other 8 channels of the layout will be automatically ignored.

Parameters

pAWE	AWE instance
inSamples	samples to read from
inStride	input buffer stride
channel	channel to write to
inType	type of input data

Returns: 0 on success, negative on error

Examples:: 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.

Like awe_audioImportSamples, this will do channel matching implicitly. For example, if you have a BSP with 2 HW output channels, then call awe_audioExportSamples twice (once for channel 0 and once for channel 1). Now, if you have a layout with one output channel, the second output channel will automatically be zeroed. Inversely, if you have a layout with 9 output channels, the additional 7 channels will be ignored.

Parameters

pAWE	AWE instance
outSamples	samples to write to
outStride	output buffer stride
channel	channel to read from
outType	type of output data

Returns: 0 on success, negative on error

Examples:: 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

pvAWE instance pointer

Returns: 0 if not started, 1 if started

Examples:: bare_metal_example.c.

◆ awe_audioGetPumpMask()

INT32 awe_audioGetPumpMask ( const 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. 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 none

Examples:: bare_metal_example.c.

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

Examples:: 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: 0 or error code

◆ 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
[out]	inCount	channels in primary input pin
[out]	outCount	channels in primary output pin

◆ 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
[out]	blockSize	block size of input pin

Returns: 0 or error code

◆ 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
[out]	sampleRate	the input pin sample rate

Returns: 0 or error code

◆ 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 not valid/loaded, 1 if it is

Examples:: bare_metal_example.c.

◆ awe_ctrlGetValue()

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

Set a scalar or array value by handle.

Parameters

pAWE	instance pointer
handle	packed object handle
value	value(s) to set
arrayOffset	array index if array
length	number of elements if array

Returns: error code

Examples:: bare_metal_example.c.

◆ awe_ctrlSetValue()

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

Get a scalar or array value by handle.

Parameters

pAWE	instance pointer
handle	packed object handle
value	value(s) got
arrayOffset	array index if array
length	number of elements if array

Returns: error code

Examples:: bare_metal_example.c.

◆ awe_ctrlSetStatus()

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

Set the status of a module.

Parameters

pAWE	instance pointer
handle	packed object handle
status	status to set

Returns: error code

◆ awe_ctrlGetStatus()

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

Get the status of a module.

Parameters

pAWE	instance pointer
handle	packed object handle
status	returned status

Returns: error code

◆ 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 by handle with mask.

A mask allows you to only

Parameters

pAWE	instance pointer
handle	packed object handle
value	value(s) to set
arrayOffset	array index if array
length	number of elements if array
mask	mask to use - 0 do not call set function

Returns: error code

◆ awe_ctrlGetValueMask()

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

Get a scalar or array value by handle with mask.

Parameters

pAWE	instance pointer
handle	packed object handle
value	value(s) got
arrayOffset	array index if array
length	number of elements if array
mask	mask to use - 0 do not call get function

Returns: error code

◆ 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 receive found object class

Returns: 0 or error code

Examples:: bare_metal_example.c.

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Typedef Documentation

◆ IOPinDescriptor

◆ AWEInstance

◆ SampleType

Enumeration Type Documentation

◆ _SampleType

Function Documentation

◆ awe_init()

◆ awe_initPin()

◆ awe_initFlashFS()

◆ awe_packetProcess()

◆ awe_audioPump()

◆ awe_audioImportSamples()

◆ awe_audioExportSamples()

◆ awe_audioIsStarted()

◆ awe_audioGetPumpMask()

◆ awe_deferredSetCall()

◆ awe_loadAWBfromArray()

◆ awe_layoutGetChannelCount()

◆ awe_layoutGetInputBlockSize()

◆ awe_layoutGetInputSampleRate()

◆ awe_layoutIsValid()

◆ awe_ctrlGetValue()

◆ awe_ctrlSetValue()

◆ awe_ctrlSetStatus()

◆ awe_ctrlGetStatus()

◆ awe_ctrlSetValueMask()

◆ awe_ctrlGetValueMask()

◆ awe_ctrlGetModuleClass()