Quickly Getting Started on TI Codec Engine

Codec Engine Overview

Codec Engine is a framework that enables applications to easily instantiate and to work with algorithms using a common API. The API is the same for all of the following situations:

• The algorithm may run locally (on the GPP) or remotely (on the DSP or Coprocessor).
• The system may be a GPP+DSP, DSP-only, GPP+Coprocessor, or GPP-only system.
• All supported GPPs and DSPs have the same API.
• All supported operating systems have the same API. For example, Linux, DSP/BIOS, and WinCE.

The Codec Engine also supports real-time, non-intrusive visibility into codec execution. It provides APIs for accessing memory and overall CPU usage statistics and execution trace information.

The application code (or the middleware it uses) calls the Codec Engine APIs. Within the Codec Engine, the VISA APIs (the set of APIs in CE that interfaces with multimedia codec instances) can be used to access the core engine and the actual codecs, which may be local (run on the same processor as the application) or remote (run on a different processor from the application processor). In this document, we focus on the case where the codecs are executed remotely as it is the more complex scenario.

Internally, the VISA API use stubs and skeletons to perform a remote procedure call to interact with the algorithm. To send information across processor boundaries, DSP/BIOS LINK is used for interprocessor communication (IPC).

In order for an algorithm to be ‘executable’ by the Codec Engine, it needs to implement the interfaces defined by TI's XDM algorithm standard which is in turn based on the XDAIS Algorithm Standard. It is important for the algorithm developer to implement these interfaces correctly in order for the Codec Engine framework to operate seamlessly. Furthermore, the algorithm libraries and the DSP executable that runs a specific set of algorithms (also named a server) both need to be packaged up in a standard form that can be easily picked up by the build tools used by the Codec Engine. The packaging can be done by using a set of packaging wizards provided by TI. More information on this topic appears later in this document.

Note that the OMAP & Davinci Software for Dummies book helps to introduce the concepts below in the context of building an Audio/Video system.

Step 1: Start with the Release Notes

The release notes can be found at <CE_INSTALL_DIR>/codec_engine_x_xx_xx_ReleaseNotes.html. The release notes contain the following important pieces of info:

• Links to bundled documentation
• New features
• Validation info (i.e. dependencies)
• Device support
• Known issues
• Any discontinuities between the current release and previous releases
• Links to more documentation on building/running the examples

In order to learn how to use Codec Engine, you should start from the release notes. After going through the release notes, beginners should be able to find the documentation and examples they want. For example, clicking the “Documentation” link shown in the below figure will bring up links to all the bundled documentation.

Step 2: Get the dependent packages

Click on “Validation Info” as shown in above Figure, you will find that Codec Engine 2.21 works with following components:

• Framework Components 2.21
• XDAIS 6.21
• Linux Utils 2.21
• XDC Tools 3.10.03
• DSP/BIOS Link 1.60
• C6x Code Generation Tools version 6.0.16
• DSP/BIOS 5.33.02
• EDMA3 Resource Manager 1.05.00
• LPM 1.21
• MontaVista Linux v5.0
• Red Hat Enterprise Linux 3 (SMP)

Therefore, you need to make sure that the above components are installed in the DVSDK and referenced by Rules.make. Otherwise, you may fail to build the examples of Codec Engine.

So what are all these software components? You can find a brief introduction of each one from their release notes in their respective root directories. However, to simplify your life, here we will give you a simple introduction to help you find the proper resources:

1. Framework Components is mainly responsible for the management of DSP side memory and DMA resources. DSP algorithm developers and server integrators are recommended to learn about this module, so that they have an idea of how the framework allocates and grants resources to the algorithms. For details, please visit the Framework Components FAQ.
2. XDAIS is an algorithm standard. It defines the standard interface of a TI DSP algorithm. If a DSP algorithm developer wants his/her algorithm to be called through Codec Engine, he/she must make sure that the algorithm is XDAIS-compliant. The DSP algorithm developer needs to be familiar with this standard. For more info, please visit here.
3. LinuxUtils, a group of Linux utilities shipped with newer DVSDKs that provides the ability for user-mode applications to access the CMEM, EDMA, SDMA and VICP utility libraries (older DVSDKs may have some of these utilities shipped individually). See the Linux Utils Overview for further info.
   • CMEM: A memory manager that can grant contiguous memory for use as image/video/audio/speech data buffers.
   • EDMA: Refers to the “Enhanced DMA” incorporated on the DaVinci and OMAP families of C64x+ devices. It is a programming module that provides the ability for user-mode applications to request EDMA channels and to provide direct, memory-mapped access to the channel’s DMA registers (Framework Components contains a layer named ACPY to manage this direct access). It also provides “blocking” support for waiting for the completion of a transfer on a particular channel. This is the ARM-side equivalent to the EDMA3 resource manager in the EDMA3 Low Level Driver (described below).
   • SDMA: Refers to the “System DMA” incorporated on the OMAP35xx family of devices. Similar to the above EDMA module, it is a programming module that provides the ability for user-mode applications to request SDMA channels and operate on the channels using direct, memory-mapped access to the channel’s DMA registers (Framework Components contains a layer named SCPY to manage this direct access). It also provides “blocking” support for waiting for the completion of a transfer on a particular channel.
   • VICP: Refers to the “Video Imaging CoProcessor” subsystem incorporated on the Davinci family of devices. It is a VICP utility library, the main functionality of which is to provide access to the completion interrupts of various coprocessor resources.
4. XDC is a tool, similar to gmake. It is a part of a technology called RTSC (Real-Time Software Components). XDC calls the corresponding ARM tool chain or DSP code generation tools to build ARM or DSP executable files according to the build instructions. You do not need go deep into XDC at the beginning. Just know how to follow the build instructions by rebuilding the examples in Codec Engine. After you become more familiar with TI software (and if you are brave enough!), you can refer to the RTSC website for more information on the XDC tools: http://rtsc.eclipse.org/docs-tip/Main_Page.
5. DSP/BIOS Link is the S/W that implements the inter-communication between ARM and DSP. Codec Engine uses it ‘underneath the hood’ so to speak. DSP/BIOS Link needs to be configured with the ARM and DSP memory maps. For example, if your board’s DDR2 size is different from the amount of memory supplied on TI’s EVM, you would need to modify the memory map of the system. If you are using DSP/BIOS Link 1.30, you need to modify its configuration file and rebuild DSP/BIOS link. For DSP/BIOS Link 1.40+ users, you do not need to do this, as Codec Engine will automatically configure DSP/BIOS Link with the memory map defined in the DSP server. For details, please visit DSPLink Overview and Changing the DVEVM Memory Map.
6. C6x Code Generation Tools consists of the compiler, linker and other compilation utilities for the TI C6000 DSPs. Related articles can be found here.
7. DSP/BIOS is a real time operating system for the DSP that is freely provided by TI. DSP system/server integrator should learn about DSP/BIOS. Many helpful articles can be found here. Also, if you are new to DSP/BIOS, you can refer to the documentation in <BIOS_INSTALL_DIR>/packages/ti/bios/doc and the basic examples of DSP/BIOS in <BIOS_INSTALL_DIR>/packages/ti/bios/examples/basic to become be familiar with the OS.
8. EDMA3 Low Level Driver (LLD) contains the EDMA3 driver and the EDMA3 Resource Manager which can be used on the DSP of a heterogeneous platform for initiating DMA transfers and for managing DMA resources on the DSP. Some of the codecs on newer platforms, such as the dm6467, uses this driver instead of the ACPY3 module in Framework Components to perform DMA transfers. To request EDMA resources from this driver, the codec implements the IRES_EDMA3CHAN interface as defined in the Framework Components.
9. LPM is a power management module that integrates with the DSP/BIOS PWRM module to enable DSP power management on ARM-DSP devices.

The above components can be downloaded here with the exception of the code generation tools which are available here.

To ease the number of downloads and reduce the possibility of an inconsistent component mix you can elect to use 'full Codec Engine' - this contains a cetools directory which brings in the 'right' version of XDAIS, FC, Link, linuxutils etc.

Step 3: Know your development role

To develop ARM+DSP platform, usually we have three kinds of engineers: ARM application developer, DSP algorithm developer and DSP server integrator. If you are using a codec from TI or a 3rd party, you can skip the section for DSP algorithm developers. If you are using ARM+Coprocessor platforms (e.g. DM355), where the DSP is absent, you only need pay attention to the section for ARM application developers. You can read more info on the various development roles here.

Where to start for DSP algorithm developers?

Here we will not discuss how to develop DSP algorithms, only guidelines for DSP algorithm developers to make their codec callable by ARM via Codec Engine. (Refer to Codec Engine Algorithm Creator User's Guide. This doc describes RTSC codec packages and related .xs and .xdc files, Codec Engine 1.20 and latter version user can skip this, as we will introduce a tool that can automatically generate these files for you.)

1. Be familiar with XDAIS and XDM. XDM is an extension of the XDAIS algorithm standard. So, you need to learn about XDAIS first.
   • You can easily find the XDAIS and XDM user guides’ link in the XDAIS release notes located at <XDAIS_INSTALL_DIR>/release_notes_xdais_x_xx_xx.html.
   • In the directory <XDAIS_INSTALL_DIR>/examples/ti/xdais/dm/examples/g711, you can find a non-XDAIS g711 algorithm we downloaded from the public internet: g711_sun_internal.c. You will also find the corresponding the XDM wrapped version to create a compliant decoder and encoder: g711dec_sun_ialg.c (decoder) and g711enc_sun_ialg.c (encoder). It is a good example to study and to learn how to "XDMize" your own codec. Some of the code in this topic may also be of use.
   • XDAIS 6.10 and latter version includes a tool named QualiTI. This tool can check if your DSP algorithm is XDAIS compliance or not (not including XDM compliance check). For details, please refer to QualiTI_XDAIS_Compliance_Tool.
2. Be familiar with Framework Components. The Framework Components mainly include two modules, DSKT2 and DMAN3. DSKT2 is responsible for DSP-side memory management; DMAN3 is responsible for DSP-side EDMA management. DSP algorithms must request memory from DSKT2 and EDMA channels from DMAN3 (or the EDMA3 LLD). In order to use the QDMA (a feature of the EDMA that is used to quickly move data asynchronously) to move data, the algorithm can leverage the ACPY3 module of the Framework Components (FC). When using the FC to manage resources, we do not need to worry if there is any resource (memory and EDMA) conflict issue when the server integrator combines different DSP algorithms into the same project. Same as with other S/W components, you can get started on FC from its release notes. There is also a fastcopy demo in FC_INSTALL_DIR\packages\ti\sdo\fc\dman3\examples. This demo can help you to better understand how to leverage ACPY3 to perform DMA transfers. You may be tempted to use the EDMA directly in DSP program without requesting DMA resources through XDAIS interfaces and ultimately through DMAN3. The disadvantage of doing so is that the system integrator may encounter EDMA resource conflicts when combine your algorithm with another algorithms.
3. Know how to package up your algorithm by using the codec package wizard.
   • A lot of the metadata regarding the algorithm is better known by the algorithm writer (e.g. worst case stack size, DARAM and SARAM scratch requirements). Hence, the codec/algorithm developer should follow the Top 10 Codec Package Checklist, and package the algorithm with its metadata before handing it off to the DSP system/server integrator.
   • RTSC_Codec_And_Server_Package_Wizards
   • RTSC_Codec_Package_Wizard_FAQ

Where to start for DSP system/server integrators?

Usually the DSP algorithm developer provides an XDM-compliant codec package containing the codec's .lib (or .a64P) to DSP system integrator. The DSP system integrator will build a DSP server (DSP executable code with extension .x64P, in the same COFF format as the .out file built using CCS for those of you who are traditional DSP programmers). Refer to Codec Engine Server Integrator User's Guide for more details on DSP server development. In particular, the document describes RTSC-related files with extensions .xdc, .bld and other files, which are useful for users of older versions of Codec Engine. On the other hand, users of Codec Engine 1.20 and later versions do not need to write these from scratch, as we will introduce a tool that can automatically generate these files for you).

1. How to make the DSP Server if you have an XDM-compliant .lib (or .a64P) library file? TI provides a tool named RTSC Codec and Server Package Wizard. Refer to the URL below, and you will learn how to wrap the .lib (or .a64P) into a RTSC codec package (if this hasn’t already been done by the algorithm developer) and DSP server package, finally build a DSP executable (.x64P).
   • RTSC_Codec_And_Server_Package_Wizards
   • I_just_want_my_video_codec_to_work_with_the_DVSDK
2. If you are using an older version of Codec Engine than 1.20, please refer to the example in Codec Engine_INSTALL_DIR/examples/servers/video_copy. You have to study the files with extension .xdc, .xs, etc. in detail. These files are mentioned in Codec Engine Algorithm Creator User's Guide and Codec Engine Server Integrator User's Guide. Most users of CE version <1.20 modify the related files of video_copy directly to create their own RTSC codec package and DSP server package. (We would highly recommend for you to use >= Codec Engine 2.0 since it has the very useful createFromServer feature as well as improved debugging capabilities)
3. Review your resource allocation (and memory mapping) among the resource managers in the .cfg file. Here are some useful links.
   • Codec_Engine_configuration_en_breve#Memory_Type_Mapping
   • Codec_Engine_configuration_en_breve#Scratch_Configuration
   • Codec_Engine_configuration_en_breve#DMAN3_configuration_in_Codec_Engine.27s_configuration_file
4. The final step is to build the DSP executable (.x64P) after creating the DSP Server package. If you are using older versions of Codec Engine (< 1.20), click the “Examples” in Figure 2, and you will find the build instructions of Codec Engine example. We suggest you try to build the example by following the instructions because you will gain a better understanding of how to build the DSP server using this procedure. The key thing is to modify user.bld and xdcpaths.mak to set the correct paths to the Codec Engine dependencies and related tools. For newer versions of Codec Engine, the RTSC_Server_Package_Wizard can be used and its instructions contain steps on how to build the DSP server. Hint: you will need to learn how to run 'xdc release'. Refer to:
   • RTSC_Server_Package_Wizard_FAQ#What_do_I_need_to_do_after_the_wizard_has_successfully_output_the_files_needed.3F
5. If you are not clear on how to define the memory map used by the DSP, and to determine the size of the DDRALGHEAP and DDR memory sections, please refer to Changing the DVEVM Memory Map.

Note that if you are using Codec Engine >= 2.20 a Combo wizard is now available to help automate the creation of DSP-servers with many multimedia codecs.

Where to start for ARM application developers?

ARM-side applications call into the codecs using the VISA API of Codec Engine. So ARM application engineers must study the VISA API according to the application, learn how to configure the ARM application to use the Codec Engine using RTSC and finally build the ARM executable code (Refer to Codec Engine Application Developer User's Guide). As a bonus, this doc mentions how to debug the Codec Engine too.)

1. Know the flow of calling Codec Engine in ARM application, VISA API and Codec Engine API. You can choose to study the simple example in Codec Engine_INSTALL_DIR/examples/apps/video_copy or the more full-featured example in DVSDK_INSTALL_DIR/demos/encode, decode or encodedecode according to your comfort level. Refer to Configuring_Codec_Engine_in_Arm_apps_with_createFromServer.
2. Study the .cfg file in the example. This file is used to configure the Codec Engine. There is some introductory material on this topic in sprue67d.pdf.
3. Click on the Examples in the release notes as shown in Figure 2, you can then learn how to build ARM executable code.
4. To learn how to call Codec Engine in multiple threads, refer to Multiple_Threads_using_Codec_Engine_Handle.
5. Refer to the below docs to learn more about the TI DVSDK demo. This would give you an example of the structure of a multi-threaded ARM-side application.
   • EncodeDecode Demo for the DaVinci DVEVM/DVSDK 1.2 (Rev. A)
   • Encode Demo for the DaVinci DVEVM/DVSDK 1.2 (Rev. A)
   • Decode Demo for the DaVinci DVEVM/DVSDK 1.2 (Rev. A)
6. To help get you up to speed with Codec Engine faster, take a look at the DaVinci Multimedia Application Interface (DMAI) and its examples. DMAI, which is provided in source code format, is a thin utility layer on top of the operating system (Linux or DSP/BIOS) and the Codec Engine to assist in quickly writing portable applications on a DaVinci/OMAP platform. Though the Codec Engine examples are great for getting an introduction to the VISA API, DMAI and its examples gives a better overview of how the VISA API should be used in a real-world application. It takes into consideration buffer management at the application level, and also makes it easier to interact with device drivers. The TI demos themselves leverage DMAI extensively.
   • One tip is that DMAI contains a set of examples with the ‘*_io’ suffix in their names. The input and output to these examples are solely file-based and do not necessitate device drivers. They are ideal for running a codec in isolation and to learn its usage through the codec engine framework without the burden of dealing with hardware drivers.
   • To get started with DMAI, see DMAI.

Some Common Questions:

1. If you have a question, the first thing to do is to first visit Codec_Engine_FAQ. It is possible that your answer is already there!
2. Some developers have no DSP development experience or no emulator to debug DSP. You can refer to the example below to build a very easy “Hello World” example, so that you can gain a general understanding on how the ARM works with the DSP. How_to_build_an_ARM/DSP_Hello_World_program_on_the_DaVinci_EVM
3. Because TI provides the source code of video_copy in Codec Engine example, some engineers (especially those using Codec Engine previous to 1.20) modified this example directly to use their own codec. So, they had to modify the buffer and parameters passed between ARM and DSP. Usually, the first step is to make sure that ARM application can successfully pass the buffers & other parameters to the DSP and that the DSP can successfully pass the processed buffers back to the ARM application. After ensuring that the interprocessor communication is working properly, you can better isolate whether the issue comes from the ARM side application or from the DSP codecs when you modify the example to run your own content. By the way, pay attention to the comments in the video_copy codecs, they are a source of guidance to help you figure out which part of the code can be deleted, modified or kept. If you need to extend the data structures of XDM, please refer to Extending_data_structures_in_xDM. However, note that whenever an interface to a codec is extended, it makes the application code codec-specific, hence it is always best to stick to what's available in the interface as it was defined and avoid extending the interface whenever possible. TopTenCodecPackageCheckList#3._VISA_XDM_API_usage
4. For Codec Engine DSP cache coherence questions, please refer to Cache_Management .
5. How to debug Codec Engine?
   • Use the Codec Engine trace. For example, we can often find the cause of failed Engine_Open and codec instance creation calls by printed trace.
     • For Codec Engine 2.0 and newer version, please refer to: Easy_CE_Debugging_Feature_in_CE_2.0
     • For debugging CE applications on heterogeneous platforms with the ARM running Linux, CE_DEBUG is a very easy way to obtain debug trace from CE and FC. See: CE_DEBUG
     • For Codec Engine 1.x versions, please refer to: TraceUtil
   • To debug the DSP server of a Codec Engine application by using CCS, please refer to: Debugging_the_DSP_side_of_a_CE_application_on_DaVinci_using_CCS and Debugging_the_DSP_side_of_a_DSPLink_application_on_OMAP_using_CCS.
   • Use the SOC Analyzer. You can use it to benchmark both ARM and DSP codes: SoC_Analyzer. Alternatively check out this article on Codec_Engine_Profiling.
   • Try to find the resource via: Category:Debug
6. In order to leave more CPU resources to the codecs, most engineers may want to learn about the overhead of Codec Engine. Please refer to Codec Engine Overhead.
7. How do you benchmark DSP code?
   • There is a 64-bits H/W Time Stamp Counter on the C64x+ core. It runs at same frequency as the CPU. The easy way is to use the lower 32-bits of the counter (TSCL). Note that the upper 32-bits (TSCH) are used by ARM in DM644x.

<syntaxhighlight lang="c">

 #include <c6x.h>
 void main (){

 // :
 // :
 // :

 // start time stamp counter with a dummy-write
 // runs forever once started
 TSCL=0;

 // :
 // :
 // :

 t1=TSCL;
 my_code_to_benchmark();
 t2=TSCL;
 printf(“# cycles ==%d\n”, (t2-t1));
 }

</syntaxhighlight>

More details on Benchmarking can be found in Media:C64p_cgt_optimization.pdf

8. How to build DSP assembly or linear assembly code under Linux when building using the XDC tools?

• In Codec Engine_INSTALL_DIR/packages/config.bld after the line

<syntaxhighlight lang='javascript'>

 var C64P = xdc.useModule(‘ti.targets.C64P’);

</syntaxhighlight>

Add this:

<syntaxhighlight lang='javascript'>

 C64P.extensions[“.sa”] = {
       suf: “.sa”, typ: “asm:-fl”
  }

</syntaxhighlight> or <syntaxhighlight lang='javascript'>

 C64P.extensions[“.asm”] = {
   suf: “.asm”, typ: “asm:-fa”
 }

</syntaxhighlight> This is basically saying for all files with suffix .sa, assume it is a linear assembly file, and for all files with extension .asm, assume it is a hand-assembly file. The appropriate tools will then be used to compile these files.

Final remarks

In this document, we just highlight how to quickly get started on TI Codec Engine. Many specific problems are not covered. Please read the corresponding docs in the release notes of S/W components. Also, do not forget [1]. They are a valuable source of updated information.