DA8xx ASP Programming Interface

Introduction

This page descibes the PA/F Programming Interface for ASP algorithms.

Performance Audio Framework (PA/F) Overview

The Performance Audio Framework contains all the components needed to form a complete digital audio processing solution. The major components of an example audio stream, as implemented using the PA/F, are shown in Figure 1-1. PA/F is described in detail in PA User's Guide.This section briefly describes the ASP component in PA/F.

Decode Component

This component is responsible for decoding the incoming audio stream which could be encoded as PCM, Dolby Digital, DTS etc.

Encode Component

The PA/F requires Decode and Encode Components, even if there is no “decoding” or “encoding” taking place. In other words, if the incoming bit stream is not encoded, there is no need for a decoding function, but there must still be a Decode Component in the system, a “PCM Decoder”. The same is true of the Encode Component. Usually, it will be a “PCM Encoder”, which really isn’t encoding to a compressed bit-stream format but must still be present.

ASP Component

This component corresponds roughly to what might be called "post processing" in other systems that are designed for audio decoding only. In PA/F, there can be more than one ASP component in a processing chain. The most common manner in which customer-specific code is inserted into the PA/F is by creating one or more of these ASP Components.

ASP algorithms may be classified depending on the kind of processing they perform. For example, the custom surround (SUR) algorithm example in this package is a surround processing ASP algorithm. It is important to remember that

• All surround processing ASPs are grouped together in the ASP chain.
• Custom surround processing ASPs, such as SUR are first.
• Standard surround processing ASPs, such as PL2x, come next.

This grouping of ASP algorithms is shown in Figure 1-2 (Arrangement of ASP Algorithms in the ASP Chain). When an ASP algorithm is able to convert an input audio stream into the desired output audio stream, it should prevent the operation of other ASP Algorithms as appropriate. For example, within the group of surround processing ASPs, only one of them may process the audio data. To preclude the operation of other surround processing ASPs further down the chain, the recommended method is to set the channel configuration accordingly to prevent surround processing by ASPs further down the chain. Even though one may be tempted to obtain a similar result by actually disabling some of the other ASP Algorithms using alpha codes (described later), this method is discouraged.

Programming Interface

The PA/F Algorithms extend the standard XDAIS Algorithm interface, in a standard, fully–compliant way, to provide the required functionality for digital audio processing as shown in Figure 1-3.

The ASP Programming Interface is established with implementation of certain functions that operate on the control and audio data and also allow for incorporation of the ASP algorithm into the Framework. These functions are:

• ALG_VEN_apply( )

Processes a frame of audio data. This function also updates the control data needed to manage the processing chain. This should be implemented in ALG_VEN_iALG.c.

• ALG_VEN_reset( )

Initialises the control data associated with the ASP algorithm. This should be implemented in ALG_VEN_iALG.c.

• ALG_VEN_control( )

Enables the Framework to “connect” the alpha code messaging mechanism to the ASP Algorithm. This function is typically implemented in the file ALG_VEN_ialg.c.

Description of ALG_VEN_apply()

What parameters are passed to it?

The _apply() function for all ASP Algorithms must have the below interface:

Int ALG_VENDOR_apply(IALG_Handle handle, PAF_AudioFrame *pAudioFrame)

Where:
IALG_Handle handle -> ASP Algorithm handle
PAF_AudioFrame *pAudioFrame -> Pointer to the AudioFrame data structure

The ASP algorithm handle contains the pointer to the algorithm status structure. The status structure of the ASP algorithm provides the interface to the user (e.g., a microcontroller). The status structure works like a memory-mapped register bank. The user can read/write to this structure to pass control information to the ASP Algorithm or to read status information back from the ASP algorithm.

The AudioFrame data structure contains the audio data that needs to be processed and control and status information that the ASP algorithms should refer to understand how the processing needs to be applied. If the ASP algorithm modifies the audio samples within the AudioFrame data structure, it may be required to modify some of the control information in the AudioFrame data structure. This enables other downstream ASP algorithms to understand the contents of the AudioFrame data structure. For example, a surround processing ASP algorithm, if it generates more audio channels than existed in the audio stream, may need to modify the ChannelConfigurationStream quantity within the AudioFrame data structure.

The AudioFrame data structure is defined in the file T:\pa\f\include\paftyp.h as:

typedef struct PAF_AudioFrame {
   PAF_AudioFunctions *fxns;
   XDAS_Int8 mode;
   XDAS_Int8 sampleDecode;
   XDAS_Int8 sampleRate;
   XDAS_Int8 unused[3];
   XDAS_Int16 sampleCount;  /* valid N */
   PAF_AudioFrameData data; /* data[M][N] */
   PAF_ChannelConfiguration channelConfigurationRequest;
   PAF_ChannelConfiguration channelConfigurationStream; 
   /* valid M*/
   PAF_ChannelConfigurationMaskTable
     *pChannelConfigurationMaskTable;
   PAF_SampleProcess sampleProcess[PAF_SAMPLEPROCESS_N];
   struct PAF_AudioFrame *root;
} PAF_AudioFrame;

The audio data is stored in AudioFrameData (indicated in italics in above structure) is defined below.

// PAF_AudioFrameData is a fixed structure which defines the
// possible data-carrying capacity of the audio frame.
typedef struct PAF_AudioFrameData {
   XDAS_Int16 nChannels;  /* max M */
   XDAS_Int16 nSamples;  /* max N */
   PAF_AudioData **sample;  /* sample[M][N] */
   PAF_AudioSize *samsiz;  /* samsiz[M] */
} PAF_AudioFrameData;

The audio data is stored in the AudioFrameData as non-interleaved PCM. That is, the data for the M channels are stored sequentially, one channel after the other. The data for any individual channel is referenced via a pointer such that sample[M] is a pointer to a vector of PCM data for channel M. paf-hd.doc shows in detail the correspondence between the channels and the elements in this array of pointers to the sample data. A custom ASP algorithm may process the available data present on any of these channels. The information extracted from AudioFrame by the _apply() function includes:

• The number of samples in each channel
• Available channels in the stream
• The audio data from available channels
• Audio sample-size (described in Audio sample-size)

This is achieved by appropriately de-referencing the pointer *pAudioFrame:

sampleCount = pAudioFrame->sampleCount;
     // Number of samples in the audio frame (in each channel)
left = pAudioFrame->data.sample[PAF_LEFT];
    // pointer to left channel audio sample buffer
rght = pAudioFrame->data.sample[PAF_RGHT];
    // pointer to right channel audio sample buffer
cntr = pAudioFrame->data.sample[PAF_CNTR];
   // pointer to center channel audio sample buffer
.
.
.
samsiz = pAudioFrame->data.samsiz; // Audio size

Finally after processing the audio data, the audio sample-size, channel configuration and other fields are updated accordingly. Please see What steps are required to properly implement an Apply Function?

When is it called?

The PA Framework calls the _apply() function for each ASP algorithm in the ASP chain. The ASP algorithms are called after the decoding operation. The generated audio data after all the ASP _apply() functions have completed the processing is passed to the encoder.

What is it supposed to do?

The ALG_VEN_apply() function is invoked by the PA/F to pass status, control, and audio data to the ASP algorithm. The algorithm uses the status information to understand the processing that needs to be applied. Most of the ASP algorithms use the status information to understand how they should modify the audio data. But ASP algorithms can be developed that may use the status information to perform certain other actions and not necessarily modify the audio data, but such occurrences are rare and not discussed here.

One of the first checks that an ASP algorithm does is to decide whether or not to process the incoming signal. This test is performed in the ALG_VEN_apply() function and consists of checking one or more of the following:

• mode control register: whether the mode is enabled or not!
• channel configuration: whether it's allowed/required to operate or not!
• other register(s) as appropriate

After processing, the algorithm must ensure that both the channel configuration and the audio size are updated accordingly.

What steps are required to properly implement an Apply Function?

The following are the important steps that need to be followed by all ASP Algorithms.

• Proper usage of the mode control register.

The first element of the algorithm's status structure must be mode. The mode variable is used to enable or disable the processing of the algorithm. The algorithm must check the mode variable as one of the first steps in the _apply() function. If the mode is disabled, the algorithm should not modify the audio samples or any quantities in the AudioFrame structure.

• Proper testing of the sample rate.

If the processing within the ASP algorithm is dependent on the sample rate of the audio stream, the algorithm must read and react to the current sample rate from the AudioFrame. If the current sample rate is different than the previous sample rate, the algorithm may have to make a configuration change or reset certain processing states. The algorithm may choose to have a separate function to perform this test and sample-rate dependent operation. Such a function can be called by the _apply() function as well as the _reset() function, if necessary.

• Check for and react to the Audio Stream’s Channel Configuration information.

The ASP algorithms must check the channelConfigurationStream register within the AudioFrame to understand the audio channels that are presented to it.

• Proper setting of the Audio sample-size register (samsiz).

The Audio sample-size is an indication of the magnitude of the audio sample data on each channel. The sasiz variable is used by the ASP algorithm to indicate the magnitude of the audio data on each channel after the processing is completed. Details on samsiz usage is available in Audio sample-size

• Updation of sample-process register (PAFProcess).

The sample-process register contains a multi-byte bit mask of values of the form (1<<PAF_PROCESS_X) that indicates the algorithms that have operated on the AudioFrame data. It is a read/write quantity, and it is the responsibility of an algorithm to update this register if appropriate. Please refer to T:/pa/f/include/pafsp.h to understand how the various bits of this register are defined. Custom ASP algorithms may also use this register to inform whether the ASP operated or not.

• Proper setting of sample-rate.

The ASP algorithms that change the sample rate must update the sampleRate information in the AudioFrame. If the algorithm performs downsampling or upsampling, then the sampleCount variable will also need to be modified.

• Proper setting of Channel Configuration register (channelConfigurationStream).

If the ASP algorithm processing changes the channel configuration, the information must be updated in the channelConfigurationStream register within the AudioFrame structure. For example, Surround Processing ASP algorithms must check the input channel configuration by checking channelConfigurationStream towards the begining of the processing. It also must check the requested channel configuration by checking the channelConfigurationRequest register in the AudioFrame structure to determine if surround processing is required. If the processing is required and performed, the algorithm must modify the channelConfigurationStream variable to indicate the resulting channel configuration of the stream.

Description of ALG_VEN_reset( )

What parameters are passed to it?

The _reset() function for all ASP algorithms must have the below interface:

Int ALG_VENDOR_reset(IALG_Handle handle, PAF_AudioFrame *pAudioFrame)

Where:
IALG_Handle handle -> ASP Algorithm handle
PAF_AudioFrame *pAudioFrame -> Pointer to the AudioFrame structure.

When is it called?

The ALG_VEN_reset() function is called before the decode processing is started. If the decode processing is stopped and restarted (e.g., when there is change in the input bitstream or the alpha code writeDECCommandRestart is issued) the ALG_VEN_reset() function of all the ASP algorithms in the ASP chain is called before the decode processing restarts.

What is it supposed to do?

The ALG_VEN_reset() function is invoked by the PA/F to pass status and control data to the ASP chain. The algorithms should use the control data to understand the initialization required to be done before the _apply() function is called. For example, based on the sample-rate information in the AudioFrame structure, different coefficients may need to be loaded for the filters. Also, clearing of state variables used in the ASP algorithm processing may need to be performed.

The complexity of having a separate function that processes control data without sample data might seem high, but has certain advantages. The main benefit of having this separate function is realized by being able to perform MIPS-intensive processing outside of the normal timing constraints that are imposed when sample data is being processed. For example, large delay buffers can be cleared or certain other computations may be performed as part of the ALG_VEN_reset() function. If performed in the ALG_VEN_apply() function, such operations would negatively impact the performance of the real-time processing on the audio data.

The ASP algorithms are passed control and status information as part of ALG_VEN_reset() function invocation. The ASP algorithms may modify some of the control and status information. This provides a method by which ASP can pass back information to the framework.

Description of ALG_VEN_control( )

The ALG_VEN_control function allows the framework to connect the Alpha Code messaging mechanism to the algorithm. The control function must always provide an algorithm-specific ALG_GETSTATUSADDRESS1 command that returns the address of the status register inside the Algorithm. This function has common functionality across all ASPs and is implemented in COM_TII_control function in com_asp.lib library available in SDK. Individual ASPs can use this function by defining:

#define ALG_VEN_control COM_TII_control