module xdc.runtime.Log
index URL

Event logging manager

RTSC modules and the application code generate Log_Event events by calling the Log module's functions. The Log module then passes those events to an ILogger instance assigned to the event originating module, specified by that module's configuration parameter common$.logger. ILogger instances handle events, usually converting events to Log_EventRec records prior to recording, transmitting, or displaying them. [ more ... ]
XDCspec summary sourced in xdc/runtime/Log.xdc
module Log {  ...
// inherits xdc.runtime.IModule
C synopsis target-domain
#include <xdc/runtime/Log.h>
module-wide constants & types
    #define Log_NUMARGS// Maximum number of arguments supported in Log events (Int)8
    #define Log_PRINTFID// The EventId for Log_print() events (Log_EventId)0
 
    typedef opaque Log_Event// Log event type;
    typedef Types_RopeId Log_EventId// Unique ID embedded in each Event;
 
    typedef struct Log_EventRec// The target representation of a recorded event {
        Types_Timestamp64 tstamp// time event was written;
        Bits32 serial// serial number of event;
        Types_Event evt// target encoding of an Event;
        IArg arg// arguments passed via Log_write/print[Log_NUMARGS];
    } Log_EventRec;
module-wide config parameters
    extern const Log_Event Log_L_construct// Lifecycle event posted when an instance is constructed;
    extern const Log_Event Log_L_create// Lifecycle event posted when an instance is created;
    extern const Log_Event Log_L_delete// Lifecycle event posted when an instance is deleted;
    extern const Log_Event Log_L_destruct// Lifecycle event posted when an instance is destructed;
module-wide functions
    Void Log_doPrint// Render an event as text via System_printf( Log_EventRec *evRec );
    macro Log_EventId Log_getEventId// Get event ID of the specified (encoded) event( Log_Event evt );
    macro Diags_Mask Log_getMask// Get the Diags mask for the specified (encoded) event( Log_Event evt );
    macro Void Log_print0// Generate a Log "print event" with 0 arguments( Diags_Mask mask, String fmt );
    macro Void Log_print1// Generate a Log "print event" with 1 argument( Diags_Mask mask, String fmt, IArg a1 );
    macro Void Log_print2// Generate a Log "print event" with 2 arguments( Diags_Mask mask, String fmt, IArg a1, IArg a2 );
    macro Void Log_print3// Generate a Log "print event" with 3 arguments( Diags_Mask mask, String fmt, IArg a1, IArg a2, IArg a3 );
    macro Void Log_print4// Generate a Log "print event" with 4 arguments( Diags_Mask mask, String fmt, IArg a1, IArg a2, IArg a3, IArg a4 );
    macro Void Log_print5// Generate a Log "print event" with 5 arguments( Diags_Mask mask, String fmt, IArg a1, IArg a2, IArg a3, IArg a4, IArg a5 );
    macro Void Log_print6// Generate a Log "print event" with 6 arguments( Diags_Mask mask, String fmt, IArg a1, IArg a2, IArg a3, IArg a4, IArg a5, IArg a6 );
    macro Void Log_put4// Unconditionally put the specified Types event( Types_Event evt, IArg a1, IArg a2, IArg a3, IArg a4 );
    macro Void Log_put8// Unconditionally put the specified Types event( Types_Event evt, IArg a1, IArg a2, IArg a3, IArg a4, IArg a5, IArg a6, IArg a7, IArg a8 );
    macro Void Log_write0// Generate a Log event with 0 arguments( Log_Event evt );
    macro Void Log_write1// Generate a Log event with 1 argument( Log_Event evt, IArg a1 );
    macro Void Log_write2// Generate a Log event with 2 arguments( Log_Event evt, IArg a1, IArg a2 );
    macro Void Log_write3// Generate a Log event with 3 arguments( Log_Event evt, IArg a1, IArg a2, IArg a3 );
    macro Void Log_write4// Generate a Log event with 4 arguments( Log_Event evt, IArg a1, IArg a2, IArg a3, IArg a4 );
    macro Void Log_write5// Generate a Log event with 5 arguments( Log_Event evt, IArg a1, IArg a2, IArg a3, IArg a4, IArg a5 );
    macro Void Log_write6// Generate a Log event with 6 arguments( Log_Event evt, IArg a1, IArg a2, IArg a3, IArg a4, IArg a5, IArg a6 );
    macro Void Log_write7// Generate a Log event with 7 arguments( Log_Event evt, IArg a1, IArg a2, IArg a3, IArg a4, IArg a5, IArg a6, IArg a7 );
    macro Void Log_write8// Generate a Log event with 8 arguments( Log_Event evt, IArg a1, IArg a2, IArg a3, IArg a4, IArg a5, IArg a6, IArg a7, IArg a8 );
module-wide built-ins
    Types_ModuleId Log_Module_id// Get this module's unique id( );
    Bool Log_Module_startupDone// Test if this module has completed startup( );
    IHeap_Handle Log_Module_heap// The heap from which this module allocates memory( );
    Bool Log_Module_hasMask// Test whether this module has a diagnostics mask( );
    Bits16 Log_Module_getMask// Returns the diagnostics mask for this module( );
    Void Log_Module_setMask// Set the diagnostics mask for this module( Bits16 mask );
 
XDCscript usage meta-domain
var Log = xdc.useModule('xdc.runtime.Log');
module-wide constants & types
    const Log.NUMARGS// Maximum number of arguments supported in Log events = 8;
    const Log.PRINTFID// The EventId for Log_print() events = 0;
 
    var obj = new Log.EventDesc// Log event descriptor;
        obj.mask// event enable mask = Bits16  ...
        obj.msg// event "printf" message format string = String  ...
 
    var obj = new Log.EventRec// The target representation of a recorded event;
        obj.tstamp// time event was written = Types.Timestamp64  ...
        obj.serial// serial number of event = Bits32  ...
        obj.evt// target encoding of an Event = Bits32  ...
        obj.arg// arguments passed via Log_write/print = IArg[Log.NUMARGS]  ...
module-wide config parameters
    Log.L_construct// Lifecycle event posted when an instance is constructed = Log.EventDesc {
        mask: Diags.LIFECYCLE,
        msg: "<-- construct: %p('%s')"
    };
    Log.L_create// Lifecycle event posted when an instance is created = Log.EventDesc {
        mask: Diags.LIFECYCLE,
        msg: "<-- create: %p('%s')"
    };
    Log.L_delete// Lifecycle event posted when an instance is deleted = Log.EventDesc {
        mask: Diags.LIFECYCLE,
        msg: "--> delete: (%p)"
    };
    Log.L_destruct// Lifecycle event posted when an instance is destructed = Log.EventDesc {
        mask: Diags.LIFECYCLE,
        msg: "--> destruct: (%p)"
    };
 
    Log.common$// Common module configuration parameters = Types.Common$ undefined;
 
XDCspec declarations sourced in xdc/runtime/Log.xdc
package xdc.runtime;
 
module Log {
module-wide constants & types
    const Int NUMARGS// Maximum number of arguments supported in Log events = 8;
    const Log.EventId PRINTFID// The EventId for Log_print() events = 0;
 
    @Encoded typedef Log.EventDesc Event// Log event type;
    typedef Types.RopeId EventId// Unique ID embedded in each Event;
 
    metaonly struct EventDesc// Log event descriptor {
        Diags.Mask mask// event enable mask;
        String msg// event "printf" message format string;
    };
 
    struct EventRec// The target representation of a recorded event {
        Types.Timestamp64 tstamp// time event was written;
        Bits32 serial// serial number of event;
        Types.Event evt// target encoding of an Event;
        IArg arg// arguments passed via Log_write/print[Log.NUMARGS];
    };
module-wide config parameters
    config Log.Event L_construct// Lifecycle event posted when an instance is constructed = {
        mask: Diags.LIFECYCLE,
        msg: "<-- construct: %p('%s')"
    };
    config Log.Event L_create// Lifecycle event posted when an instance is created = {
        mask: Diags.LIFECYCLE,
        msg: "<-- create: %p('%s')"
    };
    config Log.Event L_delete// Lifecycle event posted when an instance is deleted = {
        mask: Diags.LIFECYCLE,
        msg: "--> delete: (%p)"
    };
    config Log.Event L_destruct// Lifecycle event posted when an instance is destructed = {
        mask: Diags.LIFECYCLE,
        msg: "--> destruct: (%p)"
    };
 
    metaonly config Types.Common$ common$// Common module configuration parameters;
module-wide functions
    Void doPrint// Render an event as text via System_printf( Log.EventRec *evRec );
    @Macro Log.EventId getEventId// Get event ID of the specified (encoded) event( Log.Event evt );
    @Macro Diags.Mask getMask// Get the Diags mask for the specified (encoded) event( Log.Event evt );
    @Macro Void print0// Generate a Log "print event" with 0 arguments( Diags.Mask mask, String fmt );
    @Macro Void print1// Generate a Log "print event" with 1 argument( Diags.Mask mask, String fmt, IArg a1 );
    @Macro Void print2// Generate a Log "print event" with 2 arguments( Diags.Mask mask, String fmt, IArg a1, IArg a2 );
    @Macro Void print3// Generate a Log "print event" with 3 arguments( Diags.Mask mask, String fmt, IArg a1, IArg a2, IArg a3 );
    @Macro Void print4// Generate a Log "print event" with 4 arguments( Diags.Mask mask, String fmt, IArg a1, IArg a2, IArg a3, IArg a4 );
    @Macro Void print5// Generate a Log "print event" with 5 arguments( Diags.Mask mask, String fmt, IArg a1, IArg a2, IArg a3, IArg a4, IArg a5 );
    @Macro Void print6// Generate a Log "print event" with 6 arguments( Diags.Mask mask, String fmt, IArg a1, IArg a2, IArg a3, IArg a4, IArg a5, IArg a6 );
    @Macro Void put4// Unconditionally put the specified Types event( Types.Event evt, IArg a1, IArg a2, IArg a3, IArg a4 );
    @Macro Void put8// Unconditionally put the specified Types event( Types.Event evt, IArg a1, IArg a2, IArg a3, IArg a4, IArg a5, IArg a6, IArg a7, IArg a8 );
    @Macro Void write0// Generate a Log event with 0 arguments( Log.Event evt );
    @Macro Void write1// Generate a Log event with 1 argument( Log.Event evt, IArg a1 );
    @Macro Void write2// Generate a Log event with 2 arguments( Log.Event evt, IArg a1, IArg a2 );
    @Macro Void write3// Generate a Log event with 3 arguments( Log.Event evt, IArg a1, IArg a2, IArg a3 );
    @Macro Void write4// Generate a Log event with 4 arguments( Log.Event evt, IArg a1, IArg a2, IArg a3, IArg a4 );
    @Macro Void write5// Generate a Log event with 5 arguments( Log.Event evt, IArg a1, IArg a2, IArg a3, IArg a4, IArg a5 );
    @Macro Void write6// Generate a Log event with 6 arguments( Log.Event evt, IArg a1, IArg a2, IArg a3, IArg a4, IArg a5, IArg a6 );
    @Macro Void write7// Generate a Log event with 7 arguments( Log.Event evt, IArg a1, IArg a2, IArg a3, IArg a4, IArg a5, IArg a6, IArg a7 );
    @Macro Void write8// Generate a Log event with 8 arguments( Log.Event evt, IArg a1, IArg a2, IArg a3, IArg a4, IArg a5, IArg a6, IArg a7, IArg a8 );
}
DETAILS
RTSC modules and the application code generate Log_Event events by calling the Log module's functions. The Log module then passes those events to an ILogger instance assigned to the event originating module, specified by that module's configuration parameter common$.logger. ILogger instances handle events, usually converting events to Log_EventRec records prior to recording, transmitting, or displaying them.
All events generated by a target module are stored and displayed by an ILogger, for example, an instance of xdc.runtime.LoggerBuf or xdc.runtime.LoggerSys. However at runtime, modules generate events through this module, rather than invoking directly their ILoggers. By doing so, modules can be configured to use different ILogger implementations without any changes to their source code.
A logger instance can accept Log events from any module, but a module can put Log events to only one logger instance. There can be one or more logger instances in a system. All Log calls that are not in a module are controlled by the module xdc.runtime.Main. For example, top-level application code or any existing sources that simply call the Log or Assert methods implicitly use the logger associated with the Main module.
The generation of a Log event is controlled by a module's diagnostics mask, which is described in details in Diags. Each Log event is associated with a mask. Log events are generated only when a particular bit is set in both the Log event mask and the module's diagnostics mask. For example, a Log event mask with the USER1 bit set is generated only when the USER1 bit is also set in the module's diagnostics mask.
There are two ways to generate Log events:
  • LOG_write(), which is tailored for module writers and takes full advantage of the XDC configuration model. For example, the message string associated with the Log event need not be a part of the final application, significantly reducing the "footprint overhead" of embedding diagnostics in deployed systems. The Log_write[0-8]() functions allow up to 8 values to be passed to the logger. They expect the logger to handle any formatting. A Log event type allows you to specify the type of event.
  • LOG_print(), which is designed for arbitrary C code. The Log_print[0-6]() functions allow up to 6 values to be passed along with a printf-like format string to the logger. They handle printf-style formatting.
Both functions are controlled by the module's diagnostics mask. Their storage or output is defined by the logger that is assigned to the module that calls the Log methods or to the xdc.runtime.Main module if the caller is not part of a module.
The Log function call sites are implemented in such a way that an optimizer can completely eliminate Log code from the program if the Log functions have been permanently disabled at configuration time. If the Log functions are permanently turned on at configuration time, then the optimizer can eliminate all runtime conditional checking and simply invoke the Log functions directly. Runtime checking is performed only when the Log functions are configured to be runtime modifiable.
EXAMPLES
Example 1: The following example defines a Log event, uses that Log event in a module, and configures the program to generate the Log event. In this example, both USER1 and USER2 bits are set in the event mask. This means that if either bit is set in the module's diagnostics mask, then the Log event will be generated.
This is a part of the XDC specification file for the Mod module (Mod.xdc):
  import xdc.runtime.Diags;
  import xdc.runtime.Log;

  config Log.Event L_someEvent = {
      mask: Diags.USER1 | Diags.USER2,
      msg: "my log event message, arg1: 0x%x, arg2: 0x%x"
  };
This is a part of the C code implementation of the Mod module:
  #include <xdc/runtime/Log.h>
  UInt x, y;

  Log_write2(Mod_L_someEvent, (IArg)x, (IArg)y);
The following configuration script demonstrates how the application might control the Log statements embedded in the Mod module at configuration time. In this case, the configuration script arranges for the Log statements within the Mod module (shown above) to always generate events. Without these configuration statements, no Log events would be generated by this module.
This is part of the XDC configuration file for the application:
  var Diags = xdc.useModule('xdc.runtime.Diags');
  var Mod = xdc.useModule('my.pkg.Mod');
  Mod.common$.diags_USER1 = Diags.ALWAYS_ON;
Example 2: The following XDC configuration statements turn on enter and exit logging at configuration time for a module. Without any other changes in the runtime code, every time a module Mod's function is being called or exits, an event will be logged.
  var Diags = xdc.useModule('xdc.runtime.Diags');
  var Mod = xdc.useModule('my.pkg.Mod');

  Mod.common$.diags_ENTER = Diags.ALWAYS_ON;
  Mod.common$.diags_EXIT = Diags.ALWAYS_ON;
Example 3: The following example configures a module to support enter and exit logging, but defers the actual activation and deactivation of the logging until runtime. See the Diags_setMask() function for details on specifying the control string.
This is a part of the XDC configuration file for the application:
  var Diags = xdc.useModule('xdc.runtime.Diags');
  var Mod = xdc.useModule('my.pkg.Mod');

  Mod.common$.diags_ENTER = Diags.RUNTIME_OFF;
  Mod.common$.diags_EXIT = Diags.RUNTIME_OFF;
This is a part of the C code for the application:
  // turn on enter and exit logging in the module
  Diags_setMask("my.pkg.Mod+EX");

  // turn off enter and exit logging in the module
  Diags_setMask("my.pkg.Mod-EX");
 
const Log.NUMARGS
index URL

Maximum number of arguments supported in Log events

XDCscript usage meta-domain
const Log.NUMARGS = 8;
C synopsis target-domain
#define Log_NUMARGS (Int)8
 
 
const Log.PRINTFID
index URL

The EventId for Log_print() events

XDCscript usage meta-domain
const Log.PRINTFID = 0;
C synopsis target-domain
#define Log_PRINTFID (Log_EventId)0
 
 
typedef Log.Event
index URL

Log event type

C synopsis target-domain
typedef opaque Log_Event;
 
DETAILS
An Event is represented on the target as a 32-bit value that can be decoded offline to recover the Event information defined in a corresponding metaonly EventDesc. In addition, Events may be decoded at runtime via methods provided in this module; see getMask and getEventId.
When an event is "raised" a Types_Event is created which has the same event ID as the Log_Event but also encodes the module ID of the caller. This new event is passed to the underlying ILogger module along with any arguments associated with the event.
SEE
getMask, getEventId
 
typedef Log.EventId
index URL

Unique ID embedded in each Event

C synopsis target-domain
typedef Types_RopeId Log_EventId;
 
DETAILS
This ID must be used to compare two Events for equality. Event ids are not guaranteed to remain constant between different configurations of an application. For example, adding a module may cause the event ids of another module to change.
However, event ids declared by a module are guaranteed to be consecutive values starting from the first declared Log_Event and increasing to the last declared event. As a result, clients of a module can efficiently test ranges of events and modules can add new events, such as internal trace events, without breaking clients; simply be careful to add new events after any existing events in you module's .xdc specification.
SEE
getEventId, Event
 
metaonly struct Log.EventDesc
index URL

Log event descriptor

XDCscript usage meta-domain
var obj = new Log.EventDesc;
 
    obj.mask = Bits16  ...
    // event enable mask
    obj.msg = String  ...
    // event "printf" message format string
 
DETAILS
Each Log event is defined by a Log event descriptor.
The mask defines which bits in the module's diagnostics mask enable this Log event. Events "posted" via Log_write are only written to the underlying logger if one of the mask's bits matches the caller's module diagnostics settings (see xdc.runtime.Types.common$).
The msg defines a printf style format string that defines how to render the arguments passed along the event in a Log_write call. For a description of the allowable format strings see print6.
SEE
write8, print6
 
struct Log.EventRec
index URL

The target representation of a recorded event

XDCscript usage meta-domain
var obj = new Log.EventRec;
 
    obj.tstamp = Types.Timestamp64  ...
    // time event was written
    obj.serial = Bits32  ...
    // serial number of event
    obj.evt = Bits32  ...
    // target encoding of an Event
    obj.arg = IArg[Log.NUMARGS]  ...
    // arguments passed via Log_write/print
C synopsis target-domain
typedef struct Log_EventRec {
    Types_Timestamp64 tstamp;
    // time event was written
    Bits32 serial;
    // serial number of event
    Types_Event evt;
    // target encoding of an Event
    IArg arg[Log_NUMARGS];
    // arguments passed via Log_write/print
} Log_EventRec;
 
DETAILS
This structure defines how events are recorded on the target.
 
config Log.L_construct  // module-wide
index URL

Lifecycle event posted when an instance is constructed

XDCscript usage meta-domain
Log.L_construct = Log.EventDesc {
    mask: Diags.LIFECYCLE,
    msg: "<-- construct: %p('%s')"
};
C synopsis target-domain
extern const Log_Event Log_L_construct;
 
 
config Log.L_create  // module-wide
index URL

Lifecycle event posted when an instance is created

XDCscript usage meta-domain
Log.L_create = Log.EventDesc {
    mask: Diags.LIFECYCLE,
    msg: "<-- create: %p('%s')"
};
C synopsis target-domain
extern const Log_Event Log_L_create;
 
 
config Log.L_delete  // module-wide
index URL

Lifecycle event posted when an instance is deleted

XDCscript usage meta-domain
Log.L_delete = Log.EventDesc {
    mask: Diags.LIFECYCLE,
    msg: "--> delete: (%p)"
};
C synopsis target-domain
extern const Log_Event Log_L_delete;
 
 
config Log.L_destruct  // module-wide
index URL

Lifecycle event posted when an instance is destructed

XDCscript usage meta-domain
Log.L_destruct = Log.EventDesc {
    mask: Diags.LIFECYCLE,
    msg: "--> destruct: (%p)"
};
C synopsis target-domain
extern const Log_Event Log_L_destruct;
 
 
metaonly config Log.common$  // module-wide
index URL

Common module configuration parameters

XDCscript usage meta-domain
Log.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.
 
Log.doPrint( )  // module-wide
index URL

Render an event as text via System_printf

C synopsis target-domain
Void Log_doPrint( Log_EventRec *evRec );
 
ARGUMENTS
evRec — a nonNULL pointer to an initialized Log_EventRec structure to be formated via System_printf.
DETAILS
This method is not gated and may make more than one call to System_printf. This utility method is typically used within the implementation of a logger which initializes Log_EventRec structures based on Log events produced by the application.
 
Log.getEventId( )  // module-wide
index URL

Get event ID of the specified (encoded) event

C synopsis target-domain
macro Log_EventId Log_getEventId( Log_Event evt );
 
ARGUMENTS
evt — the Log event encoding a mask and event ID
DETAILS
This method is used to compare "known" Log events with "raised" Types_Event.
RETURNS
event ID of the specified event
SEE
Types.getEventId
 
Log.getMask( )  // module-wide
index URL

Get the Diags mask for the specified (encoded) event

C synopsis target-domain
macro Diags_Mask Log_getMask( Log_Event evt );
 
ARGUMENTS
evt — the Log event encoding a mask and event ID
RETURNS
Diags mask for the specified event
 
Log.print0( )  // module-wide
index URL

Generate a Log "print event" with 0 arguments

C synopsis target-domain
macro Void Log_print0( Diags_Mask mask, String fmt );
 
SEE
print6
 
Log.print1( )  // module-wide
index URL

Generate a Log "print event" with 1 argument

C synopsis target-domain
macro Void Log_print1( Diags_Mask mask, String fmt, IArg a1 );
 
SEE
print6
 
Log.print2( )  // module-wide
index URL

Generate a Log "print event" with 2 arguments

C synopsis target-domain
macro Void Log_print2( Diags_Mask mask, String fmt, IArg a1, IArg a2 );
 
SEE
print6
 
Log.print3( )  // module-wide
index URL

Generate a Log "print event" with 3 arguments

C synopsis target-domain
macro Void Log_print3( Diags_Mask mask, String fmt, IArg a1, IArg a2, IArg a3 );
 
SEE
print6
 
Log.print4( )  // module-wide
index URL

Generate a Log "print event" with 4 arguments

C synopsis target-domain
macro Void Log_print4( Diags_Mask mask, String fmt, IArg a1, IArg a2, IArg a3, IArg a4 );
 
SEE
print6
 
Log.print5( )  // module-wide
index URL

Generate a Log "print event" with 5 arguments

C synopsis target-domain
macro Void Log_print5( Diags_Mask mask, String fmt, IArg a1, IArg a2, IArg a3, IArg a4, IArg a5 );
 
SEE
print6
 
Log.print6( )  // module-wide
index URL

Generate a Log "print event" with 6 arguments

C synopsis target-domain
macro Void Log_print6( Diags_Mask mask, String fmt, IArg a1, IArg a2, IArg a3, IArg a4, IArg a5, IArg a6 );
 
ARGUMENTS
mask — enable bits for this Log event
fmt — a printf style format string
a1 — value for first format conversion character
a2 — value for second format conversion character
a3 — value for third format conversion character
a4 — value for fourth format conversion character
a5 — value for fifth format conversion character
a6 — value for sixth format conversion character
DETAILS
As a convenience to C (as well as assembly language) programmers, the Log module provides a variation of the ever-popular printf function. The print[0-6] functions generate a Log "print event" and route it to the current module's logger.
The arguments passed to print[0-6] may be characters, integers, strings, or pointers. However, because the declared type of the arguments is IArg, all pointer arguments must be cast to an IArg type. IArg is an integral type large enough to hold any pointer or an int. So, casting a pointer to an IArg does not cause any loss of information and C's normal integer conversions make the cast unnecessary for integral arguments.
The format string can use the following conversion characters. However, it is important to recall that all arguments referenced by these conversion characters have been converted to an IArg prior to conversion; so, the use of "length modifiers" should be avoided.
  Conversion Character    Description
  ------------------------------------------------
  %c                      Character
  %d                      Signed integer
  %u                      Unsigned integer
  %x                      Unsigned hexadecimal integer
  %o                      Unsigned octal integer
  %s                      Character string
  %p                      Pointer
  %f                      Single precision floating point (float)
Format strings, while very convenient, are a well known source of portability problems: each format specification must precisely match the types of the arguments passed. Underlying "printf" functions use the format string to determine how far to advance through their argument list. For targets where pointer types and integers are the same size there are no problems. However, suppose a target's pointer type is larger than its integer type. In this case, because integer arguments are widened to be of type IArg, a format specification of "%d" causes an underlying printf() implementation to read the extended part of the integer argument as part of the next argument(!).
To get around this problem and still allow the use of "natural" format specifications (e.g., %d and %x with optional width specifications), System.aprintf() is used which assumes that all arguments have been widened to be of type IArg.
See System.printf for complete details.
The %f format specifier is used to print a single precision float value. Note that %f assumes that sizeof(Float) <= sizeof(IArg). Most clients that interpret float values except that they are represented in IEEE 754 floating point format. Therefore, it is recommended that the float values are converted into that format prior to supplying the values to Log functions in cases where targets do not generate the float values in IEEE 754 floating point format by default.
EXAMPLES
The following example demonstrates a typical usage.
  String  list[];
  UInt    i;

  Log_print2(Diags_USER2, "list[%u] = %s\n", i, (IArg)list[i]);
Note that the IArg cast above is only necessary for pointer arguments; C's normal parameter conversions implicitly convert integral arguments.
 
Log.put4( )  // module-wide
index URL

Unconditionally put the specified Types event

C synopsis target-domain
macro Void Log_put4( Types_Event evt, IArg a1, IArg a2, IArg a3, IArg a4 );
 
ARGUMENTS
evt — the Types event to put into the log
a1 — value for first format conversion character
a2 — value for second format conversion character
a3 — value for third format conversion character
a4 — value for fourth format conversion character
DETAILS
This method unconditionally puts the specified Types.Event evt into the log. This type of event is created either implicitly (and passed to an ILogger implementation) or explicitly via Types.makeEvent().
SEE
put8
 
Log.put8( )  // module-wide
index URL

Unconditionally put the specified Types event

C synopsis target-domain
macro Void Log_put8( Types_Event evt, IArg a1, IArg a2, IArg a3, IArg a4, IArg a5, IArg a6, IArg a7, IArg a8 );
 
DETAILS
This method is identical to put4 except that it allows up to eight arguments to be passed.
SEE
put4
 
Log.write0( )  // module-wide
index URL

Generate a Log event with 0 arguments

C synopsis target-domain
macro Void Log_write0( Log_Event evt );
 
SEE
write8
 
Log.write1( )  // module-wide
index URL

Generate a Log event with 1 argument

C synopsis target-domain
macro Void Log_write1( Log_Event evt, IArg a1 );
 
SEE
write8
 
Log.write2( )  // module-wide
index URL

Generate a Log event with 2 arguments

C synopsis target-domain
macro Void Log_write2( Log_Event evt, IArg a1, IArg a2 );
 
SEE
write8
 
Log.write3( )  // module-wide
index URL

Generate a Log event with 3 arguments

C synopsis target-domain
macro Void Log_write3( Log_Event evt, IArg a1, IArg a2, IArg a3 );
 
SEE
write8
 
Log.write4( )  // module-wide
index URL

Generate a Log event with 4 arguments

C synopsis target-domain
macro Void Log_write4( Log_Event evt, IArg a1, IArg a2, IArg a3, IArg a4 );
 
SEE
write8
 
Log.write5( )  // module-wide
index URL

Generate a Log event with 5 arguments

C synopsis target-domain
macro Void Log_write5( Log_Event evt, IArg a1, IArg a2, IArg a3, IArg a4, IArg a5 );
 
SEE
write8
 
Log.write6( )  // module-wide
index URL

Generate a Log event with 6 arguments

C synopsis target-domain
macro Void Log_write6( Log_Event evt, IArg a1, IArg a2, IArg a3, IArg a4, IArg a5, IArg a6 );
 
SEE
write8
 
Log.write7( )  // module-wide
index URL

Generate a Log event with 7 arguments

C synopsis target-domain
macro Void Log_write7( Log_Event evt, IArg a1, IArg a2, IArg a3, IArg a4, IArg a5, IArg a6, IArg a7 );
 
SEE
write8
 
Log.write8( )  // module-wide
index URL

Generate a Log event with 8 arguments

C synopsis target-domain
macro Void Log_write8( Log_Event evt, IArg a1, IArg a2, IArg a3, IArg a4, IArg a5, IArg a6, IArg a7, IArg a8 );
 
ARGUMENTS
evt — the Log event to write
a1 — value for first format conversion character
a2 — value for second format conversion character
a3 — value for third format conversion character
a4 — value for fourth format conversion character
a5 — value for fifth format conversion character
a6 — value for sixth format conversion character
a7 — value for seventh format conversion character
a8 — value for eighth format conversion character
DETAILS
If the mask in the specified Log event has any bit set which is also set in the current module's diagnostics mask, then this call to write will "raise" the given Log event.
 
module-wide built-ins
index URL

C synopsis target-domain
Types_ModuleId Log_Module_id( );
// Get this module's unique id
 
Bool Log_Module_startupDone( );
// Test if this module has completed startup
 
IHeap_Handle Log_Module_heap( );
// The heap from which this module allocates memory
 
Bool Log_Module_hasMask( );
// Test whether this module has a diagnostics mask
 
Bits16 Log_Module_getMask( );
// Returns the diagnostics mask for this module
 
Void Log_Module_setMask( Bits16 mask );
// Set the diagnostics mask for this module
generated on Tue, 01 Sep 2009 00:36:16 GMT