Texas
	  Instruments Technology for
	Innovators

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.

More details are available at the Codec Engine Examples Overview wiki article.


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
    |   `---system_files        Linux scripts describing which .ko's are required and how to load them for different platforms
    |       +---DM355
    |       +---DM357
    |       +---DM6446
    |       +---DM6467
    |       +---OMAP2530
    |       +---OMAP3530
    |       `---OMAPL137
    `---ti
        `---sdo
            `---ce
                `---examples    Buildable example codecs, DSP servers, and ARM and/or DSP 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
                    |   +---viddec_copy
                    |   +---videnc1_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
                        +---speech_copy_LAD
                        +---universal_copy
                        +---vidanalytics
                        +---video1_copy
                        +---video2_copy
                        +---video2split_copy
                        +---video_copy
                        `---vidtranscode

Running the video_copy example application on the DM644x and DM6467 DVEVMs

We assume you have your DVEVM 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 necessary files into a directory visible from the DVEVM board (e.g. an NFS or hard drive mount, etc). Those files are:

Build the examples as described below, and copy into the same directory as above the DSP server and GPP client executables (do it for simplicity; the executables do not need to be in the same directory where kernel modules are, but the executables themselves must sit in the same directory together). For example, to run the video_copy example, you need:

Also copy the sample input video file to the same directory:

Boot the EVM, change to the directory where you have copied all these files, and run
    sh ./loadmodules.sh

This script installs drivers necessary for your device (e.g. CMEM and Link) with appropriate information about the memory map.

You can find more information below about the default memory map. The CMEM module above is instructed to set aside two pools, one containing 20 4K buffers, the other containing two 1MB buffers. This is good enough for the video_copy application; your application will likely need different settings.

When you run the script, you should see the following output:

    $ ./loadmodules.sh
    cmem initialized 3 pools between 0x87800000 and 0x88000000
    dsplinkk: no version for "struct_module" found: kernel tainted.
    DSPLINK Module (1.61) created on Date: XXX XX XXXX Time: XX:XX:XX

Next, run the client application, which will automatically load the DSP server image:

    ./app.out

You will see several output lines:

    App-> Application started.
    CEapp-> Allocating contiguous buffer for 'input data' of size 1024...
    CEapp-> Contiguous buffer allocated OK (phys. addr=0x87fff000)
    CEapp-> Allocating contiguous buffer for 'encoded data' of size 1024...
    CEapp-> Contiguous buffer allocated OK (phys. addr=0x87ffe000)
    CEapp-> Allocating contiguous buffer for 'output data' of size 1024...
    CEapp-> Contiguous buffer allocated OK (phys. addr=0x87ffd000)
    App-> Processing frame 0...
    App-> Processing frame 1...
    App-> Processing frame 2...
    App-> Processing frame 3...
    App-> Processing frame 4...
    App-> Finished encoding and decoding 4 frames
    App-> Application finished successfully.

To verify that the application has executed correctly, verify the newly created out.dat file against the input in.dat file. They should be identical.


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.

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 codecs running on the same processor should be built. This is typically set for single core devices (e.g. DM365, DM6437), but can als be set for multi-core devices (e.g. OMAP3530, DM6446) where the app and codec run on either the GPP or the DSP.

APP_CLIENT and DSP_SERVER typically go together, and indicate that all examples that support remote execution of codecs 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 GPP-side apps will be built (for the appropriate GPP OS's and hardware platforms set in GPPOS and DEVICES respectively).

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 codecs) will be built.

2.4 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.

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 DSP servers

Note that this is only necessary for dual processor environments, like DM6446.

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/video_copy), and type

    gmake clean
    gmake

Note: when developing your own codecs and applications, you will likely take one of the DSP server sample and modify it to suit your needs. These are the source files for this server application that you need to know about:

6. Build the GPP applications

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

    gmake clean
    gmake

7. Copy files to the target and run

For a given application you want to run, you need to copy that application's executable to the target, and if your application requires a DSP server, you need to copy that DSP server to the target as well. (You can see which DSP server -- a DSP binary with .x64P or .x674 extension -- is required by the application if you look at the application's .cfg file.) In addition, you should copy the input data file "in.dat" to the target, keeping the relative position between the application executable and the in.dat file.

Also, you must make sure that all the required kernel modules (.ko's) for your target are loaded (tyically via the loadmodules.sh shell script.)

Example 1: Running the audio_copy example on evmDM6446:
Assuming you included DM6446 in DEVICES, LINUX_GLIBC in GPPOS and APP_CLIENT in PROGRAMS, the ARM-side of the audio_copy example for evmDM6446 will be built into the examples/ti/sdo/ce/examples/apps/audio_copy/bin/ti_platforms_evmDM6446 directory. Copy the app_remote.xv5T file to the target, along with in.dat -- which is in the same directory, so on the target both files should be in the same directory, as well.

The remote.cfg file in that directory lists "all.x64P" as its DSP server image, so you must copy the all.x64P DSP executable for evmDM6446 from examples/ti/sdo/ce/examples/servers (more precisely from examples/ti/sdo/ce/examples/servers/all_codecs/bin/ti_platforms_evmDM6446/) to the target, in the same directory where the ARM-side executable is.

Example 2: Running the video1_copy example on evmDM355:
The evmDM355 only has the ARM, so we don't copy any DSP files on the target. From the build directory ti/sdo/ce/examples/apps/video1_copy/ we copy bin/ti_platforms_evmDM355/app_local.xv5T on the target, and the in.dat file as well, making sure in.dat is in the same directory on the target as the ARM executable.


Memory map

For information on the default DM6446 memory map -- as addressed by the kernel module loading scripts and DSP/BIOS configuration files (.tcf scripts) -- and instructions on how to change this map, please refer to http://tiexpressdsp.com/index.php?title=Changing_the_DVEVM_memory_map

Last updated: December 2, 2010