XDC packaging an add-on library

This topic demonstrates a use-case of how to 'wrap' a Target Content library in an XDC package so that the system-integrator doesn't need to do any add-on work (such as adding linker command files to explicitly link in that library)

Use-case Introduction : DM6467 HDVICP library

The video codecs in the 1.40 DVSDK for the DM6467 all use an accelerator library called hdvicp_ti_api_c64Plus.lib. The APIs in this library enable the codec to offload intensive video specific processing to this dedicated accelerator.

In a DVSDK context we're used to seeing codec packages with the appropriate hooks/methods to work in Codec Engine. There's even a wizard to generate these. However the HDVICP library is not a codec so we just need the basic RTSC packaging so that the XDC tools can pull in what we need (the library itself). We'll show why this adds value in the remainder of this topic.

The 'normal' way

If RTSC did not exist what would you do? You'd probably ship a README saying something like "Set an environment variable HDVICP_LIB to point to your install location. Then add -i"%HDVICP_LIB%/lib" to your build options. Then add -l hdvicp_ti_api_c64Plus.lib to your linker command file"

That's fine for 1 add-on library but if you have 10 or 20 it gets very tedious! In addition you need separate instructions for Windows .v. Linux (and separate instructions for different shells on Linux!)

We need a better way...

Wrapping HDVICP library in an XDC package - why bother?

Here are some of the reasons why we wrap the library in an XDC package: -

• We reduce or eliminate requirements on the system integrator. If there are 50 libraries to integrate, the system integrator doesn't want to learn (or even know about) 50 different include/lib paths, filename conventions etc.
• XDC packages are a standard 'box' - like shipping containers you want stuff to look & feel the same way so that they all fit nicely on the boat!
• Tooling can take advantage of the package conventions - for example repoman is an XDC tool which displays information about archived packages, extracts archived packages, extracts repositories from bundles and deletes packages from repositories.

Now that we've established the basis for putting HDVICP in a package here's how it's done: -

• make an hdvicp directory under packages/ti/sdo/codecs/

It makes sense to create our hdvicp package right beside the codecs since the (video) codecs depend on it.

• create a package.bld, package.xs, package.xdc

These are the fundamentals of a RTSC package.

package.xdc is mandatory since it declares what the package is (and its compatibility key)

<syntaxhighlight lang='javascript'> package ti.sdo.codecs.hdvicp [1, 0, 0] { } </syntaxhighlight>

package.xs implements the XDC getLibs() method to return the library name (lib/hdvicp_ti_api_c64Plus.lib) to be linked in to the server/combo or executable.

<syntaxhighlight lang='javascript'> function getLibs(prog) {

   var libList = null;

   if (prog.build.target.isa == '64P') {
       libList = "lib/hdvicp_ti_api_c64Plus.lib";
       print("    will link with " + this.$name + ":" + libList);
   }

   return (libList);

} </syntaxhighlight>

package.bld doesnt do much in this context since we're not building any target code - we're just bundling pre-existing content into a package. All it contains is a statement to tell the XDC tools to include all the files in the package when doing an xdc release.

<syntaxhighlight lang='javascript'> Pkg.attrs.exportAll = true; </syntaxhighlight>

• dont forget the library itself!

The convention is to create a directory named lib in the package. In there we put our hdvicp_ti_api_c64Plus.lib

• Build it!

We can now build the package with the XDC tools - we're not building any C code - just running the XDC tools to build the package.

<syntaxhighlight lang='javascript'> [>] <path_to_xdc_tools>/xdc </syntaxhighlight>

Done!

How to use the HDVICP package?

There are actually several ways to use the package. We explore the pros & cons of each.

Using 'requires' to let codecs 'see' our new package

In e.g. mpeg2dec/package.xdc (and all other video codecs package.xdc files) we could add: - <syntaxhighlight lang='javascript'> requires ti.sdo.codecs.hdvicp; </syntaxhighlight> This says "mpeg2dec has a hard dependency on the hdvicp package"

Advantages: -

• the server/combo or application writer does absolutely nothing! The codec declared its dependency and hence hdvicp comes along for the ride. That's quite nice data hiding - the system integrator shouldn't need to care about the sub-components of the codec.
• package management tools can check, for instance, that all 'required' packages are present
• the 'requires' statement enables you to specify a particular version of this package

Disadvantages: -

• the requires method may introduce problematic dependencies if we're not careful. For example if today's implementation of ti.sdo.codecs.hdvicp package said "requires some.other.pkg;" and some.other.pkg bumped up its compatibility key later, then existing codec packages (built-with the earlier some.other.pkg) could not be used with this new version without a complaint from the RTSC tools. In some cases flagging such an incompatibility is exactly what we want e.g. if some.other.pkg changed an API we want to know about it! If however the compatibility key is not used wisely it can lead to false alarms.
• we need to go in & modify N codecs. If N is large, and the codecs come from M different companies that can get pretty painful!

Leveraging loadPackage in the server/combo

In our server config file we could simply add a line to load the HDVICP package via loadPackage: -

<syntaxhighlight lang='javascript'> var HDVICP = xdc.loadPackage('ti.sdo.codecs.hdvicp'); </syntaxhighlight>

Advantages: -

• no modifications to the codecs. Nice separation of roles i.e. system integrator may have zero influence on the pre-existing codec & hdvicp packages.

Disadvantages: -

• system-integrator has to know about the HDVICP library - which is probably too much detail (their focus is on the codec not its sub-dependencies)
• less powerful than 'requires' or (the following) useModule paradigms. For example GUI tools can often comprehend modules better than packages.

Leveraging useModule in the codec

This requires an extra file and a few more modifications. xdc.useModule() would be necessary if we had to set configuration parameters for the module - in this case there aren't any for HDVICP but the details are included for completeness. xdc.useModule() exists to conditionally include other modules on an as needed basis.

In the HDVICP package we tweak package.xdc to declare the HDVICP module name: - <syntaxhighlight lang='javascript'> package ti.sdo.codecs.hdvicp [1, 0, 0] {

     module HDVICP;

} </syntaxhighlight>

Then we add a file HDVICP.xdc to declare that this is a metaonly (no code) module. <syntaxhighlight lang='javascript'> metaonly module HDVICP {

} </syntaxhighlight>

Then (after we build the hdvicp package) we modify the codecs package.xs to add: - <syntaxhighlight lang='javascript'> function close() {

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

} </syntaxhighlight>

Advantages: -

• Scalable. If we later add config params to the package it will 'just work'
• again, the server/combo or application writer does absolutely nothing!

Disadvantages: -

• a bit complex for this simple package.

Conclusions

Hopefully this topic shows the rationale for wrapping content in an XDC package as well as the technique to do so.

The recommended method for using the package is via requires, however the xdc.useModule() and (to a lesser extent) the xdc.loadPackage() options can also be used.