Please note as of Wednesday, August 15th, 2018 this wiki has been set to read only. If you are a TI Employee and require Edit ability please contact x0211426 from the company directory.

RTSC Codec Package Wizard FAQ

From Texas Instruments Wiki
Jump to: navigation, search
Warning: This utility is deprecated. Users are currently recommended to use GenCodecPkg.



Contents

General Questions

What does the wizard do?

The RTSC Codec Package Wizard generates the XDC files necessary to create a RTSC package containing a codec, so that codec can participate in The RTSC Flow. This tool is designed to create standardized, consistent and correct RTSC packages, even for an inexperienced user.

Existing users frequently 'copy and paste' existing XDC content when making a package which often leads to incorrect values and formats, and worse, the error then propagates. Additionally, by creating an easy way to generate the necessary stack size, the packager can be confident that the datasheet for the codec is correct. Section information is extracted from the wizard to create linker template information which can highlight the absence of partial linking or unexpected section names.

This tool will run on both Windows and Linux.

What does the wizard generate?

The wizard generates five files automatically (package.xdc, package.bld, package.xs, MOD.xdc, where MOD is a module name like H264DEC or MPEG2ENC, and link.xdt) and optionally creates Codec Engine (ce) content. If ce content is generated, it consists of four files: package.xdc, package.bld, MOD.xdc, and MOD.xs. The combination of the generated files with the user supplied documents, optional source, and codec libraries allow for a package to be created using XDC tools. The RTSC Codec Package Wizard helps inexperienced users avoid making "copy and paste" errors when creating a package, and highlights the information required to create a package and ways to find this information (such as worst case stack size and section information via OFD and CG_XML Perl Scripts, etc.).

What inputs are required?

The user must supply basic package information, such as the package's name, the type of codec, and instruction set architecture (ISA). Additionally, the wizard needs at least one library as input. To make use of all of the wizard's features, the user must also input the locations of various executables and files.

Which targets are supported? Can I run a codec created with non-TI code generation tools through the wizard?

All supported targets on your computer are allowed, however, some wizard features cannot be used on non-TI supported targets, or libraries that were not generated using TI code generation tools (CGT). The wizard defines a supported target as one implementing xdc.bld.ITarget and TI-supported targets as those implementing ti.targets.ITarget. For example, 64+ codecs built using TI CGT, will be able to utilize all of the wizard's features, whereas a DM355 codec will require more user supplied input (like knowing the required stack size). In either case, the wizard will still generate the XDC files necessary to create a RTSC package!

Does the wizard support packages with multiple ISAs?

No, at this time, the wizard only supports libraries for one ISA per package, but an unlimited number of those libraries per package. If you need to support multiple ISAs and want to use the wizard, we suggest creating multiple packages (one for each ISA) and then 'bundling' multiple packages together (see FAQ on packaging below). Alternatively, you can include libraries for multiple ISAs in a single package (not using the wizard) and we refer you to see the Codec Engine documentation for information on how to proceed.

Installation

What software prerequisites exist for using the wizard?

The wizard requires other TI tools:

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

What happens if I don't install the optional prerequisites, like CG_XML or TI Code Gen Tools?

The wizard uses the OFD utility and Perl scripts contained within CG_XML to calculate the worst case stack size and the sections required by link.xdt. If you do not install these prerequisites, you will have to manually enter the necessary stack size on Panel 5 and manually edit link.xdt (see below) to create a usable package. Additionally, the nm utility from TI Code Gen Tools is needed to find the names of the xDAIS functions, like the IALG function. Without this utility, you will manually have to enter the function names into the wizard.

Why do I need to install CG_XML v1.20? I'm currently using an earlier version and it works great!

CG_XML now contains both the Perl scripts and the Perl scripts converted to executable--the latter performing exactly the same as the former, but now without the need to install Perl or the XML::Simple module. The wizard also makes use of the --stack_max option added in call_graph.pl in v1.20.

How do I install and run the wizard?

We recommend you install the wizard (directory ceutils_x_xx) in a path without spaces. You must then install any software prerequisites, if needed, and set your XDCPATH correctly. Then you can run the graphical version of the wizard from any directory via the command:

xs ti.sdo.codecutils.genpackage -g

How do I set my XDCPATH?

You must have the following on your XDCPATH for the wizard to run:

  • Codec Engine/packages directory
  • Codec Engine cetools/packages directory or XDAIS 5.21/packages
  • ceutils_x_xx/packages directory

To set this from the command prompt in Windows, type

set XDCPATH=C:/my/path1;C:/some/other/path2

or in Linux:

 export XDCPATH="/my/path1;/some/other/path2"

So your next question is: where are these directories on my computer? If you have the DVSDK installed, the Codec Engine directory is found in /dvsdk_dir/codec_engine_1_20 and XDAIS in /dvsdk_dir/xdais_5_20

You may need to update your XDC version to 2.95.01, available at https://www-a.ti.com/downloads/sds_support/targetcontent/rtsc/index.html

Some users will have individually installed XDC and the Codec Engine. Note that the cetools directory is found in /codec_engine_1_20_dir/cetools. Codec Engine is available at https://www-a.ti.com/downloads/sds_support/targetcontent/CE/index.html

A Windows user might have to type something like:

set XDCPATH=D:/dvsdk_1_00_00_18/codec_engine_1_20/packages;
D:/dvsdk_1_00_00_18/xdais_5_20/packages;D:/ceutils_x_xx/packages

set XDCPATH=C:/codec_engine_1_20/packages;
C:/codec_engine_1_20/cetools/packages;C:/ceutils_x_xx/packages

Why do I need to use XDC 2.95.01 when XDC 2.94 is shipped with the DVSDK?

XDC 2.x releases earlier than 2.95.01 incorrectly built a dependency into every package on the xdc.runtime package. The compatibility key for the xdc.runtime package correctly changed between 2.94 and 2.95. Consequently, packages produced with 2.94 cannot be consumed by 2.95 - and vice-versa. The way to enable consumers to use your package with both 2.94 and 2.95 is to break the incorrect dependency on the xdc.runtime package. This can be done by releasing with XDC 2.95.01 or later.

  • If a package was created using 2.94, and the consumer is using 2.95 or later, the consumer will have to tell XDC to ignore the compatibility key of the xdc.runtime package which can be done as follows:
    • in user.bld, add the line:
      • Pkg.attrs.tcopts = "-Dxdc.cfg.check.exclude='xdc.runtime'";
    • or on configuro command line, add:
      • x xdc.runtime
  • Note that CE 1.20.01 was released with 2.94 and 1.20.02, with 2.95.01.
  • If a package is released with 2.95.01 or later, the package removes the xdc.runtime error, and can be consumed with both 2.94 and 2.95.01+

What files are included with the wizard?

The wizard consists of the ti.sdo.codecutils.genpackage 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

How do I run the example?

After you have started the GUI wizard, open the viddec_copy.xml file located in the examples directory of ceutils_x_xx. You can proceed from page to page to see the input used, and click Finish when done. The output will be generated in the examples/viddec_copy_packaged directory.

Running the Wizard

What if I don't know what to enter in the fields on a page?

Each panel of the wizard has a 'Help' menu item which provides more detailed instructions on the expected input.

What if the wizard takes a long time to start-up?

The wizard searches the current working directory and all paths on the XDCPATH to find packages that have interfaces that inherit from ICodec. To reduce the start-up time, consider removing unnecessary paths from your XDCPATH and running the wizard from a directory that is not a package repository.

How can I see the output of the Perl scripts that the wizard runs?

Switch to the verbose mode by selecting File->verbose. This will open a file browser so the user can indicate the location to save the output. If no file is selected, then only the commands the wizard is executing will appear on the terminal. To switch to non-verbose, click on File->verbose again.

How do I save my current input? How do I open saved files later?

To save the current input for later use, click on File->Save, or CTRL-S. Save the output as an XML file at a location of your choice. To open a saved XML file, click on File->Open or CTRL-O and browse to your saved file.

What if I want to edit the XML file generated by the wizard without running the wizard again?

It is recommended that you create an XML file as a base file by running the wizard. Alternatively, you may use the viddec_copy example XML file. The XML tags are named to match their corresponding field within the GUI. A few things to remember:

  • output refers to a repository, not the base directory!
    • e.g. if I set my output as
      /someLocation/outputrepo
      and I have a codec package named
      mycompany.mygroup.codecs.viddec_copy
      the base directory will be
      /someLocation/outputrepo/mycompany/mygroup/codecs/viddec_copy
      The wizard will generate this file structure if it does not already exist! If it exists, the wizard will output the files in the base directory.
  • Other common fields that you may decide to change in the XML file include: version or library (for example, substituting a production library for an evaluation library)
  • Note: If the XML tag looks like this:
    <version/>
    this means that there is no version information! To add it, change the tag to
    <version>1.00.001</version>
  • Command line trick: If you do not want the wizard to compute the names of config params, the worst case stack or the section information needed for link.xdt but to only use the values you have entered in the XML, use the -l option on the command line. See xs ti.sdo.codecutils.genpackage --help for more information. If you use this option, your XML file should have all of the config param, worst case stack size, and section information! If not, the files will not contain all of the necessary information which will require the user to manually edit the files.

What if my ISA isn't listed?

If you expect an ISA to be listed but it is not, you most likely have incorrectly set your XDCPATH (see above) and the XDC tools cannot find the supported targets. If you are creating a package for a non-supported target, you have the option of selecting 'None of the above' and manually editing the package.xs file to check for the correct ISA. The syntax needed to check for a particular ISA can be found in the viddec_copy example package.xs.

What if I have multiple libraries to return for a given set of Booleans?

If you must return multiple libraries, select a single library on the second page of the wizard. This will be the library that the stack size, config names, and section information will be calculated from. Then attach the other libraries in extra files, indicating that their output directory should be "lib". After the wizard has finished, edit the base directory's package.xs. Modify the line: lib = "lib/someLib.l64P"; to lib = "lib/someLib.l64P;lib/someOtherLib.l64P";


Which extra files do I need to add in step 3?

You are required to add docs (see below) and may optionally add any other files or directories. Most codecs will need an extension header (if they extend the minimum xDM interface) and this should be included in the base directory. Other commonly included files consist of /apps (perhaps with /test and /build subdirectories) or source files. The wizard puts no constraints on the number of files (or their types) or directories that can be added to the package. All files included via the wizard will be included in the tarball produced by XDC release.

How do I organize the files I want included in my 'docs' or 'src' directories?

On Panel 3 of the wizard (also Step 3), the right-most column of the table can be used to indicate the output location of files relative to the base package. For example, if I have a file, /myDocs/a-file.pdf, that has been added to the table, if I type 'docs' (no quotes) into the output-directory column, the file will be output to /myOutputRepoSelectedOnPanel1/my/package/name/docs/a-file.pdf. Similarly, you may add sources from different directories and have all of them output to 'src.'

What docs do I need and where should they be located?

According to the Package Standard, each package must, at a minimum, contain Release Notes, User's Guide, Reference Manual (may be part of the User's Guide), and Online Reference Manual. The Release Notes may HTML or PDF formatted, User's Guide and Reference Manual must be PDF formatted, and the Online Reference Manual must be in HTML. The Release Notes must be in the package's base directory while the other documents should reside in the /docs subdirectory of the base directory. See the docs in the viddec_copy example package for further information.

What is 'Stack size pad'?

The worst case stack size is generated by running the call_graph.pl Perl script on the output of the OFD. However, it's usually recommended that some overhead is allowed for. The wizard denotes this overhead as Stack Size Pad %--the default is 20, although any integer >=0 is permitted.

What if my worst case stack size is unrealistically small?

Please verify that your library was built without the -ml3 option (which is obsolete in TI's codegen tools) as DWARF cannot distinguish between call types, such as indirect vs. function pointers, etc. For C6000, you must use compiler tools 5.1.0 or greater, and avoid using the -g option when building. Also, function call optimization on 64+ can cause errors in the call graph. For further information, please see the perldoc on call_graph.pl (command: perldoc cg_xml_location/ofd/call_graph.pl) or run call_graph.pl on the OFD output of your library:

<Fast OFD executable> -xg --xml_indent=0 --obj_display=none,header,optheader
--dwarf_display=none,dinfo <your_library> | perl <CG_XML location>/ofd/call_graph.pl

Additional information on how the stack size is calculated and various caveats regarding its accuracy can be found at Stack_issues#Finding_out_static_stack_usage

Why do I need to create link.xdt? Which sections are included in the link.xdt?

The wizard optionally creates content for link.xdt which helps the server integrator place the necessary sections in memory as it's often difficult to know what needs to be placed (and where) by section name alone. The sections included in the link.xdt are any non-pre-defined sections (such as .bss, .cinit, .const, .far, .pinit, .text, .switch, and .sysinit). These sections are grouped by section type (either code, initialized data, or uninitialized data) which allows the server integrator to place the group as a whole by placing MOD.codeSection, MOD.iDataSection, or MOD.uDataSection.

How do I add alignment to my code sections for increased performance?

If the section you wish to add alignment information appears in the sections table on Panel 6, then you can add alignment information directly into the table. If the section does not appear in the table, implying that the section name is prefixed by a pre-defined section name, you must manually edit the link.xdt file before running xdc to create the package. Below is an example of proper syntax:

In link.xdt, given a code section .text:MOD_VENDOR_codeSect1:

    %if (this.MOD.codeSection) {
        .text:MOD_VENDOR_codeSect1 > `this.MOD.codeSection`, align = 0x10000
    %}

If you need to a complete list of sections in a library, run the sectti.pl script using the command:

<fast OFD executable> -x --xml_indent=0 --obj_display=none,sections,header
<your library location> | perl <CG_XML location>/ofd/sectti.pl

Why did the wizard output an empty link.xdt?

Section information is needed to generate this file, implying only TI CGT libraries for TI supported targets will have any linker content created. For all other libraries and targets, link.xdt will remain empty.

If the library was generated with TI tools, the link.xdt will be empty if all of the sections have pre-defined section names (e.g. .bss, .cinit, .const, .far, pinit, .text, .switch, or .sysinit) since these sections will be automatically placed by the linker. You may always manually edit the link.xdt as described above.

What does the "Create ce content" checkbox do?

If this box is checked, the wizard will generate Codec Engine specific content, which includes a ce directory with four files(package.bld, package.xdc, MODULE.xs, and MODULE.xdc). If unchecked, the wizard will only generate the base package content.

What if no config names are generated in the Config Table on Page 5?

The global variables in your primary library have been searched and no matches to "I"+MOD (e.g. if your module is named VIDDEC_COPY, the name searched for is [codec_name_vendor]_IVIDDEC_COPY) or "IDMA3" have been found. If the "I"+MOD is not found, then the library is searched for [codec_name_vendor]_IALG. If the [codec_name_vendor]_IALG option is used, a warning will be generated. These are required for xDAIS compliance--verify that your library meets all xDAIS requirements. If you want to see the global variables of a library, use the nm utility:

<codegen tools location>/bin/nm -g <your library>

What if I get an error indicating that I do not have the correct header?

The header is expected to be named i + module_name_in_lower_case, e.g. impeg2dec.h. If your header is attached but not named accordingly, rename this header. If you have not attached a header, re-run the wizard and add the correct header on the panel where extra files can be included.

What should I do if I receive an OFD error message in my log?

You may receive this error if you did not browse to the location of your OFD utility or CG_XML, and then attempted to use a feature requiring the above, or if you inadvertently browsed to an incorrect location. If you were able to generate a guessStackSize and link.xdt, then the error is a result of using the slow OFD utility instead of the fast OFD and an upgrade is recommended although not necessary. The fast OFD improves the time taken to calculate the worst case stack size by several fold but does not change the result.

What if I get an error indicating that my getDaramScratchSize or getSaramScratchSize is 0 and should be modified?

You can re-run the wizard and enter the correct values for these functions (usually found in the codec's documentation) in the Functions Table. Alternatively, you can manually edit the /yourpackagepath/MOD.xs file, entering the correct values in the return statements for the appropriate functions.

What if I get an error like "** warning: package xdc.tools.sg.linux_swt depends on the Mozilla browser for some functionality. Your environment doesn't currently point to Mozilla, so some XDC graphical tools may fail."?

You may follow the instructions given in the error message--involving setting a MOZILLA_FIVE environment variable. However, the RTSC Codec Package Wizard will run correctly with or without this environment variable set!

Is there a command line version?

Yes, but you must first run the graphical version and save your input to the wizard as an XML file as described above. Then execute:

xs ti.sdo.codecutils.genpackage -f=/location/of/saved/output.xml

What are some common command line usages?

With any arguments, you can always run the GUI version by adding “-g”

xs ti.sdo.codecutils.genpackage -g <some other args>

Run the command line option using an XML file as input:

xs ti.sdo.codecutils.genpackage -f = <XML File>

Note: This will re-run the utilities!

If you don't want to re-run the utilities, use the --literal option:

xs ti.sdo.codecutils.genpackage -f = <XML File> -l

If you want to see the output of the utilities being run, use --verbose:

xs ti.sdo.codecutils.genpackage -f = <XML File> -v

How do I get started on the command line?

First, run the GUI wizard and save the XML File by using File->Save. Then edit this XML file, here are some common scenario:

  • I want to re-run all utilities
    • No XML file changes are needed
  • I do not want to re-run any utilities
    • No XML file changes are needed (use the -l option)
  • I have specified a stack size (other than the wizard generated stack size) but want to run the nm and sectti utilities
    • Change the makeStackSize to false
    • Run the command line without the -l option and nm and sectti will be re-run
  • I want to modify my existing XML file to support a very similar codec
    • Delete all content from (and including) the beginning and ending generatedParameters tags
    • Modify the inputParameters for your new codec
    • Save the new XML file
    • Run the command line option without the -l option

Which wizard version supports xDM 1.x?

It doesn't matter. The wizard uses the component versions you specified on the XDCPATH to determine what gets shown in the drop-down lists. For example if you put Codec Engine 1.20.02 on your path then you'll not see IVIDDEC2 in the list of available interfaces to implement. However if you are using >= CE 2.0 then you'll see this automatically. The correspondence between xDM versions and CE ICodec interfaces can be found here. The Codec Engine Roadmap article describes which interfaces were supported in which Codec Engine release.

So, in summary, it doesn't matter which wizard version you use with respect to xDM interfaces - you just need a more recent Codec Eng if you want to see the newer interfaces in the drop-down lists automatically.

We do however recommend that you pick up the latest RTSC Codec & Server Package wizard ceutils product to get the latest bug-fixes.


Packaging

How do I make 'evaluation' and 'production' packages?

Assuming that we differentiate between the evaluation and production packages using the Boolean 'watermark,' the following steps are required to create evaluation and production packages for the same codec.

First, let's create an evaluation package. Note that the user input on every page of the wizard will be the same except for the user specified output location on Panel 1 and the library input on Panel 2. Specify the output location as my_output_dir/evaluation, or a location different from where you plan on creating the production package. On Panel 2, indicate a Boolean called 'watermark' which creates two entries in the table. For watermark==false (meaning return the production library,which doesn't exist for an evaluation package), simply input 'null' for the library. For watermark==true, add the evaluation library. Complete the wizard as usual, and select this row to be the default library by checking the left-most column.

Then run the wizard again and specify a different output location, such as /production. (Hint: since the packages are quite similar it might make sense to load the XML file from the evaluation package and make a few modifications) On Panel 2, create the same Boolean, but instead add the production library for watermark==false and set this library as the default by marking the checkbox. Finish running the wizard and release all four packages (as outlined below). If a customer uses the evaluation package and then purchases the production, they merely change their XDC path to the production package (instead of the evaluation package) to have the correct, production library returned.

How do I "xdc release" my packages now that I'm done running the wizard?

The easiest way to release the packages is to change directory to the base package (that is, if your output repository + your.package.name.with.dots.turned.to.forward.slashes). Then run:
xdc release -PR .

Don't forget the dot! This generates two tar files that can be distributed (one for the base package and another for the ce package). You may wish to only distribute a single tar file to the codec consumer--if so, see the next question!

How do I create a Release package (containing both the base codec package and ce package) now that I'm done running the wizard?

The wizard creates a codec package but not something you can readily email - what you need is a tarball with a good name - something like dm6446_mpeg2dec_1_00_001_eval_rel.tar It should contain the 2 packages that comprise a Codec-Engine-ready-codec i.e. the 'base' directory e.g. mpeg2dec and the 'ce' content i.e. mpeg2dec/ce

  • Step 1 : make a *new* directory for the release tarball destination
    • e.g. lets say your working copy for codec packaging is in dm6446_mpeg2dec_1_00_001_eval/packages/mycompany/mygroup/codecs/mpeg2dec/ then make a dir for the release tarball called dm6446_mpeg2dec_1_00_001_eval_rel
    • Note - this directory should be completely outside of any paths on your XDCPATH
  • Step 2 : Copy across any release notes, Makefile, config.bld etc (anything that may go in 'otherFiles' as shown below) from your working area. Do *not* copy across the complete packages/ directory from your work area - this will cause the to-be-released-content to be rebuilt and superflous tarballs to be created for all the sub-components.
[/home/user/dm6446_mpeg2dec_1_00_001_eval] cp -v * /home/user/release_dir_area/dm6446_mpeg2dec_1_00_001_eval_rel

(-v simply shows each file being copied. The '*' without any other recursive flags ensures all files get copied but not the packages/ directory i.e. the desired effect)

Then in the new directory dm6446_mpeg2dec_1_00_001_eval_rel add these 2 files: -

/*
 * ========== package.bld ==========
 */
 
// create the packages directory for our codec bundle
var pkgsRepository = Pkg.addRepository('packages');
 
pkgsRepository.addPackages(
	[
		'mycompany.mygroup.codecs.mpeg2dec:mycompany_mygroup_codecs_mpeg2dec',
		'mycompany.mygroup.codecs.mpeg2dec.ce:mycompany_mygroup_codecs_mpeg2dec_ce',
	]
);

...and...

/*
 * ======== package.xdc ==========
 */
requires mycompany.mygroup.codecs.mpeg2dec;
requires mycompany.mygroup.codecs.mpeg2dec.ce;
 
package dm6446_mpeg2dec_1_00_001_eval_rel[1, 0, 0] {
};

The package name *must* match the directory name!

FYI, as an aside, a full featured package.bld of a codec with an accompanying server/combo might look like: -

/*
 * ========== package.bld ==========
 */
 
Pkg.otherFiles = [
   'dm6467_audio_combo_eval_release_note.html',
   'logocorp.gif',
   'Makefile',
   'config.bld',
];
 
// create the packages directory for our codec bundle
var pkgsRepository = Pkg.addRepository('packages');
 
pkgsRepository.addPackages(
        [
                'ti.sdo.codecs.aacdec1:ti_sdo_codecs_aacdec1',
                'ti.sdo.codecs.aacdec1.ce:ti_sdo_codecs_aacdec1_ce',
                'ti.sdo.codecs.mp3dec:ti_sdo_codecs_mp3dec',
                'ti.sdo.codecs.mp3dec.ce:ti_sdo_codecs_mp3dec_ce',
                'ti.sdo.codecs.dolbyac3dec:ti_sdo_codecs_dolbyac3dec',
                'ti.sdo.codecs.dolbyac3dec.ce:ti_sdo_codecs_dolbyac3dec_ce',
                'ti.sdo.codecs.aacenc:ti_sdo_codecs_aacenc',
                'ti.sdo.codecs.aacenc.ce:ti_sdo_codecs_aacenc_ce',
                'ti.sdo.servers.audio_combo_evmdm6467:ti_sdo_servers_audio_combo_evmdm6467',
        ]
);

...and its partner package.xdc for completeness...

/*
 * ======== package.xdc ==========
 */
requires ti.sdo.codecs.aacdec1;
requires ti.sdo.codecs.aacdec1.ce;
requires ti.sdo.codecs.mp3dec;
requires ti.sdo.codecs.mp3dec.ce;
requires ti.sdo.codecs.dolbyac3dec;
requires ti.sdo.codecs.dolbyac3dec.ce;
requires ti.sdo.codecs.aacenc;
requires ti.sdo.codecs.aacenc.ce;
requires ti.sdo.servers.audio_combo_evmdm6467;
 
package dm6467_audio_combo_1_00_00_02_evaluation[1, 0, 0] {
};
  • Step 3 : in the *new* directory dm6446_mpeg2dec_1_00_001_eval_rel do: -
xdc release -PD .
  • Note - XDC tools should be in your path, or alternatively do e.g.
/home/user/xdc_2_95_01/xdc release -PD .
  • Note - don't forget the "." This command says "release" all packages (the -P option) and any packages they depend on (the -D option) in this directory (the ".").
  • Note - you do need a good XDCPATH for this step! The Makefile in ceutils >= 1.06 leverages the DVSDK Rules.make settings and can help alot. See this server wizard FAQ.
  • This will generate a tarball of the same name as your directory dm6446_mpeg2dec_1_00_001_eval_rel.tar
  • Ship your dm6446_mpeg2dec_1_00_001_eval_rel.tar :-)
  • A graphical version of these steps can be found in creating_a_package_tar_for_release.pdf, available in ceutils

How do I add extra files to the Release package that aren't in the base mycompany/mygroup/codecs/mpeg2dec/ directory?

  • the first point is you shouldn't do this! Reason is that most customers won't use the top-level directory dm6446_mpeg2dec_1_00_001_eval_rel. Instead they'll pull out the content underneath and have a standard single XDCPATH to all the codecs in use e.g. democodecs/packages. So if you put e.g. ReleaseNotes.pdf at directory level dm6446_mpeg2dec_1_00_001_eval_rel then your customers will likely never get it!
  • If you _do_ need to add content to your release tarball you can do: -
    • Step 1 : copy file(s) e.g. ReleaseNotes.pdf to dm6446_mpeg2dec_1_00_001_eval_rel
    • Step 2 : add the following to your dm6446_mpeg2dec_1_00_001_eval_rel/package.bld
Pkg.otherFiles = [
   'ReleaseNotes.pdf',
];
  • Step 3 : run the release instructions as noted above

Modifying the Wizard's Output

What if I need to edit the return values for: getDaramScratchSize(), getSaramScratchSize() or getStackSize()?

Open the generated /yourpackagepath/ce/MODULE.xs and edit the corresponding return statements.

What files do I need to edit if I manually edit link.xdt?

After editing your link.xdt file, you must make an additional change to your XDC files. In /yourpackagepath/MODULE.xdc, add the following line if you have placed a section into MOD.mynewlydefinedSection

    config String mynewlydefinedSection;

See related question above.

What is the compatibility key and do I need to set it?

Compatibility keys are found in the package.xdc files that the wizard generates. These should not be confused with a version number as two different versions may have the same compatibility key. The 3 or 4 digit compatibility key is interpreted by the XDC tools to determine if any incompatibilities exist and is formatted [M,S,R,P] corresponding to major, source, API radius, and patch. Changes of M denote incompatibility, whereas changes in S guarantee source backwards compatibility, R, binary backwards compatibility, and P, 100% binary compatibility. Note that only M, S, and R are required, P is optional.

The wizard's templates default the compatibility key to [1,0,0] and assumes that this does not need editing. If your project requires different compatibility keys, you must manually edit the package.xdc file in both the base and ce packages. If you have already released these packages via xdc release, you must re-run xdc release to correctly update the compatibility key in the /package subdirectory.

The following generalizations can be made:

  • The bundle's (package containing both the base codec package and the ce package) will always have compatibility key [1,0,0]. The bundle package name contains the version (e.g. myprod_1_52_01). The next bundle release (myprod_1_52_02) will have a different package name, and that new package will start where new packages start - at [1,0,0].
  • The base codec's key typically won't vary, but if a new feature is added (e.g. supports more control() cmds, etc), or more config params (e.g. useDMA) the radix should increase. E.g. [1,0,0] -> [1,0,1].
  • The .ce packaging most likely will never change. If extra config params, etc. are added, the key will need to change appropriately, but that's rarely done in the .ce package, rather it's done in the base codec package (so all frameworks benefit, not just CE).

Other FAQs

Other RTSC Codec Package Wizard Info