AWE Core 8.D.9 Documentation
Data Structures | Typedefs | Functions
AWEInstance.h File Reference

The AWEInstance API Header File. More...

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

Go to the source code of this file.

Data Structures

struct  _AWEInstance
 The AWE instance. More...
 
struct  AWEBuildVersionInfo
 Build versioning structure returned by awe_getBuildVersionInfo. More...
 

Typedefs

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

Detailed Description

The AWEInstance API Header File.

Typedef Documentation

◆ 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
pAWEinstance 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]pPinthe pin instance to initialize
[in]channelsnumber of channels
[in]nameoptional 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
pAWEinstance to initialize
pAWEFlashFSInstancethe file system instance
Examples
LinuxAppMulti.c.

◆ awe_packetProcess()

INT32 awe_packetProcess ( AWEInstance pAWE)

Process an AWEInstance's newly received tuning packet.

Parameters
[in]pAWEThe 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]pAWEThe AWE instance pointer to process
[in]isTuningInstanceBoolean 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]pAWEAWE instance pointer
[in]layoutIndexthe 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);
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
Data is 32 bit PCM .
Definition: StandardDefs.h:231
Parameters
[in]pAWEAWE instance
[in]inSamplespointer to first sample in buffer to import for current channel
[in]inStrideinput buffer import stride
[in]channelchannel to write to
[in]inTypetype 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);
INT32 awe_audioExportSamples(const AWEInstance *pAWE, void *outSamples, INT32 outStride, INT32 channel, SampleType outType)
Export samples to a user buffer from a channel.
Parameters
[in]pAWEAWE instance
[out]outSamplespointer to first sample in buffer to export to
[in]outStrideoutput buffer export stride
[in]channelchannel to read from
[in]outTypetype 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
pAWEinstance 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
pAWEAWE 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
pAWEAWE instance
instanceIDAWE 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
pAWEAWE instance
coreAffinityCore 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
pAWEAWE instance
start_timeStart time returned by the corresponding start function "awe_audioStartPreemption"
coreAffinityCore 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]pAWEAWE 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]pAWEAWE instance pointer
[in]pCommandsBuffer with commands to execute
[in]arraySizeNumber of DWords in command buffer
[out]pPosReport 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]pAWEAWE instance pointer
[in]binaryFileAWB file to be loaded
[out]pPosReport 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]pAWEAWE instance pointer
[in]binaryFileAWB file to be loaded
[out]pPosReport 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]pAWEAWE instance pointer
[in]pinIdxwhich input pin (always 0)
[out]inCountchannels in primary input pin
[out]outCountchannels 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]pAWEThe AWE Instance
[in]pinIdxwhich input pin (always 0)
[out]blockSizeblock 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]pAWEThe AWE Instance
[in]pinIdxwhich input pin (always 0)
[out]sampleRatethe 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]pAWEThe 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]pAWEinstance pointer
[in]handlepacked object handle
[in]valuevalue(s) to set
[in]arrayOffsetarray index if array
[in]lengthnumber 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]pAWEinstance pointer
[in]handlepacked object handle
[out]valuevalue(s) to get
[in]arrayOffsetarray index if array
[in]lengthnumber 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]pAWEinstance pointer
[in]handlepacked object handle
[in]statusstatus 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]pAWEinstance pointer
[in]handlepacked object handle
[out]statuspointer 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]pAWEinstance pointer
[in]handlepacked object handle
[in]valuevalue(s) to set
[in]arrayOffsetarray index if array
[in]lengthnumber of elements if array. 1 if scaler
[in]maskmask 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]pAWEinstance pointer
[in]handlepacked object handle
[out]valuevalue(s) to get
[in]arrayOffsetarray index if array
[in]lengthnumber of elements if array. 1 if scaler
[in]maskmask 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
pAWEinstance pointer
[in]handlehandle of object to find
[out]pClassIDpointer 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
pAWEinstance pointer
status0 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
pAWEinstance pointer
layoutIdxLayout index (typically 0, except in advanced use cases)
averageCyclesPointer 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]pInstancesArray of AWE Instance pointers that process on one core. Array must
exist as long as the system is active.
[in]numAweInstancesOnCoreNumber 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]pAWEAWE instance pointer (this)
[in]layoutNumberthe layout index to set the core affinity.
[in]coreAffinitycore 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]pAWEAWE instance pointer (this)
[in]layoutNumberthe 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]pBuildVersionInfoPointer 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.