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 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 kernel modules (.ko) and scripts that load them for different platforms

    |   |   `---davinci

    |   |       +---DM6446

    |   |       `---DM6467

    |   `---sanity_test         Sanity test -- pre-built "video_copy" application with sample input file

    |       +---evmDM6446           Arm client application and DSP server image with video_copy codecs for EVMDM6446

    |       +---evmDM6467           Arm client application and DSP server image with video_copy codecs for EVMDM6467

    |       +---evmDM355            Arm-only application with built-in video_copy codecs for EVMDM355

    |       `---evmDM6437           DSP-only application with built-in video_copy codecs for EVMDM6437

    `---ti

        `---sdo

            `---ce

                `---examples    Buildable example codecs, DSP servers, and ARM and/or DSP apps

                    +---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

                    |   +---viddec2_copy

                    |   +---viddec_copy

                    |   +---videnc1_copy

                    |   +---videnc_copy

                    |   `---vidtranscode_copy

                    +---extensions

                    |   `---scale

                    +---servers

                    |   +---all_codecs

                    |   `---video_copy

                    `---apps

                        +---audio1_copy

                       |   +---sync

                        |   `---async

                        +---audio_copy

                        |   +---dualcpu

                        |   `---singlecpu

                        +---image1_copy

                        +---image_copy

                        +---scale

                        +---speech

                        |   +---dsponly

                        |   `---linuxonly

                        +---speech1_copy

                        +---speech_copy

                        +---video1_copy

                        +---video2_copy

                        +---video_copy

                        |   +---dualcpu

                        |   +---dualcpu-separate_config

                        |   +---dualcpu-separate_config_dll

                        |   `---singlecpu

                        `---vidtranscode

Running the pre-built video_copy example application on the DM6446 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.

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

dsplinkk.ko, the pre-configured, pre-built DSP Link driver.
cmemk.ko, a Contiguous Memory allocator that allows allocation of physically contiguous buffers of arbitrary sizes (even several MB) on the GPP. The Codec Engine requires buffers to be usable by the processor on which the codec runs. In the DM6446 architecture, where the ARM creates remote codecs on the DSP, the buffers must be physically contiguous; GPP applications can use CMEM to obtain these physically contiguous buffers.
loadmodules.sh, an example loader for the two kernel modules above.

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):

apps/sanity_test/<platform>/video_copy.x64P
apps/sanity_test/<platform>/app.out

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

apps/sanity_test/<platform>/in.dat

(If you want to run the video_copy example you have built your self, you will find the DSP server image under examples as ti/sdo/ce/examples/servers/video_copy/<platform>/video_copy.x64P, while the ARM-side application is at ti/sdo/ce/examples/apps/video_copy/dual_cpu/<platform>/app.out.)

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.

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:

<CE_EXAMPLES_INSTALL_DIR> - absolute path of the examples directory or the copy you made, e.g. /usr/work/examples
<CE_INSTALL_DIR> - root directory of your Codec Engine installation. The original examples are in <CE_INSTALL_DIR>/examples.
<BIOS_INSTALL_DIR> - root directory of your DSP/BIOS installation.
<XDC_INSTALL_DIR> - root directory of your xdctools installation.
directory/file - position of the file relative to the examples directory; for examples, ti/sdo/ce/examples/codecs/makefile refers to <CE_EXAMPLES_INSTALL_DIR>ti/sdo/ce/examples/codecs/makefile.

2. Edit top-level build files to customize the build for your software installation and your hardware

At the root of the Examples directory are two build-related files that all Codec Engine examples include. We edit both of these files to specify where various software components needed by Codec Engine are on our system, and to narrow the list of hardware targets we want to build for (thereby reducing the build time and possibly the scope of external components needed).

2.1 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, and also what platforms to build for. Open this file in a text editor.

Locate in the file a build table that lists whether to build the examples for the ARM, for the DSP, and for native Linux. Each of those three has a list of supported "targets", i.e. runtime environments, for example the TI C64+ compiler for the DSP, the Montavista Arm9 and the ucLinux Arm 9 for the Arm. Those "targets" support several platforms, for example the Montavista Arm 9 target supports "evmDM6446", "evmDM355", and other platforms.

Following the simple instructions in the file's comments, disable builds that you are not interested in, in order to save time. For example, you may not be interested in building anything for the DSP; or, for the Arm, you may be interested in building only for target, "Montavista Arm 9", and for that target, you will likely be interested in only one platform, for example "evmDM6446", or "evmDM355".

For the targets that you do want to build for, you will specify the base directories of their respective tool chains, as explained and exemplified in the comments in the file.

2.2 Edit xdcpaths.mak to define the necessary variables

The xdcpaths.makfile, also 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.

Follow the instructions in the file to specify the following:

(Optional) List of hardware devices you want to build for (DM6446, DM355, etc.). This list is specified in the DEVICES variable. You will likely be interested in only one or two devices, so reduce this list to your minimum to shorten the build time and to avoid being asked for the location of components you don't need.
(Mandatory) Installation directories for the Codec Engine itself, for the XDC tools, and for the DSP/BIOS (if you build for the DSP). Those you specify in CE_INSTALL_DIR, XDC_INSTALL_DIR, and BIOS_INSTALL_DIR variables, as explained in details in the comments in the file you are editing.
(Mandatory, depending on your Codec Engine distribution) Installation directories for the "minor" components needed by the Codec Engine, such as XDAIS, Framework Components, DSP/BIOS Link, and CMEM memory manager. If you have a "full" Codec Engine distribution that has a cetools/ directory at its top, all these components will automatically be included. If you don't have this distribution, and instead xDAIS, DSP/BIOS Link and others are installed in other directories, you will have to specify their location.
(Mandatory) Location of the compiler tools for architectures you'll be building examples for, specifically Montavista Arm9 and TI C64x

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.

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:

*.cfg: Configuration script that determines what codecs should be included in the server, and how some of the components (e.g. DSKT2 and DMAN3) will be configured.
*.tcf: TConf file for the app. It is set to allow for a generous heap of 122MB and for 4MB of static code and data. Be very careful with changing the memory map.
main.c: generic main()
link.cmd: application specific linker command file.

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 on the target, and if your application requires a DSP server, you need to copy that DSP server on the target as well. (You can see which DSP server -- a DSP binary with .x64P 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:
The ARM-side of the audio_copy example for evmDM6446 is in directory examples/ti/sdo/examples/apps/audio_copy/dual_cpu/evmDM6446. Copy the app.out 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 ceapp.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 fromexamples/ti/sdo/ce/examples/servers/all_codecs/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 evmDM355/app_local.x470MV on the target, and thein.dat file as well, making sure in.dat is one level above the Arm executable on the target as it is in the build directory.

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://wiki.davincidsp.com/index.php?title=Changing_the_DVEVM_memory_map

Last updated: January 28, 2007