AWE Core OS 8.B.20 Documentation
Tuning Command Syntax and Protocol

  1. Introduction
  2. Message Structure
  3. Reply Packets
  4. Tuning-Commands Quick Table
  5. Tuning-Commands
  6. RS-232 Protocol
    1. RS-232 Time Outs and Resends
  7. SPI Protocol
  8. USB Protocol
  9. Ethernet TCP/IP Protocol

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 for two broad reasons:

  1. An issue with the AWECore itself (bad instance, unconnected module in AWB, etc).
  2. 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.

#define PACKET_LENGTH_WORDS(x) (x[0]>>16)
#define PACKET_LENGTH_BYTES(x) ((x[0]>>16) * sizeof(x[0]))
#define PACKET_INSTANCEID(x) (x[0] >> 8) & 0xff
#define PACKET_OPCODE(x) ((INT32)x[0] & 0xffU)

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'd together, the result is 0. The following pseudocode computes the CRC of a packet prior to transmission: 

  nLen = packetBuffer[0] >> 16;

  DWORD crc=0;
  for(i=0; i < (nLen-1); i++)
    {
      crc^=packetBuffer[i];
    }

  g_PacketBuffer[nLen-1] = crc;

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
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
130 PFID_GetSharedHeapSize public Gets size and usage of shared heap on target
131 PFID_GetLayoutCoreAffinity public Gets core affinity for a layout
132 PFID_GetProfileValuesPreCalc public Gets profiling information including calculated time per process
133 PFID_GetAllProfiling public Gets profiling information for all requested layouts loaded on instance
134 PFID_GetAllMatchingModules public Retrieves all modules matching keyType/Value from the running layout

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
uint instanceID
uint mask
uint CRC

Reply Format

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
uint instanceID
uint mask
uint CRC

Reply Format

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
uint instanceID
uint CRC

Reply Format

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 PFID_GetPinType
uint pinID
uint CRC

Reply Format

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
float sampleRate
uint info1
uint info2
uint info3
uint CRC

Reply Format

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
uint wireID
uint pinID
uint CRC

Reply Format

Message Length = 3 0
int error status
uint CRC

PFID_FetchValue (ID = 8)

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

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

Packet Format

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

Reply Format

Message Length = 4 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
uint address
int/float/fract32 value
uint offset
uint CRC

Reply Format

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
uint CRC

Reply Format

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
uint CRC

Reply Format

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
uint CRC

Reply Format

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
uint CRC

Reply Format

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
uint index
uint CRC

Reply Format

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
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
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
uint numModules
uint divider
uint CRC

Reply Format

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
uint instanceID
uint state
uint CRC

Reply Format

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
uint instanceID
uint CRC

Reply Format

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
uint instanceID
uint CRC

Reply Format

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
uint instanceID
uint CRC

Reply Format

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
uint CRC

Reply Format

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
uint currentInstanceID
uint CRC

Reply Format

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
uint CRC

Reply Format

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
uint currentPinID
uint CRC

Reply Format

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_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
CRC

Reply Format

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
uint CRC

Reply Format

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
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
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
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
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
uint CRC

Reply Format

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
CRC

Reply Format

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
uint CRC

Reply Format

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
uint attribute
uint file name
……
uint CRC

Reply Format

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
uint no of 32-bit words to read
uint CRC

Reply Format

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
uint num words to write
uint data
……
uint CRC

Reply Format

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 writing. Flash File System Only

Packet Format

Message Length = 2 coreID PFID_CloseFile
uint CRC

Reply Format

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
uint attribute
uint file name
……
uint CRC

Reply Format

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
uint CRC

Reply Format

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
CRC (uint)

Reply Format

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:

Audio Base Block Size 12 bits
Number of Threads Allowed 4 bits
Clock Domain of the Core (0 is the main domain) 4 bits
Are the HW pins float (1 if true) 1 bit
isAlign4 1 bit
hasBuffer 1 bit
spare 9 bits

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

Size of integers (sizeo(int)) 4 bits
isFlashSupported 1 bit
isFloatingPoint 1 bit
usesTestPadding 1 bit
spare 1 bit
numInputChannels 8 bits
numOutputChannels 8 bits
processorType 7 bits
spare 1 bit

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

packetBuffersize 13 bits
nCores 6 bits
isSMP 1 bit
nInputPins 6 bits
nOutputPins 6 bits

PFID_GetFileSystemInfo (ID = 42)

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

Packet Format

Message Length = 2 coreID PFID_GetFileSystemInfo
CRC (uint)

Reply Format

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. Optionally specify a layout index to get a specific layout's profile statistics.

Packet Format (Option 1 - All Layouts)

Message Length = 2 coreID PFID_GetProfileValue
uint CRC

Packet Format (Option 2 - Specific Layout)

Message Length = 3 coreID PFID_GetProfileValue
int layout index
uint CRC

Packet Format (Option 3 - All Layouts)

Passing -1 as the layout index will get the same response as Option 1.

Message Length = 3 coreID PFID_GetProfileValue
int layout index == -1
uint CRC

Reply Format

Message Length = 5 0
int error status
uint averageCycles
uint 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
CRC (uint)

Reply Format

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
uint objectID
uint CRC

Reply Format

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
uint layoutID
uint nModules
uint module1D
…..
CRC

Reply Format

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
uint address
int/float/fract32 value
uint mask
uint offset
uint CRC

Reply Format

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
uint address
uint offset
uint mask
uint argCount
int/float/fract32 val1
....
uint CRC

Reply Format

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
uint address
uint mask
uint offset
uint CRC

Reply Format

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
uint address
uint offset
uint mask
uint words to read
uint CRC

Reply Format

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 dereferences a target pointer

Packet Format

Message Length = 3 coreID PFID_DerefPointer
uint address
uint CRC

Reply Format

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
uint wireID
uint CRC

Reply Format

Message Length = 8 0
int error status
uint classID
float sampleRate
uint info1
uint info2
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
uint instanceID
uint newInstanceID
uint CRC

Reply Format

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
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
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
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
int error status
uint CRC

PFID_GetStatusHandle (ID = 122)

Calls awe_ctrlGetStatus (Control Interface API)

Packet Format

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

Reply Format

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 = 4 coreID PFID_SetStatusHandle
handle (UINT32)
module status (UINT32)
CRC (UINT32)

Reply Format

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
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
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
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
int error status
uint CRC

PFID_GetExtendedInfo (ID = 126)

Gets extended information about the target.

Packet Format

Message Length = 2 coreID PFID_GetExtendedInfo
CRC (uint)

Reply Format

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 a 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
CRC (uint)

Reply Format

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

PFID_GetSharedHeapSize (ID = 130)

Returns the size of the shared heap, if the target is a multi-instance enabled with shared heap memory. The size is reported in units of 32-bit words. The message returns both the overall size and the available memory in shared heap.

Packet Format

Message Length = 2 coreID PFID_GetSharedHeapSize
uint CRC

Reply Format

Message Length = 5 0
Error status
uint shared heap free space
uint shared heap overall size
uint CRC

PFID_GetLayoutCoreAffinity (ID = 131)

Get the core affinity for a specific layout. The core affinities must be set on the target with the awe_fwSetLayoutCoreAffinity function. By default, valid layouts have a core affinity of 0 and an invalid layout will have a core affinity of 0xFFFFFFFF.

Packet Format

Message Length = 3 coreID PFID_GetInstanceTable
layoutID (uint)
crc (uint)

Reply Format

Message Length = 3 0
affinity (uint)
CRC (uint)

PFID_GetProfileValuesPreCalc (ID = 132)

Returns overall MIPs profiling information for a layout with theoretically calculated time per block value.

averageCycles is the average number of profiling cycles required to process the entire layout. This is measured in real-time and averaged over all the time layout is running. timePerProcess is the amount of time between calls to the layout processing function, which is calculated theoritically based on the profiling speed, layout block size and the system sample rate as (profilingSpeed x blockSize)/SampleRate. This indicates how much total processing is available in the system. Optionally specify a layout index to get a specific layout's profile statistics.

Packet Format (Option 1 - All Layouts)

Message Length = 2 coreID PFID_GetProfileValuesPreCalc
uint CRC

Packet Format (Option 2 - Specific Layout)

Message Length = 3 coreID PFID_GetProfileValuesPreCalc
uint layout index
uint CRC

Packet Format (Option 3 - All Layouts)

Passing -1 as the layout index will get the same response as Option 1.

Message Length = 3 coreID PFID_GetProfileValuesPreCalc
uint layout index == 0xFFFFFFFF (-1)
uint CRC

Reply Format

Message Length = 5 0
int error status
uint averageCycles
uint timePerProcessPreCalc
uint CRC

PFID_GetAllProfiling (ID = 133)

Returns the profiling information for the number of layouts requested. Following profiling values per layout returned: 

timePerProcessMeasured (measured in realtime)
timePerProcessCalculated (theoretically calculated)
averageCycles
InstantaneousCycles
peakCycles
overflowCount

If the start layout offset is 0, it also returns additional header information of all layouts combined average cycles, sum of all layouts overflow count and number of expected profiling values per layout follows.

It's user responsibility to loop through if the reply values does not fit in one reply packet, with appropriate start layout offset.

Packet Format

Message Length = 4 coreID PFID_GetAllProfiling
uint layout offset (0 based)
uint number of layouts (N)
uint CRC

Reply Format (Layout offset == 0)

If the starting layout offset is 0, reply contains additional 3 words.

Message Length = 3+3+numLayoutsXprofilingValuesPerLayout 0
int error status
uint averageCyclesAllCombined
uint overflowCountAllLayouts
uint profilingValuesPerLayout
uint timePerProcess (0)
uint timePerProcessExpected (0)
uint averageCycles (0)
uint instCycles (0)
uint peakCycles (0)
uint overflow_cnt (0)
............
uint timePerProcess (N-1)
uint timePerProcessExpected (N-1)
uint averageCycles (N-1)
uint instCycles (N-1)
uint peakCycles (N-1)
uint overflow_cnt (N-1)
uint CRC

Reply Format (Layout offset > 0 (I))

Message Length = 3+numLayoutsXprofilingValuesPerLayout 0
int error status
uint timePerProcess (I)
uint timePerProcessExpected (I)
uint averageCycles (I)
uint instCycles (I)
uint peakCycles (I)
uint overflow_cnt (I)
............
uint timePerProcess (N-1)
uint timePerProcessExpected (N-1)
uint averageCycles (N-1)
uint instCycles (N-1)
uint peakCycles (N-1)
uint overflow_cnt (N-1)
uint CRC

PFID_GetAllMatchingModules (ID = 134)

Returns the module information of all modules in the loaded layout that have a keyType that matches the keyValue. If all matching modules in the layout fit in the replyBuffer, then the value of endIndex will be 0 and this PFID does not need to be called again. If endIndex is > 0, then call this PFID again with the startIndex equal to the previously returned endIndex. To return the correct modules, startIndex must be 0 the first time this PFID is called for a keyValue.

The following values are supported for keyType: KEY_CLASSID (0) - find all modules in layout that match keyValue=classID

The reply packet will return 0 (E_SUCCESS) if the packet processing is successful, and a negative number if there is an error. See Errors.h for details on error codes. E_NOT_OBJECT means that no layout was loaded when this PFID was received by the target instanceId.

This will only return the matching modules from the specified instanceId.

Packet Format

Message Length = 5 instanceId PFID_GetAllMatchingModules
keyType (uint)
keyValue (int)
startIndex (uint)
crc (uint)

Reply Format

Message Length = numModulesFound + 5 0
errorStatus (int)

| numModulesFound (uint) | | endIndex (uint) || | moduleObjectID[0] (uint) | | .... | moduleObjectID[numModulesFound - 1] | | CRC (uint) ||

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: 

ch = (unsigned char)(0x80 |  s_msg_word        & 0x7F);
ch = (unsigned char)(0x80 | (s_msg_word >>  7) & 0x7F);
ch = (unsigned char)(0x80 | (s_msg_word >> 14) & 0x7F);
ch = (unsigned char)(0x80 | (s_msg_word >> 21) & 0x7F);
ch = (unsigned char)(0x80 | (s_msg_word >> 28) & 0x7F);

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: 

Start Byte          0x02 
Sequence Byte       0x30 to 0x39    (ASCII “0” to “9”)
Message Bytes       0x80 to 0xFF.  5 bytes at a time. 
Stop Byte           0x03

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:

GetProfileValues Message Example

Which translates into the 32-bit words: 

0x0002002b
0x0002002b  (CRC is the same for 1 word payloads)

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

0x0002002b -> 0xAB 0x80 0x88 0x80 0x80
0x0002002b -> 0xAB 0x80 0x88 0x80 0x80

Adding the remaining protocol bytes, the sequence sent is: 

0x02    (start byte)
0x3X    (sequence)
0xAB 0x80 0x88 0x80 0x80 (payload)
0xAB 0x80 0x88 0x80 0x80 (CRC)
0x03

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: 

[TimeOut]
SingleCharTimeout=200
TotalTimeoutTimeout=1000
RS232RetryCount=3

(All times are in milliseconds)

SPI Protocol

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

  1. The 32-bit synchronization word 0xDEADBEEF is sent before each message.
  2. The 4 bytes within each 32-bit word are swapped. For example, 0x12345678 becomes 0x78563412.

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

GetProfileValues Message Example

This translates into the 32-bit words: 

0x0002002b
0x0002002b  (CRC is the same for 1 word payloads)

The overall message sent is: 

0xDEADBEEF  ->  0xEFBEADDE
0x0002002B      ->  0x2B000200
0x0002002B      ->  0x2B000200

To communicate to the server that the target is ready to receive a message, the entire SPI output buffer must be set to the "ready" word 0x3333AAAA. After a message is received by the target processor and the message is being processed, the entire 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 0xDEADBEEF followed by the complete message. Once the entire message has been sent, the SPI output buffer must be set to the "ready" word again. See the diagram below for how to implement a SPI based tuning interface:

SPI State Diagram

If the host processor continues to read beyond the end of a reply from the target, then the target will return 0xFFFFFFFF or the last transmitted word, which could be the "ready" word depending on the SPI peripheral configuration.

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 Protocol

Ethernet TCP/IP Protocol

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

See LinuxApp.c for an example application that integrates a TCP/IP tuning interface.

Generated by doxygen 1.9.4