module ti.sysbios.smp.LoggerBuf

A logger which stores Log events in a buffer

C synopsis
Individual elements
DETAILS
EXAMPLES
Configuration settings
Individual elements

This module provides a logger which captures xdc.runtime.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 xdc.runtime.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 ... ]

C synopsis target-domain sourced in ti/sysbios/smp/LoggerBuf.xdc

#include <ti/sysbios/smp/LoggerBuf.h>

Functions
Void	LoggerBuf_construct// Initialize a new instance object inside the provided structure(LoggerBuf_Struct structP, const LoggerBuf_Params params, Error_Block *eb);
LoggerBuf_Handle	LoggerBuf_create// Allocate and initialize a new instance object and return its handle(const LoggerBuf_Params params, Error_Block eb);
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);
Void	LoggerBuf_flush// Read, clear, and output the contents of the log(LoggerBuf_Handle handle);
Void	LoggerBuf_flushAll// Flush logs of all instances that set `exitFlush` to true();
Int	LoggerBuf_getNextEntry// Fills the passed `xdc.runtime.Log.EventRec` with the next entry in the log(LoggerBuf_Handle handle, Log_EventRec *evtRec);
Void	LoggerBuf_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(LoggerBuf_Params *params);
Void	LoggerBuf_reset// Reset a log to empty state and enable it(LoggerBuf_Handle handle);
Functions common to all ILogger modules
Bool	LoggerBuf_disable// Disable a log(LoggerBuf_Handle handle);
Bool	LoggerBuf_enable// Enable a log(LoggerBuf_Handle handle);
Void	LoggerBuf_write0// Process a log event with 0 arguments(LoggerBuf_Handle handle, Log_Event evt, Types_ModuleId mid);
Void	LoggerBuf_write1// Process a log event with 1 arguments(LoggerBuf_Handle handle, Log_Event evt, Types_ModuleId mid, IArg a1);
Void	LoggerBuf_write2// Process a log event with 2 arguments(LoggerBuf_Handle handle, Log_Event evt, Types_ModuleId mid, IArg a1, IArg a2);
Void	LoggerBuf_write4// Process a log event with up to 4 arguments(LoggerBuf_Handle handle, Log_Event evt, Types_ModuleId mid, IArg a1, IArg a2, IArg a3, IArg a4);
Void	LoggerBuf_write8// Process a log event with up to 8 arguments(LoggerBuf_Handle handle, Log_Event evt, Types_ModuleId mid, IArg a1, IArg a2, IArg a3, IArg a4, IArg a5, IArg a6, IArg a7, IArg a8);
Functions common to all IFilterLogger modules
Diags_Mask	LoggerBuf_getFilterLevel// Returns the mask of diags categories currently set to the specified level(LoggerBuf_Handle handle, Diags_EventLevel level);
Void	LoggerBuf_setFilterLevel// Set the level of detail that instances will log(LoggerBuf_Handle handle, Diags_Mask mask, Diags_EventLevel filterLevel);
Functions common to all target instances
	LoggerBuf_handle// Convert this instance structure pointer into an instance handle, LoggerBuf_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, LoggerBuf_Handle_downCast2// conditionally move 2 levels down the inheritance hierarchy; NULL upon failure, LoggerBuf_Handle_label// The label associated with this instance object, LoggerBuf_Handle_name// The name of this instance object, LoggerBuf_Handle_upCast// unconditionally move one level up the inheritance hierarchy, LoggerBuf_Handle_upCast2// unconditionally move 2 levels up the inheritance hierarchy, LoggerBuf_Object_count// The number of statically-created instance objects, LoggerBuf_Object_first// The handle of the first dynamically-created instance object, or NULL, LoggerBuf_Object_get// The handle of the i-th statically-created instance object (array == NULL), LoggerBuf_Object_heap// The heap used to allocate dynamically-created instance objects, LoggerBuf_Object_next// The handle of the next dynamically-created instance object, or NULL, LoggerBuf_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
	LoggerBuf_Module_getMask// Returns the diagnostics mask for this module, LoggerBuf_Module_hasMask// Test whether this module has a diagnostics mask, LoggerBuf_Module_heap// The heap from which this module allocates memory, LoggerBuf_Module_id// Get this module's unique id, LoggerBuf_Module_setMask// Set the diagnostics mask for this module, LoggerBuf_Module_startupDone// Test if this module has completed startup
Typedefs
typedef enum	LoggerBuf_BufType// Type of log buffer ...
typedef LoggerBuf_Object *	LoggerBuf_Handle// Client reference to an instance object;
typedef struct	LoggerBuf_Object// Opaque internal representation of an instance object LoggerBuf_Object;
typedef struct	LoggerBuf_Params// Instance config-params structure ...
typedef struct	LoggerBuf_Struct// Opaque client structure large enough to hold an instance object LoggerBuf_Struct;
Constants
extern const Bool	LoggerBuf_enableFlush// Flush all logs at system exit;
extern const Error_Id	LoggerBuf_E_badLevel// Error raised if get or setFilterLevel receives a bad level value;
extern const Bool	LoggerBuf_filterByLevel// Support filtering of events by event level;
extern const Diags_Mask	LoggerBuf_level1Mask// Mask of diags categories whose initial filtering level is Diags.LEVEL1;
extern const Diags_Mask	LoggerBuf_level2Mask// Mask of diags categories whose initial filtering level is Diags.LEVEL2;
extern const Diags_Mask	LoggerBuf_level3Mask// Mask of diags categories whose initial filtering level is Diags.LEVEL3;
extern const Diags_Mask	LoggerBuf_level4Mask// Mask of diags categories whose initial filtering level is Diags.LEVEL4;
extern const ILogger_Handle	LoggerBuf_statusLogger// Route all 'STATUS' (error and warning) events to this logger;

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.

LoggerBuf supports routing of 'STATUS' events (errors and warnings) to a separate ILogger instance. This is helpful in preserving these critical events, which may otherwise be overwritten by lower priority events. This feature is disabled by default. See statusLogger.

LoggerBuf implements the xdc.runtime.IFilterLogger interface and optionally supports filtering of events based on their detail level. This feature is disabled by default. See xdc.runtime.IFilterLogger.

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);

enum LoggerBuf_BufType