This page is a work in progress. Improvements to content and formatting are underway.

Introduction

This document will provide information about the usage, protocol, and syntax of AudioWeaver Tuning Commands. The reader should be familiar with the AWE Tuning Interface and related concepts. Note that the information in this document pertains to both AWECore and AWECoreOS implementations. For the sake of brevity, whenever "AWECore" is used in this document, it encompasses both AWECore and AWECoreOS.

The Basics: Audio Weaver Tuning Commands are sent between the PC and an AWECore enabled HW device ("Target"). With AudioWeaver Designer/Server, the PC can "configure" the AWECore HW, and exchange information over the wire (dynamically construct layouts, return profiling values, etc). Audio Weaver Tuning Command syntax is generic, but it is up to the integrator to implement the actual communication layer on the target HW (drivers, firmware, smoke signals, etc). AWE Server supports the following communication protocols.

USB
TCP/IP
RS232
SPI

Deeper Dive: What do they actually do? Tuning commands are designed to call a function (or set of functions) within the AWECore itself. When a tuning command is received and processed by awe_packetProcess, the associated function(s) are invoked. After the function runs, a reply packet is sent back to AWE Server. The reply packet contains a success/error message, and if applicable, N 32bit payload words.

Each Tuning Command is identified by a numerical 8 bit ID, which is known as its "opcode". Every Tuning Command is associated with an opcode, and every packet will contain the command's opcode. Tuning Command opcodes are defined in an enum (tProxyFuncID, located in Include/ProxyIDs.h).

PFIDs are either public (outlined in this document), deprecated (unsupported), unused (holes), or internal (DSPC internal use only). See the quick table below for a comprehensive view of a PFIDs status.

Note: For compatibility reasons, the opcode values and packet/reply structures associated must never change. This is why holes exist, and why the deprecated/internal commands are not removed in the public facing Source/Docs.

Along with the individual commands, this document will explain the general packet/reply structure of a Tuning Command, as well as an overview of the supported Tuning Command communication layer protocols.

Message Structure

Audio Weaver Tuning commands and replies use 32-bit words, with a 1 word header and 1 word CRC wrapping the payload.

The length of the packet includes the header and CRC word. Thus, the shortest possible message – one without a payload – is two words in length.


32 bit word (header)
32 bit word (CRC)

TX Packet Structure See the table below for the command structure. Note that the header is divided into three sections, 16 bits for the command length, 8 for instanceID, and 8 for opcode.


16 bit length	8 bit instanceID	8 bit opcode
PAYLOAD[0]
PAYLOAD[1]
...
PAYLOAD[N-1]
CRC WORD

RX Reply Structure

See the table below for the reply structure. Notice that the header is split in 2 sections, 16 bits for length, and 16 bits which are always set to 0.


16 bit LENGTH	16 bit 0
PAYLOAD[0]
PAYLOAD[1]
...
PAYLOAD[N-1]
CRC WORD

Reply Packets

While tuning commands sent to the target may have no payload, the tuning replies returned by AWECore will always have at least one payload word – the "Return Value". This required word will indicate whether the command was processed successfully, or if it failed.

Note: For most PFID's reply packets, the return value is stored in word 1. However, some PFID replies store the return value in some other word in the packet (ex: PFID_ClassModule_Constructor puts the return value in word 2). See each PFID details for more info.

Reply Errors Overview

A tuning command can return an error two broad reasons...

An issue with the AWECore itself (bad instance, unconnected module in AWB, etc).
An issue with tuning layer (e.g. dropped or mangled packets)

AWECore Reply Errors

The most common reply error will originate from the AWECore library itself, and is meant to inform the user about something. Note, some error codes may not mean an actual "error"; they don't indicate a fatal problem, they just convey information.

For example, when a user connects/loads a layout with AWE Designer, PFID_FileSystemReset (opcode 44) is always transmitted. When connected to a target without an AudioWeaver Flash File System, PFID_FileSystemReset's reply packet will contain the E_COMMAND_NOT_IMPLEMENTED error. This is simply meant to notify the user that there is no Flash File System on the AWECore target. It is totally acceptable to use AWECore without a Flash File System (in fact, most users don't), so this error can be safely ignored.

In situations where fatal errors are occurring, the error code returned in the reply packet will give the reason for the failure and will allow the user to take corrective action.

For example, if a user attempts to load a large AWD on an AWECore BSP with limited heap sizes, the AWECore will return the E_MALLOC_SIZE_TOO_BIG error code. This lets the user know that they must increase their heap size (as the target hardware permits) or reduce the memory required by the layout being loaded.

See Errors.h for a complete list of AWECore induced errors. Cross reference the returned error reply ID with Errors.h to find out more about the failure.

Tuning Interface/Communication Protocol Reply Errors

If a user is seeing error codes like E_MSG_TIMEOUT, or E_MESSAGE_LENGTH_TOO_LONG, it may indicate an issue with the tuning interface implementation itself. This could be a simple bug in packet handling, or even caused by external factors (bandwidth, incomplete physical connection, USB hubs, solar flares, etc).

If a user is seeing return values like E_BADPACKET or E_CRC_ERROR, it may indicate that the tuning interface is dropping packet data or packets are being mangled.

Parsing Packet Headers

AWECoreUtils.h provides helper macros to parse an incoming packet's header. Checking these out can be helpful when understanding the packet structure.

CRC

The CRC word is used to verify packet integrity. It is a 32-bit value and computed so that when all words of the message, including the CRC, are XOR'ed together, the result is 0. The following pseudocode computes the CRC of a packet prior to transmission:

This function is also defined in AWECoreUtils.h for public use.

On the target side, the CRC calculations of reply packets are handled in awe_packetProcess. It checks the CRC of the received message and computes the checksum of the reply.

Tuning Commands Quick Table

The following is a quick reference of all the available tuning commands listed in the ProxyIDs.h PFID enum.

ID	PFID	STATUS	DESCRIPTION

ID	PFID	STATUS	DESCRIPTION
0	PFID_Undefined	active	Undefined PFID
1	PFID_SetCall	active	Calls a module's set function
2	PFID_GetCall	active	Calls a module's get function
3	hole	hole	N/A
4	PFID_GetClassType	public	Get object class type
5	PFID_GetPinType	public	Get pin properties
6	PFID_ClassWire_Constructor	public	Constructs a single instance of a wire
7	PFID_BindIOToWire	public	Attaches a wire to an IO pin
8	PFID_FetchValue	public	Reads a single value from the Target
9	PFID_SetValue	public	Sets a single value on the Target
10	PFID_GetHeapCount	public	Returns the number of heaps on a Target
11	PFID_GetHeapSize	public	Returns the free space and size of each heap.
12	PFID_Destroy	public	halt realtime audio and free memory
13	PFID_GetCIModuleCount	public	Return the # of modules on the Target
14	PFID_GetCIModuleInfo	public	Get info about a module
15	PFID_ClassModule_Constructor	public	Instantiates a module
16	PFID_ClassLayout_Constructor	public	Instantiates a layout
17	hole	hole	N/A
18	hole	hole	N/A
19	PFID_SetModuleState	public	Sets the run-time status of a module
20	PFID_GetModuleState	public	Gets the run-time status of a module
21	PFID_PumpModule	public	pump a single module (testing)
22	PFID_ClassLayout_Process	public	Processes the currently defined layout
23	PFID_GetFirstObject	public	Get first objects info
24	PFID_GetNextObject	public	Gets next object info
25	PFID_GetFirstIO	public	Gets the layouts first IO pin
26	PFID_GetNextIO	public	Get the layouts next IO pin
27	PFID_StartAudio	public	Start rt audio processing
28	PFID_StopAudio	public	Stop rt audio processing
29	PFID_FetchValues	public	Reads an array of values
30	PFID_SetValues	public	Writes an array of values
31	PFID_GetSizeofInt	public	Returns the sizeof(int) on Target
32	PFID_GetFirstFile	public	Flash filesystem only
33	PFID_GetNextFile	public	Flash filesystem only
34	PFID_OpenFile	public	Flash filesystem only
35	PFID_ReadFile	public	Flash filesystem only
36	PFID_WriteFile	public	Flash filesystem only
37	PFID_CloseFile	public	Flash filesystem only
38	PFID_DeleteFile	public	Flash filesystem only
39	PFID_ExecuteFile	internal	Flash filesystem only
40	PFID_EraseFlash	public	Flash filesystem only
41	PFID_GetTargetInfo	public	Return the Target Info
42	PFID_GetFileSystemInfo	public	Flash filesystem only
43	PFID_GetProfileValues	public	Returns target profiling info
44	PFID_FileSystemReset	public	Flash filesystem only
45	hole	hole	N/A
46	PFID_GetObjectByID	public	Return info about an object by ID
47	PFID_AddModuleToLayout	public	Adds one or more modules to an existing layout
48	PFID_SetValueCall	public	SEE PFID_SetValue
49	hole	hole	N/A
50	hole	hole	N/A
51	hole	hole	N/A
52	hole	hole	N/A
53	hole	hole	N/A
54	PFID_Tick	internal	N/A
55	hole	hole	N/A
56	PFID_AllocateHeaps	deprecated	N/A
57	PFID_DestroyHeaps	deprecated	N/A
58	PFID_WritePumpRead	internal	N/A
59	hole	hole	N/A
60	PFID_SetValueSetCall	public	Set scalar value with set call
61	PFID_SetValuesSetCall	public	Set array values with set call
62	PFID_GetCallFetchValue	public	Read scalar value with get call
63	PFID_GetCallFetchValues	public	Read array values with get call
64	hole	hole	N/A
65	hole	hole	N/A
66	hole	hole	N/A
67	hole	hole	N/A
68	hole	hole	N/A
69	hole	hole	N/A
70	hole	hole	N/A
71	hole	hole	N/A
72	hole	hole	N/A
73	hole	hole	N/A
74	hole	hole	N/A
75	hole	hole	N/A
76	hole	hole	N/A
77	PFID_SetPointer	internal	N/A
78	hole	hole	N/A
79	hole	hole	N/A
80	hole	hole	N/A
81	PFID_CreateLookupTable	internal	N/A
82	hole	hole	N/A
83	hole	hole	N/A
84	PFID_DerefPointer	public	Safely dereferences a target pointer
85	PFID_GetWireType	public	Fetches details on a specified wire
86	PFID_SetInstanceID	public	Set a MODULE's instance ID
87	PFID_Get_Flash_Erase_Time	internal	Flash filesystem only
88	hole	deprecated	N/A
89	hole	deprecated	N/A
90	hole	hole	N/A
91	hole	hole	N/A
92	hole	hole	N/A
93	PFID_DestroyAll	public	aliased with PFID_Destroy
94	PFID_GetFirstCore	deprecated	N/A
95	PFID_GetNextCore	deprecated	N/A
96	hole	hole	N/A
97	PFID_GetCores	deprecated	N/A
98	PFID_FetchValues_float	public	see generic PFID
99	PFID_GetCallFetchValues_float	public	see generic PFID
100	PFID_SetValues_float	public	see generic PFID
101	PFID_SetValuesSetCall_float	public	see generic PFID
102	PFID_FetchValue_float	public	see generic PFID
103	PFID_GetCallFetchValue_float	public	see generic PFID
104	PFID_SetValue_float	public	see generic PFID
105	PFID_SetValueSetCall_float	public	see generic PFID
106	PFID_SetValuesPartial	public	see generic PFID
107	PFID_SetValuesPartial_float	public	see generic PFID
108	hole	hole	N/A
109	PFID_SetCores	deprecated	N/A
110	hole	hole	N/A
111	hole	hole	N/A
112	hole	hole	N/A
113	PFID_CheckMemory	internal	N/A
114	hole	hole	N/A
115	hole	hole	N/A
116	PFID_StartAudio2	internal	N/A
117	PFID_StopAudio2	internal	N/A
118	hole	deprecated	N/A
119	hole	deprecated	N/A
120	PFID_GetValueHandle	public	Control Interface API
121	PFID_SetValueHandle	public	Control Interface API
122	PFID_GetStatusHandle	public	Control Interface API
123	PFID_SetStatusHandle	public	Control Interface API
124	PFID_GetValueHandleMask	public	Control Interface API
125	PFID_SetValueHandleMask	public	Control Interface API
126	PFID_GetExtendedInfo	public	Get additional target info
127	PFID_GetCores2	public	Gets instanceTable from target
127	PFID_GetInstanceTable	public	Gets instanceTable from target
128	PFID_CreateWireBufferPool	future	coming soon
129	PFID_CreateWireInBufferPool	future	coming soon

Tuning Commands

Detailed PFID information below. Note: uint may be used to represent the UINT32 type for legacy reasons. Both represent unsigned 32-bit integers. Similarly, both int and INT32 refer to 32-bit signed integers.

Note: Commands which are marked as "Aliased" mean that the same internals are called. For example PFID_SetValueCall is aliased with PFID_SetValue, which means that when PFID_SetValueCall is transmitted, the AWECore processes it as PFID_SetValue.

PFID_Undefined (ID = 0)

PFID does not exist.

PFID_SetCall (ID = 1)

Calls a module's set function.

Packet Format

Message Length = 4	coreID	PFID_SetCall

Message Length = 4	coreID	PFID_SetCall
uint instanceID
uint mask
uint CRC

Reply Format

Message Length = 3	0

Message Length = 3	0
int Error status
uint CRC

PFID_GetCall (ID = 2)

Calls a module's get function.

Packet Format

Message Length = 4	coreID	PFID_GetCall

Message Length = 4	coreID	PFID_GetCall
uint instanceID
uint mask
uint CRC

Reply Format

Message Length = 3	0

Message Length = 3	0
int Error status
uint CRC

PFID HOLE (ID = 3)

PFID_GetClassType (ID = 4)

Returns the class type of an object

Packet Format

Message Length = 3	coreID	PFID_GetClassType

Message Length = 3	coreID	PFID_GetClassType
uint instanceID
uint CRC

Reply Format

Message Length = 4	0

Message Length = 4	0
int Error status
uint ClassType
uint CRC

The ClassType integer is interpreted as follows:

Input Pin = 0xBEEF0001
Output Pin = 0xBEEF0002
Layout = 0xBEEF0004
Wire = 0xBEEF0080
InputWire = 0xBEEF0081
OutputWire = 0xBEEF0082

Module classes start at 0xBEEF0800

PFID_GetPinType (ID = 5)

Queries a pin to determine its properties.

Packet Format

Message Length = 3	coreID	IPFID_GetPinType

Message Length = 3	coreID	IPFID_GetPinType
uint pinID
uint CRC

Reply Format

Message Length = 11	0

Message Length = 11	0
int error status
uint classID
uint bound wireID
float sample rate
uint info1
uint info2
uint info3
uint name0
uint name1
uint CRC

PFID_ClassWire_Constructor (ID = 6)

Constructs a single instance of a wire

Packet Format

Message Length = 6	coreID	PFID_ClassWire_Constructor

Message Length = 6	coreID	PFID_ClassWire_Constructor
float sampleRate
uint info1
uint info2
uint info3
uint CRC

Reply Format

Message Length = 4	0

Message Length = 4	0
uint wireID
int error status
uint CRC

PFID_BindIOToWire (ID = 7)

Attaches a wire to an input or output pin of the system.

Packet Format

Message Length = 4	coreID	PFID_BindIOToWire

Message Length = 4	coreID	PFID_BindIOToWire
uint wireID
uint pinID
uint CRC

Reply Format

Message Length = 3	0

Message Length = 3	0
int error status
uint CRC

PFID_FetchValue (ID = 8)

Reads a single 32-bit integer value from a specified memory address.

Can be used with all 32-bit data types (float, fract32, and int).

Packet Format

Message Length = 4	coreID	PFID_FetchValue

Message Length = 4	coreID	PFID_FetchValue
uint address
uint offset
uint CRC

Reply Format

Message Length = 3	0

Message Length = 3	0
int error status
int/float/fract32 value
uint CRC

PFID_SetValue (ID = 9)

Sets a 32-bit value on the target.

Can be used with all 32-bit data types (float, fract32, and int). Note, this function does not call the module’s set function, it only sets the parameter. To set a value and call the module’s control function use the call PFID_SetValueSetCall.

Packet Format

Message Length = 5	coreID	PFID_SetValue

Message Length = 5	coreID	PFID_SetValue
uint address
int/float/fract32 value
uint offset
uint CRC

Reply Format

Message Length = 3	0

Message Length = 3	0
Error status
CRC

PFID_GetHeapCount (ID = 10)

Returns the number of available memory heaps on the target.

Packet Format

Message Length = 2	coreID	PFID_GetHeapCount

Message Length = 2	coreID	PFID_GetHeapCount
uint CRC

Reply Format

Message Length = 3	0

Message Length = 3	0
uint count
uint CRC

PFID_GetHeapSize (ID = 11)

Returns the sizes of all of the memory heaps on the target. The size is reported in units of 32-bit words. The message returns both the overall size and the available memory in each heap.

Packet Format

Message Length = 2	coreID	PFID_GetHeapSize

Message Length = 2	coreID	PFID_GetHeapSize
uint CRC

Reply Format

Message Length = 9	0

Message Length = 9	0
Error status
uint heap 1 free space
uint heap 2 free space
uint heap 3 free space
uint heap 1 overall size
uint heap 2 overall size
uint heap 3 overall size
uint CRC

PFID_Destroy (ID = 12)

Resets the framework to its original state. This includes freeing all allocated memory and halting real-time audio.

Note: The first payload word of the reply is always 0 (E_SUCCESS), as the internal destroy function has no possible error return value.

Packet Format

Message Length = 2	coreID	PFID_Destroy

Message Length = 2	coreID	PFID_Destroy
uint CRC

Reply Format

Message Length = 3	0

Message Length = 3	0
uint 0
uint CRC

PFID_GetCIModuleCount (ID = 13)

Returns the total number of modules on the target (module table).

Packet Format

Message Length = 2	coreID	PFID_GetCIModuleCount

Message Length = 2	coreID	PFID_GetCIModuleCount
uint CRC

Reply Format

Message Length = 3	0

Message Length = 3	0
uint count
uint CRC

PFID_GetCIModuleInfo (ID = 14)

Gets information about a particular module class available on the target.

The "numAllocationParams" reply packet payload word is the number of arguments required by the module's constructor function.

Packet Format

Message Length = 3	coreID	PFID_GetCIModuleInfo

Message Length = 3	coreID	PFID_GetCIModuleInfo
uint index
uint CRC

Reply Format

Message Length = 5	0

Message Length = 5	0
int ret
uint classID
uint numAllocationParams
uint CRC

NOTE: If the function call fails with an error, ret will hold the error value. Otherwise, it will hold the module's class ID (duplicating the classID value). All module class IDs start with 0xBEEF----, which should not be interpreted as an error value (despite being notionally negative).

PFID_ClassModule_Constructor (ID = 15)

Instantiates a single instance of a module class.

When a module is allocated, specify the module class (classID), the number of input, output, and scratch wires (packed int nIO), an array of wires (pWires; arranged as input, output, and scratch wires), the number of arguments to the constructor function (argCount).

Packet Format

Message Length = 5 + nIO+ argCount	coreID	PFID_ClassModule_Constructor

Message Length = 5 + nIO+ argCount	coreID	PFID_ClassModule_Constructor
uint classID
uint nIO
uint argCount
uint wire1ID
uint wire2ID
…
uint wireNID
int/float/fract32 arg1
int/float/fract32 arg2
…
int/float/fract32 argM
uint CRC

All of the wires used by a module must be constructed prior to constructing the module. The number of wires used by the module is packed into 8-bit fields within the 32-bit integer nIO:

(numFeedback << 24) + (numScratch << 16) + (numOutput << 8) + (numInput)

Reply Format

Message Length = 4	0

Message Length = 4	0
iuint instanceID
int Error Status
uint CRC

PFID_ClassLayout_Constructor (ID = 16)

This function creates a new layout instance.

Packet Format

Message Length = 3	coreID	PFID_ClassLayout_Constructor

Message Length = 3	coreID	PFID_ClassLayout_Constructor
uint numModules
uint divider
uint CRC

Reply Format

Message Length = 4	0

Message Length = 4	0
uint instanceID
int Error Status
uint CRC

DEPRECATED PFIDs (IDs = 17-18)

PFID_SetModuleState (ID = 19)

Set the run-time state of an audio module.

The run-time state of the module is specified by an unsigned integer

0 Active

1 Bypassed

2 Muted

3 Inactive

Packet Format

Message Length = 4	coreID	PFID_SetModuleState

Message Length = 4	coreID	PFID_SetModuleState
uint instanceID
uint state
uint CRC

Reply Format

Message Length = 3	0

Message Length = 3	0
int Error Status
CRC

PFID_GetModuleState (ID = 20)

Returns the run-time state of an audio module.

The module state is returned as an unsigned integer. See PFID_SetModuleState for state definitions.

Packet Format

Message Length = 3	coreID	PFID_GetModuleState

Message Length = 3	coreID	PFID_GetModuleState
uint instanceID
uint CRC

Reply Format

Message Length = 3	0

Message Length = 3	0
int state
uint CRC

PFID_PumpModule (ID = 21)

Calls the processing function once for an audio module instance. This function is primarily used for regression testing.

Packet Format

Message Length = 3	coreID	PFID_PumpModule

Message Length = 3	coreID	PFID_PumpModule
uint instanceID
uint CRC

Reply Format

Message Length = 3	0

Message Length = 3	0
int error status
uint CRC

PFID_ClassLayout_Process (ID = 22)

Calls the layout processing function. This executes all modules in the system in the order that they were added to the layout.

Packet Format

Message Length = 3	coreID	PFID_ClassLayout_Process

Message Length = 3	coreID	PFID_ClassLayout_Process
uint instanceID
uint CRC

Reply Format

Message Length = 2	0

Message Length = 2	0
int error status
uint cycles
uint intervalCycles
uint CRC

PFID_GetFirstObject (ID = 23)

Gets information about the first object that was constructed on the target.

Packet Format

Message Length = 2	coreID	PFID_GetFirstObject

Message Length = 2	coreID	PFID_GetFirstObject
uint CRC

Reply Format

Message Length = 5	0

Message Length = 5	0
int error status
uint instanceIDs
uint classID
uint CRC

PFID_GetNextObject (ID = 24)

Gets information about the next object that exists on the target. First call PFID_GetFirstObject to get information about the first object. Then make repeated calls to this function to obtain information about subsequent objects. Once last object has been reached, this message will fail.

Information is returned about the object following currentObject.

Packet Format

Message Length = 3	coreID	PFID_GetNextObject

Message Length = 3	coreID	PFID_GetNextObject
uint currentInstanceID
uint CRC

Reply Format

Message Length = 5	0

Message Length = 5	0
int error status
uint nextInstanceID
uint classID
uint CRC

PFID_GetFirstIO (ID = 25)

Returns a pin ID, class ID, and properties for the first I/O pin in the system.

Packet Format

Message Length = 2	coreID	PFID_GetFirstIO

Message Length = 2	coreID	PFID_GetFirstIO
uint CRC

Reply Format

Message Length = 12	0

Message Length = 12	0
int error status
uint pinID
uint classID
uint hasBuffer (0 or 1)
float sampleRate
uint info1
uint info2
uint info3
uint name0
uint name1
uint CRC

PFID_GetNextIO (ID = 26)

Returns information about the next I/O pin.

Information is returned about the I/O pin following currentObject.

Packet Format

Message Length = 3	coreID	PFID_GetNextIO

Message Length = 3	coreID	PFID_GetNextIO
uint currentPinID
uint CRC

Reply Format

Message Length = 12	0

Message Length = 12	0
int error status
uint pinID
uint classID
uint hasBuffer 0or1
float sampleRate
uint info1
uint info2
uint info3
uint name0
uint name1
uint CRC

PFID_StartAudio (ID = 27)

Starts real-time audio processing on the target. Triggers a call to the user implemented cbAudioStart callback function.

Packet Format

Message Length = 2	coreID	PFID_StartAudio

Message Length = 2	coreID	PFID_StartAudio
CRC

Reply Format

Message Length = 3	0

Message Length = 3	0
int error status
CRC

PFID_StopAudio (ID = 28)

Halts real-time audio processing. Triggers a call to the user implemented cbAudioStop callback function.

Packet Format

Message Length = 2	coreID	PFID_StopAudio

Message Length = 2	coreID	PFID_StopAudio
uint CRC

Reply Format

Message Length = 3	0

Message Length = 3	0
int error status
uint CRC

PFID_FetchValues (ID = 29)

Reads a block of values from the target processor's memory.

Packet Format

Message Length = 5	coreID	PFID_FetchValues

Message Length = 5	coreID	PFID_FetchValues
uint address
uint offset
uint num words to read
uint CRC

The return message has variable size. It is the responsibility of the caller to ensure that the message buffer on the target is large enough to hold the returned message.

Reply Format

Message Length = 3 + numWords	0

Message Length = 3 + numWords	0
int error status
int/float/fract value 1
int/float/fractvalue 2
…
int/float/fractvalue N
uint CRC

PFID_SetValues (ID = 30)

Writes a block of values in the target processor's memory.

The transmitted message is variable length and it is the responsibility of the caller to ensure that the length of the message does not exceed the length of the message buffer on the target.

Packet Format

Message Length = 5 + numWords	coreID	PFID_SetValues

Message Length = 5 + numWords	coreID	PFID_SetValues
uint address
uint offset
uint num words to write
int/float/fract value 1
int/float/fractvalue 2
…
int/float/fractvalue N
uint CRC

Reply Format

Message Length = 3	0

Message Length = 3	0
int error status
CRC

PFID_GetSizeofInt (ID = 31)

Returns the value sizeof(int) evaluated on the target. This is used by Audio Weaver to determine address offsets.

Packet Format

Message Length = 2	coreID	PFID_GetSizeofInt

Message Length = 2	coreID	PFID_GetSizeofInt
uint CRC

Reply Format

Message Length = 3	0

Message Length = 3	0
int size
uint CRC

PFID_GetFirstFile (ID = 32)

Read the first file directory entry from the target flash file system. Flash File System Only

Packet Format

Message Length = 2	coreID	PFID_GetFirstFile

Message Length = 2	coreID	PFID_GetFirstFile
CRC

Reply Format

Message Length = 11	0

Message Length = 11	0
int error status
uint attribute
uint lengthWords
uint file name
……..
……..
uint CRC

PFID_GetNextFile (ID = 33)

Read the next file directory entry from the target flash file system. Flash File System Only

Packet Format

Message Length = 2	coreID	PFID_GetNextFile

Message Length = 2	coreID	PFID_GetNextFile
uint CRC

Reply Format

Message Length = 11	0

Message Length = 11	0
int error status
uint attribute
uint lengthWords
uint file name
……..
……..
uint CRC

PFID_OpenFile (ID = 34)

Opens a file for reading or creates a new file for writing. Attribute must be 0 if opening a file for reading. If file opened for writing and it already exists and is not marked as deleted an error is returned. Flash File System Only

Packet Format

Message Length = 3 + numWords	coreID	PFID_OpenFile

Message Length = 3 + numWords	coreID	PFID_OpenFile
uint attribute
uint file name
……
uint CRC

Reply Format

Message Length = 4	0

Message Length = 4	0
int error status
uint lengthWords
CRC

PFID_ReadFile (ID = 35)

Read the indicated number of words from an opened file. The number of words returned can be less than the number asked for if the end of file is reached. Flash File System Only

Packet Format

Message Length = 3	coreID	PFID_ReadFile

Message Length = 3	coreID	PFID_ReadFile
uint no of 32-bit words to read
uint CRC

Reply Format

Message Length = 4 + numWords	0

Message Length = 4 + numWords	0
int error status
uint number of words read
uint data
…..
uint CRC

PFID_WriteFile (ID = 36)

Write the indicated number of words to an opened file. Flash File System Only

Packet Format

Message Length = 3 + numWords	coreID	PFID_WriteFile

Message Length = 3 + numWords	coreID	PFID_WriteFile
uint num words to write
uint data
……
uint CRC

Reply Format

Message Length = 3	0

Message Length = 3	0
int error status
uint CRC

PFID_CloseFile (ID = 37)

Closes an opened file and writes the directory entry if file was opened for write. Flash File System Only

Packet Format

Message Length = 2	coreID	PFID_CloseFile

Message Length = 2	coreID	PFID_CloseFile
uint CRC

Reply Format

Message Length = 3	0

Message Length = 3	0
int error status
uint CRC

PFID_DeleteFile (ID = 38)

Mark a file as deleted. Flash File System Only

Packet Format

Message Length = 3 + numWords	coreID	PFID_DeleteFile

Message Length = 3 + numWords	coreID	PFID_DeleteFile
uint attribute
uint file name
……
uint CRC

Reply Format

Message Length = 3	0

Message Length = 3	0
int error status
uint CRC

PFID_ExecuteFile (ID = 39)

Internal use only

PFID_EraseFlash (ID = 40)

Erase the entire Flash file system. Flash File System Only

Packet Format

Message Length = 2	coreID	PFID_EraseFlash

Message Length = 2	coreID	PFID_EraseFlash
uint CRC

Reply Format

Message Length = 3	0

Message Length = 3	0
int error status
uint CRC

PFID_GetTargetInfo (ID = 41)

Returns information about the currently connected target.

Packet Format

Message Length = 2	coreID	PFID_GetTargetInfo

Message Length = 2	coreID	PFID_GetTargetInfo
CRC (uint)

Reply Format

Message Length = 14	0

Message Length = 14	0
error status (int)
sample rate (float)
profile clock speed in Hz (float)
packedBlockSize (uint)
packedData (uint)
version information (uint)
packetBufferSize (uint)
packedName 1 (uint)
packedName 2 (uint)
cpuClockSpeed in Hz (float)
coreID (uint)
featureBits (uint)
CRC (uint)

packedBlockSize contains several pieces of information packed into 32-bits. From the lsb to the msb, the items are:

packedData contains several pieces of information packed into 32-bits. From the lsb to the msb, the items are:

packetBufferSize contains several pieces of information packed into 32-bits. From the lsb to the msb, the items are:

PFID_GetFileSystemInfo (ID = 42)

Get the flash file system information from the target. Flash Filesystem Only

Packet Format

Message Length = 2	coreID	PFID_GetFileSystemInfo

Message Length = 2	coreID	PFID_GetFileSystemInfo
CRC (uint)

Reply Format

Message Length = 11

Message Length = 11
int error status
uint file system type
uint flash device size
uint no of words available for files
uint no of words used by the file system data structures
uint words no of allocated to deleted or corrupted files
uint no of words in use by files
uint no of words available for new files
uint allocation block size and max file length
uint CRC

PFID_GetProfileValues (ID = 43)

Returns overall MIPs profiling information for a layout.

averageCycles is the average number of profiling cycles required to process the entire layout. This is measured in real-time and averaged over approximately 100 executions of the layout. timePerProcess is the amount of time between calls to the layout processing function. This indicates how much total processing is available in the system.

Packet Format

Message Length = 2	coreID	PFID_GetProfileValue

Message Length = 2	coreID	PFID_GetProfileValue
uint CRC

Reply Format

Message Length = 5	0

Message Length = 5	0
int error status
float averageCycles
float timePerProcess
uint CRC

PFID_FileSystemReset (ID = 44)

Force the target to close any open files and reset the flash file system variables to default state. Flash Filesystem Only

Packet Format

Message Length = 2	coreID	PFID_FileSystemReset

Message Length = 2	coreID	PFID_FileSystemReset
CRC (uint)

Reply Format

Message Length = 3	0

Message Length = 3	0
error status (int)
CRC (uint)

DEPRECATED PFID (ID = 45)

PFID_GetObjectByID (ID = 46)

This function is complementary to GetFirstObject and GetNextObject. Instead of returning objects in the order that they were instantiated, this function provides direct access to the object based on its objectID.

Packet Format

Message Length = 2	coreID	PFID_GetObjectByID

Message Length = 2	coreID	PFID_GetObjectByID
uint objectID
uint CRC

Reply Format

Message Length = 5	0

Message Length = 5	0
int error status
int objectID
uint classID
uint CRC

PFID_AddModuleToLayout (ID = 47)

This function adds one or more modules to the specified layout.

Packet Format

Message Length = 2 + argCount	coreID	PFID_AddModuleToLayout

Message Length = 2 + argCount	coreID	PFID_AddModuleToLayout
uint layoutID
uint nModules
uint module1D
…..
CRC

Reply Format

Message Length = 3

Message Length = 3
int error status
uint CRC

PFID_SetValueCall (ID = 48)

ALIASED WITH PFID_SetValue (ID = 9)

PFID HOLES (IDs = 52-53)

PFID_Tick(ID = 54)

Internal use only

Used by Matlab during regression to force deferred evaluation at a time of Matlab's choosing.

DEPRECATED PFIDs (IDs = 55-57)

PFID_WritePumpRead (ID = 58)

Internal use only

A fast way of doing some regression actions, or using the DSP remotely.

DEPRECATED PFID (ID = 59)

PFID_SetValueSetCall(ID = 60)

Sets a 32-bit value on the target.

Can be used with all 32-bit data types (float, fract32, and int). After assigning the value, calls the module’s set function.

Packet Format

Message Length = 6	coreID	PFID_SetValueSetCall

Message Length = 6	coreID	PFID_SetValueSetCall
uint address
int/float/fract32 value
uint mask
uint offset
uint CRC

Reply Format

Message Length = 3	0

Message Length = 3	0
Error status
CRC

PFID_SetValuesSetCall (ID = 61)

Write values (arrays) and then calls the set function.

Packet Format

Message Length = 6 + argCount	coreID	PFID_SetValuesSetCall

Message Length = 6 + argCount	coreID	PFID_SetValuesSetCall
uint address
uint offset
uint mask
uint argCount
int/float/fract32 val1
....
uint CRC

Reply Format

Message Length = 3	0

Message Length = 3	0
int error status
uint CRC

PFID_GetCallFetchValue (ID = 62)

Performs a get call then reads scalar value.

Packet Format

Message Length = 5	coreID	PFID_GetCallFetchValue

Message Length = 5	coreID	PFID_GetCallFetchValue
uint address
uint mask
uint offset
uint CRC

Reply Format

Message Length = 4	0

Message Length = 4	0
int error status
int/float/fract32 value
uint CRC

PFID_GetCallFetchValues (ID = 63)

Performs a get call then reads values (arrays).

Packet Format

Message Length = 6	coreID	PFID_GetCallFetchValues

Message Length = 6	coreID	PFID_GetCallFetchValues
uint address
uint offset
uint mask
uint words to read
uint CRC

Reply Format

Message Length = 3 + nWords	0

Message Length = 3 + nWords	0
int error status
int/float/fract32 val 1
...
uint CRC

PFID HOLES (IDs = 64-76)

PFID_SetPointer (ID = 77)

Internal use only

PFID HOLES (IDs = 78-80)

PFID_CreateLookupTable (ID = 81)

Internal use only

PFID_PumpLayout (ID = 83)

Internal use only

PFID_DerefPointer (ID = 84)

Safely derefernces a target pointer

Packet Format

Message Length = 3	coreID	PFID_DerefPointer

Message Length = 3	coreID	PFID_DerefPointer
uint address
uint CRC

Reply Format

Message Length = 4	0

Message Length = 4	0
int error status
uint fetchedValue
uint CRC

PFID_GetWireType (ID = 85)

Fetches details on a specified wire.

Packet Format

Message Length = 3	coreID	PFID_GetWireType

Message Length = 3	coreID	PFID_GetWireType
uint wireID
uint CRC

Reply Format

Message Length = 8	0

Message Length = 8	0
int error status
uint classID
float sampleRate
uint info1
uint info3
uint info3
uint CRC

PFID_SetInstanceID (ID = 86)

Sets a module's instance ID. Note: this is unrelated to the AWEInstance->instanceID (coreID)

Packet Format

Message Length = 4	coreID	PFID_GetWireType

Message Length = 4	coreID	PFID_GetWireType
uint instanceID
uint newInstanceID
uint CRC

Reply Format

Message Length = 3	0

Message Length = 3	0
int error status
uint CRC

PFID_Get_Flash_Erase_Time (ID = 87)

Internal use only

DEPRECATED PFIDs (IDs = 88-92)

PFID_DestroyAll (ID - 93)

ALIASED with PFID_Destroy (opcode 12)

DEPRECATED PFIDs (IDs = 94-97)

Used in AWE6 but deprecated in AWE8.

PFID_Get/Set FLOAT Commands (IDs = 98-107)

These are similar to other non-float get/set calls (60-63, 29-30, etc), but specifically implemented for targets which do not support IEEE floating point data. Only used on a limited set of targets.

PFID_FetchValues_float PFID_GetCallFetchValues_float PFID_SetValues_float PFID_SetValuesSetCall_float PFID_FetchValue_float PFID_GetCallFetchValue_float PFID_SetValue_float PFID_SetValueSetCall_float PFID_SetValuesPartial PFID_SetValuesPartial_float

PFID HOLE (ID = 108)

DEPRECATED PFID (ID = 109)

PFID HOLES (IDs = 110-111)

DEPRECATED PFID (ID = 112)

PFID_CheckMemory (ID = 113)

Internal use only

DEPRECATED PFID (ID = 114)

PFID_StartAudio2 (ID = 116)

Internal use only

PFID_StopAudio2 (ID = 117)

Internal use only

DEPRECATED PFIDS (IDs = 118-119)

PFID_GetValueHandle (ID = 120)

Calls awe_ctrlGetValue (Control Interface API)

Packet Format

Message Length = 5	coreID	PFID_GetValueHandle

Message Length = 5	coreID	PFID_GetValueHandle
handle (UINT32)
array length - must be 1 if scalar (UINT32)
array offset - must be 0 if scalar (INT32)
CRC (UINT32)

Reply Format

Message Length = 16	0

Message Length = 16	0
error status (INT32)
VALUE[0]
VALUE[1]
....
VALUE[N-1]
CRC (UINT32)

PFID_SetValueHandle (ID = 121)

Calls awe_ctrlSetValue (Control Interface API)

Packet Format

Message Length = N	coreID	PFID_SetValueHandle

Message Length = N	coreID	PFID_SetValueHandle
handle (UINT32)
array length - must be 1 if scalar (UINT32)
array offset - must be 0 if scalar (INT32)
VALUE[0]
VALUE[1]
....
VALUE[N-1]
CRC (UINT32)

Reply Format

Message Length = 3	0

Message Length = 3	0
int error status
uint CRC

PFID_GetStatusHandle (ID = 122)

Calls awe_ctrlGetStatus (Control Interface API)

Packet Format

Message Length = 5	coreID	PFID_SetStatusHandle

Message Length = 5	coreID	PFID_SetStatusHandle
handle (UINT32)
CRC (UINT32)

Reply Format

Message Length = 3	0

Message Length = 3	0
error if < 0, status val if > 0
uint CRC

PFID_SetStatusHandle (ID = 123)

Calls awe_ctrlSetStatus (Control Interface API)

Packet Format

Message Length = 5	coreID	PFID_SetStatusHandle

Message Length = 5	coreID	PFID_SetStatusHandle
handle (UINT32)
module status (UINT32)
CRC (UINT32)

Reply Format

Message Length = 3	0

Message Length = 3	0
int error status
uint CRC

PFID_GetValueHandleMask (ID = 124)

Calls awe_ctrlGetValueMask (Control Interface API)

Packet Format

Message Length = 6	coreID	PFID_SetValueHandle

Message Length = 6	coreID	PFID_SetValueHandle
handle (UINT32)
array length - must be 1 if scalar (UINT32)
array offset - must be 0 if scalar (INT32)
Mask (UINT32)
CRC (UINT32)

Reply Format

Message Length = 16	0

Message Length = 16	0
error status (INT32)
VALUE[0]
VALUE[1]
....
VALUE[N-1]
CRC (UINT32)

PFID_SetValueHandleMask (ID = 125)

Calls awe_ctrlSetValueMask (Control Interface API)

Packet Format

Message Length = N	coreID	PFID_SetValueHandle

Message Length = N	coreID	PFID_SetValueHandle
handle (UINT32)
array length - must be 1 if scalar (UINT32)
array offset - must be 0 if scalar (INT32)
mask (UINT32)
VALUE[0]
VALUE[1]
....
VALUE[N-1]
CRC (UINT32)

Reply Format

Message Length = 3	0

Message Length = 3	0
int error status
uint CRC

PFID_GetExtendedInfo (ID = 126)

Gets extended information about the target.

Packet Format

Message Length = 2	coreID	PFID_GetExtendedInfo

Message Length = 2	coreID	PFID_GetExtendedInfo
CRC (uint)

Reply Format

Message Length = 16	0

Message Length = 16	0
userVersion (uint)
infoWord (uint)*
11 undefined values (uint)
CRC (uint)

*Bit packed informational word 1 bit 0: AWECoreOS product identifier bit 1-31: Unused

PFID_GetInstanceTable/PFID_GetCores2 (ID = 127)

Gets table of instances supported by the target. See the integration guide for more info.

Note: both PFID_GetInstanceTable and PFID_GetCores2 share an opcode (127).

Packet Format

Message Length = 2	coreID	PFID_GetInstanceTable

Message Length = 2	coreID	PFID_GetInstanceTable
CRC (uint)

Reply Format

Message Length = (3 + numberInstances)	0

Message Length = (3 + numberInstances)	0
numberInstances (uint)
instanceID (uint) (variable number of instanceIDs)
CRC (uint)

PFID_CreateWireBufferPool/PFID_CreateWireInBufferPool (IDs = 128-129)

Will be supported in upcoming Designer releases

RS-232 Protocol

Audio Weaver messages (commands and replies) are arrays of 32-bit integers. In the case of RS-232 communications, a lower level byte-by-byte protocol is added which provides another level of robustness to the communication link. This additional robustness is critical in RS-232 which is more susceptible to bit corruption and dropped bytes.

Each 32-bit word within the message array is expanded into 5 bytes using the code:

7 data bits are taken at a time from each message word and the high bit is set. (For the last character, only the low 4 data bits are used.)

The data is then encapsulated within a series of protocol bytes:

With this design, the protocol bytes are unique. That is, the protocol bytes (0x02, 0x03, 0x30-0x39) are never found within the data bytes since the data bytes always have the high bit set. This makes it easy to identify the start and end of data packets. The sequence byte starts at 0x30, increments 1 for each successful transmission, and then wraps from 0x39 to 0x30. The sequence byte is used to identify retransmissions.

For example, consider the command PFID_GetProfileValues with ID = 43. The message sent from the PC to the target processor is:

Message Length = 2	ID = PFID_GetProfileValue

Message Length = 2	ID = PFID_GetProfileValue
CRC

Which translates into the 32-bit words:

The 32-bit words are expanded into 5 bytes each:

Adding the remaining protocol bytes, the sequence sent is:

RS-232 Time Outs and Resends

Audio Weaver has several configurable timeouts. After a message is sent to the target processor the Server waits for a reply. When using the RS232 protocol, if the start of the reply is not received within 50 msec the Server declares a time out and resends the message (SingleCharTimeout). If the entire reply is not received within 150 msec then a timeout is declared (TotalTimeoutTimeout).

When a timeout occurs, the Server resends the message. If the same message has been sent 3 times (2 timeouts), then the Server will declare an error and inform the user.

The timeout periods can be modified to match the target application. For example, edit the AWE_Server.ini file and change the following lines to read:

(All times are in milliseconds)

SPI Protocol

The Audio Weaver SPI protocol mirrors the 32-bit packet structure. There are two differences:

The 32-bit synchronization word 0xDEADBEEF is sent before each message.
The 4 bytes within each 32-bit word as swapped. 0x12345678 it turned into 0x78563412.

For example, consider the command “PFID_GetProfileValues” with ID = 43 (0x2b). The message sent from the PC to the target processor is:

Message Length = 2	ID = PFID_GetProfileValue

Message Length = 2	ID = PFID_GetProfileValue
CRC

This translates into the 32-bit words:

The overall message sent is:

After a message is received by the target processor and the message is being processed, the SPI output buffer will be set to the “not ready” word 0xA3A3A3A3. This will allow a host processor to poll the SPI interface waiting for the target processor to complete message processing. The target processor will continue to transmit the not ready word until the message has been processed. At this point, it will switch over to the sync word followed by the complete message.

If the host processor continues to read beyond the end of a reply from the target, then the target will return 0xFFFFFFFF.

USB Protocol

Audio weaver USB communication is based on the USB HID protocol. Audio Weaver commands and replies are encapsulated in one or more 56-byte HID report packets operating over a 64-byte USB pipe. Each HID report packet starts with the HID report ID. Audio Weaver uses HID Report ID 1. If USB HID communications are used for other firmware features, those features must use a HID Report ID other than 1.

Following the HID report ID is a one byte sequence number and a two byte length field.

HID Report ID 1	Packet Seq No	Command Byte Length		AWE Packet Bytes

HID Report ID 1	Packet Seq No	Command Byte Length		AWE Packet Bytes
1 byte	1 byte	hi byte	lo byte	up to 52 bytes

Ethernet TCP/IP Protocol

Audio Weaver ethernet communication is as simple as passing commands/replies via a TCP/IP socket.

AWE Core Tuning Command Syntax and Protocol (Archived)

Introduction

Message Structure

Reply Packets

Reply Errors Overview

AWECore Reply Errors

Tuning Interface/Communication Protocol Reply Errors

Parsing Packet Headers

CRC

Tuning Commands Quick Table

Tuning Commands

PFID_Undefined (ID = 0)

PFID_SetCall (ID = 1)

Packet Format

Reply Format

PFID_GetCall (ID = 2)

Packet Format

Reply Format

PFID HOLE (ID = 3)

PFID_GetClassType (ID = 4)

Packet Format

Reply Format

PFID_GetPinType (ID = 5)

Packet Format

Reply Format

PFID_ClassWire_Constructor (ID = 6)

Packet Format

Reply Format

PFID_BindIOToWire (ID = 7)

Packet Format

Reply Format

PFID_FetchValue (ID = 8)

Packet Format

Reply Format

PFID_SetValue (ID = 9)

Packet Format

Reply Format

PFID_GetHeapCount (ID = 10)

Packet Format

Reply Format

PFID_GetHeapSize (ID = 11)

Packet Format

Reply Format

PFID_Destroy (ID = 12)

Packet Format

Reply Format

PFID_GetCIModuleCount (ID = 13)

Packet Format

Reply Format

PFID_GetCIModuleInfo (ID = 14)

Packet Format

Reply Format

PFID_ClassModule_Constructor (ID = 15)

Packet Format

Reply Format

PFID_ClassLayout_Constructor (ID = 16)

Packet Format

Reply Format

DEPRECATED PFIDs (IDs = 17-18)

PFID_SetModuleState (ID = 19)

Packet Format

Reply Format

PFID_GetModuleState (ID = 20)

Packet Format

Reply Format

PFID_PumpModule (ID = 21)

Packet Format

Reply Format

PFID_ClassLayout_Process (ID = 22)

Packet Format

Reply Format

PFID_GetFirstObject (ID = 23)

Packet Format

Reply Format

PFID_GetNextObject (ID = 24)

Packet Format

Reply Format

PFID_GetFirstIO (ID = 25)

Packet Format

Reply Format