module xdc.runtime.System

Basic system services

This module provides basic low-level "system" services; e.g., character output, printf-like output, and exit handling. [ more ... ]
C synopsis target-domain sourced in xdc/runtime/System.xdc
#include <xdc/runtime/System.h>
Functions
Void 
Int 
Int 
Bool 
Int 
Int 
Void 
Void 
Int 
Void 
Int 
Int 
System_vprintf// A VaList printf(String fmt, VaList va);
Int 
System_vsprintf// A VaList sprintf(Char buf[], String fmt, VaList va);
Functions common to all target modules
Defines
#define
Typedefs
typedef Void 
Constants
extern const Assert_Id 
extern const Int 
 
DETAILS
This module provides basic low-level "system" services; e.g., character output, printf-like output, and exit handling.
This module is gated and other modules use its gate via the Gate.enterSystem and Gate.leaveSystem. The System gate must be enterable by any thread in a multi-threaded environments. For example, in many real-time multi-threaded environments some types of threads, such as Interrupt Service Routines (ISRs), are not allowed to call operations that block the caller. In such an environment, either the System gate must disable all interrupts or ISRs must never call a function in the xdc.runtime package.
 
const System_STATUS_UNKNOWN

Unknown exit status value

C synopsis target-domain
#define System_STATUS_UNKNOWN (Int)0xCAFE
 
DETAILS
When the program exits by calling System_exit() the System's atexit functions are passed the status value passed to System_exit(). However, if the program exits using the ANSI C Standard Library exit() function, the System's atexit functions are passed System_STATUS_UNKNOWN; ANSI C atexit functions are not passed the exit status.
 
typedef System_AtexitHandler

System's atexit function prototype

C synopsis target-domain
typedef Void (*System_AtexitHandler)(Int);
 
DETAILS
Fuctions of this type can be added to the list of functions that are executed during application termination.
SEE
 
config System_A_cannotFitIntoArg  // module-wide

Assert that the target's Float type fits in an IArg

C synopsis target-domain
extern const Assert_Id System_A_cannotFitIntoArg;
 
DETAILS
This assertion is triggered when the %f format specifier is used, the argument treated as an IArg, but for the current target sizeof(Float) > sizeof(IArg).
 
config System_maxAtexitHandlers  // module-wide

Maximum number of dynamic atexit handlers allowed in the system

C synopsis target-domain
extern const Int System_maxAtexitHandlers;
 
DETAILS
Maximum number of System atexit handlers set during runtime via the System.atexit function.
 
System_abort()  // module-wide

Print a message and abort currently running executable

C synopsis target-domain
Void System_abort(String str);
 
ARGUMENTS
str — abort message (not a format string)
DETAILS
This is called when an executable abnormally terminates. The System gate is entered, the SupportProxy's abort function is called and abort is called. No exit functions bound via System_atexit() or the ANSI C Standard Library atexit() functions are executed.
 
System_aprintf()  // module-wide

printf where all optional arguments are IArgs

C synopsis target-domain
Int System_aprintf(String fmt, ...);
 
DETAILS
This function will treat each argument as though it was widened to be of type IArg prior to being passed to the printf function
SEE
 
System_asprintf()  // module-wide

sprintf where all optional arguments are IArgs

C synopsis target-domain
Int System_asprintf(Char buf[], String fmt, ...);
 
DETAILS
This function will treat each argument as though it was widened to be of type IArg prior to being passed to the sprintf function.
SEE
 
System_atexit()  // module-wide

Add an exit handler

C synopsis target-domain
Bool System_atexit(System_AtexitHandler handler);
 
ARGUMENTS
handler — the AtexitHandler to invoke during system exit processing.
DETAILS
System_atexit pushes handler onto an internal stack of functions to be executed when system is exiting (e.g. System_exit or exit is called). Up to maxAtexitHandlers functions can be specified in this manner. During the exit processing, the functions are popped off the internal stack and called until the stack is empty.
The System gate is entered before the System_atexit functions are called.
The SupportProxy's ISystemSupport.exit function is called after all the atexit functions are called.
RETURNS
If FALSE is returned, the exit handler was not added and it will not be called during an exit.
 
System_avprintf()  // module-wide

vprintf where all optional arguments are IArgs

C synopsis target-domain
Int System_avprintf(String fmt, VaList va);
 
DETAILS
This function will treat each argument as though it was widened to be of type IArg prior to being passed to the vprintf function.
SEE
 
System_avsprintf()  // module-wide

vsprintf where all optional arguments are IArgs

C synopsis target-domain
Int System_avsprintf(Char buf[], String fmt, VaList va);
 
DETAILS
This function is identical to sprintf except that its arguments are passed via a VaList (a "varargs list").
This function will treat each argument as though it was widened to be of type IArg prior to being passed to the vsprintf function
SEE
 
System_exit()  // module-wide

Exit currently running executable

C synopsis target-domain
Void System_exit(Int stat);
 
ARGUMENTS
stat — exit status to return to calling environment.
DETAILS
This function is called when an executable needs to terminate normally. This function sets the exit code and simply calls exit. All functions bound via System_atexit or the ANSI C Standar Library atexit function are then executed. The SupportProxy's exit function is called during this time.
 
System_flush()  // module-wide

Flush standard System I/O

C synopsis target-domain
Void System_flush();
 
DETAILS
This function causes any buffered output characters are "written" to the output device.
The SupportProxy's flush function is called by this function.
 
System_printf()  // module-wide

A smaller faster printf

C synopsis target-domain
Int System_printf(String fmt, ...);
 
ARGUMENTS
fmt — a 'printf-style' format string
DETAILS
This function behaves much like the ANSI C Standard printf but does not support the full range of format strings specified by the C Standard. In addition, several non-standard format specifiers are recognized.
FORMAT STRINGS
The format string is a character string composed of zero or more directives: ordinary characters (not %), which are copied unchanged to the output stream; and conversion specifications, each of which results in fetching zero or more subsequent arguments. Each conversion specification is introduced by the character %, and ends with a conversion specifier. In between there may be (in this order) zero or more flags, an optional minimum field width, an optional precision and an optional length modifier.
FLAGS
The following flags are supported:
-
The converted value is to be left adjusted on the field boundary (the default is right justification.)
0
The value should be zero padded. For d, i, o, u, and x conversions, the converted value is padded on the left with zeros rather than blanks.
FIELD WIDTH
The optional field width specifier is a decimal digit string (with nonzero first digit) specifying a minimum field width. If the converted value has fewer characters than the field width, it will be padded with spaces on the left (or right, if the left-adjustment flag has been given). Instead of a decimal digit string one may write * to specify that the field width is given in the next argument. A negative field width is taken as a '-' flag followed by a positive field width.
PRECISION
The optional precision specifier is a period ('.') followed by an optional decimal digit string. Instead of a decimal digit string one may write * to specify that the precision is given in the next argument which must be of type int.
If the precision is given as just '.', or the precision is negative, the precision is taken to be zero. This gives the minimum number of digits to appear for d, i, o, u, and x conversions, or the maximum number of characters to be printed from a string for s conversions.
LENGTH MODIFIERS
The optional length modifier is a single character from the following list.
l
A following integer conversion corresponds to a long int or unsigned long int argument
CONVERSION SPECIFIERS
The following conversion specifiers are supported.
d, i
signed integer
u
unsigned decimal
x
unsigned hex
o
unsigned octal
p
pointer (@ + hex num)
c
character
s
string
EXTENDED CONVERSION SPECIFIERS
The following conversion specifiers are optionally supported. See the extendedFormats configuration parameter for more information about how to enable these conversion specifiers.
f
decimal floating point.
$
non-ANSI conversion prefix. This prefix indicates that the next character identifies a non-ANSI standard conversion. See the next section for details.
NON ANSI CONVERSION SPECIFIERS
Among the extended conversion specifiers are unique specifiers which are not part of ANSI printf. These are specified using a $, for example %$L.
These unique specifiers do not support the minimum field width attribute. Certain specifiers have additional restrictions; see below.
'$L'
The argument is treated as a pointer to a Types.Label and is converted to an appropriate string.
'$F'
Displays a file and line number; used for displaying the call site. This specifier consumes two arguments, the file and line number, in that order. See an example below.
'$S'
The argument is treated as a format string, and is recursively formatted using any following arguments. This specifier does not support the use of the "precision" field for specifying maximum string length.
The following are example uses of the %$F and %$S format specifiers.
In this call using %$F, the compiler recognizes these symbols and fills in the file and line number.
  System_printf("%$F", __FILE__, __LINE__);
This call outputs, for example,
  "MyCode.c", line 35: 
Here is an example using %$S, passing a recursive format string.
  System_printf("Msg: %$S", "My msg, code: %d", 5);
This outputs:
  Msg: My msg, code: 5
RETURNS
printf returns the number of characters printed.
 
System_putch()  // module-wide

Output a single character

C synopsis target-domain
Void System_putch(Char ch);
 
ARGUMENTS
ch — character to be output.
DETAILS
The SupportProxy's putch function is called by this function.
 
System_sprintf()  // module-wide

Write formated output to a character buffer

C synopsis target-domain
Int System_sprintf(Char buf[], String fmt, ...);
 
ARGUMENTS
buf — a character output buffer
fmt — a 'printf-style' format string
DETAILS
This function is identical to printf except that the output is copied to the specified character buffer buf followed by a terminating '\0' character.
RETURNS
sprintf returns the number of characters output not including the '\0' termination character.
 
System_vprintf()  // module-wide

A VaList printf

C synopsis target-domain
Int System_vprintf(String fmt, VaList va);
 
ARGUMENTS
fmt — a standard 'printf-style' format string.
va — an args list that points to the arguments referenced by the fmt string
DETAILS
This function is identical to printf except that its arguments are passed via a VaList (a "varargs list").
RETURNS
vprintf returns the number of characters output.
 
System_vsprintf()  // module-wide

A VaList sprintf

C synopsis target-domain
Int System_vsprintf(Char buf[], String fmt, VaList va);
 
ARGUMENTS
buf — a character output buffer
fmt — a standard 'printf-style' format string.
va — an arguments list that points to the arguments referenced by the fmt string
DETAILS
This function is identical to sprintf except that its arguments are passed via a VaList (a "varargs list").
RETURNS
vsprintf returns the number of characters output.
Module-Wide Built-Ins

C synopsis target-domain
Types_ModuleId System_Module_id();
// Get this module's unique id
 
Bool System_Module_startupDone();
// Test if this module has completed startup
 
IHeap_Handle System_Module_heap();
// The heap from which this module allocates memory
 
Bool System_Module_hasMask();
// Test whether this module has a diagnostics mask
 
Bits16 System_Module_getMask();
// Returns the diagnostics mask for this module
 
Void System_Module_setMask(Bits16 mask);
// Set the diagnostics mask for this module
 
XDCscript usage meta-domain sourced in xdc/runtime/System.xdc
var System = xdc.useModule('xdc.runtime.System');
local proxy modules
        System.SupportProxy.delegate$ = ISystemSupport.Module null
module-wide constants & types
module-wide config parameters
        msg: "A_cannotFitIntoArg: sizeof(Float) > sizeof(Arg)"
    };
 
module-wide functions
    System.atexitMeta// Add an exit handler during configuration(Void(*)(Int) handler) returns Void
 
 
proxy System.SupportProxy

The implementation module of the low-level system functions

XDCscript usage meta-domain
System.SupportProxy = ISystemSupport.Module null
// some delegate module inheriting the ISystemSupport interface
    System.SupportProxy.delegate$ = ISystemSupport.Module null
    // explicit access to the currently bound delegate module
 
DETAILS
This configuration parameter allows one to "bind" a different implementation of the low-level services required to implement System.
      var System = xdc.useModule("xdc.runtime.System");
      var SysStd = xdc.useModule("xdc.runtime.SysStd");
      System.SupportProxy = SysStd;
If this parameter is not set, it defaults to SysMin.
 
const System.STATUS_UNKNOWN

Unknown exit status value

XDCscript usage meta-domain
const System.STATUS_UNKNOWN = 0xCAFE;
 
DETAILS
When the program exits by calling System_exit() the System's atexit functions are passed the status value passed to System_exit(). However, if the program exits using the ANSI C Standard Library exit() function, the System's atexit functions are passed System_STATUS_UNKNOWN; ANSI C atexit functions are not passed the exit status.
C SYNOPSIS
 
config System.A_cannotFitIntoArg  // module-wide

Assert that the target's Float type fits in an IArg

XDCscript usage meta-domain
System.A_cannotFitIntoArg = Assert.Desc {
    msg: "A_cannotFitIntoArg: sizeof(Float) > sizeof(Arg)"
};
 
DETAILS
This assertion is triggered when the %f format specifier is used, the argument treated as an IArg, but for the current target sizeof(Float) > sizeof(IArg).
C SYNOPSIS
 
config System.maxAtexitHandlers  // module-wide

Maximum number of dynamic atexit handlers allowed in the system

XDCscript usage meta-domain
System.maxAtexitHandlers = Int 8;
 
DETAILS
Maximum number of System atexit handlers set during runtime via the System.atexit function.
C SYNOPSIS
 
metaonly config System.common$  // module-wide

Common module configuration parameters

XDCscript usage meta-domain
System.common$ = Types.Common$ undefined;
 
DETAILS
All modules have this configuration parameter. Its name contains the '$' character to ensure it does not conflict with configuration parameters declared by the module. This allows new configuration parameters to be added in the future without any chance of breaking existing modules.
 
metaonly config System.extendedFormats  // module-wide

Optional conversions supported by System_printf

XDCscript usage meta-domain
System.extendedFormats = String "%$L%$S%$F";
 
DETAILS
This string specifies the set of optional argument conversion specifiers required by the application. By reducing the number of optional conversions understood by the System printf methods, it is possible to significantly reduce the code size footprint of the System module. This configuration parameter enables one to balance printf functionality against code size footprint.
The format of this string is simply a concatenated list of the desired conversion specifiers (with the leading % character). For example, to support both %f and %$L set extendedFormats to "%$L%f".
To disable all optional converstions, set extendedFormats to null or the empty string ("").
For a complete list of supported extensions, see the System_printf "Extended_Format_Specifiers" section.
NOTE
If an optional conversion is used by some part of the application and it is not specified in extendedFormats, the conversion character(s) and leading % are treated as ordinary characters to be output. As a result, all subsequent arguments will almost certainly be converted using the wrong conversion specifier!
SEE
 
metaonly System.atexitMeta()  // module-wide

Add an exit handler during configuration

XDCscript usage meta-domain
System.atexitMeta(Void(*)(Int) handler) returns Void
 
ARGUMENTS
handler — the AtexitHandler to invoke during system exit processing.
DETAILS
This is the static counterpart to System_atexit(). This method can be used to add atexit handlers at configuration time. These handlers do not count against the maxAtexitHandlers.
generated on Thu, 01 Mar 2012 16:58:41 GMT