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

<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. Manage xdcpaths.mak and products.mak

At the root of the Examples directory, there is a xdcpaths.mak file which has to be edited for your particular usecase. Edit the following variables described below

The variables defined in xdcpaths.mak that most users must assign are: DEVICE, GPPOS, and PROGRAMS. Each are described 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 DEVICE variable

The DEVICE 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 DEVICE variable.

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. Linux glibc), and the other GPP OS's can be removed from the GPPOS variable.

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

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 CE_INSTALL_DIR

The CE_INSTALL_DIR variable indicates where the CE product is installed.

3. Dependencies

Dependencies can be set in $(CE_INSTALL_DIR)/products.mak, which is then included by examples/xdcpaths.mak.

INSTALL_DIR

The many INSTALL_DIR variables let you set the path to other dependent components. Depending on the programs you are building and the devices you build for, you will need to set the path for one or more of these components. If your distribution includes cetools/, you can set many of these variables to $(FC_INSTALL_DIR)/cetools.

Codegen Tools

Correct code generation tool paths will need to be specified for the architectures you will be building for. For instance, to build for the C6472 device, you will need to set the appropriate cgtools variables to the TI C64x toolchain location.
Note that for TI toolchains, this is the directory that contains bin/, include/, and lib/ subdirectories.
To disable the build for a given architecture for your device, ensure that the corresponding cgtools variables are undefined. For example, to disable M3elf builds for the TI816X device, don't assign the M3 ELF cgtools variable.

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.

4. Build examples

After updating the variables described above, from your examples/ directory, type:

gmake clean
gmake

All examples appropriate for your specified environment and device will be built. This will include codecs, extensions, servers (if applicable) and apps.

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:

<CMEM_INSTALL_DIR> - root directory of your Linux Utils installation.
<LINK_INSTALL_DIR> - root directory of your SysLink installation.

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

syslink.ko, the SysLink driver, which you built in your LINK_INSTALL_DIR, according to SysLink build instructions. Please refer to the SysLink Install Guide for instructions on building the SysLink driver.
cmemk.ko, a Contiguous Memory allocator that allows allocation of physically contiguous buffers of arbitrary sizes (even several MB) on the GPP. You will need to have built this file in your CMEM_INSTALL_DIR, according to the "readme.txt" file located in <CMEM_INSTALL_DIR>/packages/ti/sdo/linuxutils/cmem.
loadmodules.sh and unloadmodules.sh, example scripts for loading any necessary kernel modules. Some platforms have different module dependencies than others, so the contents of these scripts may vary between platforms. These files can be found in <CE_INSTALL_DIR>/examples/apps/system_files/<platform>.

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 : 2.10.02.17
      SysLink module created on Date:Jan 15 2012 Time:15:23:23
      Trace disabled
      Trace entry/leave prints enabled
      Trace SetFailureReason enabled
      CMEMK module: built on Sep 9 2011 at 16:05:39
        Reference Linux version 2.6.37
        File /db/atree/library/trees/ce/ce-t03/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:

-p proc. If using a remote server, proc is the name of the remote processor on which to load the server. For example, "DSP" or "VIDEO-M3". If proc is not specified, it is assumed to be "DSP".
-e engine. Use engine, to specify the name of the engine to be opened. This is only necessary when running local apps, as the default engine is "remote_copy_<proc>", which works for remote apps. For example, to run speech1_copy locally, you would run:
./app_local.xv5T -e "speech1_copy"
-s serverSuffix. If using a remote server, serverSuffix is the name of the extension added to the server name to indicate the target it was built for. For example, "xe674", for C674 Elf targets. The default value of serverSuffix is "x64P".
-m mapFile. If the MMU is enabled for the remote processor where Codec Engine will load the server, mapFile is used to specify the name of a text file containing the remote processor's memory map. Codec Engine will use mapFile to map MMU entries. Example map files are located in the directory:
CE_INSTALL_DIR/examples/ti/sdo/ce/examples/buildutils
They can be modified if needed, and copied to the same directory on your EVM's file system where you have copied the remote server and app.

Example: Running the universal_copy example application on the TI816X

Build the examples as described in the previous sections, and copy into a directory visible from the EVM board. The servers and GPP client executables must sit in the same directory together). For example, to run the universal_copy example, you need:

ti/sdo/ce/examples/servers/all_codecs/<platform>/all.x<suffix>
ti/sdo/ce/examples/apps/universal_copy/<platform>/app_remote.xv5T

You can also copy the sample input file to the same directory:

ti/sdo/ce/examples/apps/universal_copy/in.dat

Boot the EVM, change to the directory where you have copied cmem.ko, syslink.ko, and loadmodules.sh, and run
sh ./loadmodules.sh
to install drivers necessary for your device (e.g. CMEM and SysLink) with appropriate information about the memory map.

Next, change to the directory where you have copied the Codec Engine examples. To run the client application, using the DSP as the remote server, (which will automatically load the DSP server image):

./app_remote.xv5T -p DSP -s xe674

The -p <procId> option is used to specify which slave processor is to be loaded with the server image. The -s <suffix> is the suffix used in the server executable name: xe674 for all_DSP.xe674, xem3 for all_VIDEO-M3.xem3. The server name for this example is specified in the configuration file, remote.cfg, located in
<CE_INSTALL_DIR>/examples/ti/sdo/ce/examples/buildutils
Many of the remote examples use this common configuration file.

You will see several output lines:


root@arago:# ./app_remote.xv5T -s xe674
[t=0x000017c7] [tid=0x4007c000] xdc.runtime.Main: main> ti.sdo.ce.examples.apps.universal_copy
[t=0x00001f2e] [tid=0x4007c000] xdc.runtime.Main: [+1] App-> Application started, procId DSP engineName remote_copy_DSP input-file ./in.dat
output-file ./out.dat.
[t=0x000421c5] [tid=0x4007c000] xdc.runtime.Main: [+1] Alg version:  1.00.00.00
[t=0x000435f5] [tid=0x4007c000] xdc.runtime.Main: [+1] App-> Processing frame 0...
[t=0x000437bf] [tid=0x4007c000] xdc.runtime.Main: [+2] App-> Alg frame 0 process returned - 0x0
[t=0x000438a5] [tid=0x4007c000] xdc.runtime.Main: [+1] App-> Processing frame 1...
[t=0x00043a27] [tid=0x4007c000] xdc.runtime.Main: [+2] App-> Alg frame 1 process returned - 0x0
[t=0x00043aae] [tid=0x4007c000] xdc.runtime.Main: [+1] App-> Processing frame 2...
[t=0x00043c39] [tid=0x4007c000] xdc.runtime.Main: [+2] App-> Alg frame 2 process returned - 0x0
[t=0x00043cbd] [tid=0x4007c000] xdc.runtime.Main: [+1] App-> Processing frame 3...
[t=0x00043e22] [tid=0x4007c000] xdc.runtime.Main: [+2] App-> Alg frame 3 process returned - 0x0
[t=0x00043e95] [tid=0x4007c000] xdc.runtime.Main: [+1] 4 frames processed
[t=0x0004f600] [tid=0x4007c000] xdc.runtime.Main: [+1] app done.
root@arago:#

To run the client application, using the VIDEO-M3 or VPSS-M3as the remote serve, run one of the following commands:

./app_remote.xv5T -p VIDEO-M3 -s xem3
./app_remote.xv5T -p VPSS-M3 -s xem3

To verify that the application has executed correctly, check that the newly created out.dat file is identical to the input file, in.dat.

Example: Running the universal_copy example application on EVM3530

Assuming you included OMAP3530 in DEVICES, LINUX_GLIBC in GPPOS and APP_CLIENT in PROGRAMS, the ARM-side of the universal_copy example for evm3530 will be built into the examples/ti/sdo/ce/examples/apps/universal_copy/bin/ti_platforms_evm3530 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 configuration file for this example, remote.cfg, is located in examples/ti/sdo/ce/examples/buildutils, and lists "all_DSP.x64P" as its DSP server image (indirectly by piecing together, a serverIds configuration argument passed in from the package.bld script, and serverSuffix).
So you must copy the all_DSP.x64P DSP executable for evm3530 from examples/ti/sdo/ce/examples/servers (more precisely from examples/ti/sdo/ce/examples/servers/all_codecs/bin/ti_platforms_evm3530/ ) to the target, in the same directory where the ARM-side executable is.

Load the kernel drivers using the loadmodules.sh script, as described in a previous section. Run the remote example as follows:
./app_remote.xv5T

Note that some OMAP3 systems enable the DSP's MMU, so you'll have to also use the -m option, like this:
./app_remote.xv5T -m omap3530_memmap.txt

Memory map

The platform specific memory maps for the all_codecs server are located in the file

<CE_INSTALL_DIR>/ti/sdo/ce/examples/servers/all_codecs/serverplatforms.xs

In case you need to modify the memory map, you can search for your platform in this file and modify as needed. Note that each platform memory map has a memory segment named either "SYSLINK" or "DDR3_SR0". This is used for SysLink communication between the Host and the remote processor, and the SharedRegion 0 is set to this region (see <platform>.cfg for details).

If you do change the memory map, you may also need to change the physical start and end address of CMEM_MODPARAMS in loadmodules.sh, to ensure that CMEM will not overlap with any of the other memory regions you modified. You may also want to change the Linux partion, by modifying the mem= boot argument in your Linux bootloader.

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

Last updated: February 24, 2012