Codec Engine Server Integrator User's Guide

Note: This article was sourced from, and supersedes SPRUED5.

The Codec Engine is a set of APIs that you use to instantiate and run XDAIS algorithms. Interfaces are provided for interacting with XDM-compliant XDAIS algorithms.

Users of Codec Engine play several roles, described in the Codec Engine Roles article. This article goes into detail for those playing the Server Integrator role. This role creates a Codec Server for use by an Engine Integrator and thus an Application Author. This topic explains the steps a Server Integrator should take to configure and create a Codec Engine Server.

Overview

The Server Integrator provides a Codec Server to the Engine Integrator. In practice, these roles may be shared by one person.

There are two configuration steps that the Server Integrator performs:

• Configure BIOS through a config script (BIOS 5 .tcf, BIOS 6 .cfg)
• Configure "the rest" of the components through XDC configuration. The list of components varies from system to system, but this often includes configuration of Framework Components, DSP Link, Codec Engine, and others.

The Server Integrator receives various Codec packages from Algorithm Creators, as well as packages of other components in the system (for example Framework Components and Codec Engine).

The Server Integrator uses Codec Engine and its dependent packages (BIOS, DSKT2, etc.) along with the XDC Tools to create the following:

• A server configuration file (.cfg)
• A BIOS configuration file (BIOS 5 .tcf, BIOS 6 .cfg)
• A simple main() routine to do minimal initialization
• A DSP executable created by executing the configuration scripts, and combining the various packages. This executable is a Codec Server.

The Server Integrator hands a built Server package to the Engine Integrator. This built Server package includes an executable (e.g. *.x64P file for devices with a 64+ DSP like OMAP3, *.x674 for devices with a 674 DSP like OMAP-L138, etc). It's important to provide a full Server package, not just the executable to the Engine Integrator as the Server package contains information about the configuration of the Server (e.g. Memory maps, list of codecs, etc) which the Engine Integrator can utilize - typically via a call in the Engine config script to Engine.createFromServer().

What is a Codec Server?

A Codec Server is a binary that integrates codecs, framework components, and system code. When the Codec Server is on a DSP, it uses BIOS as the DSP kernel.

In the context of the DaVinci DM644x platforms (and other GPP+DSP platforms), a Codec Server is a DSP binary. It includes a BIOS task thread that responds to requests from a client to create codecs, provide performance and resource usage information (MIPS and MEM usage).

A Codec Server performs similarly to a web server. Just as the term "web server" can refer to the actual hardware, the configured software, or the executing daemon, the term "Codec Server" can refer to the DSP, the configured image loaded on the DSP, or the executing task.

The GPP application uses the VISA APIs to invoke remote codecs and algorithms. From the perspective of the GPP application, codec execution is completely transparent, and behaves the same whether the codecs are local (on the GPP) or remote (on the DSP). When remote, Codec Engine automatically manages the necessary creation, communication, invocation, and eventual deletion of codecs from the DSP.

What is the Execution Flow?

The following steps summarize the execution flow when an application uses a remote codec to perform audio encode on a remote Server. After opening the Engine, the application makes calls to the VISA APIs, which manage the three phases of remote codec execution as follows:

1. The application calls the VISA creation API (for example, AUDENC_create()) to create an algorithm instance on the remote Server:
   • First, a generic instance object is created on the local app processor to hold the necessary state, handles, function pointers, etc.
   • A local "node" object is created to receive communication from the "remote" node.
   • A "create" message is formed to signal the function dispatcher on the remote processor to create the remote node instance.
   • The creation message is sent to the dispatcher on the remote processor.
   • On the remote processor, the dispatcher receives the "create" message. Some error checks are performed, and the Server-side state objects are created and initialized.
   • A message queue is created to allow the remote node to receive commands from the application processor.
   • The node-specific "create" function (for example, AUDENC_create()) is called to initialize the node state and algorithm-specific memory and resources. (Note that this call is made from within the dispatcher execution context, which is typically, intentionally, running at a low priority, so it doesn't disrupt any already executing real-time algorithms running.)
   • A dedicated execution thread (task) is created for the node. The new thread does not run yet, but is in a suspended state.
   • In the dispatcher thread, instance data for the new node is saved, and then the dispatcher sends a status response back to the application processor
   • On success, the app-side instance object is updated with appropriate handles and data for the new "remote" node.
   • A "start" message is then formed and sent to the dispatcher on the remote processor to start execution of the remote node.
   • Upon receiving the "start" command, the Server-side dispatcher changes the priority of the node's thread from suspended to its configured execution priority. This change in priority causes the node's "execute" function to run in the newly created node's execution context. This function blocks, awaiting commands from the application.
2. The application calls the VISA process API (for example, AUDENC_process()), which results in a remote procedure call to the Server:
   • The app-side algorithm stub is invoked and performs some basic argument validation.
   • A message structure is allocated and filled in with marshaled arguments, including potentially translated buffer addresses that are suitable for the remote processor.
   • The "process" message is sent to the remote node's message queue on the Server to invoke the remote algorithm.
   • On the Server, the node's thread wakes upon receipt of the "process" message, and calls the algorithm skeleton.
   • The skeleton unmarshalls the arguments and input and output buffers and potentially performs any necessary cache management.
   • Any algorithm scratch memory is then "activated".
   • The algorithm's actual process() function is invoked.
   • Any algorithm scratch memory is then "deactivated".
   • The skeleton potentially performs cache management.
   • The node's thread then replies with the status back to the application processor and then blocks waiting for the next message.
   • Back on the application processor, the stub unmarshalls outArgs, the returned message is freed, and a status is returned to the application
3. When processing is complete, the application calls the VISA delete API (for example, AUDENC_delete()), which causes the algorithm instance on the Server to be deleted:
   • The app-side forms and then sends a message to the remote node on the Server with a command to "exit".
   • On the Server, the remote node wakes upon receipt of the "exit" message and sends an acknowledgment back to the app.
   • On the app, a node "delete" message is formed and then sent to the dispatcher on the Server.
   • The dispatcher wakes up and deletes the remote node's execution thread.
   • The node-specific "delete" function (for example, AUDENC_delete()) is invoked to free algorithm resources and to do any node-specific cleanup. (Note that this call is from within the dispatcher execution context.)
   • The remaining Server-side instance object is deleted, and a response is sent back to the application processor.
   • The remaining app-side instance objects are deleted, the remote node message queue is closed, and then a status is returned to the application.

What About Single-Processor Systems?

On systems with a single processor, or where there are no 'remote' codecs, there is no need to configure a Codec Server. Systems with only 'local' codecs can ignore this Server User's Guide.

What Algorithms Can a Codec Server Integrate?

You can use any algorithm that is XDM-compliant in a Codec Server.

In addition, if you want to use a XDAIS-compliant algorithm that is not XDM-compliant, you can either make the algorithm conform to an XDM interface (try IUNIVERSAL!), or implement your own stubs and skeletons for that algorithm, and then use that algorithm in a Codec Server. See the Codec Engine Algorithm Creator User's Guide (SPRUED6) for details.

The Codec Engine does not provide APIs for chaining algorithms. However, you may use an XDM- or XDAIS-compliant algorithm that, behind its exposed interface, chains algorithms together.

The XDM specification defines an uniform API for each class of algorithms. From an application perspective this means that the same API will be used for an H.264 and an MPEG-4 decoder.

The algorithm is identified by an unique string in the "create" function. Everything else should remain the same. Note that the application must be aware of the restrictions of the algorithm it is trying to invoke. Be sure to review the Codec-provided documentation.

What Examples Exist?

The Codec Engine product includes example Codec Servers which you can review and use. Look in:

• $(CE_INSTALL_DIR)/examples/ti/sdo/ce/examples/servers/all_codecs

Note that old CE releases didn't have the example Server packages in the 'ti.sdo.ce.examples' namespace, so you'll find them in the $(CE_INSTALL_DIR)/examples/servers/... directory.

Are there any wizards to make this easier?

Yes, GenServer was created to simplify these integration steps.

Note that GenServer provided with CE 2.x only supports BIOS 5-based Servers. GenServer provided with CE 3.x creates BIOS 6-based Servers.

Creating a Codec Server

• Configure DSP/BIOS 5 through a Tconf script - .tcf (BIOS 5-based Servers only)
• Configure "the rest" of the components through XDC configuration - .cfg (for example, Framework Components, DSP Link, the Codec Engine, etc.). (BIOS 6-based Servers configure BIOS 6 via this same XDC config script as well)

You will modify the following files:

• package.xdc. The package definition file.
• package.bld. The build script.
• servername.cfg. The Codec Server configuration script.
• servername.tcf. The DSP/BIOS 5 configuration script (not needed on BIOS 6-based Servers).

Optionally, you may modify the following additional files:

• link.cmd. An optional linker command file.
• main.c. Contains application's main() function.

To begin creating a Codec Server, use the steps in the following subsections. The examples in this section use the $(CE_INSTALL_DIR)/examples/.../servers/all_codecs example.

So long as the algorithms you want to use implement the XDM interface, the C coding needed is limited to a simple main() routine to initialize the Codec Engine. The rest of the integration is by providing configuration information to create the Codec Server.

Creating a Package

Follow these steps to set up environment variables to point to various tools used in the build process and to create a directory with files you will modify to create your server.

1. Optionally copy the entire $(CE_INSTALL_DIR)/examples tree to a working directory. This step is optional but recommended so that you have a backup copy.
2. Edit the examples/xdcpaths.mak file with a text editor to specify the CE_INSTALL_DIR, XDC_ROOT, and BIOS_ROOT variables. Edit the paths to the TI codegen tools and other compilers and OS tools referenced in the file that you will be using. See examples/build_instructions.html for details.
3. Make a duplicate of one of the Codec Server examples in the examples/servers directory. Each of these directories is a "package". Packages must have names that match their directory location. So, you should give your duplicate directory a path that follows the examples/my_company/my_project/my_server naming convention.

You will name the package to match this location in the following section.

Editing the Package Definition

The package.xdc file is the package definition file, which defines your Codec Server's name and its dependencies.

To name your server package, edit the package.xdc file with a text editor. Rename the server package. For example, to call your server "my_server", change the bolded portion as follows:

package my_companyname.my_project.my_server

The package name must reflect the directory structure under the examples directory. For example, a package in the example/my_company/my_project/my_server directory must have a name of my_company.my_project.my_server. You should use this companyname convention to ensure that your server has a unique package name.

Editing the Codec Server Configuration Script

A file named servername.cfg configures many aspects of the Codec Server. To create this file for your own server, it is best to modify an existing example file.

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

The object model provided to configure CE (and other modules) is documented in the Configuration Reference, which is available online here or in your CE product's $(CE_INSTALL_DIR)/xdoc/index.html. For example, to see documentation for the attributes of the ti.sdo.ce.Server module, open the Config Reference Guide and follow these steps:

1. Locate and click on the ti.sdo.ce package in the tree view on the left side
2. Click the link to the Server module.
3. You see the config params that you can set for this module.

For example, you see that the Server.threadAttrs structure has several fields. The following statements cause the Server module in the ti.sdo.ce package to be made available to the configuration script. It then sets the threadAttrs.priority attribute of the Server module to Server.MINPRI. This indicates that the task threads created by the Codec Server should run at the minimum priority level.

<syntaxhighlight lang='javascript'> var Server = xdc.useModule('ti.sdo.ce.Server'); Server.threadAttrs.priority = Server.MINPRI; </syntaxhighlight>

To create your own *.cfg file for your server, follow these steps:

1. Rename the *.cfg file in your server directory to match the name of your server. For example, your file might be called "my_server.cfg".
2. Edit the servername.cfg file with a text editor.
3. BIOS5 ONLY: In order to allow application developers to use the TraceUtil module on the GPP side to gather DSP/BIOS log information, you must enable DSP/BIOS logging in your DSP server image. If the following line is not already in your server's configuration script, you should add it to enable DSP/BIOS logging:

   var LogServer = xdc.useModule('ti.sdo.ce.bioslog.LogServer');

4. Modify the statements that get codec modules to reference the codec modules you want to use. Use the package name from your codec provider. Example codecs are available in the "examples" repository beginning with the "codecs" namespace (that is, the examples\codecs directory). Your codecs should be "well named" beginning with your company name to produce unique package names.

   For example, these statements from the all.cfg file have been modified (bold text) to reference the speech encoder/decoder.

   /* get various codec modules; i.e. codec implementations */

   var SPHDEC_COPY = xdc.useModule('codecs.sphdec_copy.SPHDEC_COPY');

   var SPHENC_COPY = xdc.useModule('codecs.sphenc_copy.SPHENC_COPY');

5. Modify the attributes of the threadAttrs structure as desired. See CE_INSTALL_DIR/xdoc/index.html for details about these attributes.

   Server.threadAttrs.stackSize = 2048;

   Server.threadAttrs.priority = Server.MINPRI;

   These settings configure the Server thread, which is used to create and delete codecs as well as to support requests for dynamic resource usage. We recommend that you use Server.MINPRI so you don’t preempt real-time threads.

6. Specify the algorithms to be available in this Codec Server by modifying the Server.algs array. For example, statements from the all.cfg file have been added and modified (bold text) to reference the speech encoder/decoder and to give audio processing a higher priority than video processing.

<syntaxhighlight lang='javascript'>Server.algs = [

 {name: "viddec_copy", mod: VIDDEC_COPY, threadAttrs: {
     stackSize: 4096, stackMemId: 0, priority: Server.MINPRI + 1}
 },
 {name: "videnc_copy", mod: VIDENC_COPY, threadAttrs: {
     stackSize: 4096, stackMemId: 0, priority: Server.MINPRI + 1}
 },
 {name: "sphdec_copy", mod: SPHDEC_COPY, threadAttrs: {
     stackSize: 4096, stackMemId: 0, priority: Server.MINPRI + 2}
 },
 {name: "sphenc_copy", mod: SPHENC_COPY, threadAttrs: {
     stackSize: 4096, stackMemId: 0, priority: Server.MINPRI + 2}
 },

];</syntaxhighlight>

The example *.cfg files also 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. See the Framework Components documentation in CE_INSTALL_DIR/xdoc/index.html for details on configuring these modules.

Controlling I/O Buffer Caching

Because CE Servers run on remote processors, cache management is an important consideration. The following articles go into detail about cache management, describe Codec Engine-related overheads, and techniques to avoid these overheads when possible.

• Cache Management - General overview of cache management - especially as applied to XDAIS algorithms
• Codec Engine Overhead - Describes overheads associated with Codec Engine and options for eliminating some of them, including those related to cache

Specifying "Scratch Groups" for Algorithms

When you put together several algorithms into a Server, you may need to make them share memory, DMA and/or other resources.

Two algorithms can share resources by placing them into the same "scratch group". The Codec Engine GroupIds article describes this in more detail, and includes examples for assigning scratch groups for algorithms.

Editing the DSP/BIOS5 Configuration Script

This section only applies to Codec Engine versions with BIOS5 as the underlying OS. The Codec Server runs as a DSP/BIOS application on the DSP. As such, it has a static DSP/BIOS configuration. This is created with a .tcf file as described in the DSP/BIOS Textual Configuration (Tconf) User's Guide (SPRU007) and in the DSP/BIOS online help. The syntax used in Tconf configurations is based on JavaScript.

To create your own .tcf file for your server, follow these steps:

1. Copy all.tcf from $(CE_INSTALL_DIR)/examples/ti/sdo/ce/examples/servers/all_codecs to your server directory. Rename it to match the name of your server. For example, your file might be called "my_server.tcf".
2. Edit the servername.tcf file with a text editor.
3. Make any changes your Codec Server requires and save the file. For the Codec Server, the task threads used to process algorithms are created dynamically at runtime. This configuration file statically configures several aspects of the DSP/BIOS kernel, including:
   • The base DSP/BIOS kernel
   • Memory section names, sizes, and locations
   • Platform-specific attributes such as clock rates
   • Enables the task manager and dynamic heap allocation
   • Configures the C64+ L1 cache and corresponding memory segment

You can learn more about all of these modules and attributes in the DSP/BIOS online help or the C6000 DSP/BIOS API Reference (SPRU403).

You can add your own non-Codec Engine configuration items here if you need to add your own functionality to the Server.

DSP/BIOS Threads and Module Use

Each "remote" algorithm instance that runs on the DSP executes in a DSP/BIOS thread whose priority is specified by a static configuration parameter (see ti.sdo.ce.Server). The stack size of the thread that runs a "remote" algorithm is specified by the algorithm's implementation of the ICodec interface (see ti.sdo.ce.ICodec).

The Codec Engine runtime starts a separate thread for each "remote" algorithm instance; thus, two instances of the same algorithm run in two separate threads (even though these threads have the same stack size and priority).

Creation and deletion of algorithm instance threads is handled by a Resource Manager Server (RMS) thread. This thread is part of the Codec Engine Runtime and, by default, runs at the lowest possible priority so as to avoid affecting real-time processing performed by "remote" algorithm instances. The RMS thread also provides "resource monitoring" services to the Codec Engine Runtime. For example, it reports overall DSP CPU load to the GPP, transfers execution trace data from the DSP to the GPP, and controls the acquisition of DSP trace information based on GPP commands.

In order to support CPU load monitoring, the Codec Engine adds an idle function to the DSP/BIOS idle loop. The current implementation allows other application-specified idle functions to also run. However, to support low power modes of the DSP, future implementations may idle the CPU, which prevents other idle functions from running.

Note that the changes mentioned in this section are not certain. We are simply pointing out areas of the implementation that may be subject to change in future releases.

Codec Server Configuration (BIOS6)

This section applies to versions of Codec Engine that use BIOS6 as the underlying OS. Configuration of Codec Engine and Framework Components modules under BIOS6 is largely the same as configuration with BIOS5. Some modules, such as TraceUtil and GT have been removed, as they have been replaced by xdc.runtime Log APIs. The main changes for configuration of a codec server under BIOS6 are:

• Platform memory map configuration
• BIOS configuration
• Logging setup
• IPC configuration

As an example of a Codec Engine on BIOS6 server configuration, we can look at the files in $(CE_INSTALL_DIR)/examples/ti/sdo/ce/examples/servers/all_codecs.

Platform Memory Map Configuration (BIOS6)

In the all_codecs directory, there is a build configuration script, _config.bld, that specifies which platforms to build for the defined targets. For example, if we’re building M3elf targets for a TI816X device (devices are set in $(CE_INSTALL_DIR)/examples/xdcpaths.mak), this build script defines the M3elf platforms as:

<syntaxhighlight lang='javascript'> M3elf.platforms = [

       "ti.platforms.evmTI816X:VIDEO-M3",
       "ti.platforms.evmTI816X:VPSS-M3"

]; </syntaxhighlight>

The ti.platforms.evmTI816X platform already exists in the XDCTOOLS product, with given memory maps for the VIDEO-M3 and VPSS-M3 processors, but we may want to change them. So we define the two new M3elf platforms above, where we override the memory map in the ti.platforms.evmTI816X definition. Adding the strings ":VIDEO-M3" and ":VPSS-M3" to the original platform name causes the new platforms to inherit all properties that we do not override, from the original platform. The new memory map for the M3elf platforms is defined in the file, serverplatforms.xs in the all_codecs directory. Here we define a variable that describes the memory map (partially listed below):

<syntaxhighlight lang='javascript'> var TI816X_M3_MemoryMap = [

           ["DDR3_HOST", {
               comment: "DDR3 Memory reserved for use by the A8",
               name: "DDR3_HOST",
               base: 0x80000000,
               len:  0x0B000000    /* 176 MB */
           }],
           ...
           ["DDR3_M3", {
               comment: "DDR3 Memory reserved for use by the M3 core",
               name: "DDR3_M3",
               base: 0x8F000000,
               len:  0x00800000    /* 8 MB */
           }],
           ["DDRALGHEAP", {
               comment: "DDR3 Memory reserved for use by algorithms on the M3",
               name: "DDRALGHEAP",
               base: 0x8F800000,
               len:  0x00800000    /* 8 MB */
           }],

]; </syntaxhighlight>

Then we add the new platform to the global Build table, specifying the new external memory map and placements for code, data, and stack:

<syntaxhighlight lang='javascript'> Build.platformTable["ti.platforms.evmTI816X:VIDEO-M3"] = {

   externalMemoryMap: TI816X_M3_MemoryMap,
   codeMemory: "DDR3_M3",
   dataMemory: "DDR3_M3",
   stackMemory: "DDR3_M3"

}; </syntaxhighlight>

BIOS6 Configuration

BIOS is set up in all_syslink.cfg by including the following line:

<syntaxhighlight lang='javascript'> /* Setup xdcruntime proxys */ xdc.useModule('ti.sysbios.xdcruntime.Settings'); </syntaxhighlight>

This sets up the system to use the appropriate BIOS services.

BIOS heap configuration is separated out into the file, heaps.cfg, which is loaded by all_syslink.cfg. The BIOS heap creation is wrapped with a utility function, createHeapMem(), defined in

$(CE_INSTALL_DIR)/examples/ti/sdo/ce/examples/buildutils/heap_config.cfg

Each of the heaps is created as a global object, for example:

<syntaxhighlight lang='javascript'> Program.global.EXT_HEAP = heapConfig.createHeapMem(externalHeapSize, ".EXT_HEAP", externalMemoryName); </syntaxhighlight>

Creating heaps as global objects allows them to be used by other modules, such as DSKT2, and allows for the gathering of Memory usage statistics by the host app.

Logging Setup

Codec Engine under BIOS6 uses xdc.runtime Log APIs for trace, to be consistent with BIOS. Logging is setup for the all_codecs server by simply loading a utility file in all_syslink.cfg:

<syntaxhighlight lang='javascript'> // Set up logging xdc.loadCapsule('ti/sdo/ce/examples/buildutils/server_log.cfg'); </syntaxhighlight>

This sets up the server’s logging to enable gathering of Log data by the host application.

IPC Configuration

A Codec Engine server using SysLink for inter-processor connectivity, must configure the following modules:

• ti.sdo.utils.MultProc – Manages processor name to processor ID mapping and set the ID of the processor that the server executable is built for.
• ti.sdo.ipc.SharedRegion – Manages memory regions that are shared across processors.

For dual-core ducati subsystems, the following module must also be configured:

• ti.sysbios.family.arm.ducati.Core – Defines which core of a ducati dual-core subsystem the server is being built for. See all_syslink.cfg for an example of this configuration.

MultiProc configuration can be done as follows:

<syntaxhighlight lang='javascript'> var MultiProc = xdc.useModule('ti.sdo.utils.MultiProc'); var myName = "DSP"; // Set to the name of the processor the server is

                    // being built for, eg, "DSP", "VIDEO-M3", or
                    // "VPSS-M3"

var settings = xdc.useModule('ti.sdo.ipc.family.Settings'); var procNames = settings.getDeviceProcNames(); MultiProc.setConfig(myName, procNames); </syntaxhighlight>

The SharedRegion configuration for the all_codecs server example for the TI816X device is located in the file all_codecs/ti_platforms_evmTI816X.cfg. In this platform specific file, two SharedRegion entries are configured. The first one, which is assigned an index of 0, is used for Host to Target (DSP or M3) communication through SysLink. SharedRegion 1 is used for allocating VISA messages that are passed between the host application and the Codec server (although SharedRegion 0 could also have been used for the VISA messages).

Editing the Build Script

Edit the package.bld file with a text editor. This build script is run by the makefile. In addition to compiling code, the build script runs the DSP/BIOS 5 and XDC configuration scripts and links the executables together.

Change the bold text in the following line to match your server name: <syntaxhighlight lang='javascript'> var serverName = "my_server"; </syntaxhighlight>

When you have finished development, you may want to change "debug" in the following line to "release": <syntaxhighlight lang='javascript'> Pkg.attrs.profile = "release"; </syntaxhighlight> Do not edit package.mak, any files that begin with a period, or anything in the "package" directory. These files are generated when you build. Any modifications to these files are overwritten whenever you rebuild.

Editing main.c

The only requirement for a Server's main() function is to call CERuntime_init(). It can literally be as simple as the following:

<syntaxhighlight lang='c'>

1. include <xdc/std.h>
2. include <ti/sdo/ce/CERuntime.h>

1. ifdef BIOS6
2. include <ti/ipc/Ipc.h>
3. endif

Void main(Int argc, Char *argv[]) {

1. ifdef BIOS6

   /* BIOS 6 users must call Ipc_start() in main(), before CERuntime_init() */
   Ipc_start();

1. endif

   CERuntime_init();

   /* add any custom initialization, task creation, etc you like */

1. ifdef BIOS6

   /* Note that BIOS 6 users will need this additional statement */
   BIOS_start();

1. endif

} </syntaxhighlight>

As noted by the comment, you may add to the main.c source file as necessary. This can include non-CE-related BIOS task creation, etc.

Note that in BIOS 5 based systems, the BIOS task scheduler only begins after main() completes, so you should only put initialization statements in main(), and main() must run to completion rather than looping. In BIOS 6 based systems, BIOS_start() will not return as BIOS_start() starts the task scheduler.

See BIOS documentation for further details and constraints about code in main().

Delivering a Codec Server

To distribute a Codec Server, you should deliver the package used to produce the server, including the server executable. The package contains the configuration scripts that produced the server. The package information also specifies the version of the compiler used to make the server and the versions of the codecs used to make the server.

When you distribute a Codec Server, you should provide documentation that includes the following information:

• Codec Server name
• Build options used for compiling and linking
• List of the algorithms available in the Codec Server

Delivering Server Packages for Servers Built with XDC

If you built your server via XDC (that is, there is a "package.bld" file and the makefile is very short), you need to add the directory "package/info" to Pkg.otherFiles as follows to include the generated server info files in the release:

<syntaxhighlight lang='c'>Pkg.otherFiles = [ ...., "package/info", ... ];</syntaxhighlight>

Also, modify the makefile to run the "xdc release" step as the main goal (differences shown in bold):

<syntaxhighlight lang='c'> EXAMPLES_ROOTDIR := $(CURDIR)/../../../../../..

include $(EXAMPLES_ROOTDIR)/xdcpaths.mak

1. add the examples directory to the list of paths to packages

XDC_PATH := $(EXAMPLES_ROOTDIR);$(XDC_PATH)

1. include $(EXAMPLES_ROOTDIR)/buildutils/xdcrules.mak
2. run "xdc release" to create a tar file with the server(s)

all:

  $(XDC_INSTALL_DIR)/xdc release XDCPATH="$(XDC_PATH)" \
  XDCOPTIONS=$(XDCOPTIONS) $@ -PD .

</syntaxhighlight>

When you type "make", a .tar file will be created. That is your server deliverable.

See ti/sdo/ce/examples/servers/all_codecs/package.bld for an example.

Delivering Server Packages for Servers Built with Configuro-based makefiles

Note, using configuro-based makefiles to build/release Servers is strongly discouraged. They frequently contain mistakes which result in Engine.createFromServer() to fail. It is strongly recommended to use the package.bld based build described in the previous section. However, some releases of Codec Engine provided examples demonstrating this makefile/configure-based build technique, so this section is here for completeness.

If you built your server via Configuro (a utility that generates object and linker files from a user .cfg script) that is driven from a makefile (which is then not very short), you must add a step to the makefile to create a server package and an archive from it.

DSP servers built with Configuro do not require a package to build the server itself, but you must create one to produce a server deliverable. In that package, you must include both the server executable and the Configuro-generated "package/info/*" files.

While each Configuro-using makefile is different, here's an example of how the server package generation may look. Here we auto-generate an XDC package from the given package name $(SERVER_PKG), given the server executable name $(SERVER_EXE), and config name $(CONFIGPKG), knowing that Configuro-generated files are in the $(CONFIGPKG) directory:

<syntaxhighlight lang='c'> SERVER_PKG := ti.sdo.ce.examples.servers.video_copy.evmDM6446

SERVER_PKG_ARCHIVE := $(subst .,_,$(SERVER_PKG)).tar

1. create server release package and archive it; the package
2. contains the executable and some meta-info files

$(SERVER_PKG_ARCHIVE): $(SERVER_EXE)

 @echo "Creating server release:"
 @rm -rf package package.*
 @echo "package $(SERVER_PKG) {}" > package.xdc
 @echo "Pkg.otherFiles = ['./$(SERVER_EXE)','package/info']" \
   > package.bld
 @mkdir package ; cp -R $(CONFIGPKG)/package/info package
 @$(XDC_INSTALL_DIR)/xdc XDCPATH="$(XDC_PATH)" release
 @rm -f package.bld package.mak .[idle]*

</syntaxhighlight>

For this example to work, the makefile and the server executable must be in a directory whose path ends with "ti/sdo/ce/examples/servers/video_copy/evmDM6446", because that is the name we have given to the server package.

See ti/sdo/ce/examples/servers/video_copy/evmDM6446/makefile for an example.

Additional Documents and Resources

• Codec Engine Overview
• Codec Engine Application Developers Guide
• Integrating a Codec Engine
• Codec Engine Algorithm Creator User's Guide (PDF:SPRUED6)
• CE 2.x API Reference. (also available in $(CE_INSTALL_DIR)/docs/html/index.html)
• CE 2.x Package/Configuration Reference (also available in $(CE_INSTALL_DIR)/xdoc/index.html)
• XDAIS/XDM API Reference
• XDAIS Documentation
• XDAIS-DM (Digital Media) User Guide (PDF:SPRUEC8)