DA8xx Alpha Codes

Introduction

The PA system utilizes the PA messaging (PA/M) protocol for communication between different parts of the system. The communication is achieved by means of word-based units, where each word is a 16-bit unsigned integer of the form 0xhhhh, and is called an alpha code word. A single operation, such as writing a value to a specific register, usually involves sequence of two or more of these words. An alpha code word sequence, also referred to simply as alpha code, is represented symbolically by assigning a name that clearly describes the operation performed by the sequence.

This chapter introduces the basics of selecting alpha code symbol names and creating the corresponding alpha code words for an ASP. It is only meant to serve as an introduction and utilizes the Equalizer ASP (EQU) as an example.

Status structure

Each ASP is required to have a status structure that contains the elements that can be read or modified while it is running. The general form of this status structure is:

typedef volatile struct ALG_Status {
   Int size;             /* This value must always be here, and must be set to the 
                            total size of this structure in 8-bit bytes, as the 
                            sizeof() operator would do. */
    /* Implementation-specific structure elements.  */
} ALG_Status;

where ALG is a 2- or 3-character name that you give to your algorithm. Such a status structure conceptually serves as a memory-mapped register bank. The operation of the ASP depends on the contents of each of these registers. While the ASP is running, the PA/M protocol accesses these registers using alpha code sequences.

Example: Status structure for Equalizer example ASP
The source files of Equalizer (EQU) example are provided in the folder t:\pa\asp\aspdk\equ. The status structure is given in the file iequ.h and is reproduced below:

/*
*  ======== IEQU_Status ========
*  This Status structure defines the parameters that can be changed or read
*  during real-time operation of the algorithm.  This structure is actually
*  instantiated and initialized in iequ.c.
*/
typedef struct IEQU_Status {
   Int size;             /* This value must always be here, and must be set to the
                            total size of this structure in 8-bit bytes, as the
                            sizeof() operator would do. */
   XDAS_Int8 mode;
   XDAS_Int8 reset;
   XDAS_Int16 unused;
   XDAS_Int8 bandGain[10];
} IEQU_Status;

Communication with the EQU algorithm involves reading from or writing to the mode, reset and bandGain registers. Each of these are control registers as their values can be altered with write operations. The read and write operations are accomplished by means of alpha codes.

Alpha Code Symbol Names and Alpha Code Sequences

The status structure described in the previous section contains the elements that will be accessed by PA/M. You need to specify the alpha code symbol names and the corresponding alpha code sequences that will be used by this communication mechanism. The entire process consists of five steps:

1. Select a 2 or 3 character name for your ASP algorithm.
2. Define a status structure for your ASP.
3. Select alpha code symbol names.
4. Determine the alpha code sequence corresponding to each of the alpha code symbol names.
5. Create a header file containing definitions that map each of the alpha code symbol names.

Step1 :Select ASP name

Select a 2 or 3 character name for your ASP algorithm. This name must be unique to your ASP. To determine the names that already exist as part of the SDK that you are using, see the master alpha code symbol file, for example: P:\alpha\pa_i14_evmda830_io_a.hdM. This header file contains a number of #include statements, each corresponding to a unique header file for an ASP that already exists as part of the SDK. The names of the files being included will provide a good indication of the algorithm names already in use.

Step2 :Define a Status Structure for the ASP

The status structure contains the elements to be accessed while communicating with the ASP. In addition to defining the status structure, make a note of the size(in bytes) of each element in the status structure and from this information, calculate the corresponding offset (in bytes). These values are needed when selecting the alpha code type (explained later in this chapter) and determining the code words assigned to each alpha code symbol name.

Example: Size and Offset of elements in Status Structure
For the EQU, the status structure is IEQU_Status and the specific elements to be accessed are mode, reset and bandgain. The size and offsets of these elements are shown in Table1 (Size and Offset of Elements in the IEQU_Status Structure). The offset of any element is given by the cumulative sum of the size of all the elements preceding it.

Table 1 Size and Offset of elements in the IEQU_Status structure

Element	Register size(bits)	Register size(bytes)	Offset(bytes)
Size	32	4	0
Mode	8	1	4
Reset	8	1	5
Unused	16	2	6
bandGain[10]	80	10	8

Step3: Select Alpha Code Symbol Names

A standard nomenclature has been developed for selecting the names of the alpha code symbols. All alpha code symbol names must adhere to one of the following seven forms:

1. readALGRegisterName
2. writeALGRegisterName
3. writeALGRegisterNameValue
4. writeALGRegisterName(N)
5. wroteALGRegisterName
6. wroteALGRegisterNameValue

where the constructs like ALG, RegisterName, and Value should be replaced with the algorithm name (e.g. EQU), the name of an element of the ALG_Status structure and an appropriate value respectively. Alpha code symbol names that begin with the word wrote serve as responses to read operations. For these read operations, write symbol names do not exist. The next step describes how to determine the bit patterns that correspond to the alpha code word sequences to be assigned to the alpha code symbol names selected in this step.

Example: Alpha Code Symbol Names
For the EQU ASP, the ALG name is EQU, and the RegisterName is mode, reset and bandGain. Accordingly, the following alpha code symbol names have been chosen:

1. readEQUMode - to read the value in the mode register
2. writeEQUModeDisable - to write the value 0 in the mode register
3. writeEQUModeEnable - to write the value 1 in the mode register
4. readEQUSpare - to read the value in the spare (unused) register.
5. writeEQUSpare(N)- to write the value N in the spare register
6. writeEQUBandGain(N0,N1,N2,N3,N4,N5,N6,N7,N8,N9)- to write the values No, N1 etc in each bandGain register respectively.

Step 4: Assign Alpha commnads to the Alpha Code Symbol Names.

Communication using alpha codes is achieved by means of word-based units where each word is a 16-bit unsigned integer of the form 0xhhhh. The alpha codes corresponding to a multi-word sequence are transmitted (or received) with the least-significant word first. This is an important point to keep in mind when assigning the 16-bit code words to the alpha code symbol names.

Example: Alpha Code Word Sequences for EQU Example
The alpha code word sequences for the EQU example are defined in the file: t:\pa\asp\aspdk\equ\equ_a.h as

#define readEQUMode             0xf200+CUS_BETA_EQU,0x0400
#define writeEQUModeDisable     0xfa00+CUS_BETA_EQU,0x0400
#define writeEQUModeEnable      0xfa00+CUS_BETA_EQU,0x0401
#define readEQUReset            0xf200+CUS_BETA_EQU,0x0500
#define writeEQUResetDisable    0xfa00+CUS_BETA_EQU,0x0500
#define writeEQUResetEnable     0xfa00+CUS_BETA_EQU,0x0501
#define readEQUSpare            0xf300+CUS_BETA_EQU,0x0600
#define writeEQUSpare(N)        0xfb00+CUS_BETA_EQU,0x0600+((N)&0xff)
#define readEQUStatus           0xf508,0x0000+CUS_BETA_EQU
#define readEQUControl          readEQUStatus
#define readEQUBandGain         0xf600+CUS_BETA_EQU,0x080a
#define writeEQUBandGain(N0,N1,N2,N3,N4,N5,N6,N7,N8,N9) \
        0xfe00+CUS_BETA_EQU,0x080a,TWOUP(N0,N1),TWOUP(N2,N3),TWOUP(N4,N5),TWOUP(N6,N7),TWOUP(N8,N9)

Consider the definition for readEQUMode: #define readEQUMode 0xf200+CUS_BETA_EQU, 0x0400. The sequence corresponding to the symbol name readEQUMode consists of two words; 0xf200 and 0x0400. The first word transmitted (received) is the least-significant word, 0xf200+CUS_BETA_EQU. This is then followed by 0x0400.

An alpha code sequence may consist of two or more words. The operation to be performed by the sequence is determined by bit patterns for each of the words that make up the sequence. The description of the bit fields of the least-significant word is common to all sequences. These bit fields are shown in Figure 1 (Bit Fields in the Least-Significant Word of an Alpha Code Word Sequence) and described in Table 2 (Description of Bit Fields in the Least-Significant Word of an Alpha Code Word Sequence).

• The Legacy field, bits 14 and 15, should be set to 11b.
• The Series field, bits 12 and 13, should be set to 11b.
• The R/W (Read / Write) field, bit 11, is quite straight forward. Set this field to 0 for a read operation, and 1 for a write operation.
• The Type field, bits 8 to 10, determines the alpha code type. In this section we will focus on four types which are types 2, 3, 5 and 6.

Type 2 (b10:b8 = 010) Alpha Code

The Table 4(Description of Type 2 Alpha Codes) shows the number of words required in the alpha code sequence and also the description for each of these words for Type 2 alpha codes. A Type 2 alpha code has bits 10:8 of word 0 set to 010b which indicates the length (=2) of this alpha code.
Table 4 Description of Type 2 Alpha Codes

Type	Word	Byte	Description
2	0	MSB	As shown in Figure 1 and Table 2
-	-	LSB	Beta Unit Number as defined in cusbeta.h
-	1	MSB	Offset of register to be read or written
-	-	LSB	Data for write operation,unused for read operation

For all types of alpha codes, the 8 bits in the MSB of word 0 always correspond to the Legacy, Series, Read/Write and Type fields as shown in Figure 1 and Table 2. For a Type 2 alpha code, the LSB of word 0 corresponds to the Beta Unit number. The Beta Unit number is a unique identifier for an ASP. For example, the Beta unit number for the EQU ASP is 0x00, and is defined in the file cusbeta.h as follows:

#define CUS_BETA_EQU  0x00

The file cusbeta.h should be modified accordingly to specify the Beta unit number that you want to assign to your ASP. Type 2 alpha codes are used to read from or write to 8-bit registers. The offset of the register to be accessed corresponds to the MSB of word 1. For a write operation, the 8-bit data value is given in the the LSB of word 1.

Example: EQU example - readEQUMode
The alpha code symbol name readEQUMode is used to read the contents of the 8-bit mode register. It falls into the category of a Type 2 alpha code and requires a total of two words. Thus word 0 of the alpha code sequence for readEQUMode is equal to 0xf200 and is shown in Figure 1 (Word 0 of the Alpha Code Word Sequence for readEQUMode).
The MSB corresponds to the Legacy, Series, Read/Write and Type fields, whereas the LSB(=00h) is the Beta unit number as defined in the file cusbeta.h. The word 1 of the alpha code is equal to 0x0400 and is shown in Figure 2(Word 1 of the Alpha Code Word sequence for readEQUMode). The MSB(=04) is the offset of the mode register as obtained from Table 1. Since the LSB is not used for a read operation, it is assigned the value 0x00.

Type 3 (b10:b8 = 011) Alpha Code

The Table 5 (Description of Type 3 Alpha Codes) shows the number of words required in the alpha code sequence and also the description for each of these words for Type 3 alpha codes. A Type 3 alpha code has bits 10:8 of word 0 set to 011b which indicates the length (=3) of this alpha code.
Table 5 Description of Type 3 Alpha Codes

Type	Word	Byte	Description
3	0	MSB	As shown in Figure 1 and Table 2
-	-	LSB	Beta Unit Number as defined in cusbeta.h
-	1	All	Offset of register to be read or written
-	2	All	Data for write operation,unused for read operation

Similar to Type 2 alpha codes, the LSB of word 0 for Type 3 alpha codes also corresponds to the Beta unit number. The offset of the register to be accessed corresponds to word 1. Type 3 alpha codes are used to read from or write to, 16-bit registers. The 16-bit data is specified as word 2 for a write operation. The word 2 is not used for a read operation.

Example: EQU Example- writeEQUSpare
The alpha code writeEQUSpare is used to write to the 16-bit unused register. It falls into the category of a Type 3 alpha code and requires a total of 3 words. As specified in Table 2 (Description of Bit Fields in the Least-Significant Word of an Alpha Code Word Sequence), word 0 of the alpha code word sequence for writeEQUSpare is equal to 0xfb00 and is shown in Figure 4. The MSB corresponds to the Legacy, Series, Read/Write, and Type fields, whereas the LSB is the Beta unit number.

The word 1 of the alpha code contains the offset address, and is equal to 0x0006. The offset address was calculated in Table 1. The word 2 of the alpha code is the 16-bit data to be written. Thus word 2 is equal to 0xhhhh where 0xhhhh corresponds to the hexadecimal representation of the data.

Type 5 (b10:b8 = 101) Alpha Code

The Table 6(Description of Type 5 Alpha Codes) shows the number of words required in the alpha code sequence and also the description for each of these words for Type 5 alpha codes. A Type 5 alpha code has bits 10:8 of word 0 set to 101b. The length of a Type 5 alpha code could be anywhere from 2 to N words.

Table 6 Description of Type 5 Alpha Codes

Type	Word	Byte	Description
5	0	MSB	As shown in Figure 1 and Table 2
-	-	LSB	Extended alpha code filed
-	1-N	All	Various

For a Type 5 alpha code, the LSB of word 0 does not contain the Beta unit number. Instead, it indicates a sub-type. A listing of all possible extended alpha code sub-types is given in Table 12 of the Performance Audio Messaging Application Protocol Application Report. In this section, the discussion is limited to sub-type 8.

Example 6: EQU Example - readEQUStatus
The alpha code word corresponding to readEQUStatus is of Type 5-8. This command is used to read the contents of the entire IEQU_Status structure. The MSB of word 0 of the alpha code is as specified in Table 2(Description of Bit Fields in the Least-Significant Word of an Alpha Code Word Sequence). The LSB of word 0 specifies the sub-type, i.e. 8. Thus word 0 is equal to 0xf508 and is shown in Figure 5 (Word 0 of the Alpha Code Word Sequence for readEQUStatus).

The word 1 of the alpha code is the Beta unit number and is equal to 0x0000. This particular alpha code word sequence of Type 5-8 requires a total of two words.

Type 6 (b10:b8 = 110) Alpha Code

The Table 7(Description of Type 6 Alpha Codes) shows the number of words required in the alpha code sequence, and also the description for each of these words, for Type 6 alpha codes. A Type 6 alpha code has bits 10:8 of word 0 set to 101b. The length of a Type 6 alpha code could be anywhere from 2 to N words. Table 7 Description of Type 6 Alpha Codes

Type	Word	Byte	Description
6	0	MSB	As shown in Figure 1 and Table 2
-	-	LSB	Beta Unit Number as defined in cusbeta.h
-	1	All	Offset of register to be read or written
-	2	All	Offset for how many variables to be read/written
-	2-N	various	value to be wriiten, unused for read

Data is read from the Beta Unit at the base address indicated by the 8-bit beta field and the 8-bit offset in bytes given by the gamma field. The number of bytes read is given by the 8-bit kappa field. It may also be referred to as a variable-length read. The return value is an alpha code type 6 write with the appropriate length and data. The length of an alpha code type 6 read is 2 words.

Data is written to the Beta Unit at the base address indicated by the 8-bit beta field and the 8-bit offset in bytes given by the gamma field. The number of bytes written is given by the 8-bit kappa field. It may also be referred to as a variable-length write. The length of an alpha code type 6 write is 2+(k+1)/2 words. The return value is null.

Step 5: Create a header file alg_a.h

The final step required is to create a header file alg_a.h and place it in the folder T:\pa\asp\alg\alpha\ where alg is the name for your algorithm. The header file contains definitions that map each of the alpha code symbol names from step-3 with the corresponding alpha code sequence from step-4. The header file will contain one or more definitions of the form

#define  readALGRegisterName 0xhhhh …
#define writeALGRegisterName 0xhhhh …
#define writeALGRegisterNameValue  0xhhhh … 
#define writeALGRegisterName(N)  0xhhhh …
#define wroteALGRegisterName  0xhhhh …
#define wroteALGRegisterNameValue  0xhhhh …

where

• 0xhhhh specifies the binary values, represented as a 16-bit word, assigned to the alpha code symbol name. The symbol names were determined in step 3, and the corresponding 16-bit values were calculated in step 4.
• the ellipses, …, specify that more than one 16-bit word may be assigned to the alpha code symbol name. This is usually the case.

For eg: the alpha header file for equ example has these defined as described in Example 5 like:

#define readEQUMode 0xf200+CUS_BETA_EQU,0x0400
#define writeEQUModeDisable 0xfa00+CUS_BETA_EQU,0x0400
...