Codec Engine GenCodecPkg Wizard FAQ

Screenshots

• 

  Page 1

• 

  Page 2

• 

  Output

General Questions

What does the GenCodecPkg Wizard do?

The GenCodecPkg wizard generates the files and packaging required for integrating an algorithm into Codec Engine. There are 3 use cases this wizard supports

1. If you have an existing XDM algorithm package that was created with the XDM GenAlg wizard, the GenCodecPkg wizard will create a separate package - that 'requires' the existing GenAlg package. This generated CE Codec Packaging will not include any sources, and is only the packaging required for Codec Engine's config step.
2. If you have an existing XDM algorithm library that you wish to simply 'wrap' with the packaging necessary to integrate into Codec Engine. When run in this mode, the output is a Codec Package that redistributes the lib.
3. If you want to start from scratch, GenCodecPkg will create a single package, with Codec Engine dependencies, that includes starter C-code and headers that are XDM compliant and can be integrated into Codec Engine.

These generated Codec Packages can be integrated into a Server (e.g. for heterogeneous devices like DM644x, OMAP3, etc) using the GenServer Wizard, or as 'local' algorithms in a single processor Codec Engine application.

How is GenCodecPkg different from the RTSC Codec Package Wizard?

This wizard replaces the now deprecated RTSC Codec Package Wizard. It has support for new XDAIS interfaces such as IUNIVERSAL. It also generates makefiles as well as CCS Eclipse project files.

How is GenCodecPkg different from XDAIS GenAlg Wizard?

XDAIS also ships an algorithm wizard - GenAlg. However, GenAlg-created algorithms/projects have no binding to Codec Engine or any framework.

When using GenCodecPkg's 3rd mode - to create starter code - GenCodecPkg will create the same starter code as the GenAlg templates do. However, when using GenCodecPkg, Codec Engine-specific packaging will also be generated. GenCodecPkg is shipped as part of Codec Engine and the generated algorithms are intended for use in a Codec Engine framework.

If you intend your algorithm to be consumed by Codec Engine, GenCodecPkg is recommended. If you know your algorithm will never run within the Codec Engine framework, you can use GenAlg to avoid any Codec Engine dependencies.

Finally, note that GenCodecPkg also has an option to consume algorithms created with GenAlg - option 1 on the initial dialog.

How do I integrate the generated codec into a Codec Engine framework?

The RTSC packaging built around this codec has ties into Codec Engine to make this easy. Specifically, when using any of the VISA classes including the new IUNIVERSAL interface, you will benefit from the stubs and skeletons that are built into Codec Engine to support these interfaces. This allows you to easily make remote procedure calls (RPCs) from the ARM to an algorithm on the DSP.

How do I install the wizard?

The GenCodecPkg wizard is included with the Codec Engine product.

Requirements

• Codec Engine 2.25 or later
  • CE 2.26 improves the GUI interface and adds IRES
• XDAIS 6.25 or later
  • XDAIS 6.26 improves the code templates and adds IRES
• XDCtools 3.16 or later

Running the Wizard

Choose one of the following methods to start the wizard:

Invoking the wizard from a DVSDK makefile

If you're developing with a TI DVSDK release then you likely have already defined paths to all your tools in a Rules.make file. Inside the Makefile from the DVSDK you should append the following rule to the end:

<syntaxhighlight lang='c'> gencodecpkg: $(XDC_INSTALL_DIR)/xs --xdcpath="$(CE_INSTALL_DIR)/packages;$(XDAIS_INSTALL_DIR)/packages" ti.sdo.ce.wizards.gencodecpkg </syntaxhighlight>

Make sure you use a tab in that second line as it is required by make for all the commands.

From your DVSDK directory you can invoke gencodecpkg with the following command:

# make gencodecpkg

Creating a simple makefile to invoke the wizard

You might want to just write a separate very simple makefile for the following reasons

1. Perhaps you're not developing in a DVSDK environment.
2. Perhaps you want to grab a new version of XDAIS and/or Codec Engine to get an updated version of the gencodecpkg wizard and you don't want to change your actual build environment.

Here's an example: <syntaxhighlight lang='c'>

1. Paths to required dependencies

XDC_INSTALL_DIR := C:/ti/xdctools/xdctools_3_16_03_36 CE_INSTALL_DIR := C:/ti/codec_engine/codec_engine_2_25_01_06 XDAIS_INSTALL_DIR := $(CE_INSTALL_DIR)/cetools

1. Create an XDCPATH variable

XDCPATH = $(CE_INSTALL_DIR)/packages;$(XDAIS_INSTALL_DIR)/packages

gencodecpkg: $(XDC_INSTALL_DIR)/xs --xdcpath=$(XDCPATH) ti.sdo.ce.wizards.gencodecpkg

</syntaxhighlight>

From CCS Eclipse

If you add your Codec Engine installation directory to the "Tool Discovery Path" (Window | Preferences | CCS | RTSC | Products), you will have a new "Tools | Codec Engine Tools | GenCodecPkg" menu item.

Please bear in mind that in CCS v5.1, the Tools menu only appears when CCS is in Debug Perspective.

Note: Be sure you enable Codec Engine by checking the appropriate version in (Window | Preferences | CCS | RTSC)! If you fail to pick a version and try to launch the wizard via the menu, in the best case you'll get a confusing dialog msg, and in the worst case absolutely nothing will happen!

Batch File

At the base of the Codec Engine installation (CE 2.25.02 and later), there is a ti.sdo.ce.wizards.gencodecpkg.bat script which can be edited and run.

The Wizard GUI

Here is a description of the wizard's screens:

What type of Codec package would you like to create?

What type of Codec package would you like to create?

A codec package can be created for an XDM algorithm in 3 ways:

1. Opening a .genalg file that was saved with th XDM GenAlg wizard.

   This will create a codec package that uses the algorithm package specified in the .genalg file. The XDM GenAlg wizard is included in XDAIS 6.25 and above.

2. Selecting a library that implements an XDM interface.

   This creates a codec package that uses the algorithm library. The library file is copied into the lib subdirectoy of the base directory of the codec package.

3. Entering the XDM algorithm information manually. '

   This will create a codec package that contains a basic algorithm implementation, including source code.

Fields:

XDAIS install Dir

The location of your XDAIS installation. This may be required, depending upon the way the package is being created. On startup, the wizard will attempt to locate an XDAIS installation automatically.

Create a Codec Package From a .genalg File

Create a Codec Package From a .genalg File

Use File->Open to open a .genalg file. This will populate the Module, Vendor, Interface, XDM Algorithm Package Name and Targets fields.

Fields that can be modified:

Codec Package Name

The name of codec package that will be generated. An example codec package name: ti.xdais.dm.universal_copy.ce. When the .genalg file is loaded, the codec package name will be automatically initialized to <alg package name>.ce

Destination Directory

The location that the codec package files will be output to. For example, if the output directory is c:/output, and the codec package name is ti.xdais.dm.universal_copy.ce, the files will be output to c:/output/ti/xdais/dm/universal_copy/ce

Create a Codec Package From an XDM Algorithm Library

Create a Codec Package From an XDM Algorithm Library

Use File->Open or select the 'Library...' button to open a library file. This will populate the Module, Vendor, Interface, Suffix and Package Name fields.

Fields that can be modified:

My alg's CE Package Name

The name of codec package that will be generated. Defaults to <Vendor>.<Module>.ce

Base Interface

The XDM interface that the library implements.

Destination Directory

The location that the algorithm package files will be output to. If the output directory is c:/output, and the codec package name is mycompany.mycodec.ce, the files will be output to c:/output/mycompany/mycodec/ce

Create an XDM Algorithm and Codec Package

Create an XDM Algorithm and Codec Package

Module

The name of the algorithm you're creating

Vendor

Your company name

Interface

Has the form I<Vendor>. This field will be automatically filled after naming the module.

Base Interface

The ti.xdais.dm interface that is being implemented

Package Name

The algorithm and codec package. Defaults to <Vendor>.<Module>

Targets

Build targets. The generated makefile will build a library for each target selected.

Add IRES Interface

When checked, a generic implementation of the IRES interface will be added to the algorithm in <Module>_<Vendor>_ires.c. All IRES references will be inside #ifdef ADD_IRES_RESOURCE blocks. The generated source files will have to be modified to implement a specific resource manager.

Destination Directory

The location that the algorithm and codec package files will be output to. For example, if the output directory is c:/output, and the algorithm package name is ti.viddec_copy, the files will be output to c:/output/ti/viddec_copy

'cgtools' Directories

The location of CodeGen tools required to build for the selected targets.

Expert Mode

When left unchecked, the Interface and Package Name fields will be read-only and will be automatically generated based on Module and Vendor

After the Wizard

Building the generated package

There are several different ways to build the generated package.

Command Line

The wizard creates a makefile in the generated directory. Simply browse to the generated directory and run "gmake" to compile the code and create the necessary files to make your package ready for consumption.

The makefile contains variables that point to the following installation directories: xdctools, Codec Engine, XDAIS, and the c6000 compiler. If you wish to use a different version of any of those components simply change the variable definition in the makefile.

Command Line in a DVSDK Environment

If you're developing with one of TI's DVSDKs then you have probably already spent time setting up paths to all your software components inside a Rules.make file. If that's the case, the wizard-generated makefiles support setting the location of your Rules.make file on the command line, using the RULES_MAKE variable; then the makefile will honor the paths you've set in Rules.make.

<syntaxhighlight lang='bash'> > make RULES_MAKE=~/dvsdk_x_xx_xx/Rules.make </syntaxhighlight>

Code Composer Studio 4.x or greater

The wizard creates a project files which can be used in CCS 4.x or greater.

• Import the project in CCS by going to Project -> Import then select "Existing Project into Workspace" under the General folder.

Note: In newer versions of CCS v5.1 and in v5.1.1, there is a slight difference when importing. Use File -> Import and then select "Existing Project into Workspace" under the General folder.

• For the "root directory" click "Browse" and point it to the directory <repository>/<mycompany>/<mymodule>.
• You should see <mycompany>.<mymodule> show up under Projects.
• Click Finish to import the project into your workspace.

Note: Do not check "Copy projects into workspace" when importing your project

This is a "standard eclipse make" project meaning that clicking the "build" button in CCS will be equivalent to running "make" at the command line.

A good reason to use CCS is to take advantage of features like code completion. By pressing <Ctrl> <Space> on your keyboard you can invoke the code completion capabilities to have it finish typing the names of variables, functions, etc. You will likely want CCS to have the capability of auto-completing names/fields related to XDAIS IALG. To do so you need to do the following:

• Right-click on your project in the "C/C++ Projects" window and select Properties.
• Click on "C/C++ Include Paths & Symbols"
• Click "Add External Include Path"
• Click "Browse" and navigate to the appropriate source directory. Specifically for IALG definitions you need to point to <xdais>/packages and the <xdctools>/packages directory. You may also need to point to the include directory of the Code Generation Tools being used to build for your device. All component packages (xdais, xdctools, C6000 compiler, etc) are installed during CCS installation, if select.

Here's an example screenshot:

Note: These projects rely on an XDCROOT environment variable. Prior to CCS v5.1, this variable was set during the installation of CCS. If you are using CCS 5.1 or greater, you'll need to set the XDCROOT environment variable on your host PC manually to point to the root of your xdctools as follows:

Adding Source Files

The description of what source files are built into your algorithm library is done in the javascript language in the package.bld build script. To add a new file (e.g. "mysource.c") to the library, add it to the SRCS array. For example:

<syntaxhighlight lang='javascript'> /* ... in package.bld ... */

var SRCS = ["mymodule.c", "mysource.c"]; </syntaxhighlight>

This is a standard javascript array, so other javascript services can be used to accomplish the same thing. It's up to you how you want to structure your build script. For example, this code snippet does the same as the one line above:

<syntaxhighlight lang='javascript'> var SRCS = ["mymodule.c"]; SRCS.push("mysource.c"); </syntaxhighlight>

Adding Other Files

You describe what files go into your algorithm distribution (the generated .zip file) using XDC's xdc.bld.PackageContents object (often assigned for brevity to the Pkg variable). A full description of this Pkg object is here.

You can add files (e.g. extra headers, documentation, test vectors, etc) to the generated .zip file by adding the files to the Pkg.otherFiles array. For example, to add "myheader.h" and "mydatasheet.pdf" to the generated .zip file, do the following:

<syntaxhighlight lang='javascript'> /* ... in package.bld ... */ var Pkg = xdc.useModule('xdc.bld.PackageContents');

Pkg.otherFiles.$add("myheader.h"); Pkg.otherFiles.$add("mydatasheet.pdf"); </syntaxhighlight>

Note that the data type of this .otherFiles array is not a standard javascript array, but rather an XDC Vector type - a subtle, but important detail. As a result, you can't use typical javascript array methods to append elements to the .otherFiles array, but instead must use XDC Vector methods, like the .$add() method in the example above.

Others?

Naming conventions to adhere to? Files modified?