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 
Void 
Void 
Int 
Int 
Bool 
Int 
Int 
Void 
Void 
Void 
Void 
Int 
Void 
Void 
Int 
System_snprintf// Write formated output to a character buffer(Char buf[], SizeT n, CString fmt, ...);
Int 
Int 
System_vprintf// A VaList printf(CString fmt, VaList va);
Int 
System_vsnprintf// A VaList snprintf(Char buf[], SizeT n, CString fmt, VaList va);
Int 
System_vsprintf// A VaList sprintf(Char buf[], CString fmt, VaList va);
Functions common to all target modules
Defines
#define
Typedefs
typedef Void 
typedef Void 
typedef Void 
Constants
extern const System_AbortFxn 
extern const Assert_Id 
extern const System_ExitFxn 
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_AbortFxn

System abort function prototype

C synopsis target-domain
typedef Void (*System_AbortFxn)();
 
DETAILS
Fuctions of this type can be plugged in to System's abort function that will be executed during abnormal application termination.
SEE
 
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
 
typedef System_ExitFxn

System exit function prototype

C synopsis target-domain
typedef Void (*System_ExitFxn)(Int);
 
DETAILS
Fuctions of this type can be plugged in to System's exit function that will be executed during normal 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_abortFxn  // module-wide

Abort handler function

C synopsis target-domain
extern const System_AbortFxn System_abortFxn;
 
DETAILS
This configuration parameter allows user to plug in their own abort function. By default abortStd which calls ANSI C Standard abort() is plugged in. Alternatively abortSpin can be plugged which loops infinitely.
 
config System_exitFxn  // module-wide

Exit handler function

C synopsis target-domain
extern const System_ExitFxn System_exitFxn;
 
DETAILS
This configuration parameter allows user to plug in their own exit function. By default exitStd which calls ANSI C Standard exit() is plugged in. Alternatively exitSpin can be plugged which loops infinitely.
 
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(CString 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 then abortFxn is called. No exit functions bound via System_atexit() or the ANSI C Standard Library atexit() functions are executed.
 
System_abortSpin()  // module-wide

Lightweight implementation of abortFxn function

C synopsis target-domain
Void System_abortSpin();
 
DETAILS
This functions loops indefinitely. This can used as an alternative abortFxn when a lightweight implementation is required instead of the ANSI C Standard abort().
 
System_abortStd()  // module-wide

ANSI C Standard implementation of abortFxn function

C synopsis target-domain
Void System_abortStd();
 
DETAILS
This function calls ANSI C Standard abort() to terminate currently running executable. This function is used by default in abortFxn.
 
System_aprintf()  // module-wide

printf where all optional arguments are IArgs

C synopsis target-domain
Int System_aprintf(CString 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[], CString 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 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(CString 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[], CString 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 processes all functions bound via System_atexit and then calls exitFxn. The SupportProxy's exit function is called during this time.
 
System_exitSpin()  // module-wide

Implements an exitFxn function

C synopsis target-domain
Void System_exitSpin(Int stat);
 
ARGUMENTS
stat — exit status to return to calling environment.
DETAILS
This functions loops indefinitely. This can used as an alternative exitFxn when a light weight implementation is required instead of the ANSI C Standard exit().
 
System_exitStd()  // module-wide

Implements an exitFxn function

C synopsis target-domain
Void System_exitStd(Int stat);
 
ARGUMENTS
stat — exit status to return to calling environment.
DETAILS
This function calls ANSI C Standard exit() to terminate currently running executable normally. This function is used by default in exitFxn.
 
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(CString 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_processAtExit()  // module-wide

Processes all functions bound via System_atexit

C synopsis target-domain
Void System_processAtExit(Int stat);
 
ARGUMENTS
stat — exit status which will passed to all functions processed.
DETAILS
This function is called by System_exit to process all functions bound via System_atexit. User can add this to ANSI C standard atexit function so that all functions bound via System_atexit are processed when ANSI C standard exit function is called.
 
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_snprintf()  // module-wide

Write formated output to a character buffer

C synopsis target-domain
Int System_snprintf(Char buf[], SizeT n, CString fmt, ...);
 
ARGUMENTS
buf — a character output buffer
n — the maximum number of characters, including '\0', written to the output buffer buf
fmt — a 'printf-style' format string
DETAILS
This function is identical to sprintf except that at most n characters are copied to the specified character buffer buf. If n is zero, nothing is written to character buffer. Otherwise, output characters beyond the n - 1 are discarded rather than being written to the character buf, and a null character is written at the end of the characters written into the buffer.
RETURNS
snprintf returns the number of characters that would have been written had n been sufficiently large, not counting the terminating '\0' character.
 
System_sprintf()  // module-wide

Write formated output to a character buffer

C synopsis target-domain
Int System_sprintf(Char buf[], CString 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(CString 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_vsnprintf()  // module-wide

A VaList snprintf

C synopsis target-domain
Int System_vsnprintf(Char buf[], SizeT n, CString fmt, VaList va);
 
ARGUMENTS
buf — a character output buffer
n — at most number of characters including '\0' written to 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 snprintf except that its arguments are passed via a VaList (a "varargs list").
RETURNS
vsnprintf returns the number of characters that would have been written had n been sufficiently large, not counting the terminating '\0' character.
 
System_vsprintf()  // module-wide

A VaList sprintf

C synopsis target-domain
Int System_vsprintf(Char buf[], CString 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
 
Configuration settings 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

Configuration settings
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

Configuration settings
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

Configuration settings
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.abortFxn  // module-wide

Abort handler function

Configuration settings
System.abortFxn = Void(*)() System.abortStd;
 
DETAILS
This configuration parameter allows user to plug in their own abort function. By default abortStd which calls ANSI C Standard abort() is plugged in. Alternatively abortSpin can be plugged which loops infinitely.
C SYNOPSIS
 
config System.exitFxn  // module-wide

Exit handler function

Configuration settings
System.exitFxn = Void(*)(Int) System.exitStd;
 
DETAILS
This configuration parameter allows user to plug in their own exit function. By default exitStd which calls ANSI C Standard exit() is plugged in. Alternatively exitSpin can be plugged which loops infinitely.
C SYNOPSIS
 
config System.maxAtexitHandlers  // module-wide

Maximum number of dynamic atexit handlers allowed in the system

Configuration settings
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

Configuration settings
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

Configuration settings
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

Configuration settings
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 Tue, 14 Feb 2017 20:01:30 GMT