RTSC Server Package Wizard FAQ

END OF LIFE

This utility is deprecated. Users are currently recommended to use GenServer.

General Questions

What does the wizard do? What does the wizard generate?

The RTSC Server Package Wizard generates the files needed to create a server package containing 1 codec including:

• XDC files like package.xdc and package.bld
• A TCF file (for BIOS 5 RTOS configuration)
• XDC Configuration scripts (for both server and codec)
• A C file containing a simple main() implementation
• linker command file.

The server is generated by running the xdc release command after the wizard has finished generating the necessary files.

What inputs are required?

A RTSC Codec Package that has the same format as the packages generated by the RTSC Codec Package Wizard.

Optional Inputs:

• Platform (e.g. ti.platforms.evmdm6446)
  • If none specified, ti.platforms.evmdm6446 used by default.
• Codec Module Name (needed if the codec module name is not the suffix of the package name, e.g. ti.sdo.codecs.mpeg2dec has module mpeg2dec defined in package.xdc.
• Output Repository for the server
  • If none specified, then the output repository of the codec package is used as the server's output repository
• Server Package Name
  • If none specified, the wizard will generate a package name based on the codec package's name

Installation

What software prerequisites exist for using the wizard?

The wizard requires other TI tools:

• Codec Engine 1.20.02 or greater

• Codec Engine Tools (found in CE directory) or XDAIS 5.21 (or greater)

• DSP/BIOS

• XDC Tools 2.95 or greater

How do I install and run the wizard?

We recommend you install the wizard (directory ceutils_x_xx) in a path without spaces. After downloading and installing ceutils_x_xx:

• Step 1: Install Required Pre-requisites (listed in 1.1)

• Step 2: Add the following to your XDCPATH:
  • <your installation directory>/ceutils_x_xx/packages
  • <Codec Engine>/packages
  • <your repository containing codec packages>

An example on Linux if using 'full' Codec Engine might be: -

export XDCPATH="/home/alan/rtsc_wizards/ceutils/packages;/home/alan/workdir/codec_engine_2_20/packages;/home/alan/workdir/codec_engine_2_20/cetools/packages;/home/alan/workdir/omap3_dev/omap3_test_combos/packages"

• Step 3: Run the RTSC Server Package Wizard by executing:
  • <your XDC installation directory>/xs ti.sdo.codecutils.genserver -g

Note: You must provide a config.bld to build - XDCtools searches for this file in your current directory, then the XDCPATH, and finally XDCROOT and XDCROOT/etc. Verify the config.bld you wish to use will be found before any other config.bld by placing its parents directory earlier in your XDCPATH. If you encounter build errors related to your config.bld, verify that the paths contained in config.bld are correct. Also see xdc.pdf in XDCROOT/docs for more information.

How do I set my XDCPATH?

See the RTSC Codec Package Wizard FAQ RTSC_Codec_Package_Wizard_FAQ#How_do_I_set_my_XDCPATH here

Also see the example above.

The XDCPATH is too long to type. Is there another way?

Yes. You can do it once and put it in a file. For example you can make a file wiz_paths.txt and put inside it: -

--xdcpath
/home/alan/rtsc_wizards/ceutils/packages;/home/alan/workdir/codec_engine_2_20/packages;/home/alan/workdir/codec_engine_2_20/cetools/packages;/home/alan/workdir/omap3_dev/omap3_test_combos/packages

(this is 2 lines i.e. --xdcpath <NEWLINE> path(s) (all in 1 line) )

To invoke the wizard you then do (replace path with your path to your XDC tools): -

/opt/dmsw/xdc_3_00_06/xs @wiz_paths.txt ti.sdo.codecutils.genserver

As you can see, cetools saves you a bunch of typing in itself! The other (main) advantage is that cetools will have the right version of all its dependencies inside. No possibility of package Compatibility Key problems.

NOTE - as of ceutils 1.06 there is a "helper makefile" which vastly reduces the amount of typing (and thereby the amount of errors) you need. Here is a data dump from the makefile help: -

#
#  ======== Makefile ========
#  This makefile is optional - you can use all of it or none of it.
#  Its purpose is to save time/typing when used from the context of the DVSDK.
#  All of the paths are preset in the $(DVSDK_INSTALL_DIR)/Rules.make. The wizards
#  (particularly the server wizard) requires many of these paths hence by setting
#  the XDCPATH here we save the user some typing and package-path setup.
#  Commands (make goals): -
#  - Start the codec packaging wizard
#  [>] make genpackage
#  - Start the server wizard
#  [>] make genserver
#  - Clean the codecs/server packages
#  [>] make clean
#  - Build the codecs/server packages
#  [>] make
#  - Release the codecs/server packages (generate tarballs)
#  [>] make release
#  Note : if your codec/server packages are in a different location outside
#  the DVSDK simply override the CODEC_INSTALL_DIR on the cmd line via e.g.
#  [>] make CODEC_INSTALL_DIR="/home/user/mycodecs"
#  Note : if using the wizard standalone outside of the DVSDK you can still
#  leverage this makefile by modifying the include Import Tools Path below
#  to point to your DVSDK Rules.make
#  [>] make CODEC_INSTALL_DIR="/home/user/mycodecs" SERVERNAME="decode"
#  - Creates a DSP Server named decode.x64P
#

Because ceutils comes in a standardized place in the DVSDK this should "just work". This is true for DVSDK 2.0 & 3.0. If you're using e.g. DVSDK 1.30 or 1.40 you could just drop in ceutils_1_06 into your top-level DVSDK and it will also "just work". If you dont like modifying your base DVSDK install (perhaps its in a shared location on a team linux box) then you can just edit the ceutils/Makefile to point to your own Rules.make e.g. instead of...

# Import Tools Path from Rules.make
include ../Rules.make

...use...

# Import Tools Path from my own Rules.make
include ${HOME}/workdir/omap3_dev/Rules.make

...or similar.

What files are included with the wizard?

The wizard consists of the ti.sdo.codecutils.genserver package containing XDC files (package.xdc, package.bld, Main.xdc), XDC script files (denoted with extension .xs), templates directory (*.xdt files used to generate XDC files), docs directory (containing auto-generated JavaScript documentation), and a readme. Additionally, ceutils_x_xx contains an examples directory

Running the Wizard

How do I run the example?

After you have started the GUI wizard, open the mycompany_mygroup_servers_vc_wizard.xml file located in the examples directory of ceutils_x_xx via File->Open.

What if I need help on the command line?

See the RTSC Server Package Wizard help by: xs ti.sdo.codecutils.genserver --help

What if I need help using the GUI version?

After you have started the GUI Wizard, use Help->Instructions

When would I use the --module option on the command line or edit the module field in the GUI?

If the module name does not match the suffix of the package name, then this option must be used. For example, if the codec package name is mycompany.mygroup.codecs.viddec_copy_example and the codec package has module viddec_copy (which is found by examining the codec package's list of modules in package.xdc), then the --module option must be used.

What if I want to use a different memory map?

1. Edit server.tcf.xdt (in ti/sdo/codecutils/genserver/templates) or
2. Create a new.tcf.xdt and edit mkpkg.xdt (associate the platform file with the new .tcf)

What if I am using a platform other than ti.platforms.evmDM6446 or ti.platforms.evmDM6467?

1. Save your yourplat.tcf and yourplat.cfg files as yourplat.tcf.xdt and yourplat.cfg.xdt in ti/sdo/codecutils/genserver/templates
2. Edit mkpkg.xdt to associate these .tcf and .cfg files with your platform

What if I want to use DMAN3 on DM6467?

As of ceutils 1.07, the DM6467 server.cfg template (found at ti/sdo/codecutils/genserver/templates/ti.platforms.evmDM6467/server.cfg) does not configure DMAN3 (it instead assumes that the IRES interface is used instead of IDMA3 to request DMA resources). RMAN is used instead to talk to the IRES interface. However, DMAN3 is still supported on DM6467. If you are moving a codec from DM6437 or similar, it likely requested its DMA resources through the IDMA3 interface and you will need to manually add the configuration for DMAN3 into the server.cfg file in the unit server templates. If you want an example that shows you how to configure DMAN3, you can refer to the Codec Engine examples (the all_codec server example configures DMAN3, found at codec_engine_x_xx/examples/ti/sdo/ce/examples/servers/all_codecs/all.cfg). Simply copy the DMAN3 configuration into the wizard's DM6467 server.cfg template. Note that you should not replace the entirety of the server.cfg template with all.cfg since the wizard's templates store the codec configuration in a separate file, codec.cfg.

Improving performance on the generated servers

manageOutBufsCache cfg setting

Cache Management can introduce significant overhead when processing large data buffers. There are some techniques you can apply to minimize this overhead, when possible.

For example, on the actual combos shipped with the DVSDK you may see the following in e.g. servers/decode/decode.cfg

<syntaxhighlight lang='javascript'> /* Switching off outbufs cache management */ MPEG4DEC.manageOutBufsCache = [ false, false, false, false, false, false, false,

   false, false, false, false, false, false, false, false, false ];

</syntaxhighlight>

This field is documented in e.g. Codec Engine's ti.sdo.ce.video2.IVIDDEC2 interface reference (or any of the other Imaging and Video classes such as IVIDENC1).

This cache config param was added in CE 2.0 for XDM remote image and video algorithms. Using this feature, it is possible to configure these interfaces to not writeback the output data buffers if, for example, these are being moved between internal and external (shared) memory using DMA. This can significantly improve performance of remote process() calls, as writing back large video or image buffers is time consuming.

The server wizard doesn't automatically generate this for 2 reasons: -

• the wizard can't know whether a given codec uses DMA or the CPU. 1 version of h264dec might use the DMA, whilst another might use the CPU.
• the wizard is based off config templates for Framework Components, Codec Engine etc. We can't put individual codec package names in the templates.

Users should add the manageOutBufsCache setting to their server/combo cfg file if they know its safe.

link.xdt settings for best L1P cache performance

See the Top 10 list re performance.

You shouldn't need to do anything here if all the codec package producers did their job right. Check the server's generated package/cfg/*.xdl file. You might see content like: -

<syntaxhighlight lang='javascript'> /* Content from ti.sdo.codecs.aachedec (ti/sdo/codecs/aachedec/link.xdt): */

         SECTIONS
         {
         .text:_AACDEC_TII_decode  > DDR2
         .text:_AACDEC_TII_GetAdifHeader > DDR2
         .text:_AACDEC_TII_GetBits > DDR2
         ...

</syntaxhighlight>

Codecs often contribute memory layout content like this in their link.xdt to improve c64P cache performance (L1P conflicts).

Of course if none of the codecs have such a contribution you won't see this.

Release Issues

What do I need to do after the wizard has successfully output the files needed?

• After generating files using the RTSC Server Package Wizard, edit codec.cfg. Place each section listed in codec.cfg in a section defined in server.tcf.
  • Example:
    • Original line: VIDDEC_COPY.alg.codeSection = undefined;
    • Modified line: VIDDEC_COPY.alg.codeSection = "DDR2";
    • Don't forget the quotes!

• Note:
  • You must have the following on your XDCPATH to build a server:
    • Codec Engine Dir\packages
    • Codec Engine Dir\cetools\packages or XDAIS repository
    • BIOS Directory\packages
  • Additionally XDCTools must be supplied with a config.bld - check to see if your config.bld requires a user.bld! For example, the config.bld usually found in Codec Engine Dir\packages searches for a user.bld. The user.bld is searched for in an analogous manner as the config.bld. If you can't find a config.bld, here's a simple one Sample config.bld for C64P.zip that you can use for C64+ servers. In the file, just make sure you modify the path to the code generation tools and the platform you are building for.
    • To explicitly specificy the config.bld, modify your XDC build command to: XDCBUILDCFG=<path_to_config.bld> xdc release -PD .
    • Alternatively, the XDCTools will search for a config.bld along your XDCPATH (using the first one it finds) and then in the XDCTools Dir\packages directory.
    • Option: Start your XDCPATH with Codec Engine Dir\packages, then Codec Engine Dir\examples; then, assuming you have not added a user.bld in CE\packages, the config.bld will be used from CE\packages and the user.bld from CE\examples.

• Run xdc release -PD . to generate the server executable from the output directory (output repository + server.package.name.with.dots.turned.into.forward.slashes).

• You can override the default server name and default profile via: xdc release XDCARGS="release myNewServerName" -PD .

How do I create a server combo?

• Create the unit servers for each of the codecs to be included
• Copy a single unit server into another location e.g. packages/ti/sdo/servers/audio_server_evmdm6467 — this will become our combo package name
• Make the following changes:
  • Edit package.xdc (change the package name to the directory name of the server combo)

For example, if making an audio-only (encode + decode) example combo only on DM6467 this might be: - <syntaxhighlight lang='javascript'> package ti.sdo.servers.audio_server_evmdm6467 [1,0,0] { } </syntaxhighlight>

• • Copy each of the individual codec’s codec.cfg into a combo’s codec.cfg file - Note You may need to change the priorities (see Codec Engine documentation on how to do this). Also, you will need to combine the individual Server.algs into a single, larger Server.algs by copying and pasting {name: "xxx", ... groupId: 0,} from the individual codec Server.algs into the single, larger Server.algs to look something like Server.algs = [ {name: "xxx",...,groupId: 0}, {name: "yyy",...,groupId: 0} ];.

Again, using the audio_server example: - <syntaxhighlight lang='javascript'> var AACENC = xdc.useModule('ti.sdo.codecs.aacenc.ce.AACENC');

   // Package Config
   AACENC.alg.watermark = false;
   AACENC.alg.codeSection = 'DDR2';
   AACENC.alg.udataSection = 'DDR2';
   AACENC.alg.dataSection = 'DDR2';

var AACDEC = xdc.useModule('ti.sdo.codecs.aacdec.ce.AACDEC');

   // Package Config
   AACDEC.alg.watermark = false;
   AACDEC.alg.codeSection = 'DDR2';
   AACDEC.alg.dataSection = 'DDR2';

/*

* The array of algorithms this server can serve up.  This array also configures
* details about the threads which will be created to run the algorithms
* (e.g. stack sizes, priorities, etc.).
* Since this is audio-only we use the same groupId.
* If adding video we'd need different groupId's and priorities for video .v. audio
*/

Server.algs = [

   {name: "aacenc", mod: AACENC , threadAttrs: {
       stackMemId: 0, priority: Server.MINPRI + 2}, groupId : 0,
   },
   {name: "aacdec", mod: AACDEC , threadAttrs: {
       stackMemId: 0, priority: Server.MINPRI + 2}, groupId : 0,
   },

]; </syntaxhighlight>

Note if you're doing audio + video, then as noted above you probably want to change the groupId's and priorities. Audio (or speech) should be higher priority than video since its frame rate is higher and therefore its deadlines must not be threatened by compute-intensive video algorithms e.g. <syntaxhighlight lang='javascript'> Server.algs = [

   {name: "mpeg4dec", mod: MPEG4DEC , threadAttrs: {
       stackMemId: 0, priority: Server.MINPRI + 1}, groupId : 0,
   },
   {name: "aachedec", mod: AACHEDEC , threadAttrs: {
       stackMemId: 0, priority: Server.MINPRI + 2}, groupId : 1,
   },

]; </syntaxhighlight>

• • Add validate_one_codec() functions to package.xs for each codec (to validate the codec.cfg content from each codec)

Example: - <syntaxhighlight lang='javascript'> function validate() {

   // Each codec is validated with the following call:
   //    validate_one_codec(<package name>, <module name>);

   validate_one_codec( "ti.sdo.codecs.aacenc", "AACENC" );
   validate_one_codec( "ti.sdo.codecs.aacdec", "AACDEC" );

} </syntaxhighlight>

• Do a quick clean since you probably still have the old executables from the original unit server in there.

xdc clean

• Build it & test it! (Make sure your XDCPATH variable is set as per the codec server wizard instructions and that the appropriate config.bld file can be found by xdc)

xdc

• If you're happy with it, then it's ready for 'release'. Run

xdc release –PD .

from the combo directory (the same process as if we were releasing a unit server) and then send the resultant tar-ball to your customer :-)

Build Errors

What if I get an error like "Error: Package, mycompany.mygroup.codecs.viddec_copy, not found with module VIDDEC_COPY... modify your XDCPATH to include the package's repository." when running the RTSC Server Package Wizard?

Try the following:

1. Verify your XDCPATH includes the codec package's repository. For example, if my codec package mycompany.mygroup.codecs.viddec_copy is located in c:/my_package_repo/mycompany/mygroup/codecs/viddec_copy, make sure c:/my_package_repo is in the XDCPATH
2. Verify that your codec package has been built! Browse to the package base directory(c:/my_package_repo/mycompany/mygroup/codecs/viddec_copy) and verify a directory "package" exists with file <package name>.sch (in this example, check for c:/my_package_repo/mycompany/mygroup/codecs/viddec_copy/mycompany.mygroup.codecs.viddec_copy.sch). If this does not exist, run xdc release -PR . to release the codec package from the base directory.
3. Verify that your package does not require other packages. If it does, the repositories for these packages should also be on your XDCPATH.
4. Verify that your codec package was created using the RTSC Codec Package Wizard OR is of the same format! This includes having a CE subpackage! If the package does not have a CE directory, use the RTSC Codec Package Wizard and xdc release the package prior to running the RTSC Server Package Wizard.

What if I get an error like: js: "C:/xdc_2_95_01/include/utils.tci", line 826: exception from uncaught JavaScript throw: Error: Can't load ti.bios.tci :Error: Can't find import file: 'ti/bios/bios.tci'"?

This occurs if the ti.bios repository is not on the XDCPATH. Set your XDCPATH as shown above. An example BIOS repository is: c:/bios_5_31_02/packages

What if I get an error like "Error: Unable to find mycompany.mygroup.codecs.viddec_copy" when I attempt to build the server (after I have successfully generated files using the RTSC Server Package Wizard)?

First check that your codec package is on your XDCPATH. If it is, then verify that your codec package was created with the correct interface (e.g. IVIDDEC, IAUDENC, etc.). If it was not, re-run the RTSC Codec Package Wizard and then re-run the RTSC Server Package Wizard.

Another common gotcha is to make sure the codec package has run through the 'xdc release' step successfully. This command causes files to be generated for a codec package so that it is recognized as such by the XDCTOOLS.

What if I get an error like "Undefined symbol ... >> not built"?

Look through the will link in... build output (i.e. will link with ti.sdo.codecs.h264venc:lib/h264venc_ti.l64P). If a "null" is being linked in (i.e. will link with ti.sdo.codecs.h264venc:null), then a Boolean defined in the server package's codec.cfg may instruct the codec package's getLibs() function in package.xs to return null (instead of a library). Modify the Boolean value appropriately in codec.cfg and re-build the server.

I'm on DM6467. I get undefined symbols for TI's HDVICP library. Why?

TI's video codecs depend on an "HDVICP" library typically under the ti.sdo.codecs.hdvicp namespace.

The standard mode of operation is for a component to declare and thus bring in it's dependencies. However the TI video codecs do not presently do that hence you get a build error because the codec references a library that is not being linked in. The easiest way to address this is by adding in e.g. servers/server.cfg: -

xdc.useModule('ti.sdo.codecs.hdvicp.HDVICP');

Full details of this issue can be found at XDC_packaging_an_add-on_library.

What if I get an error like "Error: xdc.loadPackage: can't find package ti.sdo.ce.osal.bios"?

XDCtools is reporting that it cannot find package ti.sdo.ce.osal.bios on your XDCPATH. First, verify that you have the Codec Engine/packages repository on your XDCPATH. Second, verify that you are using at least Codec Engine 2.10 (earlier versions do not contain this package).

What if I get an error like "XDC runtime error: can't find the library 'lib/mp3dec_tii_l1l2l3.l64P'"?

What if you get the following?

js: "/opt/dmsw/xdc_3_00_06/packages/xdc/cfg/Main.xs", line 27: XDC runtime error: can't find the library 'lib/mp3dec_tii_l1l2l3.l64P' specified by package ti.sdo.codecs.mp3dec. It wasn't found along the path '...'

So...it found the package but not the library. So its not an XDCPATH issue. What could it be?

One obvious thing to check is the 'profile' i.e. is it production or eval codec in use. Maybe you have in the server codec.cfg: - <syntaxhighlight lang='javascript'> MP3DEC.alg.watermark = false; </syntaxhighlight>

But if you're using an evaluation codec then 'watermark' should really be true. So try flipping this to: <syntaxhighlight lang='javascript'> MP3DEC.alg.watermark = true; </syntaxhighlight>

Other Questions

Does the wizard run the same way on both Windows and Linux?

Yes, the wizard behaves the exact same way on both Windows and Linux.

Other FAQs

• RTSC Codec Package Wizard FAQ
• Codec engine FAQ
• TI official DaVinci FAQ
• Spectrum Digital (HW) FAQ
• Multimedia codec FAQ
• DVEVM and DVSDK frequently asked questions

Other RTSC Codec Package Wizard Info

• RTSC Codec And Server Package Wizards