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.
XDC 2.95 is a minor release.
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.
The following significant changes have been made since 2.94:
Source-incompatible changes to xdc.runtime package. Metaonly XDC
modules are not affected. Non-metaonly modules require at least a
recompile.
Significant functionality enhancements to the xdc.runtime
package
Improved support for ROM-able XDC target content
Usability enhancements including additions to the repoman
and cdoc tools, and fixes to previously release-noted installation
issues.
2.95 (This Release)
XDC Module Binary Contract
added the builtin function Mod_Params_copy( Mod_Params* dst,
const Mod_Params* src ) which is used to robustly copy
Mod_Params struct in light of the new Assert check;
Mod_Params_init() continues to behave as before.
XDC Runtime
set the compatibility key for xdc.runtime to [2,0,0,0]
reflecting source-incompatible changes to this module. This
requires at least a recompile of any XDC module that
has target content. The changes to the package are detailed
in the remainder of this section.
renamed the config Text.noLoadFlag (default false) to
Text.isLoaded (default true). the double-negative default was
"not never" confusing
changed the default of common$.namedModule to true
fixed a bug in xdc.runtime.LoggerBuf in which dual-entry
records were not being read/cleared correctly
Added some xdoc to ITimestampProvider.
Added a new System API: System_flush. This calls the
ISystemSupport module that is plugged into System. The
System_flush flushes pending io to stdout.
System_abort and System_exit enter the system gate at the
beginning of the functions.
The internal implementation of SysMin was changed to use a
template. This was done to completely remove HOSTwrite (or
fwrite) when not needed.
SysMin's flushFull implementation was changed slightly. It
resets the index. So if you have flushFull set to true, it will
flush when full, reset index and allow more data (which it will
flush again when full). This happens regardless of the wrap
config parameter.
added an assertion check in xdc.runtime.Core that validates
when a Params struct explicitly passed to create/construct has
been initialzed with a prior call to Params_init().
[SDSCM00017539]
added the interface xdc.runtime.ITimestampClient, which
basically abstracts the contents of the well-known
xdc.runtime.Timestamp module; the interface
xdc.runtime.ITimestampProvider now inherits this interface.
besides consolidating specs into one .xdc file, this pattern
enables other modules (e.g., LoggerSys) to bind their
respective proxies to an ITimestampClient -- either the
well-known Timestamp module or else one of the
ITimestampProviders.
fixed a bug in the xdc.runtime.Core implementation of "create"
in which a (smaller) interface Params struct passed to a proxy
create() was not being correctly assigned to the underlying
delegate's (larger) Params struct in light of the Assert check
added a 'mask' field to Assert.Desc, analogous to a
similarly-named field in Log.Desc, which further constrains
runtime execution of assert statements involving the
corresponding Assert_Id. assuming a call to
Diags_query(Diags_ASSERT) succeeds, a second Diags_query() call
is made with any other bits in the mask (after clearing
Diags_ASSERT). in general, these masks can be re-assigned at
.cfg time and even set to 0 (which will disable only this
Assert_Id)
added a Diags.INTERNAL level, with specific support for
Assert_isTrue(expr,id) calls in which NULL is passed as the
second arg. in this case, the second Diags_query() call [see
above] will implicitly test Diags_INTERNAL. since Diags.ASSERT
defaults to ALWAYS_ON, this enables "internal asserts" to be
freely placed in time-critical code.
added Diags.setMask$meta(Any pattern, Diags.Mask mask,
Diags.Mode mode), which sets the appropriate common$.diags_???
params for all modules whose fully-qualified name matches
pattern. the latter can be a string representing a
fully-qualified name (with an optional trailing '%' for
prefix-matching, not unlike in the runtime Diags_setMask
function) or else a javascript RegExp
changed the time values returned by xdc.runtime.TimestampNull
to be ~0 rather than 0, avoiding confusion with
ITimestampProvider modules that may initially return 0 (e.g.,
using an underlying Timer before interrupts are enabled).
Log_print() will continue to suppress output of timestamps when
this (new) sentinel value is present
updates to xdc.runtime.SysMin to avoid direct calls to
'write/HOSTwrite'; putting SysMin in ROM also no longer
requires .cio in the ROM linker map
fixed missing va_end in xdc.runtime.Text
added documentation to Assert.xdc, Diags.xdc, and Log.xdc.
internal changes in the implementation of ModA_construct(),
enabling run-time checking of the size of client-supplied
ModA_Struct against the actual ModA_Object size in the
underlying implementation; this check enables module producers
to grow/shrink the Instance_State struct, so long as it is not
larger than the ModA_Struct used by clients calling
ModA_construct(); more important, clients calling
ModA_construct() do *not* have to be recompiled so long as this
constraint holds.
refactored xdc.runtime.Memory to use an internal proxy in lieu
of making abstract function calls; no client impact
internal changes in the implementation of per-module gate
support, using an implicitly spec'd proxy named
Module_GateProxy in lieu of the special @System functions
defined today in xdc.runtime.IModule. no client impact
the default Heap module used by xdc.runtime.Memory, if not
default heap iinstance is provided, is *always*
xdc.runtime.HeapStd; use of xdc.runtime.HeapMin must now be
explicit
System_abort() takes a string. Deleted System_fail();
System.maxExitHandlers defaults to 8
Folded in SysMin review changes. New config parameters for
ISystemSupport interface functions. When set these functions
will override the SysMin implementations. Updated SysMin ROM
workaround to make output an internal function so that it's in
the spec file. Eliminated flushFull config parameter. SysMin
will use the System gate.
Fixed bug in LoggerBuf_getNextEntry(). Check return from
System_atexit().
If Memory.defaultHeapInstance is null, don't create a default
heap.
Fixed Startup.reset for ROM. This involved changes to Startup
module as well as boot code for all targets (now call reset__I
instead of reset__E).
Added an EXTERN_FUNC pragma to the generated Startup_reset
function so that it isn't lost in RAM assemblies, since it is
later referenced by the boot code in the final link.
System will add System_rtsExit() to list of rts exit handlers
by calling atexit() at Startup. System_rtsExit() will call all
System exit handlers and call the SupportProxy's exit function.
New System.atexitMeta to help ass System exit handlers statically.
System_exit() will call exit(). System_abort() will call abort.
SysMin and SysStd no longer call rts functions exit() and
abort().
LoggerBuf uses System.atexitMeta to plug flush function
Fixed bug in Logger_getNextEntry function
Turned on documentation for ILogger.xdc, LoggerBuf.xdc, and
LoggerSys.xdc. Documentation still in progress.
fixed a bug in System/SysMin in which System_abort() calls were
not flushing accumulated output; System_abort( String msg ) now
writes the msg using SupportProxy_putch(), calls
SupportProxy_flush(), calls SupportProxy_abort(msg), and then
abort()
fixed a bug in calls to Error_raise from legacy .c files caused
a compiler error; indirectly, this bug prevented use of
internal assert statements as well
as a rule, invocation of proxy functions on the target should
be limited to the module declaring the proxy; the only "public"
aspect of proxy is its binding in the .cfg domain. to comply,
the implementation of Gate_enterSystem() has been altered to no
longer "reach into" the System module and invoke its GateProxy.
this problem became apparent when RAM-based modules attempt to
"reach into" ROM-based modules and invoke their proxies.
if one module requires run-time access to another's proxy, the
former should declare a (internal) proxy of its own and simply
bind it accordingly. this approach has *no* impact of
target-side performance
More documentation updates to Assert and Diags modules.
Added xdoc for Defaults module.
Targets
fixed rts6000 boot file (SDSCM16337)
added empty section .sysmem to the boot files for C55 targets;
this section prevents warnings from the linker when there is
no input section .sysmem; memory.obj brings that input section
into the executable, but if no one is using malloc or SysStd is
not used, memory.obj does not get linked in
added new platform package ti.platforms.sim430xx, new runtime
package ti.targets.rts430 and a new catalog package
ti.catalog.c430 to support the MSP430 target
moved the fix for .sysmem warning on C55 targets from boot files
to Program.xdt. The previous fix in boot files, where .sysmem
section was created would cause linker to create a .sysmem
output section of size 0x1000 even if the option '-heap 0x0'
was passed to the linker. Now, Program.xdt examines
Program.heap and only if it's not 0, a dummy variable is placed
in .sysmem
ti/targets/linkcmd.xdt and linker command files in examples are
now using Program.getSectMap() function
Removed argsize directive from linkcmd.xdt for ROM assemblies.
This prevents the c_arg symbol from being created in the ROM
image.
Revert Arm compiler back to 4.1.4
Use -op2 for ARM whole_program build
fixed bugs in ti.targets linkcmd.xdt; loadSegment was referenced without
checking if it's defined
Platforms
added TNETV2685 (Kailash) catalog files
added additional XDOC for platform instances and predefined
macros
XDC Configuration
fixed a problem in sync'ing the value of Program.system with
System.SupportProxy, in the event that the latter is explictly
assigned. if Program.system is undefined, the value of
System.SupportProxy (default SysMin) is pushed into
Program.system; otherwise, the reverse assignment occurs.
assigning *both* Program.system and SystemSupportProxy is not
recommended. in general, use of Program.system should be
strongly discouraged going forward and may even generate
warnings in the future. this enables xdc.runtime.System to be
"used" and its proxy bound no differently than any other module
fixed a bug in which ModA_Handle_label__S was not being
retained in partial-links
Program.getSectMap is added to Progam. It returns the current
section map based on the same sequence of step that the linker
command file template is making when creating the final section
map. In the next tree, the template should be changed to use
the new function. (SDSCM00015209)
added cfgHome attr to xdc.bld.Executable.Attrs; this allows
one to specify the package that is bound to $homepkg in the
configuration model.
refactored the back-end of the .cfg model to ensure the
xdc.runtime package is correctly finalized; this corrects a
problem in which "early" calls to
xdc.useModule('xdc.runtime.System') were leading to unbound
proxies.
removed Program.memory; config scripts should instead directly
reference xdc.runtime.Memory; updated all examples
removed Program.common$Defaults; config scripts should instead
configure the new xdc.runtime.Defaults module through the
standard 'common$' metaonly struct, which otherwise plays the
same role; updated all examples
deprecated assignments to Program.system, with a warning now
being output. depending upon the presence of "used" target
modules, the back-end of .cfg will conditionally bring-in the
xdc.runtime.package; assignment of 'null' to Program.system is
no longer necessary for pure legacy programs; and as is the
case already, Program.system cannot be 'null' if target modules
are present. in cases where legacy code calls (say)
System_printf -- and no other modules are otherwise included --
an explict call to xdc.useModule('xdc.runtime.System') is in
order. in general, this is the recommend pattern -- #include
a module, xdc.useModule a module. Assigning the
System.SupportProxy (default, xdc.runtime.SysMin) allows
selection of alternative ISystemSupport modules (e.g.,
xdc.runtime.SysStd). updated all examples.
Program.symbol entries are now declared in the same generated
.h file including the Program.global entries; in cases where a
symbol is equated to a statically-created instance, the
declaration is of the form extern pkg_ModA_Object symName.
in general, client programs will reference the value of the
symbol through a '&symName' expression
XDC Core
Added use of radix to XVal.Number.
fixed SDSCM00015806, in which use of '()' and '(Void)' in
function-pointer declarators were yielding incompatible
signatures
fixed a problem in the generation of __E_D helper-functions
used to support per-instance proxy functions that surfaced in
the ROM flow
fixed SDSCM00015016: all "interface objects" are now sealed in
the meta-domain, preventing any changes to module-wide configs
spec'd in this interface.
Note: the parameter $used for interfaces is left unsealed, so
xdc.useModule() can have an interface as a parameter. this is
a temporary solution until we find out how should users get
handles to interfaces
the file package/cfg/*.rta.xml is now being generated for all
executable programs; it contains sufficient info to support a
standalone decoder for binary Log.EventRec structs.
the package xdc/rta contains will shortly contain a java-based
decoder that is driven by the info in this .xml file. details
of associating this .xml file with the executable image are TBD.
__ASM__ string in executables now contains absolute path to
assembly
changed the implementation of proxy-checking so that calls to
xdc.useModule() contained in module$use functions do not
immediately act upon the used module's proxies
refactored much the close() function in xdc/runtime/package.xs
into the module$use() function in xdc/runtime/System.xs.
removed the special internal function finalize() in
xdc/cfg/package.xs
generalized the implementation of proxy instances, such that a
collection of modules with proxies inheriting a common
interface can exchange instances of their respective proxies
more naturally. in effect, all proxy instance handles are
typedef'd as abstract instance handles from the inherited
interface. while some static type-safety has been sacrified at
the C compiler level, the use of config-time validation (plus
run-time asserts, if needed) make up the balance. run-time
performance is unchanged, and no source code changes are needed
in the current code base. this feature is motivated by more
"advanced" designs involving collections of abstract
interfaces, where each interface may itself spec several
abstract proxies.
Added checks to xdc.services.global.Path.setPath() to catch
XDCPATH syntax errors early and report a specific error message.
fixed a bug in the typedef of proxy-module instance handles
that surfaced when the proxy inherited an interface in a
different package
updated the generation of __E/__F stubs for vargs functions to
now call va_end(), suppressing a warning from code checkers
like coverity
In tconf.ksh and xs.ksh, exec'd to the native executable
instead of forking to it. Eliminates some corner cases that
occur when running XDC scripts that fork background threads.
In xdc.services.spec, generated Javadoc files during
package release.
fixed a bug in .sch file generation in which reference to
'xdc.rov.support' datatypes were being incorrectly named
Fixed null-pointer exception in spec.BrowserSession.loadUnit
fixed a bug in which packages containing modules whose names
conflict with IPackage functions (e.g., a module named 'close')
were yielding errors in the generated .sch file. while this
fix actually allows modules named 'close', this practice is
highly discouraged. to maintain backward-compatibility, this
fix will trigger automatic re-generation of older .sch files
upon loading their respective packages
xdc.bin was build with compatibility checking disabled, so that
we can build xdc.bin with xdc.runtime [2,0,0,0]; the package
being an issue was xdc.host.services.lib from xdcutils tree,
which was built with xdc.runtime [1,0,0,0]; this is a cycle to
be resolved
fixed a bug in xe where old #defines were not replaced with
xdc_target__os #defines
ROM Support
added the 'romPatchTable' config (default false) to common$;
this param is only meaningful when configuring ROM assemblies.
if true, all calls to the current module *from within the ROM*
will be vectored through a data-resident patch-table.
if false, calls to this module originating in the ROM are
executed through the normal runtime, enabling autoinlining with
WPO.
Program.importRomAsm() now executes the original .cfg script
associated with the ROM assembly. all modules in the ROM
assembly are also finalized through a call to module$use().
added Program.freezeRomConfig(), used in .cfg scripts or .xs
files executed during a ROM assembly to designate a particular
module-wide config to be bound ("frozen") in the ROM image.
as a side effect of this call, the designate config is sealed
to prevent further (accidental) modification. by default,
static initialization of *all* configs are deferred to the
final assembly. as a consequence, ROM functions may incur
inefficiencies when accessing module-wide configs in general.
changed Program.freezeRomConfig() to only seal configs in the
final assembly, and only after all module$use() functions for
the original ROM modules have been called. this accommondates
potentially "out-of-order" closings due to proxy-induced
config-time cycles amongst packages
further ROM optimizations, including the freezing of some
system config params as well as embedded object offsets
all "system functions" spec'd in xdc.runtime.IModule are now
ROM-able, reducing both time and space overhead; the functions
are no longer called via a patch-table
added Program.patchRom( modName, fxnName, symbol ) used for
"emergency" patches to suitably-configured modules
(patchTable == true) in final assemblies
fixed a bug in the ROM flow in which a ROM'd module and a RAM'd
module inheriting from a common interface were resulting in
multiple definitions of the special interface BASE__C symbols
Configuro Build Tool
Changed configuro to allow better use of config.bld.
Added "--cb" option to explicitly
search for config.bld along the package path. Config.bld is
now only included when it is asked for, either with --cb or
the existing -b flag.
Config.bld will be used if either
-b or --cb flags are thrown. -b takes precedence,
specifying the location of config.bld exactly.
Repoman Repository Management Tool
Sort file names returned from Java.io.File.listFiles()
Added File, Edit and Help menus & Help->About box
"fixed" repoman to not scan the current working directory
for packages; it now only scans the package path.
extract/copy repositories from compressed and installed bundles
added -o and -i args to save repository info and restore a repository
File->Save and File->Open to save and restore current state
-recognize products as packages when looking for bundles
-drag n drop crash bug when re-ordering repositories in rh pane
-gray text for read-only repositories in rh pane
-Modified text in tooltips, dialog titles,
menus, etc. to help make usage less confusing
-Added tooltips over tree titles that explains
what the tree does
-Added context menus on Available Packages tree
parent nodes
-Make sure tooltips stay inside screen
boundaries
-Make tooltip disappear when dragging a package
to a repository
new .rmn file format
--rrestore & --rrcreate for restoring/creating
repositories from file saved with -outfile
new processing of .rmn files on File->Open
Xdoc / Cdoc Package Documentation Tool
In xdc.tools.cdoc, added @fn, @typedef, @struct, and @enum
tags, modeled after Doxygen's tags of the same name. Using
these tags in a module's or interface's XDOC lets you add
comments to any declaration of the module, even generated ones.
Similarly the existing tag @param can be used to document
generated function parameters such as an instance handle or
error block.
cleaned up names of generated C function
parameters. Fixed bug in generation of links for @link'd files.
Added new command-line parameters to open
docs pages on startup. Declaration can be listed on the command
line using the same syntax as the {@link} tag.
updated index tree to show red-world and
blue-world units and functions. Generated the index tree
lazily, to minimize the delay in opening the tool. Fixed bug in
which @link targets were not correctly validated against the
known XDC declarations.
fixed bug in using from command line.
presented a simple XDC Script view. This filters
out all target-only content, and presets the metaonly and mixed
target/meta content using the XDC spec syntax. Added XDC Script
declarations for create(), construct(), and Params{}.
in xdc.tools.idl.Node, added ability to prune the node tree
while constructing from the spec, to improve cdoc speed and
memory usage.
updated the stylesheet to reduce clutter in
the generated documentation. Shortened all declarations in the
unit summary block to one line each. Reordered to put functions
first. In the details sections, removed comments from prototype
and moved them into PARAMETERS, FIELDS and VALUES sections as
in xdoc.
Path Tool
_buildRepArray: build array in path order
update xdcpkg call path for engineering tree
Configuration Viewer Tool
added an experimental xdc.tools.objviewer.sg which is
package configuration browser.
usage: xs xdc.tools.objviewer.sg
[-e executableName] [-p path] packagename
Other Tools
In xdc.tools.mkpkg, added ability to copy a file or
directory without template expansion. Enabled by adding
"@verbatim" to the file's line in the mkpkg.xdt file.
Updated package docs.
Added tests to xdc.tools.sg.swt_linux package to help diagnose
setup of Mozilla, required to use xdc.tools.cdoc.sg
documentation browser on Linux. Checks the environment
variables Mozilla requires, and prints warning text if not
correct.
In xdc.tools.Cmdr, fixed a couple of minor documentation errors
added a ResourceBundle module to xdc.tools. ResourceBundle
provides access to localized properties files within
packages. See the xdoc.
RTSC Object Viewer
fixed an ROV bug in which the xdc.runtime package was being
loaded *before* xdc.om.$name was defined
Added Model_reset() and Program.resetMods() to allow resetting
of data structures read from target at ROV time.
Added ROV views to several modules in xdc.runtime package
Examples
added the example basic.absproxy to illustrate a use-case of
proxy declarations in interfaces which in turn are referenced
as types in the same abstract spec. quite advanced, this is
actually a "solution" to a well-known type-covariance problem.
a first practical application of this pattern will be in
specifying signatures of process functions in abstract
codecs/algorithms that do *not* involve use of void* as a
unifying type.
fixed basic.scripts example to run the chack.xs script
that displays a package's dependencies
In examples/configuro/plat_inst, updated to use platform-j15
tree because of package incompatibility.
Aligned examples with System changes
added comments to local.targets example
Enhancements
The following minor enhancements were resolved:
ID
Headline
SDSCM00013705
Targets should have capability to add more steps to the build process
SDSCM00015209
Function to view Section Map
SDSCM00017102
xdc.tools.mkpkg support files in a template dir that aren't templates
Defects
The following defects were resolved:
ID
Headline
SDSCM00012747
Configuro issues
SDSCM00014574
API's Documentation missing in CDOC/XDOC
SDSCM00015016
XDC should catch invalid assignment of 'interface' config param
SDSCM00015175
XDCPATH with quotes blows up some tools
SDSCM00015806
A function pointer config parameter should allow the keyword Void in parameter list
SDSCM00016234
XDC should provide a clean way to document Mod_delete(), Mod_construct(), and Mod_destuct()
SDSCM00016337
need boot file to disable interrupts clear IER, IFR
SDSCM00016565
configuro does not support targets derived from ti.targets.ITarget
SDSCM00016762
Module_delete does not free memory back to the default Heap
SDSCM00016879
configuro doesn't pass in -D option to CFG script
SDSCM00016971
IMCOP memory should be removed from Kailash catalog files
SDSCM00017165
Move -op2 option into target for 6x
SDSCM00017188
fix the default frequency for evmDM648 board
SDSCM00017378
cdoc shows consts for interface-wide config params
SDSCM00017406
consecutive cdoc @see directives generate bad link text
SDSCM00017490
Dot in directory causes error: TypeError: Cannot call method "instance" of undefined
SDSCM00017539
need Assert to help with Xyz_Params_init() and Mod_create/construct
SDSCM00017863
sectMap[] needs to support 'address' field to allow placement at hard address
SDSCM00017890
cdoc @link to .pdf file in another package not generated correctly
SDSCM00017891
XDC BTI should make using config.bld the standard flow
SDSCM00017926
@_nodoc at module level should hide module entirely
SDSCM00017953
SysMin cleanup
SDSCM00017955
update sectMap[] to be structure with load/run fields and room for more
xdc.runtime - This package is incompatible with the
previous release. (Compatibility key: 1,0,0,0 -> 2,0,0,0)
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:
Enable tooling to identify incompatibilities between components, and
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.
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_2_93.
Subsequent releases of patch upgrades will be identified by the patch number,
ex. XDC 2.93.03 with directory xdc_2_93_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.