XDC 3.00 Release Notes

August 13, 2007

Introduction, Known Issues, Documentation, What's New, Upgrade & Compatibility Information, Host Support, Dependencies, Device Support, Validation Info, Version Information, Technical Support.

---

Introduction

eXpress DSP Components (XDC) is a standard for reusable software components, optimized for real-time embedded systems. XDC components have hardware-neutral formal interfaces, are configurable offline to optimize memory and performance, and support custom automation in the development environment via a scripting language.

This XDC release includes the following sets of packages:

• XDC core (xdc.*) - the xdc and xs command line utilities for building packages and execting scripts, together with the packages that implement XDC itself;
• User tools (xdc.tools.*) - command-line and graphical utilities for working with packages and repositories;
• Targets (*.targets.*) - definitions for using various TI and third-party compiler tool chains with XDC;
• Platforms (ti.platforms.*) - definitions for linking and running code on various TI board-level hardware and simulator products using XDC.

---

Known Issues

None.

---

Documentation

The following documentation is available:

• XDC Getting Started Guide
• XDC Consumer User's Guide
• XDC Documents Index

Release notes from previous releases are also available in the relnotes_archive directory.

---

What's New

The following significant changes have been made since 2.95:

• First General Availability release of XDC Module Binary Contract, supporting binary backwards compatibility of XDC metaonly and target packages through the XDC 3.X series.
• Enhanced documentation. Addition of Getting Started Guide, Consumer User's Guide, and improved API documentation.
• Enhanced graphical and command line user tooling.
• Bug fixes detailed below.

3.00.00.05 (This Release)

XDC Runtime

• Reworked the implementation of xdc.runtime.Text to avoid recursion when traversing ropes, which occured when printing fully-qualified module names as well as when matching module-name patterns through Diags_setMask(). Besides minimizing runtime stack usage and (theoretically) enabling static analysis of worse-case stack depth, this change also make better use of the internal rope representation to capture redundency in package-prefixes of module names; runtime code size, however, is roughly the same as before.
• Fixed a bug in xdc.runtime.Error that prevented calls to Error_raise in legacy .c files. Like other diags, the controlling module for legacy .c files automatically becomes xdc.runtime.Main
• Error_raise() is now robust against "nested errors" in which the raiseHook() itself leads to a call to Error_raise(); in this case, Error_raise terminates abruptly by calling System_abort() with a special message
• Removed error id's E_{device,value} from xdc.runtime.Error, leaving only E_{generic,memory}. These former error id's are no longer used by anyone (and in fact have an unsupported '%$R' format specifier in their msg string, proving further that no one is really using them); the format string in the remaining E_generic has also been changed to use '%s'. Since these have been on the "to-be-removed" list for sometime, no change in xdc.runtime MSRP will occur.
• Moved the handling of the abort string to the proxys. The ISystemSupport modules now flush on abort (SysMin's can be disabled via the flushAtExit config parameter). Create Memory.defaultHeapInstance if it is null or undefined.
• Documentation updates to modules Assert, Diags, Error, Log, and LoggerBuf in the xdc.runtime package.
• Renamed Diags.setMask$meta() to Diags.setMaskMeta()
• added XDOC for *Timestamp* modules and interface
• Made HeapStd thread-safe. Checking align parameter in HeapStd_alloc now. It fails if the value is larger than the supported size of malloc.
• In SysMin and SysStd, allowed for NULL string parameter to abort().
• Added Timestamp proxy config to LoggerBuf; to match LoggerSys
• In Text, fixed multiple buffer overrun bugs and premature truncation of output to buffer. pkgGroup regular expression fixed to properly match only xdc.runtime packages
• Demoted the typedef 'xdc.runtime.SysMin.OutputFunc' to internal, since this was never intended to be client-visible

Targets

• Added a missing "." to some references to 'bss' in ti/targets/linkcmd.xdt
• Added reset and exit function hooks to rts470/boot.asm
• Added '--recursion_limit=20' to the arm profile 'whole_program'
• Enabled sdkPath in microsoft.targets.Win32 to accept absolute paths (SDSCM00016858)
• Moved dependency flags into cc.cmd for MVArm9 target
• Boot code in rts5500 was invalid for small data model, could corrupt top seven bits of XAR6 register

Platforms

• Platform tests are separated into their own packages, so that loading a platform does not create a dependency on the package xdc.runtime
• added evm6452 and evmTNETV2685
• clock rate on sdp3430 changed to 312.4
• updated ti.platforms.generic XDOC to explain how to use this platform to "create" a usable platform

XDC Core

• Moved std.h out of the xdc.runtime package, and into the xdc package; std.h also no longer directly #includes . this enables legacy .c files that #include to no longer have a needless dependency on the xdc.runtime package
• Altered the generation of package/package.c to avoid unconditional #includes of xdc.runtime headers; these are only included if the package contains target modules. This change also helps reduce bogus dependencies on the xdc.runtime package, not only in packages that create legacy libraries but even legacy programs
• Relaxed a limitation in which spec'd consts associated with a (target) module were only available in the .cfg model; values of consts can now be retrieved in *any* xs context. Access to spec'd configs, on the other hand, are still contrained to the .cfg model
• Program.system is of type 'Any' to avoid dependency on xdc.runtime in the cases when there are no target modules in a program; if Program.system is needed and a module is assigned to it, the module must inherit ISystemSupport
• Added three special marker files to the package/ subdir whose names include the internal "version" of the green/red/blue worlds respectively; these files will enable future XDCTOOLS to re-generate internal files (e.g., *.ccs/*.sch/package.c files) on a more fine-grained basis. Existing packages (which, of course, don't already have these files) can be easily discerned by future XDCTOOLS, hence there is no compatibility issues here
• Removed dependency on libstdc++ when building XDC tools for Linux and Solaris
• Fixed a warning from Microsoft compilers pertaining to the internal function xdc_runtime_Text_visitRope by simplifying the declaration of its signature thru 'Fxn' and using some casts within Text.c.
• Removed spurious references to xdc.runtime from generated package.c files, as well as further decoupled xdc.cfg from xdc.runtime.
• package/build.cfg is added to the standard release; without that file, on-line rebuilding of schemas does not recreate correctly the list of libraries in pkg.build.libraries
• Fixed a bug in which units named in package.xdc that do not exist (e.g., no .xdc file) were causing a fatal java exception. a more appropriate error message is now emitted.
• Enabled a finer-grained mechanism for on-the-fly regeneration of selected package files. Using the recently added package/.vers_{rgb} files, we can independently regenerate (green) .css files, (red) .sch files, and (blue) package.c files if needed. This mechanism is critical to maintaining (full-)compability in the face of changes to these internal files; this mechanism also comprehends older packages in a backward-compatible manner. As part of this change, the .ccs file no longer carries a suffix.
• Added a distinguished package named 'xdc.corevers', whose MSRP basically reflects the overall compatibility of the core packages in this version of the XDCTOOLS with others before/after it. All released packages will depended implicitly on this 'xdc.corevers', though this special package has no content. There is also no formal relationship between this package's MSRP and the "external version" of the XDCTOOLS (e.g., 3.1.12). By convention, the MSRP of this package will change whenever a new release (major, minor, patch) of XDCTOOLS occurs, and will reflect the compatibility constraints (full vs backward vs source vs none) accordingly.
• Fixed the bug in schema regeneration code when there are libraries in the package; the libraries are listed in package/build.cfg, but that file was not a part of a standard release, so during regeneration that file would not be found and the list of libraries would be empty; in xdc-p06 we added build.cfg to the standard release, but when older packages are consumed, we need to recreate build.cfg on the fly; it is done by reading the list of libraries from package.bld.xml
• Updated documentation for getLibs in xdc.IPackage
• Changed xdc.services.spec.ParserSession System.exit() into Java exceptions. The console output on some parser errors has changed, with an additional line following the main error message: "error: compilation failed: parser failed"
• EXPERIMENTAL ADDITION -- first implementation of the @Annex() attribute, which can be applied to public target configs and functions in modules. configs/fxns annotated in this way are generated *after* all other decls, enabling addition of configs/fxns while maintaining binary backwards-compatibility when structs are used in the underlying implementation. the integer parameter must be positive to have any effect. as a rule, all decls are output in the same order as input, suggesting that simply re-ordering a module's decls can potentially break backwards-compatibility in some cases
• EXPERIMENTAL ADDITION -- first implementation of the @NoRuntime attribute, used in target modules wishing to opt-out of any xdc.runtime support. this enables target modules with const/type/extern declarations to have no implicit dependencies on the xdc.runtime package. such modules do *not* implicitly inherit xdc.runtime.IModule, and hence have no common$ metaonly config.
• EXPERIMENTAL ADDITION -- 'extern' declarations (fxns or vars) appearing in .xdc files are no longer required to have an identifier initializer. if absent, the extern 'pkg.Mod.ext' is basically an alias for the C symbol 'pkg_Mod_ext'. this offers module producers a simpler alternative to @DirectCall, in that it not only looks more "natural" in the .xdc file but also does not introduce a symbol with the __E suffix in the linkmap. this feature melds well with the new @NoRuntime attribute, and provides a potentially "lower-risk" path for migrating legacy content

Configuro Build Tool

• Explicitly set homepkg to the configuration package. Prevents problems with homepkg when the user's config script is not itself in a package. Removed the previous workaround to this problem, which was to create a stub for the user's config script in the generated package. The generated package.bld script now points directly to the user's .cfg file.

Repoman Repository Management Tool

• For --rrestore and --rcreate options, do not restore/create repository unless the operatins can be completed successfully.
• Added RepoRestore.xs, a dialog that is invoked upon opening a .rmn file.
• Removed automatic compatiblity checking from Package Path tree in xdc.tools.repoman.sg and added toolbar button that invokes a compatibility check when pressed
• Implemented lazy tree expansion for Available Packages tree and Package Path tree
• Modified command line for repo restore and repo create.
• Fixed/updated documentation in Main.xdc and package.xdc for better cdoc viewing.

Xdoc / Cdoc Package Documentation Tool

• Added checks for the case when referred-to packages are not available on the package path. If a packaged neede for documentation (e.g. it defines an interface that a module in another package implements) is not available, and not able to be recovered from private information in the dependent package, cdoc cannot show the package docs and instead shows a grey icon in the index. This use case is unique to cdoc and does not affect configuration. The full workaround is for the user to make the needed packages available on the package path.
• Updated command line usage message. Modified cdoc to use xdc.tools.ICmd to decode command line.
• Optimized program startup time. On startup the package path is inventoried, but little else. The index view is filled on demand. Added progress info in the status bar.
• Modified to use the doxygen stylesheet, which displays the generated output in a more compact format. Made generated abstract type converters @_nodoc to reduce clutter. These can still be viewed via the view @_nodoc button.

Path Tool

• Check package path packages for shadow files and flag them when found
• Fixed/updated documentation in Main.xdc and package.xdc for better cdoc viewing.

Configuration Viewer Tool

• Added right-click menu to bring up cdoc browser of any package visible in the configuration.

Other Tools

• Enhanced xdc.tools.Cmdr to allow non-Posix syntax for command-line options, for use in existing tools without breaking option compatibility. The @CommandOption() attribute now allows the '-' or '--' flag prefix to optionally be included in the attribute text, so that '-' can be used with long option names.
• Fixed xdc.tools.sg.swt_linux to not warn when used to simply determine schema dependencies

Examples

• Added examples/basic/absconst, both to illustrate the ability to define "abstract" constants in either interfaces or modules, as well as the ability of the latter to override abstract constant specs in the former. this example also includes a test script that accesses various constants outside of the .cfg model
• Added /basic/vers/rtos/test to test ability to access config parames *outside* config model
• In etrain/filters examples Fir.c, made align parameter for history alloc() work on targets with MAU sizes other than eight bits.
• In basic.instname, added test of label output to a buffer
• In basic.logging, added ability to easily switch between LoggerBuf and LoggerSys (to see "same" output).

Installer

• Added ability to install XDC tools to a shared network drive, without installing Windows registry entries
• Added ability to choose which components of XDC tools to install
• Bug fix to InstallJammer when nested inside another product installer

Enhancements

The following minor enhancements were resolved:

ID	Headline
SDSCM00017350	CDOC should allow doxygen stylesheet
SDSCM00017825	need "registryfree" install of xdc tools

Defects

The following defects were resolved:

ID	Headline
SDSCM00016858	The sdkPath property of the Win32 target should support absolute path
SDSCM00017928	incorrect XDCPATH causes xdc.tools.path.sg to emit strange warning and fail
SDSCM00018207	cdoc.sg viewer cannot resolve name ti.sysbios.interfaces.ITimer
SDSCM00018222	CDOC should not show @_nodoc functions in the TOC on LHS of page
SDSCM00018234	CDOC - move "Details" to the top of each module page and change title to "Summary"
SDSCM00018237	configuro generates duplicate -I for xdc/packages in compiler.opt file
SDSCM00018294	System_abort is passing an invalid string to the Proxy's abort
SDSCM00018304	Parts of SysStd are being pulled in along with SysMin (and vica versa).
SDSCM00018328	platform packages should not depend on xdc.runtime
SDSCM00018352	XDC build for Windows Host throws Link Error with lnkx86
SDSCM00018395	rts470 boot code needs reset function hook
SDSCM00018543	cdoc.sg index shows meta create() and construct() as target
SDSCM00018616	arm whole_program should use --recursion_limit=20 switch
SDSCM00018673	add release notes, getting started guide, user guide, cdoc, repoman, pathman under shortcuts in start menu for xdc installs
SDSCM00018692	Display horizontal rule in cdoc graphical viewer
SDSCM00018710	global TSK_Obj symbols created by Program.symbol in legacy bios are not correct
SDSCM00018831	HeapStd should fail when passed an unsupport alignment
SDSCM00018832	HeapStd is not thread safe
SDSCM00018833	System atexit handlers should always execute with the system gate entered
SDSCM00018885	Cdoc viewer crash in Node.xs
SDSCM00019014	XDC config is slow to write the generated .c file
SDSCM00019018	ti.targets.rts5000 boot code fails for C55 small model
SDSCM00019039	can't set multiple import path in the CCS - XDC tab

---

Upgrade and Compatibility Information

Warning: Beginning with XDC 2.95, XDC modules with target content (i.e. non-meta-only) are incompatible with non-metaonly modules from XDC 2.94 and earlier. Metaonly modules are not affected. Non-metaonly modules require at least a recompile.

Warning: Beginning with xdc-o02, internal C files generated when building package schemas are named package_<package name>.c instead of <package_name>.c. This may introduce incompatibilities with older xdc-n and xdc-o trees (XDC 2.X products). The compatibility with metaonly xdc-m packages (XDC 1.X products) is still maintained.

Compatibility Key Definitions

Compatibility keys are intentionally independent of Marketing product numbers and are intended to:

1. Enable tooling to identify incompatibilities between components, and
2. Convey a level of compatibility between different releases to set end user expectations.

Compatibility keys are composed of 3 comma-delimited numbers - M,S,R - where:

• M = Major. A difference in M indicates a break in compatibility.
• S = Source. A difference in S indicates source compability. That is, the user's source doesn't require change, but does require rebuilding.
• R = Radix. A difference in R indicates an introduction of new features, but compatibility with previous interfaces has not broken. If libraries are provided by the package, an application must re-link with the new libraries, but not rebuild from source.

---

Host Support

This release supports the following hosts:

• Windows XP
• RedHat Enterprise Linux 3

---

Dependencies

This release requires the following other software components and tools versions to successfully function:

• C6x Code Generation Tools version 5.3.0 or later. Version 6.0.13 or later is required in order to use whole_program build profile.
• C55 Code Generation Tools version 3.2.0. or later
• TMS470 (Arm) Code Generation Tools version 4.1.4
• GCC for x86 version 3.2.3 or later
• GCC for ARM version 3.2.3 or later

---

Device Support

This release supports the following device families:

• C67P, C67, C64P, C64, C62
• C55P, C55, C54
• C28
• TMS470
• Native development host (Windows, Linux)

---

Validation Information

This release was built and validated against using the following components:

• Code Composer Studio version 3.3
• C6x Code Generation Tools version 6.0.7 and 6.0.13
• C55 Code Generation Tools version 3.2.2
• GCC for x86 version 3.2.3
• GCC for ARM version 3.2.3

---

Version Information

This product's version follows a version format, M.mm.pp.bb, where M is a single digit Major number, mm is 2 digit minor number, pp is a 2 digit patch number, and b is an unrestricted set of digits used as an incrementing build counter.

To support multiple side-by-side installations of the product, the product version is encoded in the top level directory, e.g. xdc_3_00.

Subsequent releases of patch upgrades will be identified by the patch number, ex. XDC 3.00.03 with directory xdc_3_00_03. Typically, these patches only include critical bug fixes.

Please note that version numbers and compatibility keys are NOT the same. For an explanation of compatibility keys, please refer to the 'Upgrade and Compatibility Information' section.

---

Technical Support

For technical support, contact rtsc_champs@list.ti.com

---

Last updated: August 13, 2007