From RTSC-Pedia

—— LANDSCAPE orientation

[printable version]  [offline version]

offline version generated on 04-Aug-2010 21:08 UTC

Overview of xdc.runtime

Introduction to the xdc.runtime package

Contents 1 Introduction 2 Architecture 3 Using This Package 4 Examples 5 Extending This Package

Introduction

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())

Architecture

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.

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 can not 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.

Examples

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 04-Aug-2010 21:08 UTC