Overview of xdc.runtime

From RTSC-Pedia

Jump to: navigation, search
revision tip
—— LANDSCAPE orientation
[printable version]  [offline version]offline version generated on 17-Jan-2019 04:01 UTC 

Overview of xdc.runtime

Introduction to the xdc.runtime package



The xdc.runtime package contains many low-level modules that work together to provide "core" services appropriate for any embedded C/C++ application:

  • memory management: basic memory allocation and freeing from multiple heaps
  • concurrency support: low-level critical region protection mechanisms
  • real-time diagnostics: printf-like logging, error management, and assertion support
  • system services: system initialization and shutdown (exit(), atexit(), abort(), etc.) and basic character output (printf())


The services provided by the xdc.runtime package are partition into numerous modules. The relationship between the modules in the xdc.runtime package and the services they provide is depicted in the figure below.

xdc.runtime Architecture

All of the modules and interfaces provided in the xdc.runtime package are supplied in portable C source code form. In addition, all of the modules are designed to be thread-safe and, where necessary, use the Gate module to serialize access to global data structures.

In order to ensure platform independence, those modules that require platform-specific services are designed to support one (or more) platform-specific "service providers". Each of these providers implements one of the interfaces supplied. Simple implementations of each service provider interface are also included in this package.

Using This Package

Only a subset of the xdc.runtime package's modules are directly referenced by an application. The other modules provided in the xdc.runtime package are simple implementations of "service provider" interfaces required by the application-level modules or are supporting modules that may be used in these implementations.

The table below summarizes the application-level modules and provides links to both the reference API documentation as well as user guide information for each category of service provided by the xdc.runtime package.

Category Modules User's Guide Documentation
memory management Memory Memory Management
concurrency support Gate Mutual Exclusion Gates
real-time diagnostics Log, Assert, Error, Timestamp, Diags Event Logging, Error Handling, Timestamp Services
system services System, Startup Basic Services

Like all packages, client applications must specify in a configuration script which modules of this package are to be included in the application. This configuration script is processed by the configuration tools to produce files that must be incorporated into your application. The configuration tool and how it is used is described in Configuration Basics.

Unlike other packages, however, the xdc.runtime package is treated specially within the XDCtools product.

  1. Unless explicitly disabled, every target implicitly adds a package containing a compiled version of the xdc.runtime modules to your configuration. See the Removing xdc.runtime From an Application section of Working with xdc.runtime to see how to disable the implicit include of this package.
  2. Every RTSC target module references "service provider" modules implementing IHeap and IGateProvider and, unless you specify otherwise, each RTSC target module will be "bound" to default implementations of these interfaces: HeapMin and GateNull.
  3. Every RTSC target module also allows the client to bind a "service provider" module implementing the ILogger interface.

There are several practical consequences of this special treatment:

  • by default, all applications link with a library containing the xdc.runtime modules.
  • since the xdc.runtime modules are used by most other modules (including service providers), xdc.runtime modules often become part of a configuration even if you omit the declaration within your configuration script; e.g., configuration scripts that do not explicitly call xdc.useModule("xdc.runtime.System") may coincidently work with applications that directly reference the System module.
  • if you do not specify a module that implements the ILogger interface, all Log methods will be disabled and no Log events will be generated. In addition, unlike all other modules, you cannot use xdc.runtime.Defaults to enable logging for the modules in the xdc.runtime package; you must explicitly set the logger and diagnostics flags for any module in xdc.runtime that you want to trace.

This package includes a single C++ file that defines a single statically initialized variable - the return value of the Startup module's initialization function. Since the ANSI C++ Standard ensures that all static variables are initialized prior to main(), module initialization via Startup always occurs prior to main(). This technique of initialization, while portable, implies that applications must, by default, be linked as C++ applications. If you are using a target that does not support C++ or you need to build an application that must not include C++ startup initialization, see Using xdc.runtime Startup.

If you are using this package in a multi-threaded environment, you must supply at least one implementation of the IGateProvider interface; otherwise, some xdc.runtime operations — as well as any modules that rely on these operations — will have undefined behavior. For more information about how to use this package in a multi-threaded environment, see the Multi-Threading Support section of Working with xdc.runtime.


The best way to understand how to use and take advantage of the xdc.runtime package is to study some simple examples. In the table below, we provide examples that illustrate the use of the xdc.runtime package within different execution contexts.

Example Description Purpose
Example 1 Using xdc.runtime in native workstation applications illustrate how to configure xdc.runtime to use existing memory and I/O services provided by standard C runtime environments
Example 2 Using xdc.runtime in deeply embedded applications illustrate how to configure xdc.runtime to minimize external dependencies

Extending This Package

Every embedded system has a unique set of capabilities and resource constraints. In order to enable the APIs provided by the xdc.runtime package to be available in every application, many of the xdc.runtime package's modules can be customized or "extended" to operate in a manner consistent with the runtime requirements of the embedded application. For example, when diagnostic events are generated, these events must be transmitted or stored using capabilities unique to the embedded platform.

Many of the modules in the xdc.runtime package have a corresponding "provider" interface that can be implemented in a platform-specific manner without requiring any change to existing clients. In particular,

  • the Log module relies on an underlying module, that implements the xdc.runtime.ILogger interface, to "do something" with events logged; e.g., write to a local circular buffer, send to an adjoining processor, etc.
  • the Timestamp module relies on an underlying module, that implements the xdc.runtime.ITimestampProvider interface, to obtain a system-wide timestamp value with up to 64-bits of range. Some CPUs have a running instruction cycle counter, some have a separate real-time clock, while others simply use real-time data streams to provide a timebase.
  • the Gate module relies on an underlying module, that implements the xdc.runtime.IGateProvider interface, to obtain and release a system-wide thread-safe lock. In non-preemptive or single-threaded systems this lock doesn't need to do anything, in systems with a preemptive RTOS it needs to use the RTOS's primitives to create an appropriate mutex.
  • the System module relies in an underlying module, that implements the xdc.runtime.ISystemSupport interface, to manage the orderly termination of the application; e.g., does abort() create a "core" file to assist debugging, should exit() enter a low power state erasing local memory or simply idle the CPU, etc.
  • the Memory module relies on an underlying module, that implements the xdc.runtime.IHeap interface, to manage allocation and freeing of memory. Some systems require deterministic operation and are willing to accept sub-optimal space usage of a fixed length allocator, other systems never perform allocation in the real-time path and require the ability to use all memory even in the face of variable length allocations, and still others never free memory.

The table below summarizes interfaces defined by the xdc.runtime package, identifies simple implementations of these interfaces (provided in the xdc.runtime package itself), and provides a reference to an "extender's" document that describes how to create new implementations of each interface.

Interface Implementations Purpose Extender's Guide
xdc.runtime.ILogger LoggerBuf, LoggerSys process Log events ILogger
xdc.runtime.ITimestampProvider TimestampNull (default), TimestampStd provide current time with up to 64-bits of range ITimeStampProvider
xdc.runtime.IGateProvider GateNull (default) thread-safe mutex IGateProvider
xdc.runtime.ISystemSupport SysMin (default), SysStd handle application termination and basic character output ISystemSupport
xdc.runtime.IHeap HeapStd (default), HeapMin allocate and free memory IHeap

Although, there is just one module responsible for implementing the ISystemSupport and ITimestampProvider interfaces, every module in a system can have an independent ILogger, IGateProvider, and IHeap implementation.

[printable version]  [offline version]offline version generated on 17-Jan-2019 04:01 UTC 
Copyright © 2008 The Eclipse Foundation. All Rights Reserved
Personal tools
package reference