AWEInstance.h

The AWEInstance API Header File.

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

Detailed Description

The AWEInstance API Header File.

Typedef Documentation

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

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

ReturnsE_SUCCESS, E_NULL_PACKET_BUFFER_POINTER, E_NULL_REPLY_BUFFER_POINTER, E_ZERO_PACKET_BUFFER_LENGTH, E_EXCEPTION, E_PARAMETER_ERROR, E_NOT_CREATED

Examplesbare_metal_example.c, ControlApp.c, LinuxApp.c, and singleinstance_simple.c.

◆ awe_initPin()

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

ReturnsE_SUCCESS

Examplesbare_metal_example.c, ControlApp.c, LinuxApp.c, and singleinstance_simple.c.

◆ awe_initFlashFS()

Initialize the file system.

Parameters

◆ awe_packetProcess()

Process an AWEInstance's newly received tuning packet.

Parameters

Returnserror E_SUCCESS, E_COMMAND_NOT_IMPLEMENTED, E_MESSAGE_LENGTH_TOO_LONG, E_CRC_ERROR, E_BADPACKET

Examplesbare_metal_example.c, LinuxApp.c, and singleinstance_simple.c.

◆ awe_audioPump()

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

ReturnsE_SUCCESS, E_NO_LAYOUTS, or 1 (indicating that deferred set is needed, see documentation)

Examplesbare_metal_example.c, ControlApp.c, and LinuxApp.c.

◆ awe_audioImportSamples()

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:

Parameters

ReturnsE_SUCCESS, E_AUDIO_NOT_STARTED

Examplesbare_metal_example.c, ControlApp.c, and LinuxApp.c.

◆ awe_audioExportSamples()

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:

Parameters

ReturnsE_SUCCESS, E_AUDIO_NOT_STARTED

Examplesbare_metal_example.c, ControlApp.c, and LinuxApp.c.

◆ awe_audioIsStarted()

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

Returns0 if audio is not started, 1 if audio is started. No error conditions

Examplesbare_metal_example.c, ControlApp.c, and LinuxApp.c.

◆ awe_audioGetPumpMask()

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

Returnsbit vector of threads to run, 0 if no threads, E_AUDIO_NOT_STARTED

Examplesbare_metal_example.c, ControlApp.c, and LinuxApp.c.

◆ awe_deferredSetCall()

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

ReturnsfinishedProcessing Will return 1 when processing is incomplete, 0 when complete. No error codes.

Examplesbare_metal_example.c, and LinuxApp.c.

◆ awe_loadAWBfromArray()

Executes packet commands from an in-memory array.

Designer can generate AWB arrays directly from a layout.

Parameters

ReturnsE_SUCCESS, E_EXCEPTION, E_UNEXPECTED_EOF

ExamplesControlApp.c.

◆ awe_layoutGetChannelCount()

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

Parameters

ExamplesControlApp.c.

◆ awe_layoutGetInputBlockSize()

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

ReturnsE_SUCCESS, E_NO_LAYOUTS

ExamplesControlApp.c.

◆ awe_layoutGetInputSampleRate()

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

ReturnsE_SUCCESS, E_NO_LAYOUTS

◆ awe_layoutIsValid()

Determines if a layout is loaded and valid.

Parameters

Returns0 if layout is not valid/loaded, 1 if layout is valid. No error codes.

Examplesbare_metal_example.c, ControlApp.c, and LinuxApp.c.

◆ awe_ctrlSetValue()

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

Parameters

ReturnsE_SUCCESS, E_ARGUMENT_ERROR, E_BAD_MEMBER_INDEX, E_CLASS_NOT_SUPPORTED, E_LINKEDLIST_CORRUPT, E_NO_MORE_OBJECTS

Examplesbare_metal_example.c, and ControlApp.c.

◆ awe_ctrlGetValue()

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

Parameters

ReturnsE_SUCCESS, E_ARGUMENT_ERROR, E_BAD_MEMBER_INDEX, E_CLASS_NOT_SUPPORTED, E_LINKEDLIST_CORRUPT, E_NO_MORE_OBJECTS

Examplesbare_metal_example.c, and ControlApp.c.

◆ awe_ctrlSetStatus()

Set the runtime status of a module.

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

Parameters

ReturnsE_SUCCESS, E_NOT_MODULE, E_LINKEDLIST_CORRUPT, E_NO_MORE_OBJECTS

◆ awe_ctrlGetStatus()

Get the runtime status of a module.

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

Parameters

ReturnsE_SUCCESS, E_NOT_MODULE, E_LINKEDLIST_CORRUPT, E_NO_MORE_OBJECTS, E_PARAMETER_ERROR

◆ awe_ctrlSetValueMask()

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

ReturnsE_SUCCESS, E_ARGUMENT_ERROR, E_BAD_MEMBER_INDEX, E_CLASS_NOT_SUPPORTED, E_OBJECT_ID_NOT_FOUND, E_NOT_MODULE

◆ awe_ctrlGetValueMask()

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

ReturnsE_SUCCESS, E_ARGUMENT_ERROR, E_BAD_MEMBER_INDEX, E_CLASS_NOT_SUPPORTED, E_OBJECT_ID_NOT_FOUND, E_NOT_MODULE

◆ awe_ctrlGetModuleClass()

Get an object class from its handle.

Parameters

ReturnsE_SUCCESS, E_NO_MORE_OBJECTS, E_LINKEDLIST_CORRUPT

Examplesbare_metal_example.c, and ControlApp.c.

◆ awe_setProfilingStatus()

Enable or disable the profiling ability of the AWECore.

Both top and module level profiling enabled by default at awe_init. Use this 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.

Parameters

ReturnsE_SUCCESS, E_NOT_OBJECT, E_PARAMETER_ERROR

ExamplesControlApp.c, and LinuxApp.c.

◆ awe_getAverageLayoutCycles()

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

ReturnsE_SUCCESS, E_PARAMETER_ERROR, E_NO_LAYOUTS