module xdc.runtime.LoggerBuf

A logger which stores Log events in a buffer

C synopsis
XDCscript usage
XDCspec declarations
Individual elements
Additional documentation
DETAILS
EXAMPLES

This module provides a logger which captures Log events to a buffer in realtime. The Log events stored in the buffer are unformatted; Log event formatting is deferred until some client reads the raw event data from the buffer. You can use LoggerBuf_flush() to process the Log events stored in the buffer and stream the formatted output to stdout (via System.printf). Alternatively, you can read a raw event (via getNextEntry) and send it to another client that has the resources to format the event for display. [ more ... ]

XDCspec summary sourced in xdc/runtime/LoggerBuf.xdc

@Gated @ModuleStartup

module LoggerBuf { ...

// inherits xdc.runtime.ILogger

// inherits xdc.runtime.IModule

instance: ...

C synopsis target-domain

#include <xdc/runtime/LoggerBuf.h>

module-wide constants & types

typedef enum LoggerBuf_BufType// Type of log buffer {

LoggerBuf_BufType_CIRCULAR// The log buffer wraps, overwriting old entries,

LoggerBuf_BufType_FIXED// The log buffer halts collection when full

} LoggerBuf_BufType;

module-wide config parameters

extern const Bool LoggerBuf_enableFlush// Flush all logs at system exit;

module-wide functions

Void LoggerBuf_flushAll// Flush logs of all instances of LoggerBuf( );

module-wide built-ins

Types_ModuleId LoggerBuf_Module_id// Get this module's unique id( );

Bool LoggerBuf_Module_startupDone// Test if this module has completed startup( );

IHeap_Handle LoggerBuf_Module_heap// The heap from which this module allocates memory( );

Bool LoggerBuf_Module_hasMask// Test whether this module has a diagnostics mask( );

Bits16 LoggerBuf_Module_getMask// Returns the diagnostics mask for this module( );

Void LoggerBuf_Module_setMask// Set the diagnostics mask for this module( Bits16 mask );

per-instance object types

typedef struct LoggerBuf_Object// Opaque internal representation of an instance object LoggerBuf_Object;

typedef LoggerBuf_Object *LoggerBuf_Handle// Client reference to an instance object;

typedef struct LoggerBuf_Struct// Opaque client structure large enough to hold an instance object LoggerBuf_Struct;

LoggerBuf_Handle LoggerBuf_handle// Convert this instance structure pointer into an instance handle( LoggerBuf_Struct *structP );

LoggerBuf_Struct *LoggerBuf_struct// Convert this instance handle into an instance structure pointer( LoggerBuf_Handle handle );

per-instance config parameters

typedef struct LoggerBuf_Params// Instance config-params structure {

IInstance_Params *instance;

IHeap_Handle bufHeap// The heap that contains the Log buffer for dynamic instances;

LoggerBuf_BufType bufType// Log buffer type;

Bool exitFlush// Flush log at system exit;

Int numEntries// Number of entries in buffer;

} LoggerBuf_Params;

Void LoggerBuf_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation( LoggerBuf_Params *params );

per-instance creation

LoggerBuf_Handle LoggerBuf_create// Allocate and initialize a new instance object and return its handle( const LoggerBuf_Params *params, Error_Block *eb );

Void LoggerBuf_construct// Initialize a new instance object inside the provided structure( LoggerBuf_Struct *structP, const LoggerBuf_Params *params, Error_Block *eb );

per-instance deletion

Void LoggerBuf_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL( LoggerBuf_Handle *handleP );

Void LoggerBuf_destruct// Finalize the instance object inside the provided structure( LoggerBuf_Struct *structP );

per-instance functions

Bool LoggerBuf_disable// Disable a log( LoggerBuf_Handle handle );

Bool LoggerBuf_enable// Enable a log( LoggerBuf_Handle handle );

Void LoggerBuf_flush// Read, clear, and output the contents of the log( LoggerBuf_Handle handle );

Int LoggerBuf_getNextEntry// Fills the passed Log.EventRec with the next entry in the log( LoggerBuf_Handle handle, Log_EventRec *evtRec );

Void LoggerBuf_reset// Reset a log to empty state and enable it( LoggerBuf_Handle handle );

Void LoggerBuf_write4// Process a log event with up to 4 arguments( LoggerBuf_Handle handle, Types_Event evt, IArg a1, IArg a2, IArg a3, IArg a4 );

Void LoggerBuf_write8// Process a log event with up to 8 arguments( LoggerBuf_Handle handle, Types_Event evt, IArg a1, IArg a2, IArg a3, IArg a4, IArg a5, IArg a6, IArg a7, IArg a8 );

per-instance convertors

ILogger_Handle LoggerBuf_Handle_upCast// unconditionally move one level up the inheritance hierarchy( LoggerBuf_Handle handle );

LoggerBuf_Handle LoggerBuf_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure( ILogger_Handle handle );

per-instance built-ins

Int LoggerBuf_Object_count// The number of statically-created instance objects( );

LoggerBuf_Handle LoggerBuf_Object_get// The handle of the i-th statically-created instance object (array == NULL)( LoggerBuf_Object *array, Int i );

LoggerBuf_Handle LoggerBuf_Object_first// The handle of the first dynamically-created instance object, or NULL( );

LoggerBuf_Handle LoggerBuf_Object_next// The handle of the next dynamically-created instance object, or NULL( LoggerBuf_Handle handle );

IHeap_Handle LoggerBuf_Object_heap// The heap used to allocate dynamically-created instance objects( );

Types_Label *LoggerBuf_Handle_label// The label associated with this instance object( LoggerBuf_Handle handle, Types_Label *buf );

String LoggerBuf_Handle_name// The name of this instance object( LoggerBuf_Handle handle );

XDCscript usage meta-domain

var LoggerBuf = xdc.useModule('xdc.runtime.LoggerBuf');

local proxy modules

LoggerBuf.TimestampProxy// User supplied time-stamp proxy = ITimestampClient.Module null

LoggerBuf.TimestampProxy.delegate$ = ITimestampClient.Module null

module-wide constants & types

values of type LoggerBuf.BufType// Type of log buffer

const LoggerBuf.BufType_CIRCULAR// The log buffer wraps, overwriting old entries;

const LoggerBuf.BufType_FIXED// The log buffer halts collection when full;

var obj = new LoggerBuf.BasicView// ;

obj.label = String ...

obj.lastSerial = Int ...

obj.enabledFlag = Bool ...

var obj = new LoggerBuf.RecordView// ;

obj.serial = Int ...

obj.timestamp = Int ...

obj.modName = String ...

obj.text = String ...

obj.eventId = Int ...

obj.eventName = String ...

obj.arg0 = IArg ...

obj.arg1 = IArg ...

obj.arg2 = IArg ...

obj.arg3 = IArg ...

module-wide config parameters

LoggerBuf.enableFlush// Flush all logs at system exit = Bool false;

LoggerBuf.common$// Common module configuration parameters = Types.Common$ undefined;

per-instance config parameters

var params = new LoggerBuf.Params// Instance config-params object;

params.bufHeap// The heap that contains the Log buffer for dynamic instances = IHeap.Handle null;

params.bufSection// Section name for the buffer managed by the static instance = String null;

params.bufType// Log buffer type = LoggerBuf.BufType LoggerBuf.BufType_CIRCULAR;

params.exitFlush// Flush log at system exit = Bool false;

params.numEntries// Number of entries in buffer = Int 64;

per-instance creation

var inst = LoggerBuf.create// Create an instance-object( params );

XDCspec declarations sourced in xdc/runtime/LoggerBuf.xdc

package xdc.runtime;

@Gated @ModuleStartup

module LoggerBuf inherits ILogger {

local proxy modules

proxy TimestampProxy inherits ITimestampClient;

module-wide constants & types

enum BufType// Type of log buffer {

BufType_CIRCULAR// The log buffer wraps, overwriting old entries,

BufType_FIXED// The log buffer halts collection when full

};

metaonly struct BasicView// {

String label;

Int lastSerial;

Bool enabledFlag;

};

metaonly struct RecordView// {

Int serial;

Int timestamp;

String modName;

String text;

Int eventId;

String eventName;

IArg arg0;

IArg arg1;

IArg arg2;

IArg arg3;

};

module-wide config parameters

config Bool enableFlush// Flush all logs at system exit = false;

metaonly config Types.Common$ common$// Common module configuration parameters;

module-wide functions

Void flushAll// Flush logs of all instances of LoggerBuf( );

instance:

per-instance config parameters

config IHeap.Handle bufHeap// The heap that contains the Log buffer for dynamic instances = null;

config LoggerBuf.BufType bufType// Log buffer type = LoggerBuf.BufType_CIRCULAR;

config Bool exitFlush// Flush log at system exit = false;

config Int numEntries// Number of entries in buffer = 64;

metaonly config String bufSection// Section name for the buffer managed by the static instance = null;

per-instance creation

create// Create an instance-object( );

per-instance functions

Bool disable// Disable a log( );

Bool enable// Enable a log( );

Void flush// Read, clear, and output the contents of the log( );

Int getNextEntry// Fills the passed Log.EventRec with the next entry in the log( Log.EventRec *evtRec );

Void reset// Reset a log to empty state and enable it( );

Void write4// Process a log event with up to 4 arguments( Types.Event evt, IArg a1, IArg a2, IArg a3, IArg a4 );

Void write8// Process a log event with up to 8 arguments( Types.Event evt, IArg a1, IArg a2, IArg a3, IArg a4, IArg a5, IArg a6, IArg a7, IArg a8 );

}

DETAILS

The implementation of this logger is fast with minimal stack usage making it appropriate for a realtime application. This logger writes all Log events to a circular buffer. As a result, the execution time of all Log methods bound to this type of logger are deterministic (and quite short) because there are no additional memory allocation calls after the circular buffer was allocated.

If this logger is used in a preemptive environment, then an appropriate gate must be assigned to the module. For example, if events are generated from an interrupt context, then a gate that disables interrupts must be used.

  var LoggerBuf = xdc.useModule('xdc.runtime.LoggerBuf');
  LoggerBuf.common$.gate = ...some gate instance...

If the buffer type is circular, the log buffer of size numEntries contains the last numEntries of Log events. If the buffer type is fixed, the log buffer contains the first numEntries events.

EXAMPLES

Configuration example: The following XDC configuration statements create a logger instance, assign it as the default logger for all modules, and enable USER1 logging in all modules of the package my.pkg. See the Diags.setMaskMeta() function for details on specifying the module names.

  var Defaults = xdc.useModule('xdc.runtime.Defaults');
  var Diags = xdc.useModule('xdc.runtime.Diags');
  var LoggerBuf = xdc.useModule('xdc.runtime.LoggerBuf');

  LoggerBuf.enableFlush = true;
  var LoggerBufParams = new LoggerBuf.Params();
  LoggerBufParams.exitFlush = true;
  Defaults.common$.logger = LoggerBuf.create(LoggerBufParams);
  Diags.setMaskMeta("my.pkg.%", Diags.USER1, Diags.RUNTIME_ON);

proxy LoggerBuf.TimestampProxy