Download - xDM 0.9 to 1.0 Migration - Texas Instruments Wikiprocessors.wiki.ti.com/images/d/de/XDM_migration0_9to1_0... · 2008-08-11 · xDM 0.9 to xDM 1.0 Migration 1 Introduction xDM is a

xDM 0.9 to 1.0 Migration

ABSTRACT

xDM is an extension of xDAIS for multimedia algorithms and provides uniform APIs for basic functionality, parameters and status. It enables plug and play for multimedia codecs across standards and vendors. This document describes the changes between xDM 0.9 to xDM1.0 and provides a guideline for the migration from xDM 0.9 to xDM 1.0.

1

xDM 0.9 to xDM 1.0 Migration

Contents 1 Introduction .....................................................................................................................................3 2 Why XDM 1.0? .................................................................................................................................3

2.1 Drawbacks of xDM 0.9 ..............................................................................................................3 2.2 Improved Buffer Management for Video ...................................................................................4 2.3 Hooks for Video Transcoding ....................................................................................................4 2.4 Improved channel density for speech........................................................................................4 2.5 Introduction of Single Buffer Descriptor.....................................................................................5 2.6 Other Improvements..................................................................................................................5

3 Header File Cchanges between xDM0.9 and xDM 1.0..................................................................6 4 Codec Changes for xDM 1.0...........................................................................................................6 5 Application Changes for xDM 1.0 ..................................................................................................6

5.1 Frame Buffer Management by Application ................................................................................6 6 Important Links .............................................................................................................................14

Figures Figure 1. Interaction of frame buffers between application and framework.................................7

2 xDM 0.9 to 1.0 Migration


1 Introduction xDM is a uniform lightweight APIs used across various classes of multimedia algorithms, such as audio, video, speech, and image. This document details the changes between xDM 0.9 to xDM 1.0 and its implications in existing codec and application software. This document provides the guidelines to users who are using xDM0.9 in their application/codec and need to migrate to xDM 1.0.

xDM 0.9 evolved around programmable DSP that can handle SD multimedia content. The SoCs had all the multimedia algorithms running on a single processor. As the technology evolved and demand increased for HD video, TI SoCs were built using H/W accelerators. xDM 0.9 was not capable of handling such designs, which led to the introduction of xDM 1.0.

Many new interface changes were added to xDM 1.0 based on feedback accumulated for xDM 0.9. These changes effected all the interfaces namely, speech, audio and video. A brief listing is described below -

• xDM 1.0 interfaces are provided in addition to the previously released xDM 0.9 interfaces. Both 0.9 and 1.0 interfaces are provided in the ti.xdais.dm package.

o To enable both xDM 0.9 and 1.0 compliant algorithms/frameworks/apps to reside in a system, unique names were created as new interfaces were developed. For example, in xDM 0.9, video decoders used the IVIDDEC_ prefix; in xDM 1.0, they use the IVIDDEC2_ prefix. In this way, there is no naming collision, and the two classes can coexist in a single application.

o In fact, if an algorithm provider so wished, the algorithm can implement both interfaces. It can provide and document two IALG function tables, one complying with the 0.9 interface, and the other complying with the 1.0 interface. The system integrator could then choose which one to instantiate, based on the interface the application using the algorithm was written.

2 Why XDM 1.0? This sections details information about why xDM 1.0 came into existence.

2.1 Drawbacks of xDM 0.9

This section provides information on the drawbacks of xDM 0.9 that required commissioning of updated interfaces.

xDM 0.9 was essentially a beta interface; it was an initial effort to standardize the application’s view of Video/Imaging/Speech/Audio codecs.

Although xDM 0.9 has been highly successful and many codecs implement these interfaces, it has the following limitations:

xDM 0.9 to 1.0 Migration 3


• Requires application customizations for several advanced algorithms. Recall that VISA is intended to enable plug and play (from a base parameters perspective), that is, a MPEG4 decoder can be swapped for another MPEG2 decoder without modifying the application code. However, the only way to support interlaced content in MPEG2 Main Profile is to extend xDM 0.9 and add custom application logic (specifically related to outArgs) to distinguish between when the codec is being primed (first frame) and when a frame is interlaced. Therefore, if the first frame of an MPEG2 clip is interlaced, the application cannot determine what to do in xDM 0.9 context. The DVSDK 1.30 demos on DM6446 add custom logic to accommodate this. However, with DM6467 DVSDK 1.40, the demos are ‘clean’ with respect to MPEG2 decoder since IVIDDEC2 comprehends this issue. For more information about this, click here.

• Inefficient channel density for speech. When creating systems with multiple speech decoder channels, the size per channel structures is important. For example, several fields in ISPHDEC_Params were 32 bits where 16 bits would have been sufficient.

• Incompatible I/O buffers for speech encoder and decoder which was an issue incase of hybrid devices like DM644x. Remotablity was a another limitation. xDM1.0 specifies more generic buffer pointers for speech encoders and decoders.

• Did not comprehend new application scenarios. The initial focus was on Video, Imaging, Audio and Speech. However interfaces such as Transcode and Video Analytics were not comprehended at the time of xDM 0.9.

In summary, xDM 0.9 had some limitations. However, it is a supported interface and works well for common codecs such as MPEG4 video decoder and AAC audio decoder. xDM 1.0 was necessary to handle additional High-Definition use-cases and other new applications. The fact that both interfaces can coexist (IVIDDEC, IVIDDEC2, and so on) improves the migration. However, it is recommend that codec producers and system integrators adopt xDM 1.0 for the reasons outlined in this document.

2.2 Improved Buffer Management for Video

High Definition video handling has to be more sensitive towards data bandwidth and memory requirements.

With the new xDM 1.0, decoder does not request for frame buffer at the time of alg_create(). It uses buffer from xDM1_BufDesc *outBufs, which it obtains during each decode process call. Hence, there is no distinction between algorithm and application buffers. The framework needs to ensure that it does not overwrite the buffers that are locked by the codec.

2.3 Hooks for Video Transcoding

In xDM 1.0, new element was added in base class to help transcoding feature.

2.4 Improved Channel Density for Speech

To improve channel density, the sizes of many of the speech structure fields have decreased. Only the speech interfaces were compressed as those interfaces are often used in high density systems.


http://wiki.davincidsp.com/index.php?title=Extending_data_structures_in_xDM#The_perils_of_extending_inArgs.2C_outArgs


Note:

Structures were padded as required to preserve 32-bit alignment. This is essential as many structures support extended arguments that immediately follow the base structures and these fields must be 32-bit aligned.

2.5 Introduction of Single Buffer Descriptor

For improved performance of codec classes that do not require multiple buffers (that is, xDM_BufDesc, xDM_SingleBufDesc) was introduced.

To enable applications and frameworks integrating xDM algorithms, xDM1_BufDesc and xDM1_SingleBufDesc were introduced. These buffer descriptors include a per-buffer "access mask" indicating how the algorithm accessed that buffer. A typical use case for this flag is that applications can now identify when an algorithm filled a buffer using DMA, rather than CPU access, and avoid unnecessary cache write back-related maintenance of that buffer. Previously, the application had to know the behavior of the algorithm, and assume there may be dirty cache write lines.

2.6 Other Improvements

• Introduced XDM_EUNSUPPORTED error value (as a peer to XDM_EOK and XDM_EFAIL). This will also be reflected in the xDM 1.0 classes (example, ISPHDEC1_EUNSUPPORTED)

o XDM_ERUNTIME was removed. As the xDM 0.9 interface included this definition, it is available for backward compatibility in xdm.h, but the source must #define XDM_INCLUDE_DOT9_SUPPORT to have XDM_ERUNTIME defined.

• Introduced XDM_CmdId, XDM_GETVERSION. Applications can issue this command to query the algorithms for its version.

• Introduced a data field of type XDM1_SingleBufDesc to all *1_Status structures. This is used to support the XDM_GETVERSION command, and passes arbitrary buffers of data between the codec and application in control() calls.

o This is an IN/OUT buffer. It can be used to provide information to the algorithm and to receive information from it. For further details, see each algorithm's documentation.



3 Header File Changes between xDM0.9 and xDM 1.0 See \xdais_6_10_01\packages\ti\xdais\dm\docs\xdm1_differences.pdf file for details.

Alternatively, you can download the document from the following link:

https://www-a.ti.com/downloads/sds_support/targetcontent/XDAIS/xdais_6_10/xdais_6_10_01/packages/ti/xdais/dm/docs/xdm1_differences.pdf

4 Codec Changes for xDM 1.0 With the new xDM 1.0, codec needs to be changed to utilize the new features added in xDM1.0 (to be published in next revision of the document).

5 Application Changes for xDM 1.0 With the new xDM 1.0, application needs to be changed to utilize the new features added in xDM1.0. This section lists them in detail

5.1 Frame Buffer Management by Application

With the new xDM 1.0, decoder does not request for frame buffer at the time of alg_create() using ialg interface. It uses buffer from XDM1_BufDesc *outBufs, which it gets during each, decode process call. Hence, there is no distinction between codec and application buffers. The framework needs to ensure that it does not overwrite the buffers that are locked by the codec.

H264VDEC_create();

H264VDEC_control(XDM_GETBUFINFO); /*Returns default PAL D1 size */

do{

H264VDEC_decode(); /* call the decode API

H264VDEC_control(XDM_GETBUFINFO); /* updates the memory required

as per the size parsed in

stream header */

}

While(all frames)

Note:

Application can take that information and change the size of the buffer passed in the next process call.

It can re-use the extra buffer space of the 1st frame, if the above control call returns a small size than that was provided.






The frame pointer given by application and that returned by algorithm may be different. BufferID (InputID/outputID) provides the unique ID to keep record of the buffer given to the algorithm and released by the algorithm.

The application framework can efficiently manage frame buffers by keeping a pool of free frames from which it gives the decoder empty frames on request.

Figure 1. Interaction of frame buffers between application and framework

The functions of buffer manager in application can be implemented in various ways. The below set of functions illustrates a sample use case. The code snippets in the document are for reference only and provided “as it is” basis with no liability.

1. BUFFMGR_Init()

The BUFFMGR_Init function is called by the test application to initialize the global buffer element array to default and to allocate required number of memory data for reference and output buffers. The maximum required DPB size is defined by the supported profile and level.

Video Decode Thread

GetFreeBuffer

Free Frame Buffers

Buffer Manager

Video Decoder

XDM API ReleaseBuffer

Framework Algorithm

Post Processing or Display Subsystem



/*****************************************************************************/ /** *@func BUFFMGR_Init() *@brief TI's (Texas Instrument) implementation of buffer manager * initialization module * * The BUFFMGR_Init function is called by the test application to * initialise the global buffer element array to default and to allocate * required number of memory data for reference and output buffers. * The maximum required dpb size is defined by the supported profile & * level. * *@param totBufSize * Total buffer size to be allocated * *@return Success(0)/failure(-1) in allocating and initialising * */ /*****************************************************************************/ XDAS_Int32 BUFFMGR_Init(XDAS_Int32 totBufSize) { XDAS_UInt32 tmpCnt; /* total buffer size allocatable is divided into three parts one part goes * to luma buffers and the other two parts go to luma buffers */ chromaGlobalBufferSize = (totBufSize/3); lumaGlobalBufferSize = (chromaGlobalBufferSize*2); if(lumaGlobalBufferHandle == NULL) { /* Allocate the global buffers */ lumaGlobalBufferHandle = malloc(lumaGlobalBufferSize); if(lumaGlobalBufferHandle == NULL) { return -1; } chromaGlobalBufferHandle = malloc(chromaGlobalBufferSize); if(chromaGlobalBufferHandle == NULL) { free(lumaGlobalBufferHandle); return -1; } } memset(lumaGlobalBufferHandle, 0x66, lumaGlobalBufferSize); memset(chromaGlobalBufferHandle, 0x66, chromaGlobalBufferSize); /* Initialise the elements in the global buffer array */ for(tmpCnt = 0; tmpCnt < MAX_BUFF_ELEMENTS; tmpCnt++) { buffArray[tmpCnt].bufId = tmpCnt+1; buffArray[tmpCnt].bufStatus = BUFFMGR_BUFFER_FREE; buffArray[tmpCnt].bufSize[1] = 0; buffArray[tmpCnt].bufSize[0] = 0; buffArray[tmpCnt].buf[1] = NULL; buffArray[tmpCnt].buf[0] = NULL; } /* Initialise the entire buffer space to first frame and * re-modify buffer sizes as per the picture frame sizes * after first frame decode */ buffArray[0].buf[1] = chromaGlobalBufferHandle; buffArray[0].bufSize[1] = chromaGlobalBufferSize; buffArray[0].buf[0] = lumaGlobalBufferHandle;



buffArray[0].bufSize[0] = lumaGlobalBufferSize; return 0; }

2. BUFFMGR_ReInit()

The BUFFMGR_ReInit function allocates global luma and chroma buffers and allocates entire space to first element. This element will be used in first frame decode. After the picture height and width, and its luma and chroma buffer requirements are obtained, the global luma and chroma buffers are re-initialized to other elements in the buffer array.



/*****************************************************************************/ /** *@func BUFFMGR_ReInit() *@brief TI's (Texas Instrument) implementation of buffer manager * re-initialization module * * The BUFFMGR_ReInit function allocates global luma and chroma buffers * and allocates entire space to first element. This element will be used * in first frame decode. After the picture's height and width and its luma * and chroma buffer requirements are obtained the global luma and chroma * buffers are re-initialised to other elements in teh buffer arary. * *@param lumaOneFrameBufSize * Buffer size for one luma frame in bytes * *@param chromaOneFrameBufSize * Buffer size for one chroma frame in bytes * *@return Success(0)/failure(-1) in allocating and initialising * */ /*****************************************************************************/ XDAS_Int32 BUFFMGR_ReInit(XDAS_Int32 lumaOneFrameBufSize, XDAS_Int32 chromaOneFrameBufSize) { XDAS_Int32 tmpLum, tmpChrm, tmpCnt; XDAS_UInt8 *tmpLumaBuf, *tmpChrmBuf; /* check if the requested sizes exceed allocated buffer sizes */ if((lumaOneFrameBufSize > lumaGlobalBufferSize) || (chromaOneFrameBufSize > chromaGlobalBufferSize)) { return -1; } tmpLum = lumaGlobalBufferSize; tmpChrm = chromaGlobalBufferSize; tmpLumaBuf = lumaGlobalBufferHandle; tmpChrmBuf = chromaGlobalBufferHandle; /* now re-allocate buffer sizes for each element based on the * per frame buffer requirements */ for(tmpCnt = 0; (tmpCnt < MAX_BUFF_ELEMENTS) && ((tmpLum - lumaOneFrameBufSize) >= 0) && ((tmpChrm - chromaOneFrameBufSize) >= 0); tmpCnt++) { buffArray[tmpCnt].buf[0] = tmpLumaBuf; buffArray[tmpCnt].buf[1] = tmpChrmBuf; buffArray[tmpCnt].bufSize[1] = chromaOneFrameBufSize; buffArray[tmpCnt].bufSize[0] = lumaOneFrameBufSize; /* update the local variables for next iteration */ tmpLum -= lumaOneFrameBufSize; tmpChrm -= chromaOneFrameBufSize; tmpLumaBuf += lumaOneFrameBufSize; tmpChrmBuf += chromaOneFrameBufSize; } #ifdef _DBG_VERBOSE printf("Can now support upto %d number of reference frames\ with the given buffer size \n", tmpCnt+1);



#endif /* Initialise rest of the elements to NULL - not really required since * they are anyway initialised to these default values in Init function */ for(; (tmpCnt < MAX_BUFF_ELEMENTS); tmpCnt++) { buffArray[tmpCnt].buf[0] = NULL; buffArray[tmpCnt].buf[1] = NULL; buffArray[tmpCnt].bufSize[1] = 0; buffArray[tmpCnt].bufSize[0] = 0; } return 0; }

3. BUFFMGR_GetFreeBuffer()

The BUFFMGR_GetFreeBuffer function searches for a free buffer in global buffer array and returns the address of that element. Incase, if none of the elements are free, then it returns NULL. /*****************************************************************************/ /** *@func BUFFMGR_GetFreeBuffer() *@brief TI's (Texas Instrument) implementation of buffer manager * re-initialization module * * The BUFFMGR_GetFreeBuffer function searches for a free buffer in the * global buffer array and returns the address of that element. Incase * if none of the elements are free then it returns NULL * * *@return Valid buffer element address or NULL incase if no buffers are empty * */ /*****************************************************************************/ BUFFMGR_buffEleHandle BUFFMGR_GetFreeBuffer() { XDAS_UInt32 tmpCnt; /* Since buffers are re-initialised later on its perfectly possible to * have buffer elements with NULL as the buffer pointers - as soon as * such buffer elements are encountered we need to stop search for * free buffers */ for(tmpCnt = 0; (tmpCnt < MAX_BUFF_ELEMENTS) && (buffArray[tmpCnt].buf[0] != NULL); tmpCnt++) { /* Check for first empty buffer in the array and return its address */ if(buffArray[tmpCnt].bufStatus == BUFFMGR_BUFFER_FREE) { buffArray[tmpCnt].bufStatus = BUFFMGR_BUFFER_USED; return (&buffArray[tmpCnt]); } } printf("Run short of frames !!\n"); /* Incase if no elements in the array are free then return NULL */ return NULL; }



4. BUFFMGR_ReleaseBuffer()

The BUFFMGR_ReleaseBuffer function takes an array of buffer-IDs that are released by the test-application. “0" is not a valid buffer ID. Hence, this function keeps moving until it encounters a buffer ID as zero or it hits the MAX_BUFF_ELEMENTS.



/*****************************************************************************/ /** *@func BUFFMGR_ReleaseBuffer(buffId) *@brief TI's (Texas Instrument) implementation of buffer manager * re-initialization module * * The BUFFMGR_ReleaseBuffer function takes an array of buffer-ids * which are released by the test-app. "0" is not a valid buffer Id * hence this function keeps moving until it encounters a buffer Id * as zero or it hits the MAX_BUFF_ELEMENTS * * *@return None * */ /*****************************************************************************/ void BUFFMGR_ReleaseBuffer(XDAS_UInt32 bufffId[]) { XDAS_UInt32 tmpCnt, tmpId; for(tmpCnt = 0; (tmpCnt < MAX_BUFF_ELEMENTS); tmpCnt++) { tmpId = bufffId[tmpCnt]; /* * Check if the buffer Id = 0 condition has reached. zero is not a * valid buffer Id hence that value is used to identify the end of * buffer array */ if(tmpId == 0) { break; } /* * convert the buffer-Id to its corresponding index in the global * array */ tmpId--; if(tmpId >= MAX_BUFF_ELEMENTS) { /* Inidcates an invalid buffer Id passed - this buffer Id can be * ignored!! alternatively we can break here. */ printf("Trying to release a buffer using an invalid bufferId %d \ ignoring..\n", tmpId+1); continue; } if(buffArray[tmpId].bufStatus == BUFFMGR_BUFFER_FREE) { /* Trying to release an already free bufffer this idicates some mismanagement * in buffer usage following printf will help application developer to identify * any such problem in her algorithm */ printf("Trying to release an already free buffer Id %d \n", tmpId+1); } /* Set the status of the buffer to FREE */ buffArray[tmpId].bufStatus = BUFFMGR_BUFFER_FREE; } #ifdef _DBG_VERBOSE printf("Currrently locked buffers after release are: "); for(tmpCnt = 0;



(tmpCnt < MAX_BUFF_ELEMENTS); tmpCnt++) { if(buffArray[tmpCnt].bufStatus != BUFFMGR_BUFFER_FREE && buffArray[tmpCnt].buf[1] != NULL) { printf("%d, ", tmpCnt+1); } } printf("- \n"); #endif return; }

5. BUFFMGR_DeInit()

The BUFFMGR_DeInit function releases all memory allocated by buffer manager.

/*****************************************************************************/ /** *@func BUFFMGR_DeInit() *@brief TI's (Texas Instrument) implementation of buffer manager * re-initialization module * * The BUFFMGR_DeInit function releases all memory allocated by buffer * manager. * *@return None * */ /*****************************************************************************/ void BUFFMGR_DeInit() { if(lumaGlobalBufferHandle) free(lumaGlobalBufferHandle); lumaGlobalBufferHandle = NULL; if(chromaGlobalBufferHandle) free(chromaGlobalBufferHandle); chromaGlobalBufferHandle = NULL; return; }

6 Important Links • http://tiexpressdsp.com/wiki/index.php?title=XDM_FAQ#What.27s_with_the_xDM_versioning.3F

• https://www-a.ti.com/downloads/sds_support/targetcontent/XDAIS/xdais_6_10/xdais_6_10_01/packages/ti/xdais/dm/docs/xdm1_differences.pdf


http://tiexpressdsp.com/wiki/index.php?title=XDM_FAQ#What.27s_with_the_xDM_versioning.3F





DOCUMENT VERSION HISTORY

Version Number Date Description

0.5 11th August 2008 First draft of the migration document


Download - xDM 0.9 to 1.0 Migration - Texas Instruments Wikiprocessors.wiki.ti.com/images/d/de/XDM_migration0_9to1_0... · 2008-08-11 · xDM 0.9 to xDM 1.0 Migration 1 Introduction xDM is a

Top Related