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.

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 RTSC packages, and there are links to the autogenerated RTSC documentation. In some cases, the examples are not proper RTSC packages, and documentation is provided in other means (see the specific example's directory). 

examples
    `---ti
        `---sdo
            `---ce
                `---examples
                    +---codecs
                    |   +---auddec1_copy
                    |   +---auddec_copy
                    |   +---audenc1_copy
                    |   +---audenc_copy
                    |   +---g711
                    |   +---imgdec1_copy
                    |   +---imgdec_copy
                    |   +---imgenc1_copy
                    |   +---imgenc_copy
                    |   +---scale
                    |   +---sphdec1_copy
                    |   +---sphdec_copy
                    |   +---sphenc1_copy
                    |   +---sphenc_copy
                    |   +---viddec1_copy
                    |   +---viddec_copy
                    |   +---videnc1_copy
                    |   +---videnc_copy
                    |   `---vidtranscode_copy
                    |
                    +---extensions
                    |   `---scale
                    |
                    +---servers
                    |   +---all_codecs
                    |   `---video_copy
                    |
                    `---apps
                        +---audio1_copy
                        +---audio_copy
                        |   +---dualcpu
                        |   `---singlecpu
                        +---image1_copy
                        +---image_copy
                        +---scale
                        +---speech
                        |   +---dsponly
                        |   `---linuxonly
                        +---speech1_copy
                        +---speech_copy
                        +---video1_copy
                        +---video_copy
                        |   +---dualcpu
                        |   +---dualcpu-separate_config
                        |   +---dualcpu-separate_config_dll
                        |   `---singlecpu
                        +---vidtranscode
                        `---system_files
                            `---davinci

Building the example: 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 XDC user build configuration file, user.bld

File user.bld at the root of the Examples directory informs the XDC tools (tooling which the Codec Engine uses to build itself, codecs, servers, etc) where to find compilers and other tools on the user's system. Open this file in a text editor.

Build.targets

Toolchain roots - rootDir

3. Edit xdcpaths.mak to define the necessary variables

The xdcpaths.mak file, located at the root of the examples/ directory, defines where the Codec Engine is installed, where BIOS is, where the XDC tools are, and where individual Codec Engine packages are. Open this file in a text editor.

If you're CE distribution does not include a cetools directory, you may also have to define the following variables:

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, that every individual path (segment separated by the semicolon) is correct, character for character, and the build process is very likely to go smoothly.

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

5. Build example DSP servers

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

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:

7. Edit paths in the GPP application makefiles

Some of the example applications are provided with GNU makefiles in an attempt to demonstrate to those familiar with GNU makefiles how to build outside of the XDC build engine. For these examples, the makefiles do not utilize the paths set in user.bld, but rather require an explicit path to the user's tool chain. These makefiles do demonstrate techniques for executing the necessary configuration step - see comments in the makefiles for details.

Specifically, ti/sdo/ce/examples/apps/video_copy/dualcpu/makefile, ti/sdo/ce/examples/apps/audio_copy/dualcpu/makefile, and ti/sdo/ce/examples/apps/speech/linuxonly/makefile will need the CC variable to be set to match your development environment.

8. Build the GPP applications

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

    gmake clean
    gmake

Running the video_copy example application on the DM644x DVEVM

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.

In an NFS directory visible from the DVEVM board, copy all the files found in apps/system_files/davinci/. Those files are:

Copy to the same directory as above the DSP client and GPP server executables you have built (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):

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 creates /dev devices for CMEM and DSPLINK if they do not exist already, and, more importantly, loads both modules with appropriate information about the memory map. For your reference, here is the contents of the script:

# insert cmemk, tell it to occupy physical 120MB-128MB, create
# 20 4K buffers, 10 128K buffers and two 1MB buffers
insmod cmemk.ko phys_start=0x87800000 phys_end=0x88000000 pools=20x4096,10x131072,2x1048576

# insert dsplinkk
insmod dsplinkk.ko

# make /dev/dsplink
rm -f /dev/dsplink
mknod /dev/dsplink c `awk "\\$2==\"dsplink\" {print \\$1}" /proc/devices` 0

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
    cmemk: module license '(c) Texas Instruments' taints kernel.
    cmem initialized 3 pools between 0x87800000 and 0x88000000
    dsplinkk: no version for "struct_module" found: kernel tainted.
     DDR_START 0x8fa00000 DDR_SIZE 0x400000

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.

The internal memory map

The DSP has 64K + 80K of internal memory available for code/data allocation and/or cache. A DSP server's TCONF (.tcf) file completely controls how this memory space is partitioned.

By default, server examples (found in servers/ directory) are configured to use:

Please refer to the individual .tcf files for more information about these memory segments and how you can change them if you need to.

The external memory map

ARM and DSP applications must agree on how the physical memory is partitioned between them, as they must use the same numbers. The memory layout concerns the kernel-module loading script on the ARM side, and the TCONF configuration and one linker command file on the DSP side.

The default memory map is set to provide generous amount of space for DSP code and data, plenty of private heap for the DSP algorithms, and large space for shared buffers between Arm and DSP:
       (*) are actual DSP linker segments.

Here are the rules for changing the segments:
The above rules assume apply to individual segments; if your memory map change affects more than one segment, apply all the relevant rules.

Last updated: May 14, 2007