Migration/Integration Guide for DM36x H.264 version 2.x codecs

Migration Guide for DM36x H.264 version 2.0 codecs

---

---

Migration guide: DM36x ver 2.0 H.264 codec

This document describes the change done in H.264 ver 2.0 codec over the previous 1.1 codec. It outlines the advantages to migrate to the new codec and the steps needed to do so.

Note: This document has been written in context of below H.264 codec version and above -

Encoder: 2.00.00.10

Decoder: 2.00.00.10

Download Link: http://software-dl.ti.com/dsps/dsps_public_sw/codecs/DM365/index_FDS.html

New Features in Version 2.0 H.264 codec

New DM36x version 2.0 H.264 codec is an enhanced version of the existing ver 1.1 codec that supports more features and better performance. This codec is also known as Platinum codec.

The salient new features are:

• H.264 encoder
  • New enhanced codec version with 1.5x more performance than earlier version without impacting quality.
  • Achieves 1080P@30fps on DM368
  • More feature rich codecs which includes
    • Smart codec technology
    • Low latency API support
• H.264 decoder
  • Achieves 1080P@30fps on DM368 for streams encoded by DM36x encoder
  • More feature rich codec which includes
    • Low latency API support with fixed packet size mode
    • Can decode SVC-T stream produced by DM368 encoder

For more details: H.264 DM36x Ver 2.0 Codec

Comparison between version 2.0 and 1.1 codec

Please see H.264 DM36x Ver 2.0 Codec

API changes in version 2.0 encoder

There are changes in extended parameter of Dm365 encoder and decoder when compared to ver 1.1. The changes are listed below –

IH264VENC_Params

Parameter	Ver. 2.0	Ver. 1.1	Comments
unrestrictedMV	Reserved:	Supported	UMV is always ON in ver 2.0, the parameter value is don't care by encoder Default value: 0
seqScalingFlag	Valid value: 0-3 Value = 4 is depreciated	Valid value: 0-4	Value of 4, which corresponded to HIGH/SHARP matrix, is depreciated in ver 2.0 codec Default value: 1
encQuality	Value = 1 is depreciated Supported value: 0 and 2	Value:0 -2	encQuality which corresponded to erstwhile HIGH quality(value = 1) is depreciated in ver 2.0 due to performance reasons Default value: 2
enableDDRbuff	Enables to use DDR instead of VICP buffers	Not present	Newly added in ver 2.0 codec. This allows VICP based codec/algorithm to run in parallel to H.264 codec, subject to other resource like EDMA availability. Default value: 0
sliceMode	Multiple slice mode of operation	Not present	Newly added in ver 2.0 codec for enabling various method of specifying slice size. Default value: 0
outputDataMode	Switch to control low latency call back	Not present	Newly added in ver 2.0 codec as part of low latency support Default value: 1
sliceFormat	Control for NAL and byte stream bitstream format	Not present	Newly added in ver 2.0 codec as part of low latency support Default value: 1

IH264VENC_Dynamic_Params

Parameter	Ver. 2.0	Ver. 1.1	Comments
rcQMaxI	Max QP in Intra frame	Not present	Newly added in ver 2.0 codec as part of RC enhancements Default: 36
rcQMinI	Min QP in Intra frame	Not present	Newly added in ver 2.0 codec as part of RC enhancements Default: 10
meMultiPart	Depreciated	Supported when encQuality = 1	Depreciated as encQuality =1 is no longer supported in ver 2.0 encoder Default: 0
intraSliceNum	Depreciated	Supported when encQuality = 1	Depreciated as encQuality =1 is no longer supported in ver 2.0 encoder Default: 0
intraThrQF	Depreciated	Supported when encQuality = 1	Depreciated as encQuality =1 is no longer supported in ver 2.0 encoder Default: 0
enableROI	Control for Region of interest (ROI) encoding	Not present	Newly added in ver 2.0 codec as part of ROI support Default: 0
metaDataGenerateConsume	Control for pseudo two pass encode	Not present	Newly added in ver 2.0 codec as part of ROI support Default: 0
putDataGetSpaceFxn	Low latency - Call back function handle	Not present	Newly added in ver 2.0 codec as part of low latency support Default: NULL
dataSyncHandle	Low latency - Callback data sync handle	Not present	Newly added in ver 2.0 codec as part of low latency support Default: NULL

IH264VENC_InArgs

Parameter	Ver. 2.0	Ver. 1.1	Comments
roiParameters	Structure to pass ROI details	Not present	Newly added in ver 2.0 codec as part of ROI support Default: can be kept uninitialized(as enableROI = 0 in default mode)
numOutputDataUnits	Granularity in which the call back happens to the application	Not present	Newly added in ver 2.0 codec as part of low latency support Default: 0

API changes in version 2.0 decoder

There are changes in extended parameter of Dm365 encoder and decoder when compared to ver 1.1. The changes are listed below –

IH264VDEC_Params

Parameter	Ver. 2.0	Ver. 1.1	Comments
inputDataMode	Switch to control low latency call back	Not present	Newly added in ver 2.0 codec as part of low latency support Default value: 1
sliceFormat	Control for NAL and byte stream bitstream format	Not present	Newly added in ver 2.0 codec as part of low latency support Default value: 1

IH264VDEC_Status

Parameter	Ver. 2.0	Ver. 1.1	Comments
frameType	Frame type(I, P or B)	Not present	Populates the value when decoder is run in decodeHeader mode. Useful for trick play(FF, Seek).
firstMBinSlc	First MB number of the slice	Not present	Populates the value when decoder is run in decodeHeader mode. Useful for trick play(FF, Seek).
frmNuminSlcHdr	Frame number as decoder in slice header	Not present	Populates the value when decoder is run in decodeHeader mode. Useful for trick play(FF, Seek).

IH264VDEC_Dynamic_Params

Parameter	Ver. 2.0	Ver. 1.1	Comments
getDataFxn	Low latency - Call back function handle	Not present	Newly added in ver 2.0 codec as part of low latency support Default: NULL
dataSyncHandle	Low latency - Callback data sync handle	Not present	Newly added in ver 2.0 codec as part of low latency support Default: NULL

IH264VDEC_InArgs

Parameter	Ver. 2.0	Ver. 1.1	Comments
pNumBytesInDesc [] |Related to low latency operation	Not present	Array to specify valid bytes in input buffers provided at the time of decoder process call Default: Can be kept uninitialized

IH264VDEC_OutArgs

Parameter	Ver. 2.0	Ver. 1.1	Comments
numBlocksConsumed	Related to low latency operation	Not present	Number of NALs consumed from last set of NALs provided through through getDataFxn callback for that process call

How to integrate ver 2.0 codec in existing application?

• Update below mentioned software components to the version no. specified along side

Framework Component: Version No.framework_components_2_24_01 (FC_INSTALL_DIR) Linux Utils : Version No. linuxutils_2_24_03 (LINUXUTILS_INSTALL_DIR)

One may have to recompile the KOs using the new linuxUtils version. Please refer to DVSDK 3.10 Makefile usage for some details.

The new version 2.0 codec also uses ARM926 TCM for its operation in base mode. Hence it is recommended to check if the below points are taken care -

• check if the cfg file has the MEMTCM module defined –

<syntaxhighlight lang='javascript'> var MEMTCM = xdc.useModule('ti.sdo.fc.ires.memtcm.MEMTCM'); MEMTCM.cmemBlockId = 1;

var EDMA3 = xdc.useModule('ti.sdo.fc.edma3.Settings'); EDMA3.maxRequests = 128; </syntaxhighlight>

• The loadmodules should have the below appended in the cmem allocation

"allowOverlap=1 phys_start_1=0x00001000 phys_end_1=0x00008000 pools_1=1x28672"

• In case application is using only base class for encode and decode operation, they can just replace the existing codec RTSC package with the new ver 2.0 codec RTSC package and rebuild the application.

Note: In the new codec, there is change in the DMA library name and hence just dropping the new libraries in the existing RTSC package will not work. One will see compilation failure when this approach is followed. Hence, it is recommended to completely replace the RTSC package with the new one.

• In case the application uses extended parameter, one will need to do modification in the app code depending on the usage of the new features. Please refer to the new interface file, sample test application and user guide to understand the changes in detail.

• Only applicable if application is using MVL based LSP 2.1 - The new ver 2.1 codec need more EDMA channels. If the existing application is also using good number of EDMA channels, integrating new codec may cause channel shortage. In such case, one can visit file: $LINUX/include/asm-arm/arch-davinci/edma.h and modify DM365_DMACH2EVENT_MAP0 and DM365_DMACH2EVENT_MAP1. The bit position which are set to 1 has the EDMA event reserved for corresponding LSP driver. If the user application is not using that driver, it can release that EDMA channel for codec/app use by setting the bit to 0.

How to run codec standalone test application package in DVSDK 2.1 environment ?

Below instructions are for DVSDK 2.10.01.18.

• Update below mentioned software components to the version no. specified along side.

Framework Component: Version No.framework_components_2_24_01 (FC_INSTALL_DIR) Linux Utils : Version No. linuxutils_2_24_03 (LINUXUTILS_INSTALL_DIR) XDAIS = Version No. xdais_6_25_02_11 (XDAIS_INSTALL_DIR)

• Update path of the various tools used in rule.make file of test application as per your installation directory. Keep the default compiler option unchanged to COMPILER = mvl (Montvista Cross Compiler) in building test application in rule.make file. Please change path of the tools as per the compiler option.

• Build you own kernel modules using the DVSDK installed and update the same in test application directory "../apps/client/build/arm926/"

Visit http://processors.wiki.ti.com/index.php/DVSDK_3.10_Makefile_usage for more details.

How to integrate ver 2.0 codec in DVSDK 2.1 demo?

Encoder Demo

• Update below mentioned software components to the version no. specified along side.

Framework Component: Version No.framework_components_2_24_01 (FC_INSTALL_DIR) Linux Utils : Version No. linuxutils_2_24_03 (LINUXUTILS_INSTALL_DIR)

One may have to recompile the KOs using the new Linux Utils version. Please refer to DVSDK 3.10 Makefile usage for some details.

• Add below lines in configuration file encode.cfg of encoder demo code of DM365 DVSDK demo.

<syntaxhighlight lang='javascript'> var MEMTCM = xdc.useModule('ti.sdo.fc.ires.memtcm.MEMTCM'); MEMTCM.cmemBlockId = 1;

var EDMA3 = xdc.useModule('ti.sdo.fc.edma3.Settings'); EDMA3.maxRequests = 128; </syntaxhighlight>

• In the loadmodules_hd.sh file, append below content at the end of line in where pool sizes are declared for encode and decode demo.

allowOverlap=1 phys_start_1=0x00001000 phys_end_1=0x00008000 pools_1=1x28672

Decoder Demo

• For decoder demo, do the same modification as mentioned above for encoder demo. The cfg file modification needs to be done in in decode.cfg.

If you are running decoder demo, you might observe segmentation fault. To avoid this, video.c file of decoder demo has to be modified depending upon param mode (base/extended) in which decoder is required to run. Hence, apart from these changes, following changes need to be incorporated for decoder demo.

• Modify lines from 209 to 217 in video.c as below.

<syntaxhighlight lang='c'>

1. if 1 // Enable this code for extended param mode

extnParams.displayDelay = 8; extnParams.levelLimit = 0; extnParams.disableHDVICPeveryFrame = 0; extnParams.inputDataMode = 1; extnParams.sliceFormat = 1; extnParams.frame_closedloop_flag = 1;

if (strcmp(envp->videoDecoder, "h264dec") == 0)

   params->size = sizeof(IH264VDEC_Params);

extnParams.viddecParams = *params;

/* Create the video decoder */ hVd2 = Vdec2_create(hEngine, envp->videoDecoder, (VIDDEC2_Params*)&extnParams, dynParams);

1. else // Enable this code for base param mode

params->size = sizeof(IVIDDEC2_Params); hVd2 = Vdec2_create(hEngine, envp->videoDecoder, params, dynParams);

1. endif

</syntaxhighlight>

• Also, modify lines from 519 -520 in video.c as below

<syntaxhighlight lang='c'>

1. if 1 // Enable this code for extended param mode

hVd2 = Vdec2_create(hEngine, envp->videoDecoder, (VIDDEC2_Params*)&extnParams, dynParams);

1. else // Enable this code for base param mode

hVd2 = Vdec2_create(hEngine, envp->videoDecoder, params, dynParams);

1. endif

</syntaxhighlight>

How to run codec standalone test application package in DVSDK 3.1 environment ?

Below instructions are for DVSDK 3.10.00.19.

• Update below mentioned software components to the version no. specified along side.

Framework Component: Ver. No. framework_components_2_25_02_06 (FC_INSTALL_DIR) Linux Utils : Ver No. linuxutils_2_25_04_10 (LINUXUTILS_INSTALL_DIR) XDAIS = Ver No. xdais_6_25_02_11(XDAIS_INSTALL_DIR)

One may have to recompile the KOs using the new linuxUtils version. Please refer to http://processors.wiki.ti.com/index.php/DVSDK_3.10_Makefile_usage for some details.

• Update path of the various tools used in rule.make file of test application as per your installation directory. Specify the compiler option, which you would like to use for building test application in rule.make file.

COMPILER = mvl /* Montvista Cross Compiler */ COMPILER = cst /* CodeSourcery_Toolchain */

• Default option is "mvl". Please change path of the tools as per the compiler option.

• Build you own kernel modules using the DVSDK installed and update the same in test application directory "../apps/client/build/arm926/"

Visit http://processors.wiki.ti.com/index.php/DVSDK_3.10_Makefile_usage for more details.

How to integrate ver 2.0 codec in DVSDK 3.1 demo?

Encoder Demo

• Add below lines in configuration file (encode.cfg) of encoder demo code of DM365 DVSDK demo.

var MEMTCM = xdc.useModule( ’ ti.sdo.fc.ires.memtcm.MEMTCM ’ ); MEMTCM.cmemBlockId = 1; var EDMA3 = xdc.useModule( ’ ti.sdo.fc.edma3.Settings ’ ); EDMA3.maxRequests = 128;

• In the loadmodules_hd.sh file, append below content at the end of line in which pool sizes are declared for encode and decode demo.

allowOverlap=1 phys_start_1=0x00001000 phys_end_1=0x00008000 pools_1=1x28672

Decoder Demo

• For decoder demo, do the same modification as mentioned above for encoder demo. The cfg file modification needs to be done in in decode.cfg.

If you are running decoder demo, you might observe segmentation fault. To avoid this, video.c file of decoder demo has to be modify depending upon param mode (base/extended) in which decoder is required to run. Hence, apart from these changes, following changes need to be incorporated for decoder demo.

• Modify lines from 209 -217 in video.c as below.

# if 1 // Enable this code for extended param mode extnParams.displayDelay = 8; extnParams.levelLimit = 0; extnParams.disableHDVICPeveryFrame = 0; extnParams.inputDataMode = 1; extnParams.sliceFormat = 1; extnParams.frame_closedloop_flag = 1; if(strcmp(envp- > videoDecoder,"h264dec") == 0) params- > size = sizeof(IH264VDEC_Params); extnParams.viddecParams = *params; /* Create the video decoder */ hVd2 = Vdec2_create(hEngine, envp- > videoDecoder, (VIDDEC2_Params*)&extnParams, dynParams); # else // Enable this code for base param mode params- > size = sizeof(IVIDDEC2_Params); hVd2 = Vdec2_create(hEngine, envp- > videoDecoder, params, dynParams); # endif

• Also, modify lines from 516 - 517 in video.c as below,

# if 1 // Enable this code for extended param mode hVd2 = Vdec2_create(hEngine, envp- > videoDecoder, (VIDDEC2_Params*)&extnParams, dynParams); # else // Enable this code for base param mode hVd2 = Vdec2_create(hEngine, envp- > videoDecoder, params, dynParams); # endif

---