AWE Core OS 8.B.19 Documentation
Functions
AWECoreOS API

Functions

UINT32 aweOS_getThreadPIDs (AWEOSInstance *pAWEOS, AWEOSThreadPIDs_t *threadPIDs)
 Return the PIDs of all internally spawned AWE Core OS threads. More...
 
INT32 aweOS_getParamDefaults (AWEOSConfigParameters *aweParams)
 Populates an AWEOSConfigParameters structure with defaults. More...
 
INT32 aweOS_init (AWEOSInstance **pAWEOS, const AWEOSConfigParameters *aweParams, const void *pModuleDescriptorTable, UINT32 moduleDescriptorTableSize)
 Initialize the AWEOSInstance with the specified configuration parameters. More...
 
INT32 aweOS_tuningSocketOpen (AWEOSInstance **pAWEOS, INT32 portNo, UINT32 numInstances)
 Initialize and open an integrated TCP/IP tuning interface socket. More...
 
void aweOS_tuningSocketClose (AWEOSInstance *pAWEOS)
 Close a running integrated TCP tuning socket. More...
 
INT32 aweOS_tuningLoggingEnable (AWEOSInstance *pAWEOS, char *path, char *baseName, UINT32 verbosity)
 Enable logging of the tuning packets sent and received by the AWEOSInstance. More...
 
INT32 aweOS_loadAWBFromArray (AWEOSInstance *pAWEOS, const UINT32 *pArray, UINT32 arraySize, UINT32 *pErrorOffset)
 Executes packet commands from an in-memory array. More...
 
INT32 aweOS_loadAWBFile (AWEOSInstance *pAWEOS, const char *binaryFile, UINT32 *pErrorOffset)
 Executes packet commands from an AWB file on the filesystem. More...
 
INT32 aweOS_layoutGetChannelCount (const AWEOSInstance *pAWEOS, UINT32 *inCount, UINT32 *outCount)
 Returns the number of input and output channels in the loaded layout. More...
 
INT32 aweOS_layoutGetBlockSize (const AWEOSInstance *pAWEOS, UINT32 *blockSize)
 Returns the block size of the loaded layout. More...
 
INT32 aweOS_layoutGetSampleRate (const AWEOSInstance *pAWEOS, FLOAT32 *sampleRate)
 Returns the sample rate of the loaded layout. More...
 
INT32 aweOS_audioPumpAll (AWEOSInstance *pAWEOS)
 Pump one fundamental block size of audio through the loaded layout and all of its sublayouts. More...
 
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. More...
 
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. More...
 
INT32 aweOS_layoutIsValid (const AWEOSInstance *pAWEOS)
 Determines if a layout is loaded and valid. More...
 
INT32 aweOS_audioIsStarted (const AWEOSInstance *pAWEOS)
 Check if this instance has received an Audio Start command. More...
 
const char * aweOS_errorToString (INT32 errorCode)
 Convert an error code (INT32) to its corresponding error string. More...
 
INT32 aweOS_tuningPacketProcess (AWEOSInstance *pAWEOS)
 Process the packet buffer in the AWEOSInstance. More...
 
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. More...
 
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. More...
 
INT32 aweOS_ctrlSetStatus (const AWEOSInstance *pAWEOS, UINT32 handle, UINT32 *status)
 Set the status of a module. More...
 
INT32 aweOS_ctrlGetStatus (const AWEOSInstance *pAWEOS, UINT32 handle, UINT32 *status)
 Get the status of a module. More...
 
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. More...
 
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. More...
 
INT32 aweOS_ctrlGetModuleClass (const AWEOSInstance *pAWEOS, UINT32 handle, UINT32 *pClassID)
 Get a module's object class from its handle. More...
 
INT32 aweOS_destroy (AWEOSInstance **pAWEOS)
 Destroys the AWEOSInstance and closes all associated threads. More...
 
INT32 aweOS_setProfilingStatus (AWEOSInstance *pAWEOS, UINT32 status)
 Enable or disable the profiling ability of the AWE Core OS Instance. More...
 
INT32 aweOS_getAverageLayoutCycles (AWEOSInstance *pAWEOS, UINT32 idx, UINT32 *averageCycles)
 Get the average cycles of a running layout, in units of cycles at profileSpeed. More...
 
void aweOS_getVersion (AWEOSVersionInfo_t *versionInfo)
 Get the version information of the AWE Core OS library. More...
 
INT32 aweOS_audioRecordingEnable (AWEOSInstance *pAWEOS, char *path, char *baseName, UINT32 bufferLength, SampleType sampleType)
 Enables recording of all input and output audio of AWEOSInstance. More...
 
INT32 aweOS_audioRecordingRegisterNotificationCallback (AWEOSInstance *pAWEOS, recordNotificationCallbackFunction recordNotificationCallback, UINT32 recordNotificationMask)
 Register a callback function for audio recording event notificiations. More...
 
INT32 aweOS_audioRecordingDisable (AWEOSInstance *pAWEOS)
 Disable recording of input and output audio of AWEOSInstance. More...
 
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. More...
 
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. More...
 
INT32 aweOS_wavFileWrite (FILE *fp, void *samples, UINT32 numSamples, UINT32 sampleSize)
 Write audio data to .wav file created using aweOS_wavFileCreate. More...
 
INT32 aweOS_wavFileRead (FILE *fp, void *samples, UINT32 numSamples, UINT32 sampleSize)
 Read audio data from .wav file opened using aweOS_wavFileOpen. More...
 
INT32 aweOS_wavFileClose (FILE *fp)
 Close the.wav file opened using aweOS_wavFileOpen or aweOS_wavFileCreate. More...
 
INT32 aweOS_setInstancesInfo (AWEOSInstance **pInstances, INT32 numInstances)
 Profiling related setup function only intended for systems with multiple AWEOS Instances in a single application. More...
 

Detailed Description

Function Documentation

◆ aweOS_getThreadPIDs()

UINT32 aweOS_getThreadPIDs ( AWEOSInstance pAWEOS,
AWEOSThreadPIDs_t threadPIDs 
)

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

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.

Parameters
[in]pAWEOSAWE Core OS instance pointer
[in]threadPIDsAWEOSThreadPIDs struct ptr which is populated with PIDs
Returns
E_SUCCESS, E_NOT_CREATED, E_SYSCALL
Examples
Multi-Instance.c, and RTAudio-alsa.c.

◆ aweOS_getParamDefaults()

INT32 aweOS_getParamDefaults ( AWEOSConfigParameters aweParams)

Populates an AWEOSConfigParameters structure with defaults.

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.

Parameters
[out]aweParamsthe AWEOSConfigParameters struct
Returns
E_SUCCESS, E_EXCEPTION
Examples
HelloWorld.c, LayoutControl.c, Libtester.c, Multi-Instance.c, and RTAudio-alsa.c.

◆ aweOS_init()

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

Initialize the AWEOSInstance with the specified configuration parameters.

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.

Parameters
[out]pAWEOSDouble pointer to the AWEOSInstance variable. This will be the "handle" of the AWEOSInstance.
[in]aweParamsThe user's AWEOSConfigParameters structure
[in]pModuleDescriptorTableA ptr to the module table (see ModuleList.h)
[in]moduleDescriptorTableSizeThe size of the moduleDescriptorTable
Returns
E_SUCCESS, E_HEAPS_NOT_INITIALIZED, E_HEAPS_ALREADY_INITIALIZED, E_PARAMETER_ERROR, E_CANNOT_CREATE_THREAD
Examples
HelloWorld.c, LayoutControl.c, Libtester.c, Multi-Instance.c, and RTAudio-alsa.c.

◆ aweOS_tuningSocketOpen()

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

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

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

Parameters
[in]pAWEOSAWE Core OS instance double pointer
[in]portNoport to open the socket on. Must be even number between 15002 and 15098
[in]numInstancesnumber 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.
Returns
E_SUCCESS, E_NOT_CREATED, E_INVALID_PORTNO, E_SOCKET_OPEN_FAIL, E_SCHEDULER_PERMISSION_DENIED
Examples
HelloWorld.c, Libtester.c, Multi-Instance.c, and RTAudio-alsa.c.

◆ aweOS_tuningSocketClose()

void aweOS_tuningSocketClose ( AWEOSInstance pAWEOS)

Close a running integrated TCP tuning socket.

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.

Parameters
[in]pAWEOSAWE Core OS instance pointer

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

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.

Parameters
[in]pAWEOSAWE Core OS instance pointer
[in]pathPath to desired logging directory. Will use current directory if NULL or ""
[in]baseNameBase name of logging file. Will use 'awe_tuning' if NULL or ""
[in]verbosityVerbosity level of tuning log. One of TUNING_LOG_ERROR, TUNING_LOG_INFO, TUNING_LOG_DATA
Returns
E_SUCCESS, E_NOT_CREATED, E_CANTCREATE, E_CANTOPEN
Examples
Libtester.c, and Multi-Instance.c.

◆ aweOS_loadAWBFromArray()

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

Executes packet commands from an in-memory array.

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.

Parameters
[in]pAWEOSAWE Core OS instance pointer
[in]pArrayArray of commands
[in]arraySizeSize of command array
[out]pErrorOffsetReport failing word index
Returns
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

◆ aweOS_loadAWBFile()

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

Executes packet commands from an AWB file on the filesystem.

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

Parameters
[in]pAWEOSAWE Core OS instance pointer
[in]binaryFilefull filepath to AWB file on fileystem
[out]pErrorOffsetReport failing word index
Returns
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
Examples
LayoutControl.c, Libtester.c, and RTAudio-alsa.c.

◆ 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
[in]pAWEOSAWE Core OS instance pointer
[out]inCountnumber of input channels
[out]outCountnumber of output channles
Returns
E_SUCCESS, E_NOT_CREATED, E_NO_LAYOUTS
Examples
LayoutControl.c, Libtester.c, and Multi-Instance.c.

◆ aweOS_layoutGetBlockSize()

INT32 aweOS_layoutGetBlockSize ( const AWEOSInstance pAWEOS,
UINT32 *  blockSize 
)

Returns the block size of the loaded layout.

Input and output blockSize are the same for all layouts.

Parameters
[in]pAWEOSAWE Core OS instance pointer
[out]blockSizeblock size of layout
Returns
E_SUCCESS, E_NOT_CREATED, E_NO_LAYOUTS
Examples
LayoutControl.c, Libtester.c, and Multi-Instance.c.

◆ aweOS_layoutGetSampleRate()

INT32 aweOS_layoutGetSampleRate ( const AWEOSInstance pAWEOS,
FLOAT32 *  sampleRate 
)

Returns the sample rate of the loaded layout.

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

Parameters
[in]pAWEOSAWE Core OS instance pointer
[out]sampleRatesample rate of layout
Returns
E_SUCCESS, E_NOT_CREATED, E_NO_LAYOUTS
Examples
LayoutControl.c, Libtester.c, and Multi-Instance.c.

◆ aweOS_audioPumpAll()

INT32 aweOS_audioPumpAll ( AWEOSInstance pAWEOS)

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

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.

Parameters
[in]pAWEOSAWE Core OS instance pointer
Returns
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
Examples
LayoutControl.c, Libtester.c, Multi-Instance.c, and RTAudio-alsa.c.

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

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);
@ Sample32bit
Data is 32 bit PCM .
Definition: StandardDefs.h:231
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
[in]pAWEOSAWE Core OS instance pointer
[in]inSamplesbuffer to read input samples from
[in]inStrideinput buffer stride
[in]channelchannel of instance pin to write to
[in]inTypetype of input data
Returns
E_SUCCESS, E_NOT_CREATED, E_PARAMETER_ERROR, E_NO_LAYOUTS, E_AUDIO_NOT_STARTED
Examples
LayoutControl.c, Libtester.c, Multi-Instance.c, and RTAudio-alsa.c.

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

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);
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
[in]pAWEOSAWE Core OS instance pointer
[out]outSamplesbuffer to write output audio to
[in]outStrideoutput buffer stride
[in]channelchannel of instance pin to read from
[in]outTypetype of output data
Returns
E_SUCCESS, E_NOT_CREATED, E_PARAMETER_ERROR, E_NO_LAYOUTS, E_AUDIO_NOT_STARTED
Examples
LayoutControl.c, Libtester.c, Multi-Instance.c, and RTAudio-alsa.c.

◆ aweOS_layoutIsValid()

INT32 aweOS_layoutIsValid ( const AWEOSInstance pAWEOS)

Determines if a layout is loaded and valid.

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.

Parameters
[in]pAWEOSAWE Core OS instance pointer
Returns
1 if layout is valid, 0 if invalid, or E_NOT_CREATED
Examples
LayoutControl.c, Libtester.c, Multi-Instance.c, and RTAudio-alsa.c.

◆ aweOS_audioIsStarted()

INT32 aweOS_audioIsStarted ( const AWEOSInstance pAWEOS)

Check if this instance has received an Audio Start command.

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.

Parameters
[in]pAWEOSAWE Core OS instance pointer
Returns
1 if started, 0 if not started, E_NOT_CREATED, E_NO_LAYOUTS
Examples
LayoutControl.c, Libtester.c, Multi-Instance.c, and RTAudio-alsa.c.

◆ aweOS_errorToString()

const char * aweOS_errorToString ( INT32  errorCode)

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

Parameters
[in]errorCodeerror code that you wish to convert
Returns
error as string, or failures "invalid error code, not a negative number", "not a valid error. error code out of range"
Examples
HelloWorld.c, LayoutControl.c, Libtester.c, Multi-Instance.c, and RTAudio-alsa.c.

◆ aweOS_tuningPacketProcess()

INT32 aweOS_tuningPacketProcess ( AWEOSInstance pAWEOS)

Process the packet buffer in the AWEOSInstance.

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.

Parameters
[in]pAWEOSAWE Core OS instance pointer
Returns
E_SUCCESS, E_NOT_CREATED

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

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.

Parameters
[in]pAWEOSAWE Core OS instance pointer
[in]handlepacked object handle
[in]valuevalue(s) to set
[in]arrayOffsetarray offset if array. 0 if scalar.
[in]lengthnumber of elements to set if array. 1 if scalar.
Returns
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
Examples
LayoutControl.c.

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

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.

Parameters
[in]pAWEOSAWE Core OS instance pointer
[in]handlepacked object handle
[out]valueretrieved value(s)
[in]arrayOffsetarray offset if array. 0 if scalar
[in]lengthnumber of elements to retrieve if array. 1 if scalar
Returns
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
Examples
LayoutControl.c.

◆ aweOS_ctrlSetStatus()

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

Set the status of a module.

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.

Parameters
[in]pAWEOSAWE Core OS instance pointer
[in]handlepacked object handle
[in]statusstatus to set
Returns
E_SUCCESS, E_ARGUMENT_ERROR, E_LINKEDLIST_CORRUPT, E_NO_MORE_OBJECTS, E_NOT_CREATED, E_NO_LAYOUTS

◆ aweOS_ctrlGetStatus()

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

Get the status of a 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.

Parameters
[in]pAWEOSAWE Core OS instance pointer
[in]handlepacked object handle
[out]statusreturned status
Returns
E_SUCCESS, E_ARGUMENT_ERROR, E_LINKEDLIST_CORRUPT, E_NO_MORE_OBJECTS, E_NOT_CREATED, E_NO_LAYOUTS, E_NOT_MODULE

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

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.

Parameters
[in]pAWEOSAWE Core OS instance pointer
[in]handlepacked object handle
[in]valuevalue(s) to set
[in]arrayOffsetarray offset if array. 0 if scalar
[in]lengthnumber of elements if array. 1 if scalar
[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, E_NOT_CREATED, E_NO_LAYOUTS

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

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.

Parameters
[in]pAWEOSAWE Core OS instance pointer
[in]handlepacked object handle
[out]valuevalue(s) to get
[in]arrayOffsetarray offset if array. 0 if scalar.
[in]lengthnumber of elements if array. 1 if scalar
[in]maskmask to use - 0 to not call get function
Returns
E_SUCCESS, E_ARGUMENT_ERROR, E_OBJECT_ID_NOT_FOUND, E_CLASS_NOT_SUPPORTED, E_NOT_MODULE, E_BAD_MEMBER_INDEX

◆ aweOS_ctrlGetModuleClass()

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

Get a module's object class from its handle.

Parameters
[in]pAWEOSinstance pointer
[in]handlehandle of object to find
[out]pClassIDpointer to found object class
Returns
E_SUCCESS, E_NO_MORE_OBJECTS, E_LINKEDLIST_CORRUPT, E_NOT_CREATED, E_NO_LAYOUTS
Examples
LayoutControl.c.

◆ aweOS_destroy()

INT32 aweOS_destroy ( AWEOSInstance **  pAWEOS)

Destroys the AWEOSInstance and closes all associated threads.

Frees all internal memory and sets the AWEOSInstance to NULL.

Parameters
[in]pAWEOSpointer to pointer of AWE Core OS instance to destroy
Returns
E_SUCCESS, E_NOT_CREATED
Examples
LayoutControl.c, Libtester.c, and Multi-Instance.c.

◆ aweOS_setProfilingStatus()

INT32 aweOS_setProfilingStatus ( AWEOSInstance pAWEOS,
UINT32  status 
)

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

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.

Parameters
[in]pAWEOSAWE Core OS instance pointer
[in]status0 to disable both, 1 to enable both, 2 to enable module level only and 3 to enable top level only
Returns
E_SUCCESS, E_NOT_OBJECT, E_NOT_CREATED
Examples
Libtester.c.

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

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

Parameters
[in]pAWEOSAWE Core OS instance pointer
[in]idxLayout index (typically 0, except in advanced use cases)
[out]averageCyclesPointer to average cycles
Returns
E_SUCCESS, E_NOT_CREATED, E_NO_LAYOUTS, E_PARAMETER_ERROR
Examples
LayoutControl.c, Libtester.c, and Multi-Instance.c.

◆ aweOS_getVersion()

void aweOS_getVersion ( AWEOSVersionInfo_t versionInfo)

Get the version information of the AWE Core OS library.

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

Parameters
[out]versionInfoPointer to a version info data structure
Examples
Libtester.c.

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

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

Parameters
[in]pAWEOSAWE Core OS instance pointer
[in]pathPath to desired logging directory. Will use the directory application is called from if NULL or ""
[in]baseNameBase name of audio files. Will use 'awe_audio' if NULL or ""
[in]bufferLengthLength 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
[in]sampleTypeData type of recorded audio. Supports 'Sample32bit' and 'Sample16bit' only
Returns
E_SUCCESS, E_NOT_CREATED, E_PARAMETER_ERROR
Examples
RTAudio-alsa.c.

◆ aweOS_audioRecordingRegisterNotificationCallback()

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

Register a callback function for audio recording event notificiations.

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.

Parameters
[in]pAWEOSAWE Core OS instance pointer
[in]recordNotificationCallbackFunction pointer to register for error/info notification during recording
[in]recordNotificationMaskBit mask to control notification types
Returns
E_SUCCESS, E_NOT_CREATED, E_PARAMETER_ERROR
Examples
RTAudio-alsa.c.

◆ aweOS_audioRecordingDisable()

INT32 aweOS_audioRecordingDisable ( AWEOSInstance pAWEOS)

Disable recording of input and output audio of AWEOSInstance.

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.

Parameters
[in]pAWEOSAWE Core OS instance pointer
Returns
E_SUCCESS, E_NOT_CREATED

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

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.

Parameters
[in]filefull path to name of the .wav file
[out]sampleRatesample rate value extracted from header
[out]numChannelsnumber of audio channels extracted from header
[out]sampleSizesize of each audio sample, in bytes
[out]numSamplestotal number of audio samples in file
[out]fppointer to opened FILE
Returns
E_SUCCESS, E_IOERROR, E_ILLEGAL_FILE_ATTRIBUTE, E_CANTOPEN
Examples
Libtester.c.

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

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.

Parameters
[in]filefull path to name of the .wav file
[in]sampleRatesample rate
[in]numChannelsnumber of audio channels in data to be written
[in]sampleSizesize of each audio sample, in bytes
[out]fppointer to created FILE
Returns
E_SUCCESS, E_PARAMETER_ERROR, E_IOERROR, E_CANTCREATE
Examples
Libtester.c.

◆ aweOS_wavFileWrite()

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

Write audio data to .wav file created using aweOS_wavFileCreate.

Parameters
[in]fppointer to file to write data to
[in]samplespointer to buffer of samples to write to file
[in]numSamplestotal number of samples to write
[in]sampleSizesize of each audio sample, in bytes
Returns
number of samples written, E_BADFILE, E_IOERROR
Examples
Libtester.c.

◆ aweOS_wavFileRead()

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

Read audio data from .wav file opened using aweOS_wavFileOpen.

Parameters
[in]fppointer to file to read data from
[out]samplespointer to buffer to populate with samples from file
[in]numSamplestotal number of samples to read
[in]sampleSizesize of each audio sample, in bytes
Returns
number of samples read, E_BADFILE, E_IOERROR
Examples
Libtester.c.

◆ aweOS_wavFileClose()

INT32 aweOS_wavFileClose ( FILE *  fp)

Close the.wav file opened using aweOS_wavFileOpen or aweOS_wavFileCreate.

Parameters
[in]fppointer to file to read data from
Returns
E_SUCCESS, E_NO_OPEN_FILE
Examples
Libtester.c.

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

Call this function at startup after aweOS_init is done in the sequence.

Parameters
[in]pInstancesArray of AWEOS Instance pointers. Array must exist as long as the system is active.
[in]numInstancesNumber of AWEOS Instances in pInstances array.
Returns
E_SUCCESS, E_PARAMETER_ERROR
Examples
Multi-Instance.c.