module xdc.runtime.Log

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 ... ]
C synopsis target-domain sourced in xdc/runtime/Log.xdc
#include <xdc/runtime/Log.h>
Functions
Void 
macro Void 
macro Void 
macro Void 
macro Void 
Log_error3// Generate a Log "error event" with 3 arguments(CString fmt, IArg a1, IArg a2, IArg a3);
macro Void 
Log_error4// Generate a Log "error event" with 4 arguments(CString fmt, IArg a1, IArg a2, IArg a3, IArg a4);
macro Void 
Log_error5// Generate a Log "error event" with 5 arguments(CString fmt, IArg a1, IArg a2, IArg a3, IArg a4, IArg a5);
macro Log_EventId 
macro Diags_Mask 
macro Void 
macro Void 
macro Void 
macro Void 
Log_info3// Generate a Log "info event" with 3 arguments(CString fmt, IArg a1, IArg a2, IArg a3);
macro Void 
Log_info4// Generate a Log "info event" with 4 arguments(CString fmt, IArg a1, IArg a2, IArg a3, IArg a4);
macro Void 
Log_info5// Generate a Log "info event" with 5 arguments(CString fmt, IArg a1, IArg a2, IArg a3, IArg a4, IArg a5);
macro Void 
macro Void 
macro Void 
macro Void 
Log_print3// Generate a Log "print event" with 3 arguments(Diags_Mask mask, CString fmt, IArg a1, IArg a2, IArg a3);
macro Void 
Log_print4// Generate a Log "print event" with 4 arguments(Diags_Mask mask, CString fmt, IArg a1, IArg a2, IArg a3, IArg a4);
macro Void 
Log_print5// Generate a Log "print event" with 5 arguments(Diags_Mask mask, CString 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, CString fmt, IArg a1, IArg a2, IArg a3, IArg a4, IArg a5, IArg a6);
macro Void 
macro Void 
macro Void 
macro Void 
macro Void 
Log_put8// Unconditionally put the specified Log event and 8 arguments(Log_Event evt, Types_ModuleId mid, IArg a1, IArg a2, IArg a3, IArg a4, IArg a5, IArg a6, IArg a7, IArg a8);
macro Void 
macro Void 
macro Void 
macro Void 
Log_warning3// Generate a Log "warning event" with 3 arguments(CString fmt, IArg a1, IArg a2, IArg a3);
macro Void 
Log_warning4// Generate a Log "warning event" with 4 arguments(CString fmt, IArg a1, IArg a2, IArg a3, IArg a4);
macro Void 
Log_warning5// Generate a Log "warning event" with 5 arguments(CString fmt, IArg a1, IArg a2, IArg a3, IArg a4, IArg a5);
macro Void 
macro Void 
macro Void 
macro Void 
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);
Functions common to all target modules
Defines
#define
#define
Typedefs
typedef opaque
typedef Types_RopeId 
typedef struct
Constants
extern const Log_Event 
extern const Log_Event 
extern const Log_Event 
extern const Log_Event 
extern const Log_Event 
extern const Log_Event 
extern const Log_Event 
 
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, examples of which are instances of xdc.runtime.LoggerBuf or xdc.runtime.LoggerSys. 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.
The Log calls can also be completely removed by defining the symbol xdc_runtime_Log_DISABLE_ALL. This can be done on the compile line, e.g. -Dxdc_runtime_Log_DISABLE_ALL. This will completely remove the Log statements from any code compiled with this flag, regardless of the application's logging configuration or your compiler's optimization settings.
It is also possible to remove all logging except for Log_error, Log_warning, or Log_info statements. This is done by first defining xdc_runtime_Log_DISABLE_ALL, followed by defining one or more of the symbols below to leave that type of logging enabled:
  • xdc_runtime_Log_ENABLE_ERROR
  • xdc_runtime_Log_ENABLE_WARNING
  • xdc_runtime_Log_ENABLE_INFO
For example, to disable all Log statements except for Log_error, add the following to the compile line:
      -Dxdc_runtime_Log_DISABLE_ALL -Dxdc_runtime_Log_ENABLE_ERROR
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,
      level: Diags.LEVEL1,
      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 LoggerSys = xdc.useModule('xdc.runtime.LoggerSys');
  var Mod = xdc.useModule('my.pkg.Mod');
  Mod.common$.diags_USER1 = Diags.ALWAYS_ON;
  Mod.common$.logger = LoggerSys.create();

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

Maximum number of arguments supported in Log events

C synopsis target-domain
#define Log_NUMARGS (Int)8
 
 
const Log_PRINTFID

The EventId for Log_print() events

C synopsis target-domain
#define Log_PRINTFID (Log_EventId)0
 
 
typedef Log_Event

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
 
typedef Log_EventId

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
 
struct Log_EventRec

The target representation of a recorded event

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

Lifecycle event posted when an instance is constructed

C synopsis target-domain
extern const Log_Event Log_L_construct;
 
 
config Log_L_create  // module-wide

Lifecycle event posted when an instance is created

C synopsis target-domain
extern const Log_Event Log_L_create;
 
 
config Log_L_delete  // module-wide

Lifecycle event posted when an instance is deleted

C synopsis target-domain
extern const Log_Event Log_L_delete;
 
 
config Log_L_destruct  // module-wide

Lifecycle event posted when an instance is destructed

C synopsis target-domain
extern const Log_Event Log_L_destruct;
 
 
config Log_L_error  // module-wide

Error event posted by Log_errorX API

C synopsis target-domain
extern const Log_Event Log_L_error;
 
DETAILS
This event is marked as a STATUS event and given the priority level of ERROR.
This event prints the Log call site (%$F) and a format string (%$S) which is recursively formatted with any additional arguments.
 
config Log_L_info  // module-wide

Info event posted by Log_infoX API

C synopsis target-domain
extern const Log_Event Log_L_info;
 
DETAILS
This event is marked as an INFO event. The event priority is not specified in the event definition. Rather, it is specified as an argument to the Log_infoX APIs.
This event prints the Log call site (%$F) and a format string (%$S) which is recursively formatted with any addition arguments.
 
config Log_L_warning  // module-wide

Warning event posted by Log_warningX API

C synopsis target-domain
extern const Log_Event Log_L_warning;
 
DETAILS
This event is marked as a STATUS event and given the priority level of WARNING.
This event prints the Log call site (%$F) and a format string (%$S) which is recursively formatted with any addition arguments.
 
Log_doPrint()  // module-wide

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_error0()  // module-wide

Generate a Log "error event" with 0 arguments

C synopsis target-domain
macro Void Log_error0(CString fmt);
 
SEE
 
Log_error1()  // module-wide

Generate a Log "error event" with 1 argument

C synopsis target-domain
macro Void Log_error1(CString fmt, IArg a1);
 
SEE
 
Log_error2()  // module-wide

Generate a Log "error event" with 2 arguments

C synopsis target-domain
macro Void Log_error2(CString fmt, IArg a1, IArg a2);
 
SEE
 
Log_error3()  // module-wide

Generate a Log "error event" with 3 arguments

C synopsis target-domain
macro Void Log_error3(CString fmt, IArg a1, IArg a2, IArg a3);
 
SEE
 
Log_error4()  // module-wide

Generate a Log "error event" with 4 arguments

C synopsis target-domain
macro Void Log_error4(CString fmt, IArg a1, IArg a2, IArg a3, IArg a4);
 
SEE
 
Log_error5()  // module-wide

Generate a Log "error event" with 5 arguments

C synopsis target-domain
macro Void Log_error5(CString fmt, IArg a1, IArg a2, IArg a3, IArg a4, IArg a5);
 
ARGUMENTS
fmt — a reference to a constant error string / fmt string
a1 — value for an additional parameter (e.g. an error code)
a2 — value for an additional parameter
a3 — value for an additional parameter
a4 — value for an additional parameter
a5 — value for an additional parameter
DETAILS
The Log_error APIs are intended to allow users to easily log error events in their code. Similar to the Log_print APIs, Log_error does not require that you define an event. You simply pass an informative error string which can optionally be formatted with additional arguments. The error is logged with the predefined event L_error.
Log_error prepends a string to the message which identifies it as an ERROR and specifies the filename and line number of the Log_error call site. A simple example:
  Log_error0("Invalid argument");
This event will be formatted as (assuming that the above call was line 35 of "MyCode.c")
  ERROR at "MyCode.c", line 35: Invalid argument
Users may provide additional information in the error event, such as a predefined error code or details of the error. These additional values will be used to format the string passed to Log_error.
Log_error does not use a variable length argument list--you must call the appropriate Log_errorX API based on the number of arguments.
SEE
EXAMPLES
The following example demonstrates a typical usage.
  Int myArg;

  Log_error1("Invalid argument: %d", myArg);
The above event is formatted as, for example:
  ERROR: "MyCode.c", line 35: Invalid argument: -1
 
Log_getEventId()  // module-wide

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
 
Log_getMask()  // module-wide

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_info0()  // module-wide

Generate a Log "info event" with 0 arguments

C synopsis target-domain
macro Void Log_info0(CString fmt);
 
SEE
 
Log_info1()  // module-wide

Generate a Log "info event" with 1 argument

C synopsis target-domain
macro Void Log_info1(CString fmt, IArg a1);
 
SEE
 
Log_info2()  // module-wide

Generate a Log "info event" with 2 arguments

C synopsis target-domain
macro Void Log_info2(CString fmt, IArg a1, IArg a2);
 
SEE
 
Log_info3()  // module-wide

Generate a Log "info event" with 3 arguments

C synopsis target-domain
macro Void Log_info3(CString fmt, IArg a1, IArg a2, IArg a3);
 
SEE
 
Log_info4()  // module-wide

Generate a Log "info event" with 4 arguments

C synopsis target-domain
macro Void Log_info4(CString fmt, IArg a1, IArg a2, IArg a3, IArg a4);
 
SEE
 
Log_info5()  // module-wide

Generate a Log "info event" with 5 arguments

C synopsis target-domain
macro Void Log_info5(CString fmt, IArg a1, IArg a2, IArg a3, IArg a4, IArg a5);
 
ARGUMENTS
fmt — reference to a constant event string / fmt string
a1 — value for an additional parameter (e.g. an event code)
a2 — value for an additional parameter
a3 — value for an additional parameter
a4 — value for an additional parameter
a5 — value for an additional parameter
DETAILS
The Log_info APIs are provided for easily logging generic "informational" events with call site information. They are similar to the Log_print APIs in that they do not require you to define an event-- you simply pass an informative printf-style string which can optionally be formatted with additional arguments. The info record is logged with the predefined event 'L_info'.
The Log_info APIs log the L_info event which uses the 'INFO' diags category. They do not allow you to specify an event priority.
Log_info prepends the filename and line number of the call site to the message.
EXAMPLES
The following example demonstrates a typical usage.
  Int load;

  Log_info1("Current load: %d", load);
The above event is formatted as, for example:
  "MyCode.c", line 15: Current load: 25
 
Log_print0()  // module-wide

Generate a Log "print event" with 0 arguments

C synopsis target-domain
macro Void Log_print0(Diags_Mask mask, CString fmt);
 
SEE
 
Log_print1()  // module-wide

Generate a Log "print event" with 1 argument

C synopsis target-domain
macro Void Log_print1(Diags_Mask mask, CString fmt, IArg a1);
 
SEE
 
Log_print2()  // module-wide

Generate a Log "print event" with 2 arguments

C synopsis target-domain
macro Void Log_print2(Diags_Mask mask, CString fmt, IArg a1, IArg a2);
 
SEE
 
Log_print3()  // module-wide

Generate a Log "print event" with 3 arguments

C synopsis target-domain
macro Void Log_print3(Diags_Mask mask, CString fmt, IArg a1, IArg a2, IArg a3);
 
SEE
 
Log_print4()  // module-wide

Generate a Log "print event" with 4 arguments

C synopsis target-domain
macro Void Log_print4(Diags_Mask mask, CString fmt, IArg a1, IArg a2, IArg a3, IArg a4);
 
SEE
 
Log_print5()  // module-wide

Generate a Log "print event" with 5 arguments

C synopsis target-domain
macro Void Log_print5(Diags_Mask mask, CString fmt, IArg a1, IArg a2, IArg a3, IArg a4, IArg a5);
 
SEE
 
Log_print6()  // module-wide

Generate a Log "print event" with 6 arguments

C synopsis target-domain
macro Void Log_print6(Diags_Mask mask, CString fmt, IArg a1, IArg a2, IArg a3, IArg a4, IArg a5, IArg a6);
 
ARGUMENTS
mask — enable bits and optional detail level for this 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 expect that they are represented in IEEE 754 floating point format. Therefore, it is recommended that the float values be 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.
The first argument to a Log_print call is the diags category to be associated with the event.
It is also possible to associate an event level with the event to enable filtering of events based on event level. Conceptually, it is best to regard the event level as completely separate from the event's diags category; however, the priority value actually occupies a part of the diags mask. For this reason, it is possible to specify an event level by OR'ing the level with the diags mask. For example, to print an Diags_INFO event of Diags_LEVEL2, you'd simply write: (Diags_INFO | Diags_LEVEL2)
Specifying an event level is optional. Log_print calls which do not specify a level will receive the highest priority 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.
To simplify the conversion from float arguments to IArg, the standard header xdc/std.h provides a macro, named floatToArg(), to do this conversion in a type safe manner. So, the following statement will print "float = 2.3456":
    Log_print1(Diags_USER1, "float = %f", floatToArg(2.34567));
Note that, if you are formatting events on the target, you must also add support for floating point to ASCII conversion to System.printf; for more information, see the System.extendedFormats reference documenation. For example:
      var System = xdc.useModule('xdc.runtime.System');
      System.extendedFormats = "%f";
 
Log_put0()  // module-wide

Unconditionally put the specified Log event with 0 arguments

C synopsis target-domain
macro Void Log_put0(Log_Event evt, Types_ModuleId mid);
 
SEE
 
Log_put1()  // module-wide

Unconditionally put the specified Log event and 1 argument

C synopsis target-domain
macro Void Log_put1(Log_Event evt, Types_ModuleId mid, IArg a1);
 
SEE
 
Log_put2()  // module-wide

Unconditionally put the specified Log event and 2 arguments

C synopsis target-domain
macro Void Log_put2(Log_Event evt, Types_ModuleId mid, IArg a1, IArg a2);
 
SEE
 
Log_put4()  // module-wide

Unconditionally put the specified Log event and 4 arguments

C synopsis target-domain
macro Void Log_put4(Log_Event evt, Types_ModuleId mid, IArg a1, IArg a2, IArg a3, IArg a4);
 
SEE
 
Log_put8()  // module-wide

Unconditionally put the specified Log event and 8 arguments

C synopsis target-domain
macro Void Log_put8(Log_Event evt, Types_ModuleId mid, IArg a1, IArg a2, IArg a3, IArg a4, IArg a5, IArg a6, IArg a7, IArg a8);
 
ARGUMENTS
evt — the Log event to put into the log
mid — module ID of the module putting the event
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
This method unconditionally puts the specified Event evt into the log. The Types.ModuleId mid should be the module ID of the module which is putting the event.
 
Log_warning0()  // module-wide

Generate a Log "warning event" with 0 arguments

C synopsis target-domain
macro Void Log_warning0(CString fmt);
 
SEE
 
Log_warning1()  // module-wide

Generate a Log "warning event" with 1 argument

C synopsis target-domain
macro Void Log_warning1(CString fmt, IArg a1);
 
SEE
 
Log_warning2()  // module-wide

Generate a Log "warning event" with 2 arguments

C synopsis target-domain
macro Void Log_warning2(CString fmt, IArg a1, IArg a2);
 
SEE
 
Log_warning3()  // module-wide

Generate a Log "warning event" with 3 arguments

C synopsis target-domain
macro Void Log_warning3(CString fmt, IArg a1, IArg a2, IArg a3);
 
SEE
 
Log_warning4()  // module-wide

Generate a Log "warning event" with 4 arguments

C synopsis target-domain
macro Void Log_warning4(CString fmt, IArg a1, IArg a2, IArg a3, IArg a4);
 
SEE
 
Log_warning5()  // module-wide

Generate a Log "warning event" with 5 arguments

C synopsis target-domain
macro Void Log_warning5(CString fmt, IArg a1, IArg a2, IArg a3, IArg a4, IArg a5);
 
ARGUMENTS
fmt — reference to a constant warning string / fmt string
a1 — value for an additional parameter (e.g. a warning code)
a2 — value for an additional parameter
a3 — value for an additional parameter
a4 — value for an additional parameter
a5 — value for an additional parameter
DETAILS
The Log_warning APIs provide the same features as the Log_error APIs, but are used to specifically log "warning" events.
The Log_warning APIs are equivalent to the Log_error APIs except that they use the predefined L_warning event. Log_warning prepends a string to the message which identifies it as a WARNING and specifies the filename and line number of the Log_warning call site.
SEE
EXAMPLES
The following example demonstrates a typical usage.
  Int myArg;

  Log_warning1("Value may be too high: %d", myArg);
The above event is formatted as:
  WARNING: "MyCode.c", line 50: Value may be too high: 4096
 
Log_write0()  // module-wide

Generate a Log event with 0 arguments

C synopsis target-domain
macro Void Log_write0(Log_Event evt);
 
SEE
 
Log_write1()  // module-wide

Generate a Log event with 1 argument

C synopsis target-domain
macro Void Log_write1(Log_Event evt, IArg a1);
 
SEE
 
Log_write2()  // module-wide

Generate a Log event with 2 arguments

C synopsis target-domain
macro Void Log_write2(Log_Event evt, IArg a1, IArg a2);
 
SEE
 
Log_write3()  // module-wide

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
 
Log_write4()  // module-wide

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
 
Log_write5()  // module-wide

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
 
Log_write6()  // module-wide

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
 
Log_write7()  // module-wide

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
 
Log_write8()  // module-wide

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

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
 
Configuration settings sourced in xdc/runtime/Log.xdc
var Log = xdc.useModule('xdc.runtime.Log');
module-wide constants & types
 
    var obj = new Log.EventDesc// Log event descriptor;
        obj.mask// event enable mask = Bits16  ...
        obj.msg// event "printf" message format string = String  ...
 
        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
        mask: Diags.LIFECYCLE,
        msg: "<-- construct: %p('%s')"
    };
        mask: Diags.LIFECYCLE,
        msg: "<-- create: %p('%s')"
    };
        mask: Diags.LIFECYCLE,
        msg: "--> delete: (%p)"
    };
        mask: Diags.LIFECYCLE,
        msg: "--> destruct: (%p)"
    };
        mask: Diags.STATUS,
        level: Diags.ERROR,
        msg: "ERROR: %$F%$S"
    };
        mask: Diags.INFO,
        msg: "%$F%$S"
    };
        mask: Diags.STATUS,
        level: Diags.WARNING,
        msg: "WARNING: %$F%$S"
    };
 
 
 
const Log.NUMARGS

Maximum number of arguments supported in Log events

Configuration settings
const Log.NUMARGS = 8;
 
C SYNOPSIS
 
const Log.PRINTFID

The EventId for Log_print() events

Configuration settings
const Log.PRINTFID = 0;
 
C SYNOPSIS
 
metaonly struct Log.EventDesc

Log event descriptor

Configuration settings
var obj = new Log.EventDesc;
 
    obj.mask = Bits16  ...
    // event enable mask
    obj.level = Diags.EventLevel  ...
    // event level relative to other events
    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 'level' defines the event level of the event. While the diags bits selected in the 'mask' signify the "category" of the event (e.g. Entry/Exit, Analysis, Info), the 'level' field allows you to assign a "priority" or "detail level" to the event relative to other events in that category. There are four event levels defined by 'xdc.runtime.Diags.EventLevel'.
Filtering of events by level is handled by the ILogger implementation. ILogger implementations which also implement the IFilterLogger interface support filtering of events based on priority level.
Specifying an event level is optional. Events that don't specify a level will receive Diags.LEVEL1 by default, making them the highest priority and ensuring that they will not inadvertently be filtered out by level-based filtering.
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
 
struct Log.EventRec

The target representation of a recorded event

Configuration settings
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
 
DETAILS
This structure defines how events are recorded on the target.
C SYNOPSIS
 
config Log.L_construct  // module-wide

Lifecycle event posted when an instance is constructed

Configuration settings
Log.L_construct = Log.EventDesc {
    mask: Diags.LIFECYCLE,
    msg: "<-- construct: %p('%s')"
};
 
C SYNOPSIS
 
config Log.L_create  // module-wide

Lifecycle event posted when an instance is created

Configuration settings
Log.L_create = Log.EventDesc {
    mask: Diags.LIFECYCLE,
    msg: "<-- create: %p('%s')"
};
 
C SYNOPSIS
 
config Log.L_delete  // module-wide

Lifecycle event posted when an instance is deleted

Configuration settings
Log.L_delete = Log.EventDesc {
    mask: Diags.LIFECYCLE,
    msg: "--> delete: (%p)"
};
 
C SYNOPSIS
 
config Log.L_destruct  // module-wide

Lifecycle event posted when an instance is destructed

Configuration settings
Log.L_destruct = Log.EventDesc {
    mask: Diags.LIFECYCLE,
    msg: "--> destruct: (%p)"
};
 
C SYNOPSIS
 
config Log.L_error  // module-wide

Error event posted by Log_errorX API

Configuration settings
Log.L_error = Log.EventDesc {
    mask: Diags.STATUS,
    level: Diags.ERROR,
    msg: "ERROR: %$F%$S"
};
 
DETAILS
This event is marked as a STATUS event and given the priority level of ERROR.
This event prints the Log call site (%$F) and a format string (%$S) which is recursively formatted with any additional arguments.
C SYNOPSIS
 
config Log.L_info  // module-wide

Info event posted by Log_infoX API

Configuration settings
Log.L_info = Log.EventDesc {
    mask: Diags.INFO,
    msg: "%$F%$S"
};
 
DETAILS
This event is marked as an INFO event. The event priority is not specified in the event definition. Rather, it is specified as an argument to the Log_infoX APIs.
This event prints the Log call site (%$F) and a format string (%$S) which is recursively formatted with any addition arguments.
C SYNOPSIS
 
config Log.L_warning  // module-wide

Warning event posted by Log_warningX API

Configuration settings
Log.L_warning = Log.EventDesc {
    mask: Diags.STATUS,
    level: Diags.WARNING,
    msg: "WARNING: %$F%$S"
};
 
DETAILS
This event is marked as a STATUS event and given the priority level of WARNING.
This event prints the Log call site (%$F) and a format string (%$S) which is recursively formatted with any addition arguments.
C SYNOPSIS
 
metaonly config Log.common$  // module-wide

Common module configuration parameters

Configuration settings
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.
generated on Thu, 25 May 2017 22:12:13 GMT