Codec Engine

Codec Engine Overview

What is the Codec Engine?

From the application developer’s perspective, the Codec Engine is a set of APIs that you use to instantiate and run XDAIS algorithms. A VISA interface is provided as well for interacting with XDM-compliant XDAIS algorithms.

The API is the same for all of the following situations:

• The algorithm may run locally (e.g. on the ARM of an OMAP3) or remotely (on the DSP of an OMAP3).
• The system may be a GPP+DSP (e.g. OMAP3), DSP-only (e.g. DM6437), homogeneous multi-core DSP (e.g. C6472), or GPP-only (DM365) system.
• All supported GPPs and DSPs have the same API.
• All supported operating systems (e.g. Linux, WinCE, BIOS, etc.) have the same API.

Any XDM algorithm is compliant with the eXpressDSP Algorithm Interface Standard (XDAIS). Additionally, it implements the XDAIS-DM (XDM) interface, an extension to the XDAIS standard that provides support for digital media encoders, decoders, and codecs. The XDM specification defines APIs for digital media codecs by class, with extensions defined for video, imaging, speech, and audio codec classes.

The XDM interfaces divide codec algorithms into four classes: Video, Image, Speech, and Audio (VISA). VISA reflects this XDM interface. One set of APIs is provided per codec class. Thus, MP3 can be replaced with WMA without changing the application source code. Only the configuration needs to be changed.

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 Codec Engine libraries are provided in binary form, ensuring application libraries independently built against same Codec Engine release are always compatible; Codec Engine does not require rebuilding its libraries. Beginning with the Codec Engine 2.20 release, full source code is provided, and [although officially unsupported] there is documentation for Rebuilding Codec Engine from source.

Why Should I Use It?

The Codec Engine is designed to solve some common problems associated with developing system-on-a-chip (SoC) applications. The most significant problems include:

• Debugging in a heterogeneous processor environment can be painful. There are multiple debuggers and complex bootstrapping.
• Different implementations of the same algorithm, such as MP3, have different APIs. Changing to a more efficient algorithm involves significant recoding.
• Portability issues are compounded with two processors. You may want to port to a different board with a newer DSP or a newer GPP.
• Some algorithms may run on either the GPP or the DSP. To balance system load, “low complexity” algorithms can run on a GPP, but the definition of “low” changes over time. If changing the location where the algorithm runs were easy, you wouldn’t have to weigh performance issues against the difficulty of changing the application.
• For market success, most applications need to support multiple codecs to handle the same type of media. For example, an application might need to support three or four audio formats.
• Programmers with a GPP (general-purpose processor) view typically don’t want to have to learn to be DSP programmers. And, they don’t want to have to worry about a DSP’s complex memory management and DSP real-time issues.

The Codec Engine addresses these problems by providing a standard software architecture and interfaces for algorithm execution.

The Codec Engine is:

• Easy-to-use. Application developers specify what algorithm needs to be run, not how or where.
• Extensible and configurable. New algorithms can be added by anyone, using standard tools and techniques.
• Portable. The APIs are target, platform, and even codec independent.

Where Does the Codec Engine Fit into My Architecture?

The application code (or the middleware it uses) calls the Codec Engine APIs. Within the Codec Engine, the VISA APIs use stubs and skeletons to access the core engine and the actual codecs, which may be local or remote.

The following figure shows the general architecture of an application that uses the Codec Engine. It also shows the user roles involved in creating various portions of the application.

Codec Engine Application Architecture

The application (or middleware it uses) calls the core Engine APIs and the VISA APIs. The VISA APIs use stubs to access the core engine SPIs (System Programming Interfaces) and the skeletons. The skeletons access the core engine SPIs and the VISA SPIs. The VISA SPIs access the underlying algorithms.

The following figure is a modification of the previous diagram that shows how this architecture is distributed in a GPP+DSP system. In this example, yellow portions run on the GPP, and grey portions run on the DSP. That is, the video encoder skeleton and the video encoder codecs are on the DSP and the application and video encoder stubs are on the GPP.

Codec Engine Application Architecture for GPP+DSP

Since Codec Engine is flexible, alternate diagrams could be shown for GPP-only and DSP-only systems.

What Are the User Roles?

The Codec Engine has several customer use cases, from application developers to codec authors. In some cases, these roles may be played by a single person. In other development environments, a different developer may be assigned each role.

Because Codec Engine is very portable and configurable and can run in many different environments, the descriptions of these roles are intentionally generalized. When applicable, specific hardware and software environments are described after the general descriptions.

Where Can I Get More Information?

The release_notes*.html file at the top of the Codec Engine installation provides general information, information about changes in the latest version, devices supported and validation information, known issues, and links to online documentation provided with the Codec Engine. The online documentation provided with the Codec Engine is as follows:

• Codec Engine API Reference.

CE_INSTALL_DIR/docs/html/index.html

• Codec Engine SPI Reference Guide.

CE_INSTALL_DIR/docs/spi/html/index.html

• Configuration Reference Guide.

CE_INSTALL_DIR/xdoc/index.html

• Example Build and Run Instructions.

CE_INSTALL_DIR/examples/build_instructions.html

For information about XDM, see the XDAIS-DM (Digital Media) User Guide (SPRUEC8).

For platform-specific help, see the Getting Started Guide for your platform.

Installation and Setup

This section describes steps you may need to perform for installation and setup.

Installing Codec Engine

The Codec Engine may have already been installed on your system as part of a larger installation. For example, the DVSDK software installation installs the Codec Engine in the codec_engine_#_## subdirectory of the main DVSDK software directory.

If you have downloaded the Codec Engine as a standalone piece of software, follow these instructions:

1. Copy the codec_engine_#_##.tar.gz file to the directory where you want to install the software (where #_## is the version number).
2. Unzip the file with an unzip utility.
3. Open the release_notes*.html file at the top level of the installation.
4. Follow the steps to build and run Codec Engine examples.

Packages and Repositories

Codec Engine is delivered as a set of "packages". A package corresponds to a directory that contains all the files required for an independent component plus metadata about that component.

Each package has a unique name that reflects its directory name. For example, "ti.sdo.ce.audio" is the name of a package that must be in a directory whose path ends with "/ti/sdo/ce/audio". Packages may be nested within another package. "Package repositories" are directories that contain one or more packages.

A package places its metadata in a sub-directory named "package". This sub-directory contains metadata files that you do not need to be concerned with unless you are creating your own packages. A package also always contains a file named “package.xdc”, which declares the package’s name and an optional compatibility key. This key is used to ensure compatibility between packages.

As an application developer using the Codec Engine, the main reason you should be aware of packages is to understand the #include paths you need to use for header files. These paths are relative to a package repository. The package repositories used by the Codec Engine are part of the "package path", which matches the sequence of –I options you need to pass to the compiler when compiling source files that use a module in the Codec Engine. Since packages all have unique names, even if they are in different repositories, the #include statement tells you which package contains a particular header file.

The Codec Engine distribution contains several package repositories:

• The core set of Codec Engine packages are in a repository named "packages". This corresponds to the CE_INSTALL_DIR/packages directory.
• The examples are distributed in a separate repository named "examples". This corresponds to the CE_INSTALL_DIR/examples directory.
• Some distributions of Codec Engine include a third repository containing a collection of dependant packages for convenience. This repository is named "cetools.packages", which corresponds to the CE_INSTALL_DIR/cetools/packages directory.

The XDC Tools provide an xdcpkg command (in the XDC_INSTALL_DIR/bin directory) that identifies all the packages in a directory. For example:

xdcpkg –a –l .

Directory Structure

The top-level directories within the Codec Engine installation are as follows:

• cetools. [optional] Contains dependent packages used by the Codec Engine.
• docs. Contains documentation files.
• examples. Contains a number of example applications.
• packages. The Codec Engine packages. The /ti/sdo/ce subdirectory (that is, the ti.sdo.ce package) contains the VISA APIs and the stubs and skeletons that enable remote invocation of the VISA APIs. The /ti/sdo/ce/osal subdirectory contains the OS abstraction layer.
• xdoc. Contains documentation files for the packages in the Codec Engine distribution.

Using the Sample Applications

This section describes how to test the sample applications provided with the Codec Engine.

Overview

The CE_INSTALL_DIR/examples repository contains a collection of example packages demonstrating the various use cases that Codec Engine users may develop. These example packages fall into the following categories:

• ti.sdo.ce.examples.codecs namespace. (Note that the codecs in the ti.xdais.dm.examples namespace are copies of those distributed with XDAIS 5.20+.)
• Extensions. Contains a scale example that extends the VISA API. These are in the ti.sdo.ce.examples.extensions namespace.
• Servers. Contains two pre-configured and pre-linked Codec Servers (see Section 1.4.2, Server Integrator). These are in the ti.sdo.ce.examples.servers namespace.
• Applications. Contains example applications. These are in the ti.sdo.ce.examples.apps namespace.

The "copy" encoders/decoders replicate data rather than compressing/decompressing it. This is for simplicity in the examples. The Codec Engine distribution includes copy encoders/decoders for audio, image, speech, and video data for all XDM interfaces.

The two pre-configured Codec Servers are: all_codecs and video_copy. If you are using the DVSDK, you use these pre-configured Codec Servers when evaluating the board and learning to use the Codec Engine. Note that the memory maps that these Codec Servers are configured with matches that of the DVSDK.

See the CE_INSTALL_DIR/examples/build_instructions.html file for a full list of examples and links to details about them.

Building Applications

To build the example applications provided with the Codec Engine, follow the steps in the CE_INSTALL_DIR/examples/build_instructions.html file. These steps may change in different versions of the Codec Engine, so you should review this document whenever you upgrade to a new version.

In general, you will optionally make a copy of the examples tree, edit the user.bld file to specify the locations of your tools, edit various makefiles, and then build the examples.

Running Applications

To run the example applications provided with the Codec Engine, follow the steps in the CE_INSTALL_DIR/examples/build_instructions.html file. This document provides platform-specific and version-specific steps for running applications.

Additional Documents and Resources

• Codec Engine Server Integrator User's Guide
• Codec Engine Algorithm Creator User's Guide (SPRUED6)
• Codec Engine Application (API) Reference Guide - Also distributed in $(CE_INSTALL_DIR)/docs/html/index.html
• Configuration Reference Guide - Also distributed in $(CE_INSTALL_DIR)/xdoc/index.html
• Example Build and Run Instructions. - Note these occasionally change, so refer to your build instructions distributed in $(CE_INSTALL_DIR)/examples/build_instructions.html
• XDM API Reference - Also distributed in $(XDAIS_INSTALL_DIR)/docs/html/index.html
• XDAIS-DM (Digital Media) User Guide (SPRUEC8)
• TMS320 DSP Algorithm Standard Rules and Guidelines (SPRU352)
• TMS320 DSP Algorithm Standard API Reference (SPRU360)
• TMS320 DSP Algorithm Standard Developer’s Guide (SPRU424)
• TMS320 DSP Algorithm Standard Demonstration Application (SPRU361)
• Codec Engine Overview
• Integrating a Codec Engine