Texas Instruments Technology for Innovators(tm)

Build/Run Instructions for Codec Engine Examples

General Information

This page explains how to build the examples provided in the Codec Engine (CE) product.

Examples currently contain the simple pass-through (copy) codecs, implemented in the XDM algorithm standard.

See the Codec Engine Examples User's Guide for details on which examples demonstrate particular features.

Requirements

See the release notes for the specific software and hardware components this release of Codec Engine has been validated against.

Directory Structure

This section describes the layout under the examples directory. In most cases, these examples are XDC packages, and there are links to the autogenerated XDC documentation. In some cases, the examples are not proper XDC packages, and documentation is provided in other means (see the specific example's directory). 

examples
    +---apps

    `---ti
        `---sdo
            `---ce
                `---examples    Buildable example codecs, servers, and apps
                    +---codecs
                    |   +---auddec1_copy
                    |   +---auddec1_ires
                    |   +---auddec_copy
                    |   +---audenc1_copy
                    |   +---audenc_copy
                    |   +---g711
                    |   +---imgdec1_copy
                    |   +---imgdec_copy
                    |   +---imgenc1_copy
                    |   +---imgenc_copy
                    |   +---scale
                    |   +---sphdec1_copy
                    |   +---sphdec_copy
                    |   +---sphenc1_copy
                    |   +---sphenc_copy
                    |   +---universalcopy
                    |   +---vidanalytics_copy
                    |   +---viddec1_copy
                    |   +---viddec2_copy
                    |   +---viddec2split_copy
                    |   +---viddec3_copy
                    |   +---viddec_copy
                    |   +---videnc1_copy
                    |   +---videnc2_copy
                    |   +---videnc_copy
                    |   `---vidtranscode_copy
                    |
                    +---extensions
                    |   `---scale
                    |
                    +---servers
                    |   `---all_codecs
                    |
                    `---apps
                        +---audio1_copy
                        |   +---async
                        |   `---sync
                        +---audio1_ires
                        +---audio_copy
                        +---image1_copy
                        +---image_copy
                        +---scale
                        +---server_api_example
                        +---server_trace
                        +---speech
                        +---speech1_copy
                        +---speech_copy
                        +---universal_copy
                        +---vidanalytics
                        +---video1_copy
                        +---video2_copy
                        +---video2split_copy
                        +---video3_copy
                        +---video_copy
                        `---vidtranscode

Building the examples: step-by-step instructions

1. [Optional] Copy the entire "examples" tree out of the product

This step is optional, but recommended if you plan to modify the samples in any way. It will ensure you have a backup copy of the original examples, as provided by the Codec Engine product.

Important: throughout the rest of this document, we will use the following notation:

2. Edit xdcpaths.mak to customize the build for your software installation and your hardware

At the root of the Examples directory is a build-related file named xdcpaths.mak that all Codec Engine example makefiles include. All users must edit this file to specify where various software components needed by Codec Engine are on their system, and often to narrow the list of hardware platforms to build for (thereby reducing the example build time and possibly the scope of external components).

The variables defined in xdcpaths.mak that most users must assign are: DEVICES, GPPOS, PROGRAMS, and various *_INSTALL_DIR variables. Each are described more below as well as in comments throughout the xdcpaths.mak file.

Advanced users will note that these GNU make-based variables can be overridden on the command line. As a result, it is possible to tailor these makefiles without modifying them - by simply setting the variables on the command line when running "gmake".

2.1 xdcpaths.mak's DEVICES variable

The DEVICES variable indicates which hardware platforms should be built for. Most users are only interested in building for a single platform, and the other platforms can be removed from the DEVICES variable.

Note that there is a one-to-one mapping between the "short name" in the DEVICES macro and the "platform package" which is used. For example, the OMAP3530 value in DEVICES maps to the ti.platforms.evmOMAP3530 platform package.

2.2 xdcpaths.mak's GPPOS variable

The GPPOS variable indicates which GPP (General Purpose Processor, often an ARM) OS's should be built for. Most users are only interested in building for a single GPP OS (e.g. WinCE or Linux glibc or Linux uClibc), and the other GPP OS's can be removed from the GPPOS variable.

Note that there is a one-to-one mapping between the "short name" in the GPPOS macro and the "target module" which is used. For example, the WINCE value in GPPOS maps to the microsoft.targets.arm.WinCE target Module.

If you are on a single-core or multi-core BIOS-only system, the GPPOS variable is ignored.

2.3 xdcpaths.mak's PROGRAMS variable

The PROGRAMS variable indicates roughly which system architecture the examples should be built for. Generally, Codec Engine supports "local" and "remote" codecs, and as a result there are 3 types of executables that can be built - APP_LOCAL, APP_CLIENT and DSP_SERVER.

APP_LOCAL indicates that all examples that support the apps and algorithms running on the same processor should be built. This is typically set for single core devices (e.g. DM365, DM6437), but can also be set for multi-core devices (e.g. OMAP3530, DM6446, C6472). In heterogenous multi-core systems (e.g. OMAP3530), a 'local' app will be built for each core. In homogeneous multi-core systems (e.g. C6472), a 'local' app will be built for a single core, but often it can be loaded on all cores.

APP_CLIENT and DSP_SERVER typically go together, and indicate that all examples that support remote execution of algorithms should be built. If DSP_SERVER is set in the PROGRAMS variable and an appropriate multi-core platform is set in the DEVICES variable, the examples in examples/ti/sdo/ce/examples/servers may be built. APP_CLIENT indicates the "client" side of a "client/server" system, so 'client' apps (e.g., GPP-side apps for heterogenous systems and 'master' core apps for homogeneous systems) will be built.

Note that you can set all 3 (APP_LOCAL, APP_CLIENT, and DSP_SERVER) or any subset of them. As a further example, if only DSP_SERVER is set, no applications will be built, but all components required to create a server (including algorithms) will be built.

2.4 xdcpaths.mak's *_FORMAT variable

The *_FORMAT variables (e.g. C64P_FORMAT, C674_FORMAT) indicates which file format the binaries should be built for. On some architectures, Codec Engine supports multiple binary file formats (e.g. COFF and ELF) and and this variable describes which file formats should be built. This variable can be set to more than one value (e.g. setting it to "ELF COFF" will build both ELF and COFF if Codec Engine supports it.

If you are on an architecture where only one binary file format is supported, there may not be a variable you need to set. For example, there is no "WINCE_FORMAT" since we only support one type of WinCE binary.

2.5 xdcpaths.mak's various *_INSTALL_DIR, CGTOOLS_* and CC_* variables

The xdcpaths.mak file also contains variables to indicate where products which Codec Engine may depend on are installed. The list of dependent products is a direct result of what values are assigned in the DEVICES, GPPOS and PROGRAMS variables. For example, if you've set PROGRAMS to only APP_LOCAL, DEVICES to only DM355, and GPP_OS to LINUX_UCLIBC, you aren't required to provide DSPLINK_INSTALL_DIR, BIOS_INSTALL_DIR, CGTOOLS_V5T or CC_V5T

Further, if you're using a "full" installation of Codec Engine (see http://tiexpressdsp.com/index.php?title=Codec_Engine_FAQ#Why_do_some_distributions_have_a_cetools_directory_and_others_don.27t.3F for more details), many of the dependencies will be "auto-assigned" for you to the cetools/packages directory.

Also, if you're building for a heterogenous device, and only want to build for a subset of the cores, you can set the toolchain for the _other_ cores (that you don't want to build for) to empty. Make sure you don't accidentally set the variable to a 'space' character, the value must actually be an empty string - that is, there should be no space after the '=' char.

Please refer to the comments throughout xdcpaths.mak for more details.

Each directory contains a GNU makefile which enables you to build the sample in the current directory. Top-level directories also contain a makefile which steps into subdirectories and builds all the examples under the parent directory.

FYI, the xdcpaths.mak file is included by the individual makefiles for all the example codecs, servers, and applications.

Please keep in mind that MOST BUILD TROUBLES OCCUR WHEN ONE OF THE VARIOUS *_INSTALL_DIR VARIABLES ARE INCORRECT! Make sure there are no extra spaces (check the end of lines!), that every individual path (segment separated by the semicolon) is correct, character for character, and the build process is very likely to go smoothly.

3. Build example codecs

Change directory to ti/sdo/ce/examples/codecs and type

    gmake clean
    gmake

Alternatively, you can change into a specific codec's directory (e.g. ti/sdo/ce/examples/codecs/viddec_copy), and type

    gmake clean
    gmake

4. Build example extensions

Change directory to ti/sdo/ce/examples/extensions and type

    gmake clean
    gmake

Alternatively, you can change into a specific example extension directory (e.g. ti/sdo/ce/examples/extensions/scale), and type

    gmake clean
    gmake

5. Build example servers

Note that this is only necessary for multi-core environments, like DM6446, OMAP3, C6472, etc.

Change directory to ti/sdo/ce/examples/servers and type

    gmake clean
    gmake

Alternatively, you can change into a specific server's directory (e.g. ti/sdo/ce/examples/servers/all_codecs), and type

    gmake clean
    gmake

Note: when developing your own algorithms and applications, you will likely take one of the server examples and modify it to suit your needs.

6. Build the applications

Change directory to ti/sdo/ce/examples/apps (where the makefile is) and type

    gmake clean
    gmake

Running the example applications

Most of the Codec Engine examples are designed to support both local and remote application configurations, and are portable to multiple platforms. Linux based systems require the loading of one or more kernel drivers in order to run the examples. This is described in the following section.

Installing Kernel Drivers for Linux Based Systems

Linux based systems require the CMEM driver to be loaded, and if remote processing is to be supported, the SysLink driver most also be loaded. A shell script, loadmodules.sh, is provided to facilitate this.

We will use the following additional notation:

We assume you have your EVM properly set up, and that you are able to mount an NFS.

You must pass the MEM=120M (or less than 120M) parameter to your Linux kernel from your u-boot prompt, or you must have your Linux kernel configured to use no more than 120MB of physical memory. Read more in the following sections about the memory map.

Copy the following necessary files into a directory visible from the EVM board (e.g. an NFS or hard drive mount, etc):

The following line in loadmodules.sh, specifies the start and end addresses of CMEM memory, and instructs the CMEM module to set aside three pools, one containing 20 4K buffers, one containg 10 128K buffers, and the third containing two 1MB buffers.

CMEM_MODPARAMS="phys_start=0xa0000000 phys_end=0xa07fffff pools=20x4096,10x131072,2x1048576"

This is good enough for the Codec Engine example applications; your application will likely need different settings.

When you run the loadmodules.sh script, you should see output similar to the following (if the output does not appear on the console, try running dmesg to see the output): 

    $ ./loadmodules.sh
      SysLink version : internal sl tree
      SysLink module created on Date:Jul 15 2011 Time:15:23:23
      Trace disabled
      Trace entry/leave prints enabled
      Trace SetFailureReason enabled
      Trace class 3
      CMEMK module: built on Mar 15 2011 at 16:05:39
        Reference Linux version 2.6.37
        File /db/atree/library/trees/ce/ce-s13x/imports/ti/sdo/linuxutils/cmem/src/module/cmemk.c
      allocated heap buffer 0xc9000000 of size 0x4ac000
      cmemk initialized

Command Line Options for Linux Examples

In order to support multiple platforms and configurations, most Codec Engine examples running on a Linux-based GPP have the following usage format:

app.xv5T [-p proc] [-e engine] [-s serverSuffix] [-m mapFile] input-file output-file

The options are: