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

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

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

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

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

INT32	aweOS_registerLoggingCallback (AWEOSInstance *pAWEOS, cbAweOSLogging_t cbAweOSLogging, INT32 logLevel, UINT32 logTypeMask)
	Register the logging callback with required logging level and logging type mask. More...

INT32	aweOS_registerEventCallbacks (AWEOSInstance *pAWEOS, cbAweOSEventTrigger_t cbAweOSEventTrigger, cbAweOSEventRegister_t cbAweOSEventRegister, cbAweOSEventDeregister_t cbAweOSEventDeregister)
	Register the event callbacks used by the Event Module. More...

Detailed Description

Typedef Documentation

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

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

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

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

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]	pAWEOS	AWE Core OS instance pointer
[in]	threadPIDs	AWEOSThreadPIDs 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] aweParams the 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]	pAWEOS	Double pointer to the AWEOSInstance variable. This will be the "handle" of the AWEOSInstance.
[in]	aweParams	The user's AWEOSConfigParameters structure
[in]	pModuleDescriptorTable	A ptr to the module table (see ModuleList.h)
[in]	moduleDescriptorTableSize	The 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 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]	pAWEOS	AWE Core OS instance double pointer
[in]	portNo	port to open the socket on. Must be even number between 15002 and 15098
[in]	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.

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] pAWEOS AWE 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. 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.

Parameters

[in]	pAWEOS	AWE Core OS instance pointer
[in]	path	Path to desired logging directory. Will use current directory if NULL or ""
[in]	baseName	Base name of logging file. Will use 'awe_tuning' if NULL or "". path + baseName must be < 1024 chars.
[in]	verbosity	Verbosity level of tuning log. One of TUNING_LOG_NONE, 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]	pAWEOS	AWE Core OS instance pointer
[in]	pArray	Array of commands
[in]	arraySize	Size of command array
[out]	pErrorOffset	Report 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]	pAWEOS	AWE Core OS instance pointer
[in]	binaryFile	full filepath to AWB file on fileystem
[out]	pErrorOffset	Report 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]	pAWEOS	AWE Core OS instance pointer
[out]	inCount	number of input channels
[out]	outCount	number 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]	pAWEOS	AWE Core OS instance pointer
[out]	blockSize	block 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]	pAWEOS	AWE Core OS instance pointer
[out]	sampleRate	sample 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] pAWEOS AWE 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

@ Sample32bit

Data is 32 bit PCM .

Definition: StandardDefs.h:231

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

[in]	pAWEOS	AWE Core OS instance pointer
[in]	inSamples	buffer to read input samples from
[in]	inStride	input buffer stride
[in]	channel	channel of instance pin to write to
[in]	inType	type 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);

Parameters

[in]	pAWEOS	AWE Core OS instance pointer
[out]	outSamples	buffer to write output audio to
[in]	outStride	output buffer stride
[in]	channel	channel of instance pin to read from
[in]	outType	type 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] pAWEOS AWE 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] pAWEOS AWE 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] errorCode error 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] pAWEOS AWE 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]	pAWEOS	AWE Core OS instance pointer
[in]	handle	packed object handle
[in]	value	value(s) to set
[in]	arrayOffset	array offset if array. 0 if scalar.
[in]	length	number 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]	pAWEOS	AWE Core OS instance pointer
[in]	handle	packed object handle
[out]	value	retrieved value(s)
[in]	arrayOffset	array offset if array. 0 if scalar
[in]	length	number 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]	pAWEOS	AWE Core OS instance pointer
[in]	handle	packed object handle
[in]	status	status 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]	pAWEOS	AWE Core OS instance pointer
[in]	handle	packed object handle
[out]	status	returned 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]	pAWEOS	AWE Core OS instance pointer
[in]	handle	packed object handle
[in]	value	value(s) to set
[in]	arrayOffset	array offset if array. 0 if scalar
[in]	length	number of elements if array. 1 if scalar
[in]	mask	mask 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]	pAWEOS	AWE Core OS instance pointer
[in]	handle	packed object handle
[out]	value	value(s) to get
[in]	arrayOffset	array offset if array. 0 if scalar.
[in]	length	number of elements if array. 1 if scalar
[in]	mask	mask 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]	pAWEOS	instance pointer
[in]	handle	handle of object to find
[out]	pClassID	pointer 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] pAWEOS pointer 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]	pAWEOS	AWE Core OS instance pointer
[in]	status	0 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]	pAWEOS	AWE Core OS instance pointer
[in]	idx	Layout index (typically 0, except in advanced use cases)
[out]	averageCycles	Pointer 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] versionInfo Pointer 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]	pAWEOS	AWE Core OS instance pointer
[in]	path	Path to desired logging directory. Will use the directory application is called from if NULL or ""
[in]	baseName	Base name of audio files. Will use 'awe_audio' if NULL or ""
[in]	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
[in]	sampleType	Data 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]	pAWEOS	AWE Core OS instance pointer
[in]	recordNotificationCallback	Function pointer to register for error/info notification during recording
[in]	recordNotificationMask	Bit 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] pAWEOS AWE 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]	file	full path to name of the .wav file
[out]	sampleRate	sample rate value extracted from header
[out]	numChannels	number of audio channels extracted from header
[out]	sampleSize	size of each audio sample, in bytes
[out]	numSamples	total number of audio samples in file
[out]	fp	pointer 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]	file	full path to name of the .wav file
[in]	sampleRate	sample rate
[in]	numChannels	number of audio channels in data to be written
[in]	sampleSize	size of each audio sample, in bytes
[out]	fp	pointer 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]	fp	pointer to file to write data to
[in]	samples	pointer to buffer of samples to write to file
[in]	numSamples	total number of samples to write
[in]	sampleSize	size 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]	fp	pointer to file to read data from
[out]	samples	pointer to buffer to populate with samples from file
[in]	numSamples	total number of samples to read
[in]	sampleSize	size 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] fp pointer 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]	pInstances	Array of AWEOS Instance pointers. Array must exist as long as the system is active.
[in]	numInstances	Number of AWEOS Instances in pInstances array.

Returns: E_SUCCESS, E_PARAMETER_ERROR

Examples: Multi-Instance.c.

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

The type mask is used to filter out undesired event types

Parameters

[in]	pAWEOS	AWEOS instance pointer
[in]	cbAweOSLogging	Function pointer of the logging callback
[in]	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
[in]	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.

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

Examples: Libtester.c.

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

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

Parameters

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

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

Examples: Libtester.c.

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ cbAweOSLogging_t

◆ cbAweOSEventTrigger_t

◆ cbAweOSEventRegister_t

◆ cbAweOSEventDeregister_t

Function Documentation

◆ aweOS_getThreadPIDs()

◆ aweOS_getParamDefaults()

◆ aweOS_init()

◆ aweOS_tuningSocketOpen()

◆ aweOS_tuningSocketClose()

◆ aweOS_tuningLoggingEnable()

◆ aweOS_loadAWBFromArray()

◆ aweOS_loadAWBFile()

◆ aweOS_layoutGetChannelCount()

◆ aweOS_layoutGetBlockSize()

◆ aweOS_layoutGetSampleRate()

◆ aweOS_audioPumpAll()

◆ aweOS_audioImportSamples()

◆ aweOS_audioExportSamples()

◆ aweOS_layoutIsValid()

◆ aweOS_audioIsStarted()

◆ aweOS_errorToString()

◆ aweOS_tuningPacketProcess()

◆ aweOS_ctrlSetValue()

◆ aweOS_ctrlGetValue()

◆ aweOS_ctrlSetStatus()

◆ aweOS_ctrlGetStatus()

◆ aweOS_ctrlSetValueMask()

◆ aweOS_ctrlGetValueMask()

◆ aweOS_ctrlGetModuleClass()

◆ aweOS_destroy()

◆ aweOS_setProfilingStatus()

◆ aweOS_getAverageLayoutCycles()

◆ aweOS_getVersion()

◆ aweOS_audioRecordingEnable()

◆ aweOS_audioRecordingRegisterNotificationCallback()

◆ aweOS_audioRecordingDisable()

◆ aweOS_wavFileOpen()

◆ aweOS_wavFileCreate()

◆ aweOS_wavFileWrite()

◆ aweOS_wavFileRead()

◆ aweOS_wavFileClose()

◆ aweOS_setInstancesInfo()

◆ aweOS_registerLoggingCallback()

◆ aweOS_registerEventCallbacks()