Please note as of Wednesday, August 15th, 2018 this wiki has been set to read only. If you are a TI Employee and require Edit ability please contact x0211426 from the company directory.

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

From Texas Instruments Wiki
Jump to: navigation, search

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 –
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;
  • 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.
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 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.
#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 519 -520 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

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