Integrating a Codec Engine

This section describes how the Engine Integrator should configure an Engine for use by the application developer.

Overview

The Application Author gets an Engine configuration from the Engine Integrator. In practice, these roles may be shared by one person.

An Engine configuration is stored in an XDC *.cfg file and processed by the makefile using package.xdc to generate a *.c file and a linker command file (*.xdl) from the *.cfg file. For build instructions, see CE_INSTALL_DIR/examples/build_instructions.html.

The Codec Engine example applications typically support GPP+DSP, GPP-only, and DSP-only usage. For GPP+DSP usage, the Engine configuration is often defined in a file named remote.cfg, designating codecs run remotely on a DSP server. For GPP-only or DSP-only usage the configuration often resides in a file named "local.cfg", designating that the codecs run locally, on the same CPU as the main application.

An Engine configuration can include the names of the Engines, as well as the codecs and their names within each Engine, whether each codec is local or remote relative to the application, which groups each codec should be integrated into (for environments that support resource sharing), the name of the Server image if a particular Engine contains remote codecs, and more.

In its simplest form, however, the Engine configuration script can simply name the DSP server package and the corresponding server executable, and automatically import all the server's codec definitions. This makes the codecs available for use from the application as remote codecs.

For the latter form of configuration to work, it is important that you receive your DSP server in a package—which is the default server delivery method as of CE 2.00—instead of getting just one DSP server binary executable.

A Reusable Example

The video_copy example uses the following ceapp.cfg configuration file:

<syntaxhighlight lang='javascript'>

/* ======== ceapp.cfg ======== */
/* use the tracing utility module */
var TraceUtil = xdc.useModule('ti.sdo.ce.utils.trace.TraceUtil');
//TraceUtil.attrs = TraceUtil.SOCRATES_TRACING;

/* set up OSAL */
var osalGlobal = xdc.useModule('ti.sdo.ce.osal.Global');
osalGlobal.runtimeEnv = osalGlobal.DSPLINK_LINUX;

/* ======== Engine Configuration ======== */
var Engine = xdc.useModule('ti.sdo.ce.Engine');
var myEngine = Engine.createFromServer(
      "video_copy",     // Engine name (as referred to in the C app)
      "./video_copy.x64P", // path to server exe, relative to its package dir
      "ti.sdo.ce.examples.servers.video_copy.evmDM6446" // server package
);

</syntaxhighlight>

Most of this configuration file can be used as is. For your applications, you should modify the portions shown in bold: the name of your engine (your choice), the name of the server executable, and the name of the server executable's package.

The codecs included in the server will be available to the application under their original names, which for convenience are shown during the application's build—as shown in this excerpt:

configuring ceapp.x470MV from package/cfg/ceapp_x470MV.cfg ...
Info: Configuring engine named 'video_copy' from the info file for DSP server
'./video_copy.x64P', located in package
'ti.sdo.ce.examples.servers.video_copy.evmDM6467':
   Target app will look for the DSP server image 'video_copy.x64P' in its current directory.
Adding codec 'viddec_copy'
(ti.sdo.ce.examples.codecs.viddec_copy.VIDDEC_COPY), scratch groupId=0
Adding codec 'videnc_copy'
(ti.sdo.ce.examples.codecs.videnc_copy.VIDENC_COPY), scratch groupId=0

Info: Reading DSP memory map from the info file for DSP server './video_copy.x64P',
located in package 'ti.sdo.ce.examples.servers.video_copy.evmDM6467': ...

It is good practice to verify that the information in this build log (server executable/package name, codec names, scratch groups) matches what you expect.

Even though the engine is configured from the information stored in the server package, you still must have all the codecs included in the server in your package path. If you do not have a required codec package, the build will fail. If you have a codec package of a different version than the one used to build the server, you will get a warning.

Advanced Engine Creation

The Engine.createFromServer() method in the previous configuration example is available as of Codec Engine 2.00, and is strongly recommended when configuring an Engine with a remote Server. See this article for more details. It replaces the lower-level Engine.create() method for most common use cases, and helps avoid the complexity of matching the DSP-side codec/algorithm lists and system memory maps.

The lower-level Engine.create() method is still available. Although you typically do not need to use it, its usage is documented here for users of Codec Engine 1.x:

<syntaxhighlight lang='javascript'> /* get various codec modules; i.e., implementation of codecs */ var VIDDEC_COPY = xdc.useModule('ti.sdo.ce.examples.codecs.viddec_copy.VIDDEC_COPY'); var VIDENC_COPY = xdc.useModule('ti.sdo.ce.examples.codecs.videnc_copy.VIDENC_COPY');

/* ======== Engine Configuration ======== */ var Engine = xdc.useModule('ti.sdo.ce.Engine'); var myEngine = Engine.create("video_copy", [

   {name: "videnc_copy", mod: VIDENC_COPY, local: false},
   {name: "viddec_copy", mod: VIDDEC_COPY, local: false}

]); myEngine.server = "./video_copy.x64P";

/* ======== Server memory map (DSPLINK) configuration ========

* This table must match exactly the addresses and sizes of segments in the Server’s
* BIOS configuration (.tcf) script. There is exactly one "main", one "link", and
* one "reset" segment type, and zero or more of "other" types.

• /

myEngine.armDspLinkConfig = {

   memTable: [
       ["DDRALGHEAP", {addr: 0x88000000, size: 0x07A00000, type: "other"}],
       ["DDR2",       {addr: 0x8FA00000, size: 0x00400000, type: "main" }],
       ["DSPLINKMEM", {addr: 0x8FE00000, size: 0x00100000, type: "link" }],
       ["RESETCTRL",  {addr: 0x8FF00000, size: 0x00000080, type: "reset"}],
   ],

}; </syntaxhighlight>

Understanding Engine Configuration Syntax

The syntax used in Engine configurations is based on JavaScript, which is also used for the Tconf language used to statically configure DSP/BIOS. (See DSP/BIOS 5.30 Textual Configuration (Tconf) User’s Guide (SPRU007) for details.)

Unlike the JavaScript used in web pages, an object model is provided to meet the needs of Engine configuration. This object model is documented in the Configuration Reference, which is available at CE_INSTALL_DIR/xdoc/index.html.

For example, the following statements cause the Global module in the ti.sdo.ce.osal package to be made available to the configuration script. It then sets the runtimeEnv attribute of the Global module to DSPLINK_LINUX. This indicates that an application that uses this Engine can use the DSP/BIOS Link and Linux operating environments.

<syntaxhighlight lang='javascript'> var osalGlobal = xdc.useModule('ti.sdo.ce.osal.Global'); osalGlobal.runtimeEnv = osalGlobal.DSPLINK_LINUX; </syntaxhighlight>

To see the other options for the runtimeEnv attribute, follow these steps:

1. Open CE_INSTALL_DIR/xdoc/index.html to see the Configuration Reference. Depending on your browser, you may need to enable active content to view the list of nodes on the left.
2. Click the link to the ti.sdo.ce.osal package.
3. Click the link to the Global module.
4. You see the valid settings for runtimeEnv and other documentation for the Global module.
5. Click "Back" in the upper-right corner of the window. Note that the usual Back button in your browser does not function as expected in this online help system.

After setting the runtime environment, the example ceapp.cfg configuration file gets access to the codec modules it will need.

For example: <syntaxhighlight lang='javascript'> var VIDDEC_COPY = xdc.useModule('ti.sdo.ce.examples.codecs.viddec_copy.VIDDEC_COPY'); </syntaxhighlight>

This statement "uses" the VIDDEC_COPY module in the "ti.sdo.ce.examples.codecs.viddec_copy" package, and stores the handle to it in a variable named VIDDEC_COPY. A similar statement gets the corresponding video encoder. You can modify these statements to reference any of the codecs provided with Codec Engine.

The ti.sdo.ce.examples.codecs.viddec_copy package corresponds to CE_INSTALL_DIR/examples/ti/sdo/ce/examples/codecs/viddec_copy and VIDDEC_COPY matches the VIDDEC_COPY.xdc filename in that directory.

The next group of statements declare the contents of an Engine. <syntaxhighlight lang='javascript'> var Engine = xdc.useModule('ti.sdo.ce.Engine'); var vcr = Engine.create("video_copy", [

   {name: "videnc_copy", mod: VIDENC_COPY, local: false},
   {name: "viddec_copy", mod: VIDDEC_COPY, local: false}
   ]

); </syntaxhighlight> First, they make the Engine module in the ti.sdo.ce package available to the script. Then they use the create() method of the Engine module to create an Engine. As with the Global module in the ti.sdo.ce.osal package, you can use the Configuration Reference online help to get details about the Engine module in the ti.sdo.ce package.

Each Engine has a name that will be used by the Application Author in the Engine_open() API they call. In this case, the Engine name is "video_copy".

The create method then expects an array of algorithm descriptions. Each algorithm description contains the following fields:

• name. This string specifies the "local" name to be used by the Application Author to identify an algorithm to instantiate in the VIDENC_create and VIDDEC_create VISA APIs.
• mod. This field is a reference that identifies the actual module implementing the algorithm to instantiate. This is the same as the name declared as a variable in the previous statement that called xdc.useModule to get the ti.sdo.ce.examples.codecs.viddec_copy.VIDDEC_COPY module.
• local. If true, the algorithm is instantiated on the "local" CPU. Otherwise, the Codec Server creates a remote instance of the algorithm identified by mod.

Framework Components Configuration

The example configuration files—remote.cfg (for GPP+DSP) and local.cfg (for GPP-only and DSP-only)—often configure the ti.sdo.fc.dskt2.DSKT2 and ti.sdo.fc.dman3.DMAN3 modules, which are part of Framework Components. DSKT2 is the xDAIS algorithm memory allocation manager, and DMAN3 is the DMA manager. For details on configuring these modules, see the Framework Components documentation in CE_INSTALL_DIR/xdoc/index.html.

Additional Documents and Resources

• Codec Engine Server Integrator User's Guide (SPRUED5)
• Codec Engine Algorithm Creator User's Guide (SPRUED6)
• Codec Engine Application (API) Reference Guide CE_INSTALL_DIR/docs/html/index.html
• Configuration Reference Guide. CE_INSTALL_DIR/xdoc/index.html
• Example Build and Run Instructions. CE_INSTALL_DIR/examples/build_instructions.html
• xDM API Reference. XDAIS_INSTALL_DIR/docs/html/index.html
• xDAIS-DM (Digital Media) User Guide (SPRUEC8)
• TMS320 DSP Algorithm Standard Rules and Guidelines (SPRU352)
• TMS320 DSP Algorithm Standard API Reference (SPRU360)
• TMS320 DSP Algorithm Standard Developer’s Guide (SPRU424)
• TMS320 DSP Algorithm Standard Demonstration Application (SPRU361)