XDM FAQ

General

Where can I download the XDM interface spec?

XDM is distributed with the XDAIS product, in the ti.xdais.dm package. The XDAIS product can be downloaded here.

What's with the XDM versioning?

First, this is often asked by codec vendors and applications when wondering how to document which version of XDM they implement and/or support. It is strongly recommended that, rather than a marketing version, users refer to specific named interfaces - e.g. IVIDDEC, IVIDDEC1, and IVIDDEC2. Codec data sheets and docs should state the interface(s) they implement (e.g. IVIDDEC2, IDMA3, IRES, etc.), not an unspecific marketing version of XDM they implement.

That said, here's the breakdown of what interfaces were introduced in which releases of XDM:

• XDM 0.9 - I{VID|IMG|SPH|AUD}{ENC|DEC}
• XDM 1.0 - I{VID|IMG|SPH|AUD}{ENC|DEC}1
• XDM 1.1 - IVID{ANALYTICS|TRANSCODE}
• XDM 1.2 - IVIDDEC2

How can I check that my algorithm is XDM compliant?

First, ensure your algorithm is XDAIS compliant using the QualiTI compliancy tool.

There is, unfortunately, no similar test for XDM compliance, as it requires runtime execution of the codec, which the QualiTI tool does not [yet] support. The closest thing we have is to integrate the codec and your test app into the Codec Engine environment and enable the Codec Engine CE_CHECK feature.

Any violations found (e.g. writing to read-only struct fields) will be emitted in the trace logs.

Note, if your test system is a dual-core device (e.g DM6446 or DM6467), you should also enable checking in the Server executable. You can do this by adding the following line to the DSP-side config script:

<syntaxhighlight lang="javascript"> xdc.useModule('ti.sdo.ce.Settings').checked = true; </syntaxhighlight>

What is the *_Status->data buffer used for in XDM 1.0?

The I*_Status.data field is a feature in newer XDM interfaces that is used to support the XDM_GETVERSION command, and to enable the ability to pass arbitrary buffers of data between the codec and application in control() calls.

In addition to supporting the general XDM_GETVERSION command, concrete interfaces can utilize this buffer for interface-specific purposes. For example, in the image encoders interface, IIMGENC1, IIMGENC1_Status.data is used to insert a comment in the encoded jpeg stream.

This buffer is defined to be both an input and an output buffer - and frameworks should manage it as such (e.g. regarding cache).

The size of the *_Status->data buffer is defined in the bufSize field of the buffer descriptor.

How do I decode extendedError?

Many XDM output structures include a .extendedError field. This field is a 32 bit field carved into several bit fields.

• Bits 31-16 are reserved.
• Bits 15-8 are defined by XDM.
• Bits 7-0 are codec and implementation specific. The codec users guide should document the meaning of these bits, if they're used.

Bits 15-8 are documented in the XDM_ErrorBit enum - see that documentation for details:

• Bit 15 - XDM_FATALERROR
• Bit 14 - XDM_UNSUPPORTEDPARAM
• Bit 13 - XDM_UNSUPPORTEDINPUT
• Bit 12 - XDM_CORRUPTEDHEADER
• Bit 11 - XDM_CORRUPTEDDATA
• Bit 10 - XDM_INSUFFICIENTDATA
• Bit 9 - XDM_APPLIEDCONCEALMENT
• Bit 8 - XDM_PARAMSCHANGE

Is it Ok to extend inArgs, outArgs of an XDM interface?

Not really. See the Extending data structures in XDM article for complete details on how this results in custom application code.

This article also gives more details on XDM API usage.

How do I know which XDM interface version this codec implements?

See this wiki topic.

Speech

How many bytes are generated by an XDM 1.0 Speech Encoder?

Lets look at this from the perspective of knowing the input buffer size required by the decoder. DMAI - the DaVinci Multimedia Application Interface API has the following code in Sdec1.c

<syntaxhighlight lang="c"> Int32 Sdec1_getInBufSize(Sdec1_Handle hSd) {

   Int32 size = 0;

   assert(hSd);

   size = hSd->minInBufSize[0];

   return (size);

} </syntaxhighlight>

This maps to the xdm.h XDM_AlgBufInfo structure. For a real speech algorithm like G.729AB the input and output sizes are part of that algorithm's ITU or ETSI standard. The G729AB encoder produces 10 bytes for every 80 input samples (160 bytes). Hence the minInBufSize[0] will be 10. This is nice because we have no hardcoded magic numbers in the application.

The only corner case are the PCM codecs - for example G.711 can operate on sample by sample. Processing on single samples is not smart on a DSP - we need to buffer up samples to minimize the impact of function call overheads etc. Hence, speech_decode1, an example application in the DMAI distribution does the following: -

<syntaxhighlight lang="c"> if (strcmp(args->codecName, "g711dec") == 0) {

   lAttrs.readSize = BUFSIZE;

} else { // G729ABDEC, G723DEC all have 'sensible' minInBufSize

   lAttrs.readSize = Sdec1_getInBufSize(hSd);

} </syntaxhighlight>

BUFSIZE is 80 in this application but it could be any value.

We get the initial minInBufSize data via an XDM_GETBUFINFO call. For example DMAI Sdec1.c does: -

<syntaxhighlight lang="c"> /* Get buffer information from video decoder */ status = SPHDEC1_control(hDecode, XDM_GETBUFINFO, dynParams,

                        &decStatus);

if (status != SPHDEC1_EOK) {

   Dmai_err0("XDM_GETBUFINFO control failed\n");
   cleanup(hSd);
   return NULL;

}

Dmai_dbg2("Speech decoder requires min buffer sizes in %lu and out %lu\n",

         decStatus.bufInfo.minInBufSize[0],
         decStatus.bufInfo.minOutBufSize[0]);

memcpy(hSd->minInBufSize,

      decStatus.bufInfo.minInBufSize, sizeof(hSd->minInBufSize));

</syntaxhighlight>

How do we communication bit-rate to speech decoders?

In XDM 1.0 a new bitRate parameter was added for both Encode & Decode. This is documented in xdais_n_mm\packages\ti\xdais\dm\docs\xdm1_differences.pdf. bitRate is used by GSM-AMR, WB-AMR, G.726 and G.723.

For example the G.726 codec can operate at 16/24/32/40 kbps.

The good thing is that the extensions for bitrate are in a separate file e.g. in G726 it's in ispeech1_g726.h. Furthermore, its only enumerations in this header file e.g.

<syntaxhighlight lang="c"> typedef enum {

   ISPEECH1_G726_BITRATE_16  = 0,     /**<  16  kbps */
   ISPEECH1_G726_BITRATE_24  = 1,     /**<  24  kbps */
   ISPEECH1_G726_BITRATE_32  = 2,     /**<  32  kbps */
   ISPEECH1_G726_BITRATE_40  = 3,     /**<  40  kbps */

   /** Default setting. */
   ISPEECH1_G726_BITRATE_DEFAULT = ISPEECH1_G726_BITRATE_40

} ISPEECH1_G726_BitRate; </syntaxhighlight>

Note however that the bitRate parameter can only be set at creation time via ISPHDEC1_Params, and not dynamically at runtime via ISPHDEC1_DynamicParams.

This is because the typical mode is to set the bitRate once. Different streams/instances can be instantiated with different bit rates naturally.

One disadvantage is that if you do... <syntaxhighlight lang="c"> params.bitRate = ISPEECH1_G726_BITRATE_24; </syntaxhighlight> ...then clearly your application is no longer speech-codec agnostic i.e. you've hardwired it to a particular codec class (i.e., G.726).

A few things could help here: -

• the defaults often suffice e.g. G726 defaults to 40kbps in which case you don't need any G726 specifics
• a big 2-D array indexed by codec-name matrix - you could set a bunch of upfront parameters and then loop thru the codecs.
• you could modify the data fields in default parameters e.g. in speech_decode1 you could have a parameter e.g. Sdec1_Params_APP_DEFAULTS and modify the structure field directly. In this way at least you don't have custom code-logic, just a different set of data defaults.

What is the tablesPtr field in XDM 1.0 Speech initialization parameters?

Question? What is the usage scenario of tablesPtr in initialization parameters (e.g. ISPHENC1_Params and ISPHDEC1_Params)? This is not available in the Dynamic parameters structure (e.g. ISPHDEC1_DynamicParams and ISPHENC1_DynamicParams).

Answer: Most often this parameter is simply initialized to NULL. This parameter specifies the pointer to the Table Block Pointer Array. If the application requires the codec to select the default Table Address Array pointer (inside the codec itself), set tablesPtr to NULL. This parameter could be used by sophisticated applications to pass in e.g. new Speech codebook constants or to share tables between codecs (the parameter is an input to codecs not an Input/Output).

Why is the size field for Speech XDAS_Int16 instead of XDAS_Int32?

To improve channel density, the sizes of many of the speech structure fields were decreased in XDM 1.0. Only the speech interfaces were compressed as those interfaces are often uses in very dense systems with many, many channels.

Note that the structures were padded when necessary to preserve 32-bit alignment. This is necessary because many of these structures support extended arguments immediately following the base structures; those fields must be 32-bit aligned.

Nothing should change in your application to accommodate this. Standards C struct initialization techniques apply:

<syntaxhighlight lang="c"> const SPHDEC1_Params Sdec1_Params_DEFAULT = {

   sizeof(SPHDEC1_Params),
   ISPEECH1_PCM_COMPAND_ALAW,
   0,
   0,
   0,
   0,
   NULL,

}; </syntaxhighlight>

Video

How is IVIDEO_NONE used in XDM 1.0?

IVIDEO_NONE is defined in the file ivideo.h in the video rate control preset enumeration, IVIDEO_RateControlPreset. The IVIDENC1_Params.rateControlPreset parameter is set to IVIDEO_NONE when there is no rate control algo used in the encoder. In the absence of rate control algo, the encoder will use a constant Qp that is usually set via an encoder specific parameter.

The usage of IVIDEO_NONE is the same in all the XDM versions.

How is the operating point of an encoder fine tuned with XDM 1.0?

At create time the encoder is configured with the base (as shown in the Codec Engine-based example below) or extended creation parameters.

<syntaxhighlight lang="c"> /* Base Class Structures */ VIDENC1_Params params;

encHandle = VIDENC1_create(hEngine, "h264enc", &params); </syntaxhighlight>

After creation, the encoder can be configured with the run time parameters using the VIDENC1_control() call as shown in the example below. It is also possible to configure the codec with the extended creation parameters which include codec specific information.

<syntaxhighlight lang="c"> /* Base Class Structures */ VIDENC1_DynamicParams dynamicParams;

/* Optional: Set Run time parameters in the Algorithm via control() */ ret = VIDENC1_control(encHandle, XDM_SETPARAMS, &dynamicParams, &status); </syntaxhighlight>

The behavior is the same for codecs that implement IVIDENC (i.e., XDM 0.9 video encoders).

How does XDM 1.0 support buffer management for encoders/decoders with B frames?

XDM 1.0 supports buffer management for decoders but not for encoders. This is a limitation of XDM 1.0 that may be addressed in a future XDM revision.

For decoders, the IVIDDEC1_OutArgs.freeBufID provides information on the frames that have been locked in the current process call.

How are IVIDENC1_InArgs->inputID and IVIDENC1_OutArgs->outputID used?

The inputID and outputID are useful for encoders that support B frames. These encoders do not encode the frames in the order they receive them from the application and IDs are required to track which buffers have been processed. The buffers identified by returned ID's in the VIDENC1_OutArgs.outputID can be reused by the application.

How is VIDENC1_OutArgs->bytesGenerated used by the application?

The VIDENC1_OutArgs.bytesGenerated field indicates how many bytes have been generated by the compression of the frame in the previous VIDENC1_process() call. This is the number of bytes that will be added to the encoded stream.

If the number of bytes generated is 0, this shows that the frame was skipped and no bytes were generated.