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:

  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

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

AWE Core Tuning Command Syntax and Protocol (Archived)