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.

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

Examples are provided in zip file format under the directory

where <CE_INSTALL_DIR> is the root directory of your Codec Engine insatallation. Under the archive directory, you will find directories named for platforms containing zipped examples specific to the given platform. Each example is self-contained, so that it can be unzipped and built in a directory of your choice. It is also possible to build all the examples for your platform from the makefile located in <CE_INSTALL_DIR>/examples.

Directories containing examples:
examples
    +---archive  Platform directories 
        +---C6A8149_bios_elf Zipped BIOS examples for C6A8149 EVM 
        +---C6472_bios_coff Zipped BIOS examples for C6472 EVM 
        +---C6472_bios_elf Zipped BIOS examples for C6472 EVM 
        +---OMAP3530_bios_elf Zipped BIOS examples for OMAP3530 EVM 
        +---OMAP3530_linux_elf Zipped Linux examples for OMAP3530 EVM 
        +---TI814X_bios_elf Zipped BIOS examples for TI814X EVM 
        +---TI814X_linux_elf Zipped Linux examples for TI814X EVM 
        +---TI816X_bios_elf Zipped BIOS examples for TI816X EVM 
        +---TI816X_linux_elf Zipped Linux examples for TI816X EVM 
The archive folders ending in "_elf" build the BIOS executables with ELF format. The archive folders ending in "_linux_elf" contain local Linux examples, and remote linux examples with a server. The server will be built with ELF format.

Building the examples: step-by-step instructions

Here we will describe the steps to build all the examples for your platform, from the root of the examples directory.

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

1. Dependencies

Dependencies can be set in $(CE_INSTALL_DIR)/products.mak. This file is then included by the individual example makefiles, if they are built under <CE_INSTALL_DIR>/examples. You can also copy the $(CE_INSTALL_DIR)/products.mak to a specific example directory if you move the example to another location.

INSTALL_DIR

Codegen Tools

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

It may no longer be necessary to copy the entire "examples" tree out of the product, since all examples are now contained in .zip files, which can be re-extracted to recover the original example. However, if you do copy the examples folder to another location, you will need to

3. Manage examples makefile

At the root of the examples directory you will find the makefile, which must be edited for your particular platform. Edit the following variable in makefile, as described below.

3.1 DEVICE

The DEVICE variable indicates which hardware platforms should be built for. Set this variable to one of the supported platforms listed in the makefile.

The makefile in the top-level example directory unzips the examples for the specified device, into the examples directory, and then builds them. Each example contains a GNU makefile and a products.mak, which enable you to build it in the directory where it is unzipped. The products.mak for the individual example will look for a products.mak file one, two, or three directories above, to allow for a common products.mak file that can be used for the examples.

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.

To copy the built examples to a location on your target's file system, type:

    gmake install INSTALL_DIR=<INSTALL_DIR>

where <INSTALL_DIR> is the location to copy to.

If for whatever reason you want to remove all the extracted examples, type:

    gmake clobber


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

The local Linux universal copy example can be run as follows:

./universal_copy_local_.xv5T

To run the remote Linux universal copy example,

./universal_copy_remote.xv5T [-p proc] [-m mapFile]

The options are:


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, and by running

gmake install INSTALL_DIR=<INSTALL_DIR>

all the files necessary to run the application will be copied to <INSTALL_DIR>.

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 built Codec Engine examples. To run the client application, using the DSP as the remote server, (which will automatically load the DSP server image):

    ./universal_copy_remote.xv5T -p dsp

The -p <proc> option is used to specify which slave processor is to be loaded with the server image.

You will see several output lines:


root@arago:# ./universal_copy_remote.xv5T
[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:

    ./universal_copy_remote.xv5T -p video
    ./universal_copy_remote.xv5T -p vpss

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

Note: Each example comes with a run.sh script which can be used to run the example, or viewed to see the example usage.


Memory map

The platform specific memory maps for the servers that are used by remote apps, are located in the _config.bld file where the server is built. For example, ex01_universalcopy_remote/dsp/_config.bld contains the memory map for the DSP.

In case you need to modify the memory map, you can modify the _config.bld file as needed. Note that each platform memory map has a memory segment named "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 partition, 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: August 14, 2012