AWECoreOS API

Types

	Name
typedef void()(AWEOSInstance pAWEOS, INT32 level, UINT32 type, void *payload, INT32 payloadSizeInBytes)	cbAweOSLogging_t OPTIONAL This callback is invoked from multiple places in the AWE framework to log any message to the BSP.
typedef INT32()(AWEOSInstance pAWEOS, INT32 eventType, UINT32 moduleObjId, void payload, INT32 payloadSizeInBytes, void userHandle)	cbAweOSEventTrigger_t OPTIONAL These callback are invoked only from the Event Module.
typedef INT32()(AWEOSInstance pAWEOS, INT32 eventType, UINT32 moduleObjId, INT32 payloadSizeInBytes, void **userHandle)	cbAweOSEventRegister_t The Event Register callback is called by an Event Module when it is constructed.
typedef INT32()(AWEOSInstance pAWEOS, INT32 eventType, UINT32 moduleObjId, void **userHandle)	cbAweOSEventDeregister_t The Event Deregister callback is called by the Event Module when it is destroyed.

Functions

	Name
UINT32	aweOS_getThreadPIDs(AWEOSInstance * pAWEOS, AWEOSThreadPIDs_t * threadPIDs) Return the PIDs of all internally spawned AWE Core OS threads.
INT32	aweOS_getParamDefaults(AWEOSConfigParameters * aweParams) Populates an AWEOSConfigParameters structure with defaults.
INT32	aweOS_init(AWEOSInstance ** pAWEOS, const AWEOSConfigParameters * aweParams, const void * pModuleDescriptorTable, UINT32 moduleDescriptorTableSize) Initialize the AWEOSInstance with the specified configuration parameters.
INT32	aweOS_tuningSocketOpen(AWEOSInstance ** pAWEOS, INT32 portNo, UINT32 numInstances) Initialize and open an integrated TCP/IP tuning interface socket.
void	aweOS_tuningSocketClose(AWEOSInstance * pAWEOS) Close a running integrated TCP tuning socket.
INT32	aweOS_tuningLoggingEnable(AWEOSInstance * pAWEOS, char * path, char * baseName, UINT32 verbosity) Enable logging of the tuning packets sent and received by the AWEOSInstance.
INT32	aweOS_loadAWBFromArray(AWEOSInstance * pAWEOS, const UINT32 * pArray, UINT32 arraySize, UINT32 * pErrorOffset) Executes packet commands from an in-memory array.
INT32	aweOS_loadAWBFile(AWEOSInstance * pAWEOS, const char * binaryFile, UINT32 * pErrorOffset) Executes packet commands from an AWB file on the filesystem.
INT32	aweOS_loadSubcanvasAWBfromArray(AWEOSInstance * pAWEOS, UINT32 SubcanvasModObjectID, const UINT32 * pCommands, UINT32 arraySize, UINT32 * pPos) Executes packet commands from an in-memory array and loads AWB in Subcanvas module.
INT32	aweOS_loadSubcanvasAWBfromFile(AWEOSInstance * pAWEOS, UINT32 SubcanvasModObjectID, const char * binaryFile, UINT32 * pPos) Load an AWB file from stdio into Subcanvas module.
INT32	aweOS_appendModules(AWEOSInstance * pAWEOS, size_t length, const void const modules) Append an array of module class pointers to the AWECoreOS instance's dynamic module list.
INT32	aweOS_layoutGetChannelCount(const AWEOSInstance * pAWEOS, UINT32 * inCount, UINT32 * outCount) Returns the number of input and output channels in the loaded layout.
INT32	aweOS_layoutGetBlockSize(const AWEOSInstance * pAWEOS, UINT32 * blockSize) Returns the block size of the loaded layout.
INT32	aweOS_layoutGetSampleRate(const AWEOSInstance * pAWEOS, FLOAT32 * sampleRate) Returns the sample rate of the loaded layout.
INT32	aweOS_audioPumpAll(AWEOSInstance * pAWEOS) Pump one fundamental block size of audio through the loaded layout and all of its sublayouts.
INT32	aweOS_audioImportSamples(AWEOSInstance * pAWEOS, void * inSamples, INT32 inStride, INT32 channel, SampleType inType) Import samples from an audio buffer to a specific channel of the AWEOSInstance's input pin.
INT32	aweOS_audioExportSamples(AWEOSInstance * pAWEOS, void * outSamples, INT32 outStride, INT32 channel, SampleType outType) Export samples to a user buffer from a specific channel of the AWEOSInstance's output pin.
INT32	aweOS_layoutIsValid(const AWEOSInstance * pAWEOS) Determines if a layout is loaded and valid.
INT32	aweOS_audioIsStarted(const AWEOSInstance * pAWEOS) Check if this instance has received an Audio Start command.
const char *	aweOS_errorToString(INT32 errorCode) Convert an error code (INT32) to its corresponding error string.
INT32	aweOS_tuningPacketProcess(AWEOSInstance * pAWEOS) Process the packet buffer in the AWEOSInstance.
INT32	aweOS_ctrlSetValue(const AWEOSInstance * pAWEOS, UINT32 handle, void * value, INT32 arrayOffset, UINT32 length) Set a scalar or array value(s) of a module parameter by handle.
INT32	aweOS_ctrlGetValue(const AWEOSInstance * pAWEOS, UINT32 handle, void * value, INT32 arrayOffset, UINT32 length) Get a scalar or array value(s) of a module parameter by handle.
INT32	aweOS_ctrlSetStatus(const AWEOSInstance * pAWEOS, UINT32 handle, UINT32 * status) Set the status of a module.
INT32	aweOS_ctrlGetStatus(const AWEOSInstance * pAWEOS, UINT32 handle, UINT32 * status) Get the status of a module.
INT32	aweOS_ctrlSetValueMask(const AWEOSInstance * pAWEOS, UINT32 handle, void * value, INT32 arrayOffset, UINT32 length, UINT32 mask) Set a scalar or array value(s) of a module variable by handle with mask.
INT32	aweOS_ctrlGetValueMask(const AWEOSInstance * pAWEOS, UINT32 handle, void * value, INT32 arrayOffset, UINT32 length, UINT32 mask) Get a scalar or array value(s) of a module variable by handle with mask.
INT32	aweOS_ctrlGetModuleClass(const AWEOSInstance * pAWEOS, UINT32 handle, UINT32 * pClassID) Get a module's object class from its handle.
INT32	aweOS_destroy(AWEOSInstance ** pAWEOS) Destroys the AWEOSInstance and closes all associated threads.
INT32	aweOS_setProfilingStatus(AWEOSInstance * pAWEOS, UINT32 status) Enable or disable the profiling ability of the AWE Core OS Instance.
INT32	aweOS_getAverageLayoutCycles(AWEOSInstance * pAWEOS, UINT32 idx, UINT32 * averageCycles) Get the average cycles of a running layout, in units of cycles at profileSpeed.
void	aweOS_getVersion(AWEOSVersionInfo_t * versionInfo) Get the version information of the AWE Core OS library.
INT32	aweOS_audioRecordingEnable(AWEOSInstance * pAWEOS, char * path, char * baseName, UINT32 bufferLength, SampleType sampleType) Enables recording of all input and output audio of AWEOSInstance.
INT32	aweOS_audioRecordingRegisterNotificationCallback(AWEOSInstance * pAWEOS, recordNotificationCallbackFunction recordNotificationCallback, UINT32 recordNotificationMask) Register a callback function for audio recording event notificiations.
INT32	aweOS_audioRecordingDisable(AWEOSInstance * pAWEOS) Disable recording of input and output audio of AWEOSInstance.
INT32	aweOS_wavFileOpen(const char * file, FLOAT32 * sampleRate, UINT32 * numChannels, UINT32 * sampleSize, UINT32 * numSamples, FILE ** fp) Open a .wav file and populate the user arguments with the header information in the file.
INT32	aweOS_wavFileCreate(const char * file, FLOAT32 sampleRate, UINT32 numChannels, UINT32 sampleSize, FILE ** fp) Create a .wav file and populate the header with the passed in arguments.
INT32	aweOS_wavFileWrite(FILE * fp, void * samples, UINT32 numSamples, UINT32 sampleSize) Write audio data to .wav file created using aweOS_wavFileCreate.
INT32	aweOS_wavFileRead(FILE * fp, void * samples, UINT32 numSamples, UINT32 sampleSize) Read audio data from .wav file opened using aweOS_wavFileOpen.
INT32	aweOS_wavFileClose(FILE * fp) Close the.wav file opened using aweOS_wavFileOpen or aweOS_wavFileCreate.
INT32	aweOS_setInstancesInfo(AWEOSInstance ** pInstances, INT32 numInstances) Profiling related setup function only intended for systems with multiple AWEOS Instances in a single application.
INT32	aweOS_registerLoggingCallback(AWEOSInstance * pAWEOS, cbAweOSLogging_t cbAweOSLogging, INT32 logLevel, UINT32 logTypeMask) Register the logging callback with required logging level and logging type mask.
INT32	aweOS_registerEventCallbacks(AWEOSInstance * pAWEOS, cbAweOSEventTrigger_t cbAweOSEventTrigger, cbAweOSEventRegister_t cbAweOSEventRegister, cbAweOSEventDeregister_t cbAweOSEventDeregister) Register the event callbacks used by the Event Module.

Types Documentation

typedef cbAweOSLogging_t

typedef void(* cbAweOSLogging_t) (AWEOSInstance *pAWEOS, 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 aweOS_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.

typedef cbAweOSEventTrigger_t

typedef INT32(* cbAweOSEventTrigger_t) (AWEOSInstance *pAWEOS, INT32 eventType, UINT32 moduleObjId, void *payload, INT32 payloadSizeInBytes, void *userHandle);

OPTIONAL These callback are invoked only from the Event Module.

Use the aweOS_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.

typedef cbAweOSEventRegister_t

typedef INT32(* cbAweOSEventRegister_t) (AWEOSInstance *pAWEOS, 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.

typedef cbAweOSEventDeregister_t

typedef INT32(* cbAweOSEventDeregister_t) (AWEOSInstance *pAWEOS, 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.

Functions Documentation

function aweOS_getThreadPIDs

UINT32 aweOS_getThreadPIDs(
    AWEOSInstance * pAWEOS,
    AWEOSThreadPIDs_t * threadPIDs
)

Return the PIDs of all internally spawned AWE Core OS threads.

Parameters:

pAWEOS AWE Core OS instance pointer
threadPIDs AWEOSThreadPIDs struct ptr which is populated with PIDs

Return: E_SUCCESS, E_NOT_CREATED, E_SYSCALL

Get the PIDs of internal AWE Core OS pump, work, and socket threads. Provide a pointer to an AWEOSThreadPIDs struct, which is populated with available IDs when the API is called. See the AWEOSThreadPIDs struct for details. The max size of the pumpThreadPIDs array will always be numThreads If no layout is loaded, numPumpThreads and pumpThreadPIDs are zeroed. If the user does not open a tuning socket, socketThreadPID = 0.

Note: Only internally spawned pump thread PIDs will be returned, NOT the main audio thread (created by user, calls aweOS_audioPumpAll()). In low latency mode (layoutBS == fundamentalBS), the base layout audio pump is executed on the MAIN USER AUDIO THREAD. As a result, this API will skip the base layout, and begin the PID returning at the second layout.

function aweOS_getParamDefaults

INT32 aweOS_getParamDefaults(
    AWEOSConfigParameters * aweParams
)

Populates an AWEOSConfigParameters structure with defaults.

Parameters:

aweParams the AWEOSConfigParameters struct

Return: E_SUCCESS, E_EXCEPTION

Once it has been populated with defaults, the user can overwrite the members as needed for custom configuration.

If heap pointers are left as NULL, then the aweOS_init function internally allocates heaps of the sizes specified by the heapSize parameters. If a user wants specific control of heap memory locations, allocate the memory for the heaps before calling aweOS_init and overwrite the heapSize parameters with the allocated sizes.

pPacketBuffer and pReplyBuffer should only be non-NULL if a user created tuning interface is being used in place of aweOS_tuningSocketOpen.

function aweOS_init

INT32 aweOS_init(
    AWEOSInstance ** pAWEOS,
    const AWEOSConfigParameters * aweParams,
    const void * pModuleDescriptorTable,
    UINT32 moduleDescriptorTableSize
)

Initialize the AWEOSInstance with the specified configuration parameters.

Parameters:

pAWEOS Double pointer to the AWEOSInstance variable. This will be the "handle" of the AWEOSInstance.
aweParams The user's AWEOSConfigParameters structure
pModuleDescriptorTable A ptr to the module table (see ModuleList.h)
moduleDescriptorTableSize The size of the moduleDescriptorTable

Return: E_SUCCESS, E_HEAPS_NOT_INITIALIZED, E_HEAPS_ALREADY_INITIALIZED, E_PARAMETER_ERROR, E_CANNOT_CREATE_THREAD

A user will define an AWEOSInstance pointer (handle) and pass a pointer to it (double pointer) to this function, along with the configured aweParams struct (see AWEOSConfigParameters). The AWEOSInstance will be allocated and then its members will be set with the values of the user's aweParams. This function must be called before using any other function that requires an AWEOSInstance as an argument. Failure to do so will lead to memory corruption and program crashes.

function aweOS_tuningSocketOpen

INT32 aweOS_tuningSocketOpen(
    AWEOSInstance ** pAWEOS,
    INT32 portNo,
    UINT32 numInstances
)

Initialize and open an integrated TCP/IP tuning interface socket.

Parameters:

pAWEOS AWE Core OS instance double pointer
portNo port to open the socket on. Must be even number between 15002 and 15098
numInstances number of AWEOSInstances that the opened socket will service. If using Multi-Instance single socket, then this will be the number of instances in the array. For single instances, always pass in 1.

Return: E_SUCCESS, E_NOT_CREATED, E_INVALID_PORTNO, E_SOCKET_OPEN_FAIL, E_SCHEDULER_PERMISSION_DENIED

AWE Core OS has an optional integrated tuning interface that is enabled by calling this function after the AWEOSInstance has been initialized. A TCP socket is opened on the specified port for the passed in instance. For multiple AWEOSInstances on a single tuning interface, pass in the array of instances and the number of instances. For a single shared tuning interface, each AWEOSInstance's instanceID should be uniquely configured to 0, 16, 32, etc. For multiple AWEOSInstances where each instance has it's own tuning interface, call this function for each instance with unique ports for each call. For multiple sockets, both instance's should be configured with instanceID member set to 0. See the MultiInstance example for more information.

function aweOS_tuningSocketClose

void aweOS_tuningSocketClose(
    AWEOSInstance * pAWEOS
)

Close a running integrated TCP tuning socket.

Parameters:

pAWEOS AWE Core OS instance pointer

Call this function to close an AWEOSInstance's integrated tuning socket. Note: For a multi-instance tuning integrated socket, aweOS_tuningSocketClose only needs to be called on the first instance in the array. For multiple sockets, aweOS_tuningSocketClose should be called for each instance with an open socket.

function aweOS_tuningLoggingEnable

INT32 aweOS_tuningLoggingEnable(
    AWEOSInstance * pAWEOS,
    char * path,
    char * baseName,
    UINT32 verbosity
)

Enable logging of the tuning packets sent and received by the AWEOSInstance.

Parameters:

pAWEOS AWE Core OS instance pointer
path Path to desired logging directory. Will use current directory if NULL or ""
baseName Base name of logging file. Will use 'awe_tuning' if NULL or "". path + baseName must be < 1024 chars.
verbosity Verbosity level of tuning log. One of TUNING_LOG_NONE, TUNING_LOG_ERROR, TUNING_LOG_INFO, TUNING_LOG_DATA

Return: E_SUCCESS, E_NOT_CREATED, E_CANTCREATE, E_CANTOPEN

Will create new uniquely named .log files in the specified directory. Logging tuning packets can be useful for debugging purposes. This will only log packets sent and received by the internal socket based tuning interface enabled with aweOS_tuningSocketOpen. Tuning logging is disabled by default. Call this after aweOS_init for proper functionality. The output file path and name are set only on the first call to this function. Subsequent calls can be used only to update the verbosity level of the logging (TUNING_LOG_NONE can be used to stop logging entirely). If aweOS_tuningSocketClose or aweOS_destroy are called, then this function must be called again to re-enable tuning packet logging.

function aweOS_loadAWBFromArray

INT32 aweOS_loadAWBFromArray(
    AWEOSInstance * pAWEOS,
    const UINT32 * pArray,
    UINT32 arraySize,
    UINT32 * pErrorOffset
)

Executes packet commands from an in-memory array.

Parameters:

pAWEOS AWE Core OS instance pointer
pArray Array of commands
arraySize Size of command array
pErrorOffset Report failing word index

Return: E_SUCCESS, E_NOT_CREATED, E_ZERO_PACKET_BUFFER_LENGTH, E_NULL_PACKET_BUFFER_POINTER, E_NULL_REPLY_BUFFER_POINTER, E_EXCEPTION, E_UNEXPECTED_EOF

AWE Designer can generate AWB arrays directly from a layout, which can then be compiled directly into the application. See Tools->Generate Target Files in Designer.

function aweOS_loadAWBFile

INT32 aweOS_loadAWBFile(
    AWEOSInstance * pAWEOS,
    const char * binaryFile,
    UINT32 * pErrorOffset
)

Executes packet commands from an AWB file on the filesystem.

Parameters:

pAWEOS AWE Core OS instance pointer
binaryFile full filepath to AWB file on fileystem
pErrorOffset Report failing word index

Return: E_SUCCESS, E_CANTOPEN, E_NOSUCHFILE, E_NOT_CREATED, E_ZERO_PACKET_BUFFER_LENGTH, E_NULL_PACKET_BUFFER_POINTER, E_NULL_REPLY_BUFFER_POINTER, E_EXCEPTION, E_UNEXPECTED_EOF

AWB files can be generated for any layout from AWE Designer using Tools->Generate Target Files.

function aweOS_loadSubcanvasAWBfromArray

INT32 aweOS_loadSubcanvasAWBfromArray(
    AWEOSInstance * pAWEOS,
    UINT32 SubcanvasModObjectID,
    const UINT32 * pCommands,
    UINT32 arraySize,
    UINT32 * pPos
)

Executes packet commands from an in-memory array and loads AWB in Subcanvas module.

Parameters:

pAWEOS AWE Core OS instance pointer
SubcanvasModObjectID Object ID of the Subcanvas module
pCommands Buffer with commands to execute
arraySize Number of DWords in command buffer
pPos Report failing word index

Return: E_SUCCESS, E_CLASS_NOT_SUPPORTED, E_EXCEPTION, E_UNEXPECTED_EOF, E_END_OF_FILE, E_MESSAGE_LENGTH_TOO_LONG, E_BADPACKET

Designer can generate AWB arrays directly from a Subcanvas layout.

function aweOS_loadSubcanvasAWBfromFile

INT32 aweOS_loadSubcanvasAWBfromFile(
    AWEOSInstance * pAWEOS,
    UINT32 SubcanvasModObjectID,
    const char * binaryFile,
    UINT32 * pPos
)

Load an AWB file from stdio into Subcanvas module.

Parameters:

pAWEOS AWE Core OS instance pointer
SubcanvasModObjectID Object ID of the Subcanvas module
binaryFile AWB file to be loaded
pPos Report failing word index

Return: E_SUCCESS, E_CLASS_NOT_SUPPORTED, E_EXCEPTION, E_UNEXPECTED_EOF, E_END_OF_FILE, E_MESSAGE_LENGTH_TOO_LONG, E_BADPACKET, E_CANTOPEN

function aweOS_appendModules

INT32 aweOS_appendModules(
    AWEOSInstance * pAWEOS,
    size_t length,
    const void *const * modules
)

Append an array of module class pointers to the AWECoreOS instance's dynamic module list.

Parameters:

pAWEOS AWE Core OS instance pointer
length Number of module class pointers in the modules array (not the size of the array in bytes).
modules Array of module class pointers.

Return: E_SUCCESS, E_NOT_CREATED, E_PARAMETER_ERROR (indicates an internal failure with awe_moduleDescriptorList_append), E_MALLOC_SIZE_TOO_BIG

function aweOS_layoutGetChannelCount

INT32 aweOS_layoutGetChannelCount(
    const AWEOSInstance * pAWEOS,
    UINT32 * inCount,
    UINT32 * outCount
)

Returns the number of input and output channels in the loaded layout.

Parameters:

pAWEOS AWE Core OS instance pointer
inCount number of input channels
outCount number of output channles

Return: E_SUCCESS, E_NOT_CREATED, E_NO_LAYOUTS

function aweOS_layoutGetBlockSize

INT32 aweOS_layoutGetBlockSize(
    const AWEOSInstance * pAWEOS,
    UINT32 * blockSize
)

Returns the block size of the loaded layout.

Parameters:

pAWEOS AWE Core OS instance pointer
blockSize block size of layout

Return: E_SUCCESS, E_NOT_CREATED, E_NO_LAYOUTS

Input and output blockSize are the same for all layouts.

function aweOS_layoutGetSampleRate

INT32 aweOS_layoutGetSampleRate(
    const AWEOSInstance * pAWEOS,
    FLOAT32 * sampleRate
)

Returns the sample rate of the loaded layout.

Parameters:

pAWEOS AWE Core OS instance pointer
sampleRate sample rate of layout

Return: E_SUCCESS, E_NOT_CREATED, E_NO_LAYOUTS

Input and output sample rates are the same for all layouts.

function aweOS_audioPumpAll

INT32 aweOS_audioPumpAll(
    AWEOSInstance * pAWEOS
)

Pump one fundamental block size of audio through the loaded layout and all of its sublayouts.

Parameters:

pAWEOS AWE Core OS instance pointer

Return: E_SUCCESS, E_NOT_CREATED, E_NO_LAYOUTS, E_SCHEDULER_PERMISSION_DENIED, E_CANNOT_CREATE_THREAD, E_PRIORITY_NOT_HI_ENOUGH, E_CALLBACK_NOT_REALTIME

This function will coordinate the audio processing threads to process audio through the loaded layouts and sublayouts as needed. The user calls this function in their audio callback, which should be set to the highest priority possible on the system, after calling aweOS_audioImportSamples and aweOS_audioExportSamples. Each sublayout (including the base layout) gets its own thread where the audio will be pumped. The priority level of each sublayout's pump thread will decrement by one from the audio callback's priority level. For example, if the audio callback has priority 99, and the loaded layout has 2 sublayouts, 1 with a clockdivider of 1 and the other with a clockdivider of 16, thread priority levels will be: (audiocallback: 99, pumpthread0: 98, pumpthread1: 97). AWE Core OS names these threads if given permission, and the names/priorities can be seen with top/htop in Linux. To ensure a close to real-time priority system, the priority level of the audio callback that calls this function must be greater than (AWEOSConfigParameters.numThreads + 2). If this function is not called at a high enough priority to set the decreasing priorities, all pumpthreads are set to the current priority, and E_PRIORITY_NOT_HI_ENOUGH is returned. Users can ignore this error at their own risk. If this function isn't called at any RT priority level, then E_CALLBACK_NOT_REALTIME is returned. Note: Linux requires elevated privileges to change thread priority levels (i.e., application should be run as root). If the application does not have permission to set priorities, then E_PRIORITY_NOT_HI_ENOUGH is returned.

function aweOS_audioImportSamples

INT32 aweOS_audioImportSamples(
    AWEOSInstance * pAWEOS,
    void * inSamples,
    INT32 inStride,
    INT32 channel,
    SampleType inType
)

Import samples from an audio buffer to a specific channel of the AWEOSInstance's input pin.

Parameters:

pAWEOS AWE Core OS instance pointer
inSamples buffer to read input samples from
inStride input buffer stride
channel channel of instance pin to write to
inType type of input data

Return: E_SUCCESS, E_NOT_CREATED, E_PARAMETER_ERROR, E_NO_LAYOUTS, E_AUDIO_NOT_STARTED

The value of the fundamentalBlockSize member of the AWEOSInstance determines the number of samples that are imported with each call. Call this function once for each audio channel available from the input audio device. Channel matching between hardware capabilities and layout will be done automatically. For example, if the audio device 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 input audio device 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 user's audio buffer being read from. A typical usage for a single source, interleaved stereo input of 32-bit samples could look like this:

aweOS_audioImportSamples(pAWEOS, &inSamples[0], 2, 0, Sample32bit);
aweOS_audioImportSamples(pAWEOS, &inSamples[1], 2, 1, Sample32bit);

function aweOS_audioExportSamples

INT32 aweOS_audioExportSamples(
    AWEOSInstance * pAWEOS,
    void * outSamples,
    INT32 outStride,
    INT32 channel,
    SampleType outType
)

Export samples to a user buffer from a specific channel of the AWEOSInstance's output pin.

Parameters:

pAWEOS AWE Core OS instance pointer
outSamples buffer to write output audio to
outStride output buffer stride
channel channel of instance pin to read from
outType type of output data

Return: E_SUCCESS, E_NOT_CREATED, E_PARAMETER_ERROR, E_NO_LAYOUTS, E_AUDIO_NOT_STARTED

The value of the fundamentalBlockSize member of the AWEOSInstance determines the number of samples that are exported with each call. Call this function once for each audio output channel available on audio device. Like aweOS_audioImportSamples, this will do channel matching automatically. For example, if the audio device 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 audio device 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:

aweOS_audioExportSamples(pAWEOS, &outSamples[0], 3, 0, Sample32bit);
aweOS_audioExportSamples(pAWEOS, &outSamples[1], 3, 1, Sample32bit);
aweOS_audioExportSamples(pAWEOS, &outSamples[2], 3, 2, Sample32bit);

function aweOS_layoutIsValid

INT32 aweOS_layoutIsValid(
    const AWEOSInstance * pAWEOS
)

Determines if a layout is loaded and valid.

Parameters:

pAWEOS AWE Core OS instance pointer

Return: 1 if layout is valid, 0 if invalid, or E_NOT_CREATED

Use before processing audio in audio callback to avoid pumping through a dead layout. In some applications, the user may want to pass input audio straight to the output device if aweOS_audioIsStarted is TRUE but this function returns FALSE. This design can be useful for debugging audio drivers.

function aweOS_audioIsStarted

INT32 aweOS_audioIsStarted(
    const AWEOSInstance * pAWEOS
)

Check if this instance has received an Audio Start command.

Parameters:

pAWEOS AWE Core OS instance pointer

Return: 1 if started, 0 if not started, E_NOT_CREATED, E_NO_LAYOUTS

Audio Start can be received over the tuning interface, and it is also usually the last command in an AWB file. Use this before pumping audio to avoid processing before it has been requested. This command will begin returning 0 once an Audio Stop command is received.

function aweOS_errorToString

const char * aweOS_errorToString(
    INT32 errorCode
)

Convert an error code (INT32) to its corresponding error string.

Parameters:

errorCode error code that you wish to convert

Return: error as string, or failures "invalid error code, not a negative number", "not a valid error. error code out of range"

function aweOS_tuningPacketProcess

INT32 aweOS_tuningPacketProcess(
    AWEOSInstance * pAWEOS
)

Process the packet buffer in the AWEOSInstance.

Parameters:

pAWEOS AWE Core OS instance pointer

Return: E_SUCCESS, E_NOT_CREATED

This function should never be called if an AWE Core OS integrated tuning socket is open (see aweOS_tuningSocketOpen). This function is used only by user created tuning interfaces to process received tuning commands. See the Tuning Command Syntax and Protocol document for details.

function aweOS_ctrlSetValue

INT32 aweOS_ctrlSetValue(
    const AWEOSInstance * pAWEOS,
    UINT32 handle,
    void * value,
    INT32 arrayOffset,
    UINT32 length
)

Set a scalar or array value(s) of a module parameter by handle.

Parameters:

pAWEOS AWE Core OS instance pointer
handle packed object handle
value value(s) to set
arrayOffset array offset if array. 0 if scalar.
length number of elements to set if array. 1 if scalar.

Return: E_SUCCESS, E_ARGUMENT_ERROR, E_BAD_MEMBER_INDEX, E_CLASS_NOT_SUPPORTED, E_LINKEDLIST_CORRUPT, E_NO_MORE_OBJECTS, E_NOT_CREATED, E_NO_LAYOUTS

Module handles and parameter sizes can be generated for any layout using Tools->Generate Target Files in AWE Designer. Select the ControlInterface.h checkbox to generate control files.

function aweOS_ctrlGetValue

INT32 aweOS_ctrlGetValue(
    const AWEOSInstance * pAWEOS,
    UINT32 handle,
    void * value,
    INT32 arrayOffset,
    UINT32 length
)

Get a scalar or array value(s) of a module parameter by handle.

Parameters:

pAWEOS AWE Core OS instance pointer
handle packed object handle
value retrieved value(s)
arrayOffset array offset if array. 0 if scalar
length number of elements to retrieve if array. 1 if scalar

Return: E_SUCCESS, E_ARGUMENT_ERROR, E_BAD_MEMBER_INDEX, E_CLASS_NOT_SUPPORTED, E_LINKEDLIST_CORRUPT, E_NO_MORE_OBJECTS, E_NOT_CREATED, E_NO_LAYOUTS

Module handles and parameter sizes can be generated for any layout using Tools->Generate Target Files in AWE Designer. Select the ControlInterface.h checkbox to generate control files.

function aweOS_ctrlSetStatus

INT32 aweOS_ctrlSetStatus(
    const AWEOSInstance * pAWEOS,
    UINT32 handle,
    UINT32 * status
)

Set the status of a module.

Parameters:

pAWEOS AWE Core OS instance pointer
handle packed object handle
status status to set

Return: E_SUCCESS, E_ARGUMENT_ERROR, E_LINKEDLIST_CORRUPT, E_NO_MORE_OBJECTS, E_NOT_CREATED, E_NO_LAYOUTS

Valid status values are: 0=Active

1=Bypass

2=Mute

3=Inactive

Module handles sizes can be generated for any layout using Tools->Generate Target Files in AWE Designer. Select the ControlInterface.h checkbox to generate control files.

function aweOS_ctrlGetStatus

INT32 aweOS_ctrlGetStatus(
    const AWEOSInstance * pAWEOS,
    UINT32 handle,
    UINT32 * status
)

Get the status of a module.

Parameters:

pAWEOS AWE Core OS instance pointer
handle packed object handle
status returned status

Return: E_SUCCESS, E_ARGUMENT_ERROR, E_LINKEDLIST_CORRUPT, E_NO_MORE_OBJECTS, E_NOT_CREATED, E_NO_LAYOUTS, E_NOT_MODULE

Module handles sizes can be generated for any layout using Tools->Generate Target Files in AWE Designer. Select the ControlInterface.h checkbox to generate control files.

function aweOS_ctrlSetValueMask

INT32 aweOS_ctrlSetValueMask(
    const AWEOSInstance * pAWEOS,
    UINT32 handle,
    void * value,
    INT32 arrayOffset,
    UINT32 length,
    UINT32 mask
)

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

Parameters:

pAWEOS AWE Core OS instance pointer
handle packed object handle
value value(s) to set
arrayOffset array offset if array. 0 if scalar
length number of elements if array. 1 if scalar
mask mask to use - 0 to not call set function.

Return: E_SUCCESS, E_ARGUMENT_ERROR, E_BAD_MEMBER_INDEX, E_CLASS_NOT_SUPPORTED, E_OBJECT_ID_NOT_FOUND, E_NOT_MODULE, E_NOT_CREATED, E_NO_LAYOUTS

A mask allows you to only call module's set function for a single variable, or skip the set function all together. For advanced users.

function aweOS_ctrlGetValueMask

INT32 aweOS_ctrlGetValueMask(
    const AWEOSInstance * pAWEOS,
    UINT32 handle,
    void * value,
    INT32 arrayOffset,
    UINT32 length,
    UINT32 mask
)

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

Parameters:

pAWEOS AWE Core OS instance pointer
handle packed object handle
value value(s) to get
arrayOffset array offset if array. 0 if scalar.
length number of elements if array. 1 if scalar
mask mask to use - 0 to not call get function

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

A mask allows you to only call module's get function for a single variable, or skip the get function all together. For advanced users.

function aweOS_ctrlGetModuleClass

INT32 aweOS_ctrlGetModuleClass(
    const AWEOSInstance * pAWEOS,
    UINT32 handle,
    UINT32 * pClassID
)

Get a module's object class from its handle.

Parameters:

pAWEOS instance pointer
handle handle of object to find
pClassID pointer to found object class

Return: E_SUCCESS, E_NO_MORE_OBJECTS, E_LINKEDLIST_CORRUPT, E_NOT_CREATED, E_NO_LAYOUTS

function aweOS_destroy

INT32 aweOS_destroy(
    AWEOSInstance ** pAWEOS
)

Destroys the AWEOSInstance and closes all associated threads.

Parameters:

pAWEOS pointer to pointer of AWE Core OS instance to destroy

Return: E_SUCCESS, E_NOT_CREATED

Frees all internal memory and sets the AWEOSInstance to NULL.

function aweOS_setProfilingStatus

INT32 aweOS_setProfilingStatus(
    AWEOSInstance * pAWEOS,
    UINT32 status
)

Enable or disable the profiling ability of the AWE Core OS Instance.

Parameters:

pAWEOS AWE Core OS instance pointer
status 0 to disable both, 1 to enable both, 2 to enable module level only and 3 to enable top level only

Return: E_SUCCESS, E_NOT_OBJECT, E_NOT_CREATED

Both top and module level profiling enabled by default by aweOS_init. Use this function to selectively enable or disable per pump profiling during runtime. Disabling profiling saves a small amount of cycles per pump. Do not call this API from the audio start/stop callbacks. User can also enable or disable independently module level profiling and top level profiling.

function aweOS_getAverageLayoutCycles

INT32 aweOS_getAverageLayoutCycles(
    AWEOSInstance * pAWEOS,
    UINT32 idx,
    UINT32 * averageCycles
)

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

Parameters:

pAWEOS AWE Core OS instance pointer
idx Layout index (typically 0, except in advanced use cases)
averageCycles Pointer to average cycles

Return: E_SUCCESS, E_NOT_CREATED, E_NO_LAYOUTS, E_PARAMETER_ERROR

Returns cycles in 24.8 format, so shift right by 8 bits for integer value. To get CPU cycles, multiply by target cpuSpeed / profileSpeed.

function aweOS_getVersion

void aweOS_getVersion(
    AWEOSVersionInfo_t * versionInfo
)

Get the version information of the AWE Core OS library.

Parameters:

versionInfo Pointer to a version info data structure

Can be used without initializing an AWEOSInstance. AWE Core OS versions are of form .... All values are integers execpt for majorAPIVer, which is a single, capital letter.

function aweOS_audioRecordingEnable

INT32 aweOS_audioRecordingEnable(
    AWEOSInstance * pAWEOS,
    char * path,
    char * baseName,
    UINT32 bufferLength,
    SampleType sampleType
)

Enables recording of all input and output audio of AWEOSInstance.

Parameters:

pAWEOS AWE Core OS instance pointer
path Path to desired logging directory. Will use the directory application is called from if NULL or ""
baseName Base name of audio files. Will use 'awe_audio' if NULL or ""
bufferLength Length in milliseconds of audio FIFO used to buffer audio data for writing to file. Increase to handle large system I/O costs and avoid xruns
sampleType Data type of recorded audio. Supports 'Sample32bit' and 'Sample16bit' only

Return: E_SUCCESS, E_NOT_CREATED, E_PARAMETER_ERROR

Will create unique input and output .wav files in the specified directory. Recording input and output audio can be useful for debugging purposes. Audio recording happens in a background thread so as not to interrupt real time audio processing. If the system is heavily loaded, it is possible that overruns can occur while writing the audio to files. If overruns do occur on the system, increasing the size of bufferLength and using the 'Sample16bit' sampleType can help avoid missed audio samples in the recorded files. Audio recording is disabled by default at aweOS_init time. Call this function after aweOS_init to enable recording on the next Audio Start command. For greater control of audio recording capabilities, see the Wave File Source and Sink modules in Designer.

Recording audio during real-time processing

function aweOS_audioRecordingRegisterNotificationCallback

INT32 aweOS_audioRecordingRegisterNotificationCallback(
    AWEOSInstance * pAWEOS,
    recordNotificationCallbackFunction recordNotificationCallback,
    UINT32 recordNotificationMask
)

Register a callback function for audio recording event notificiations.

Parameters:

pAWEOS AWE Core OS instance pointer
recordNotificationCallback Function pointer to register for error/info notification during recording
recordNotificationMask Bit mask to control notification types

Return: E_SUCCESS, E_NOT_CREATED, E_PARAMETER_ERROR

Events include errors (file create or I/O) or xruns. Mask controls which type of notifications to enable for callback. First bit of mask enables error notifications, second bit enables xrun notifications. An AWEOSAudioRecordNotification_t structure is passed as the only argument to the callback function.

function aweOS_audioRecordingDisable

INT32 aweOS_audioRecordingDisable(
    AWEOSInstance * pAWEOS
)

Disable recording of input and output audio of AWEOSInstance.

Parameters:

pAWEOS AWE Core OS instance pointer

Return: E_SUCCESS, E_NOT_CREATED

Can be called during runtime while audio recording is ongoing to halt recording. To record audio again on next Audio Start command, must call aweOS_audioRecordingEnable again.

function aweOS_wavFileOpen

INT32 aweOS_wavFileOpen(
    const char * file,
    FLOAT32 * sampleRate,
    UINT32 * numChannels,
    UINT32 * sampleSize,
    UINT32 * numSamples,
    FILE ** fp
)

Open a .wav file and populate the user arguments with the header information in the file.

Parameters:

file full path to name of the .wav file
sampleRate sample rate value extracted from header
numChannels number of audio channels extracted from header
sampleSize size of each audio sample, in bytes
numSamples total number of audio samples in file
fp pointer to opened FILE

Return: E_SUCCESS, E_IOERROR, E_ILLEGAL_FILE_ATTRIBUTE, E_CANTOPEN

Returns the pointer to the opened file in the fp argument. No audio data is read in this function call. Use aweOS_wavFileRead to access the audio data after the file is opened. aweOS_wavFileClose can be used to close the file once fully read.

function aweOS_wavFileCreate

INT32 aweOS_wavFileCreate(
    const char * file,
    FLOAT32 sampleRate,
    UINT32 numChannels,
    UINT32 sampleSize,
    FILE ** fp
)

Create a .wav file and populate the header with the passed in arguments.

Parameters:

file full path to name of the .wav file
sampleRate sample rate
numChannels number of audio channels in data to be written
sampleSize size of each audio sample, in bytes
fp pointer to created FILE

Return: E_SUCCESS, E_PARAMETER_ERROR, E_IOERROR, E_CANTCREATE

Returns the pointer to the created file in the fp argument. No audio data is written in this function call. Use aweOS_wavFileWrite to write the audio data after the file is created. aweOS_wavFileClose can be used to close the file once fully written.

function aweOS_wavFileWrite

INT32 aweOS_wavFileWrite(
    FILE * fp,
    void * samples,
    UINT32 numSamples,
    UINT32 sampleSize
)

Write audio data to .wav file created using aweOS_wavFileCreate.

Parameters:

fp pointer to file to write data to
samples pointer to buffer of samples to write to file
numSamples total number of samples to write
sampleSize size of each audio sample, in bytes

Return: number of samples written, E_BADFILE, E_IOERROR

function aweOS_wavFileRead

INT32 aweOS_wavFileRead(
    FILE * fp,
    void * samples,
    UINT32 numSamples,
    UINT32 sampleSize
)

Read audio data from .wav file opened using aweOS_wavFileOpen.

Parameters:

fp pointer to file to read data from
samples pointer to buffer to populate with samples from file
numSamples total number of samples to read
sampleSize size of each audio sample, in bytes

Return: number of samples read, E_BADFILE, E_IOERROR

function aweOS_wavFileClose

INT32 aweOS_wavFileClose(
    FILE * fp
)

Close the.wav file opened using aweOS_wavFileOpen or aweOS_wavFileCreate.

Parameters:

fp pointer to file to read data from

Return: E_SUCCESS, E_NO_OPEN_FILE

function aweOS_setInstancesInfo

INT32 aweOS_setInstancesInfo(
    AWEOSInstance ** pInstances,
    INT32 numInstances
)

Profiling related setup function only intended for systems with multiple AWEOS Instances in a single application.

Parameters:

pInstances Array of AWEOS Instance pointers. Array must exist as long as the system is active.
numInstances Number of AWEOS Instances in pInstances array.

Return: E_SUCCESS, E_PARAMETER_ERROR

Call this function at startup after aweOS_init is done in the sequence. Note: this function can only be safely used if all instances share the same lifetime. If some instances will be destroyed while others continue to pump, then this function should not be used.

function aweOS_registerLoggingCallback

INT32 aweOS_registerLoggingCallback(
    AWEOSInstance * pAWEOS,
    cbAweOSLogging_t cbAweOSLogging,
    INT32 logLevel,
    UINT32 logTypeMask
)

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

Parameters:

pAWEOS AWEOS instance pointer
cbAweOSLogging Function pointer of the logging callback
logLevel Logging level. 0 = AWE_LOG_LEVEL_NONE, 1 = AWE_LOG_LEVEL_ERROR, 2 = AWE_LOG_LEVEL_WARNING, 3 = AWE_LOG_LEVEL_INFO, 4 = AWE_LOG_LEVEL_DEBUG
logTypeMask Logging type mask. Combination of any logging type like AWE_LOG_SYSTEM_MSG_ASCII | AWE_LOG_DATA_DUMP_FLOAT Please note that ASCII messages don't end with a newline so the user callback has to apply that as desired.

Return: E_SUCCESS or E_NOT_OBJECT if invalid pAWE or E_PARAMETER_ERROR if invalid cbAweOSLogging.

The type mask is used to filter out undesired event types

function aweOS_registerEventCallbacks

INT32 aweOS_registerEventCallbacks(
    AWEOSInstance * pAWEOS,
    cbAweOSEventTrigger_t cbAweOSEventTrigger,
    cbAweOSEventRegister_t cbAweOSEventRegister,
    cbAweOSEventDeregister_t cbAweOSEventDeregister
)

Register the event callbacks used by the Event Module.

Parameters:

pAWEOS AWEOS instance pointer
cbAweOSEventTrigger Function pointer of the event trigger callback.
cbAweOSEventRegister Function pointer of the event register callback.
cbAweOSEventDeregister Function pointer of the event deregister callback.

Return: E_SUCCESS on success, or E_NOT_OBJECT if invalid pAWEOS, or E_PARAMETER_ERROR if invalid cbAweOSEventTrigger.

cbAweOSEventTrigger must be non-null. The cbAweOSEventRegister and cbAweOSEventDeregister can be null.

Updated on 2026-02-10 at 15:44:47 -0500