MCSDK VIDEO 2.x DSP Development Guide

MCSDK Video

Version 2.x

DSP Development Guide

Last updated: 11/11/2013

---

Introduction

MCSDK Video DSP application builds on BIOS-MCSDK and executes highly compute intensive video processing on TI C66x multi-core DSPs. It has been developed to facilitate the development and testing of video, audio, and image Codecs. Standardized XDM compliant wrappers are provided to exercise codec APIs, with various pre-integrated video codecs as the example. Specifically, this MCSDK Video DSP Development Guide provides information about

• Call flow of MCSDK Video DSP Application
• Framework Folders and Make Instructions
• Integrating New Codec in MCSDK Video DSP Build
• Cache Usage
• Multi Core Video Interface APIs

Call Flow of MCSDK Video DSP Application

The call flow of MCSDK Video DSP via TFTP data IO is as follows:

• Platform initialization
• Network interface initialization

1. Read network configuration file via JTAG file I/O
2. Configure network channel for streaming, and local/remote network endpoints;

• Read test cases configuration file via JTAG file I/O
• Loop through all test cases

1. Parse test case configuration file, and set static and dynamic parameters
2. Codec initialization
3. Loop through all frames until end of file reached

• TFTP Get input file into DDR
• Process frames (decode or encode)
• TFTP Put generated bytes to TFTP server

In the above call flow, only codec initialization and frame processing are specific for individual codecs. The rest is common for all codecs.

Framework Folders and Make Instructions

Framework Folders

The following table lists the folders required for building Codec Codec Framework. It also highlights the folders which users expect to change when plugging in a new XDM compliant codec in the framework.

Top Level Folder	Brief Description	Users Expected to Change?
\dsp
	Build related perl files	NO
	Bootloader shared information with the application	NO
	Build framework files (ggcfg)	YES
	Hardware Abstraction Layer	NO
	Memory management and utilities	NO
	Main Makefile (mkrel)	YES for setupenvMsys.sh
	Network Driver Interface	NO
	Codec integration framework (siu)	YES
	Build files (ggcfg\build\sv04)	YES
\components	Video components	NO
\inc	Include files to talk to various components	NO

Make Instructions

Before making the Codec Test Application, please refer to Getting Started Guide for details on installing the MCSDK Video and its required tools.

When it is desired to change one (or more) of the codec algorithms or add a new codec algorithm, the following steps are needed in order to change and rebuild the Codec Test Application.

• Make a copy of dsp directory and modify desired files in their home directories and save.
• Configure environment: the build directory is dsp\mkrel. Run the batch file "\dsp\mkrel\setupenvMsys.bat bypass" to configure the environment. The batch file calls "\dsp\mkrel\setupenvMsys.sh" which will check if all the required components and tools are available at the specified locations.
• Run dsp/mkrel/makefile to build DSP code: make sv04.
• The build procedure will produce directory: \dsp\mkrel\sv04 with the following files: sv04.out, sv04.map, readme_sv04.txt

Useful Tip 1. If a source debugger requires all source files to be combined into a single directory, "FLAT=YES" may be added in the make command line, which will create the directory mkrel\sv04\flat containing all source and header files used for the build. 2. After making the first build, if there is no source file change in \components directory, "RTSCBYPASS=YES" may be added in the make command line, which will bypass compiling the components. If there is no source file change in dsp\ggcfg\build\hdg\sv04\bios directory, "BIOSCFGPKGBYPASS=YES" may be added in the make command line, which will bypass compiling the BIOS configuration package.

Integrating New Codec in MCSDK Video DSP Build

In MCSDK Video 2.1, all the C6678 codec available at C6678 Codecs have been integrated. In MCSDK Video 2.2, HEVC encoder and HEVC decoder are further integrated. Please follow the following steps to add a new codec.

Codec Algorithm

New Codec can be plug and play in the existing sv04 infrastructure if it is XDM 0.9 or XDM 2.0 compliant encoder or XDM 1.3 compliant decoder. For the product release of MCSDK Video, it further supports XDM 1.0 compliant video encoder and XDM 1.0 compliant video decoder, as well as XDM 1.0 compliant image encoder and XDM 1.0 compliant image decoder. If the codec is not compliant with any of the above XDM versions, XDM wrapper needs to be created using the existing three XDM wrapper as references.

Codec algorithm source code can be compiled either via make or CCS to make a library. Once the Codec library with public API files is ready, need to add its environment to "\dsp\mkrel\setupenvMsys.sh" following the example below.

# H264BP encoder

VIDEO_H264_ENC_VERSION="C66x_h264venc_01_24_00_01_ELF"

VIDEO_H264_ENC_RUNPATH="$VIDEOBASE/$VIDEO_H264_ENC_VERSION"

make_shortname "VIDEO_H264_ENC_RUNPATH"

VIDEO_H264_ENC_SRCPATH="$VIDEO_H264_ENC_RUNPATH"

check_exist "VIDEO_H264_ENC_SRCPATH" "/packages/ti/sdo/codecs/h264venc/ih264venc.h"

COPY_TOOLS_LIST="$COPY_TOOLS_LIST VIDEO_H264_ENC"

...

export VIDEO_H264_ENC_DOS="`echo $VIDEO_H264_ENC_RUNPATH | $make_dos_sed_cmd`/packages"

Then, add the new codec path to "FXDCINC" in "\dsp\mkrel\c64x\makedefs.mk", following any of the video codecs as the example from the code below:

FXDCINC = $(GGROOT)/mkrel/rtsc;$(TOOLSXDCDOS)/packages;$(BIOS_MCSDK_PDK6678_DOS);$(NWAL_C66X_DOS);$(VIDEO_MPEG4_ENC_DOS);$(VIDEO_MPEG4_DEC_DOS);$(VIDEO_MPEG2_DEC_DOS);$(VIDEO_H264_ENC_DOS);$(VIDEO_H264_DEC_DOS);$(VIDEO_H264HP_DEC_DOS);$(VIDEO_AVCIU_ENC_DOS);$(VIDEO_J2K_ENC_DOS);$(VIDEO_J2K_DEC_DOS);$(DSP_INSTALL_DIR_DOS)

Codec Client Glue Code

In order to glue a new codec to the framework, the following files must be written and placed as indicated:

• Decoder: vct<codec>DecClient.c and vct<codec>DecClient.h files in siu\vct\codec\decoder\codec folder
• Encoder: vct<codec>EncClient.c and vct<codec>EncClient.h files in siu\vct\codec\encoder\codec folder

JPEG2K decoder and H.264BP encoder client code can be referred to as example. <codec>encAPI and <codec>decAPI for the new codec must be defined according to the corresponding data structures defined in siuVctCodecAPI.h.

Update siuVctSupportedCodecs.c

Edit the file siuVctSupportedCodecs.c. Include the Client Glue code header file vct<codec>EncClient.h or vct<codec>DecClient.h and update the data structure encoderAPI_t or decoderAPI_t with the new API definition.

Edit makefile

siu\c64x\make\makefile must be edited to include the new header files and also compile the client glue code. Search for “avciu” in this makefile and make similar changes

Update Linker Command File

ggcfg\build\hdg\sv04\ggvf0.becmd must be updated to include the new Codec library

Create Config Files

Create multiClip.cfg and codecParams.cfg for the codec (under siu/vct/testVecs/<codec>/config), and update the codecName in the codecParams.cfg with the string name that is used in the Glue Code. To test the newly added codec, modify siu/vct/testVecs/testVecs.cfg to update the path.

Cache Usage

The following describes the Cache configuration in sv04 build and the APIs available to perform cache operations such as wirteback and invalidate.

Cacheability of DDR

Sections of DDR can be made cacheable or non-cacheable, prefetchable or non-prefetchable using the MAR registers and the granularity is 16MB. For the entire DDR of 512 MB on Shannon (0x80000000 – 0x9FFFFFFF), One 16MB DDR section (0x80000000 – 0x80FFFFFF) is configured as non-cacheable and non-prefetchable while all the other DDR sections are cacheable and prefetchable. The only non-cacheable and non-prefetchable DDR section is used for multi-core synchronization buffers for multi-core codecs. The MAR definition can be found from “TMS320C66x DSP CorePac User Guide” (Literature Number: SPRUGW0A). The DDR Cache setting can be changed by editing the file ggcfg\build\hdg\sv04\ggmemdef.bec in the structure vigdkMemoryContext_t.

Cacheability of L1P, L1D and L2

Cache configuration for L1P, L1D and L2 is done in the file ggcfg\build\hdg\sv04\ gghwcfg.h. Recommended configuration is to use HAL_L1P_CACHE_32K, HAL_L1D_CACHE_32K and HAL_L2_CACHE_64K.

Cache Control APIs

The following functions (defined in dsp\siu\osal\bios6\siuOsalBios6.c) are available to perform various cache operations. They are wrappers calling BIOS 6 Cache APIs.

• void siu_osal_wbinv_cache_all(void);
• void siu_osal_wbinv_cache(void *base, tulong length, bool wait);
• void siu_osal_inv_cache(void *base, tulong length, bool wait);
• void siu_osal_wb_cache(void *base, tulong length, bool wait);

Multi Core Video Interface APIs

In order to facilitate development of multi-core/multi-chip codecs, MCSDK Video provides multi-core video interface (ividmc) APIs. ividmc APIs allow application framework to set and implement the interface APIs. In video codec creation phase, the actual implementation of the APIs is passed through codec static parameters as a set of function pointers. Then, video codec is internally using only these APIs to do inter-core/inter-chip sync-up and/or communication.

MCSDK Video provides two versions of multi-core video interface (ividmc) APIs: ividmc and ividmc3. ividmc supports multi-core within a single chip, while ividmc3 supports multi-core and multi-chip. Their corresponding API files 'ividmc.h’ and 'ividmc3.h’ are located in dsp\siu\ividmc folder. The following describes some details of ividmc3 APIs.

Overall structure of ividmc3 APIs is as follows:

typedef struct IVIDMC3_s {
XDAS_Void *(*keyCreate) (XDAS_UInt8 *name, XDAS_Int32 user_id, IVIDMC3_KEY_SPACE_e key_space, 
                    XDAS_Int32 num_users, XDAS_Int32 *user_ids, IVIDMC3_KeyCfg_t *cfg);
XDAS_Int32 (*barrWait)(XDAS_Int32 user_id, XDAS_Void *barrHandle);
XDAS_Int32 *(*shmMap) (XDAS_Int32 user_id, XDAS_Void *shmemHandle);
XDAS_Int32 (*shmSync)(XDAS_Int32 user_id, XDAS_Void *shmemHandle, XDAS_Int32 *shmem_base,
                 XDAS_Int32 shmem_size, IVIDMC3_SYNC_ATTRIBS shmem_sync_attribs);
XDAS_Int32 (*shmSyncWait)(XDAS_Int32 user_id, XDAS_Void *shmemHandle, XDAS_Int32 *shmem_transid);
XDAS_Int32 (*lockAcquire)  (XDAS_Int32 user_id, XDAS_Void *lockHandle);
XDAS_Int32 (*lockRelease)  (XDAS_Int32 user_id, XDAS_Void *lockHandle);
XDAS_Int32 (*lockCheck)    (XDAS_Int32 user_id, XDAS_Void *lockHandle);
XDAS_Int32 (*mailBoxOpen)(XDAS_Void *mailBoxHandle);
XDAS_Int32 (*mailBoxWrite) (XDAS_Void *mailBoxHandle, XDAS_UInt8 *buf, XDAS_UInt32 size, XDAS_UInt32 trans_id);
XDAS_Int32 (*mailBoxRead) (XDAS_Void *mailBoxHandle, XDAS_UInt8 *buf, XDAS_UInt32 *size, XDAS_UInt32 *trans_id);
XDAS_Int32 (*mailBoxQuery) (XDAS_Void *mailBoxHandle);
XDAS_Int32 num_users;
IVIDMC3_TASK_e task_ID;
XDAS_Int32 user_id;
} IVIDMC3_t

Brief description of each item is as below:

• XDAS_Int32 user_id:
  core ID, including core ID inside the chip and also the chip ID
  
• IVIDMC3_TASK_e task_ID:
  core task identification, can be global master, chip local master, or slave
• num_users:
  number of cores in the team, i.e., the number of cores running together for processing the same stream
• XDAS_Void *(*keyCreate) (XDAS_UInt8 *name, XDAS_Int32 user_id, IVIDMC3_KEY_SPACE_e key_space, XDAS_Int32 num_users, XDAS_Int32 *user_ids, IVIDMC3_KeyCfg_t *cfg):
  key assignment for Barrier, Shmem, Locks and Mailboxes; Barrier, Shmem and Locks resources are also initialized.
• XDAS_Int32 (*barrWait)(XDAS_Int32 user_id, XDAS_Void *barrHandle):
  function call which will block until all other users have also called it
• XDAS_Int32 *(*shmMap) (XDAS_Int32 user_id, XDAS_Void *shmemHandle)
  dynamically allocates shared memory region identified with handle "shmemHandle"; if region with same "shmemHandle" is already allocated, its base address is provided
• XDAS_Int32 (*shmSync)(XDAS_Int32 user_id, XDAS_Void *shmemHandle, XDAS_Int32 *shmem_base, XDAS_Int32 shmem_size, IVIDMC3_SYNC_ATTRIBS shmem_sync_attribs):
  synchronizes shared memory region
• XDAS_Int32 (*shmSyncWait)(XDAS_Int32 user_id, XDAS_Void *shmemHandle, XDAS_Int32 *shmem_transid):
  waits for synchronization operation to finish
• XDAS_Int32 (*lockAcquire) (XDAS_Int32 user_id, XDAS_Void *lockHandle):
  critical region lock acquire in multi-core environment; if spinlock has been succesfully acquired, this function returns 1; if same spinlock has been already acquired by another participant, this function returns 0
• XDAS_Int32 (*lockRelease) (XDAS_Int32 user_id, XDAS_Void *lockHandle):
  critical region lock release in multi-core environment
• XDAS_Int32 (*lockCheck) (XDAS_Int32 user_id, XDAS_Void *lockHandle):
  critical region lock check to see if any of the users currently have acquired the lock
• XDAS_Int32 (*mailBoxOpen)(XDAS_Void *mailBoxHandle): 
  opens a mailBox; this is a blocking call, it waits untill the mailBox creater is ready
• XDAS_Int32 (*mailBoxWrite) (XDAS_Void *mailBoxHandle, XDAS_UInt8 *buf, XDAS_UInt32 size, XDAS_UInt32 trans_id):
  writes into a mailBox to deliver a message to remote; it is a non blocking call 
• XDAS_Int32 (*mailBoxRead) (XDAS_Void *mailBoxHandle, XDAS_UInt8 *buf, XDAS_UInt32 *size, XDAS_UInt32 *trans_id):
  reads from a mailBox; it is a non blocking call
• XDAS_Int32 (*mailBoxQuery) (XDAS_Void *mailBoxHandle):
  polls mailBoxes for any available messages; it is a non blocking call

Useful Resources and Links

Product Download and Updates

For product download and updates, please visit the links listed in the table below.

	Product Download Link
MCSDK Video (2.1 GA) Download	http://software-dl.ti.com/sdoemb/sdoemb_public_sw/mcsdk_video/latest/index_FDS.html
MCSDK Video (2.2 Alpha) Download	http://software-dl.ti.com/sdoemb/sdoemb_public_sw/mcsdk_video/02_02_00_23/index_FDS.html http://software-dl.ti.com/sdoemb/sdoemb_public_sw/mcsdk_video/02_02_00_28/index_FDS.html
BIOS MCSDK Download	http://software-dl.ti.com/sdoemb/sdoemb_public_sw/bios_mcsdk/02_01_02_05/index_FDS.html
Desktop Linux SDK Download	http://software-dl.ti.com/sdoemb/sdoemb_public_sw/desktop_linux_sdk/01_00_00_07/index_FDS.html
C6678 Codec Download	http://software-dl.ti.com/dsps/dsps_public_sw/codecs/C6678/index.html

MCSDK Video Instructions

Please visit the links below to install MCSDK Video, run the video demos, and get the details on how the MCSDK Video demos are developed.

	Wiki Links
Getting Started Guide	MCSDK Video Getting Started for Linux MCSDK Video Getting Started for Windows Desktop Linux SDK Getting Started
Demo Guide	Run PCIe based Demos on Advantech DSPC-8681E & DSPC-8682E Run TFTP based Demos on TMDXEVM6678LXE
Development Guide	MCSDK Video Host (via PCIe) Development Guide MCSDK Video DSP Development Guide

Technical Support

For technical discussions and issues, please visit the links listed in the table below.

	Forum/Wiki Link
C66x Multicore forum	http://e2e.ti.com/support/dsp/c6000_multi-core_dsps/f/639.aspx
Multimedia Software Codecs forum	http://e2e.ti.com/support/embedded/multimedia_software_codecs/default.aspx
TI-RTOS forum	http://e2e.ti.com/support/embedded/f/355.aspx
Code Composer Studio forum	http://e2e.ti.com/support/development_tools/code_composer_studio/f/81/t/3131.aspx
TI C/C++ Compiler forum	http://e2e.ti.com/support/development_tools/compiler/f/343/t/34317.aspx
Embedded Processors wiki	http://processors.wiki.ti.com

Note: When asking for help in the forum you should tag your posts in the Subject with “MCSDK VIDEO”, the part number (e.g. “C6678”) and additionally the component (e.g. “NWAL”).