module ti.uiactools.runtime.LoggerSTM

A logger which writes Log events to the System Trace Module (STM)

C synopsis
Individual elements
DETAILS
EXAMPLES
XDCscript usage
Individual elements

This module provides a logger which writes Log events to the System Trace Module 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. [ more ... ]

C synopsis target-domain sourced in ti/uiactools/runtime/LoggerSTM.xdc

#include <ti/uiactools/runtime/LoggerSTM.h>

Functions
Void	LoggerSTM_construct// Initialize a new instance object inside the provided structure(LoggerSTM_Struct structP, const LoggerSTM_Params params, Error_Block *eb);
LoggerSTM_Handle	LoggerSTM_create// Allocate and initialize a new instance object and return its handle(const LoggerSTM_Params params, Error_Block eb);
Void	LoggerSTM_delete// Finalize and free this previously allocated instance object, setting the referenced handle to NULL(LoggerSTM_Handle *handleP);
Void	LoggerSTM_destruct// Finalize the instance object inside the provided structure(LoggerSTM_Struct *structP);
macro Int32	LoggerSTM_getOSTHeader// returns the OST Header to use as the first word of the STM event(Int numBytes);
Ptr	LoggerSTM_getSTMBaseAdrs// Gets the STM base address (STM channel 0) that events are to be written to();
Bits8	LoggerSTM_getSTMChannelRangeMax// Gets the highest STM channel number that events are to be written to(LoggerSTM_Handle handle);
Bits8	LoggerSTM_getSTMChannelRangeMin// Gets the lowest STM channel number that events are to be written to(LoggerSTM_Handle handle);
Void	LoggerSTM_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(LoggerSTM_Params *params);
Void	LoggerSTM_printToSTM// Helper function that prints formatted strings to STM(Int chanNum, Log_Event evt, IArg a1, IArg a2, IArg a3, IArg a4, IArg a5, IArg a6, IArg a7, IArg a8);
Void	LoggerSTM_setProcessId// Sets the active process ID to log with the event (default is 0)(UInt32 processId);
Void	LoggerSTM_setSTMBaseAdrs// Sets the base address (STM channel 0) that events are to be written to(Ptr adrs);
Void	LoggerSTM_setSTMChannelRangeMax// Sets the highest STM channel number that events are to be written to(LoggerSTM_Handle handle, Bits8 chanNum);
Void	LoggerSTM_setSTMChannelRangeMin// Sets the lowest STM channel number that events are to be written to(LoggerSTM_Handle handle, Bits8 chanNum);
Functions common to all ILogger modules
Bool	LoggerSTM_disable// Disable a log(LoggerSTM_Handle handle);
Bool	LoggerSTM_enable// Enable a log(LoggerSTM_Handle handle);
Void	LoggerSTM_write0// Process a log event with 0 arguments(LoggerSTM_Handle handle, Log_Event evt, Types_ModuleId mid);
Void	LoggerSTM_write1// Process a log event with 1 argument(LoggerSTM_Handle handle, Log_Event evt, Types_ModuleId mid, IArg a1);
Void	LoggerSTM_write2// Process a log event with 2 arguments(LoggerSTM_Handle handle, Log_Event evt, Types_ModuleId mid, IArg a1, IArg a2);
Void	LoggerSTM_write4// Process a log event with 4 arguments(LoggerSTM_Handle handle, Log_Event evt, Types_ModuleId mid, IArg a1, IArg a2, IArg a3, IArg a4);
Void	LoggerSTM_write8// Process a log event with 8 arguments(LoggerSTM_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 IUIATransfer modules
Bool	LoggerSTM_getContents// Fills buffer that is passed in with unread data, up to size bytes in length(LoggerSTM_Handle handle, Ptr hdrBuf, SizeT size, SizeT *cpSize);
UInt16	LoggerSTM_getInstanceId// Returns an ID value that uniquely identifies this instance of the logger(LoggerSTM_Handle handle);
SizeT	LoggerSTM_getMaxLength// (LoggerSTM_Handle handle);
IUIATransfer_TransferType	LoggerSTM_getTransferType// (LoggerSTM_Handle handle);
Bool	LoggerSTM_isEmpty// Returns true if the transfer buffer has no unread data(LoggerSTM_Handle handle);
Void	LoggerSTM_reset// Reset a log to empty state and enable it(LoggerSTM_Handle handle);
Functions common to all IFilterLogger modules
Diags_Mask	LoggerSTM_getFilterLevel// Returns the mask of diags categories currently set to the specified level(LoggerSTM_Handle handle, Diags_EventLevel level);
Void	LoggerSTM_setFilterLevel// Sets the level of detail that instances will log(LoggerSTM_Handle handle, Diags_Mask mask, Diags_EventLevel filterLevel);
Functions common to all ILoggerSnapshot modules
Void	LoggerSTM_writeMemoryRange// Process a log a snapshot of a range of memory values (e.g. array values, memory mapped registers, strings, etc.)(LoggerSTM_Handle handle, Log_Event evt, Types_ModuleId mid, UInt32 snapshotId, IArg fileName, IArg LineNum, IArg fmt, IArg startAdrs, UInt32 lengthInMAUs);
Functions common to all target instances
	LoggerSTM_handle// Convert this instance structure pointer into an instance handle, LoggerSTM_Handle_downCast// conditionally move one level down the inheritance hierarchy; NULL upon failure, LoggerSTM_Handle_downCast2// conditionally move 2 levels down the inheritance hierarchy; NULL upon failure, LoggerSTM_Handle_downCast3// conditionally move 3 levels down the inheritance hierarchy; NULL upon failure, LoggerSTM_Handle_downCast4// conditionally move 4 levels down the inheritance hierarchy; NULL upon failure, LoggerSTM_Handle_label// The label associated with this instance object, LoggerSTM_Handle_name// The name of this instance object, LoggerSTM_Handle_upCast// unconditionally move one level up the inheritance hierarchy, LoggerSTM_Handle_upCast2// unconditionally move 2 levels up the inheritance hierarchy, LoggerSTM_Handle_upCast3// unconditionally move 3 levels up the inheritance hierarchy, LoggerSTM_Handle_upCast4// unconditionally move 4 levels up the inheritance hierarchy, LoggerSTM_Object_count// The number of statically-created instance objects, LoggerSTM_Object_first// The handle of the first dynamically-created instance object, or NULL, LoggerSTM_Object_get// The handle of the i-th statically-created instance object (array == NULL), LoggerSTM_Object_heap// The heap used to allocate dynamically-created instance objects, LoggerSTM_Object_next// The handle of the next dynamically-created instance object, or NULL, LoggerSTM_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
	LoggerSTM_Module_getMask// Returns the diagnostics mask for this module, LoggerSTM_Module_hasMask// Test whether this module has a diagnostics mask, LoggerSTM_Module_heap// The heap from which this module allocates memory, LoggerSTM_Module_id// Get this module's unique id, LoggerSTM_Module_setMask// Set the diagnostics mask for this module, LoggerSTM_Module_startupDone// Test if this module has completed startup
Typedefs
typedef LoggerSTM_Object *	LoggerSTM_Handle// Client reference to an instance object;
typedef struct	LoggerSTM_Object// Opaque internal representation of an instance object LoggerSTM_Object;
typedef struct	LoggerSTM_Params// Instance config-params structure ...
typedef struct	LoggerSTM_Struct// Opaque client structure large enough to hold an instance object LoggerSTM_Struct;
typedef enum	LoggerSTM_TransferType// ...
Constants
extern const UInt16	LoggerSTM_endpointId// Endpoint ID for the CPU that is logging the event;
extern const Bool	LoggerSTM_filterByLevel// Support filtering of events by event level;
extern const Bool	LoggerSTM_isGenerateSTMLibSupportFnsEnabled// Configures whether helper functions required by STMLib are automatically generated (default) or not;
extern const Bool	LoggerSTM_isStringOutputModeEnabled// if true, events are logged to STM as strings instead of raw UIA data. Only enable this mode if not using System Analyzer to analyze and display events;
extern const Diags_Mask	LoggerSTM_level1Mask// Mask of diags categories whose initial filtering level is Diags.LEVEL1;
extern const Diags_Mask	LoggerSTM_level2Mask// Mask of diags categories whose initial filtering level is Diags.LEVEL2;
extern const Diags_Mask	LoggerSTM_level3Mask// Mask of diags categories whose initial filtering level is Diags.LEVEL3;
extern const Diags_Mask	LoggerSTM_level4Mask// Mask of diags categories whose initial filtering level is Diags.LEVEL4;
extern const Ptr	LoggerSTM_stmBaseAdrs// Base address for the STM channel that events are to be written to;
extern const Int	LoggerSTM_stmChannelResolution// Base address for the STM channel that events are to be written to;

DETAILS

EXAMPLES

Configuration Example 1: The following XDC configuration script statements show how to use the ti.uiactools.sysbios.LoggingSetupSTM module to enable instrumentation for SysBIOS modules, with the resulting UIA software events being logged to System Trace as STM software messages:

 var LoggerSTM = xdc.useModule('ti.uiactools.runtime.LoggerSTM');
 LoggerSTM.TimestampProxy = xdc.useModule('xdc.runtime.Timestamp');
 
 // The following stmBaseAdrs setting is valid for C66X devices only.
 // For other devices, please check the device's Technical Reference / Data
 // Manual for the STM base address.

 LoggerSTM.stmBaseAdrs = 0x20000000;
 LoggerSTM.stmChannelResolution = 0x1000;
 
 LoggerSTM.isStringOutputModeEnabled = false;
 

 // If you wish to provide a custom memory allocation
 // procedure for use by LoggerSTM and stmLib, you should
 // set the following to false.  You will then need to provide 
 // your own implementation of the following helper functions:
 // void * cTools_memAlloc(size_t sizeInBytes);
 // void cTools_memFree(void * ptr);
 // void * cTools_memMap(unsigned int phyAddr, unsigned int mapSizeInBytes);
 // void cTools_memUnMap(void * vAddr, unsigned int mapSizeInBytes);
 //
 // See ti.uiactools.runtime.LoggerSTM.xdt for the default implementation
 // of these functions.

 LoggerSTM.isGenerateSTMLibSupportFnsEnabled = true;
 
 // Configure which STM channels the messages are to be logged to.
 // The channel number is incremented (and wrapped around if necessary)
 // for each message so that, if the code logging the message is preempted
 // by another task that also needs to log a message, the messages can be
 // properly decoded by the host.
 // Typically, channel 200 is reserved for synchronization events.
 // (See the cdoc documentation for ti.uiactools.runtime.SyncSTM
 // for more information).

 var LoggerSTMParams = new LoggerSTM.Params;
 LoggerSTMParams.stmChannelRangeMin = 128;
 LoggerSTMParams.stmChannelRangeMax = 199;
 var loggerSTM0 = LoggerSTM.create(LoggerSTMParams);
 Program.global["loggerSTMInstStatic"] = loggerSTM0;
 
 //Configure the LogSnapshot module to log snapshot events
 //(e.g. dynamically allocated strings and memory ranges)
 //to STM
 var LogSnapshot = xdc.useModule('ti.uia.runtime.LogSnapshot');
 LogSnapshot.common$.logger = loggerSTM0;
 
 var LoggingSetup = xdc.useModule('ti.uiactools.sysbios.LoggingSetupSTM');
 LoggingSetup.logger = loggerSTM0;
 LoggingSetup.sysbiosTaskLogging = true;
 LoggingSetup.loadLogging = false;
 LoggingSetup.mainLogging = true;

 // The following lines enable correlation of STM events 
 // with UIA software events:
 var LogSync = xdc.useModule('ti.uia.runtime.LogSync');
 LoggerSTMParams.stmChannelRangeMin = 200;
 LoggerSTMParams.stmChannelRangeMax = 200;
 var loggerSTMsync = LoggerSTM.create(LoggerSTMParams);
 LogSync.syncLogger = loggerSTMsync;

 // If correlation of STM events with UIA software events is not
 // required (e.g. to reduce the code footprint), the
 // above lines should be commented out and the following line
 // enabled:
 // LoggingSetup.disableMulticoreEventCorrelation = false;

Configuration Example 2: The following XDC configuration script 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 Main = xdc.useModule('xdc.runtime.Main');
  var Diags = xdc.useModule('xdc.runtime.Diags');
  var LoggerSTM = xdc.useModule('ti.uiactools.runtime.LoggerSTM');

  // Configure LoggerSTM to log to channels 100-128.
  // (assumes that the device has the STM base address at the
  // default address of 0x20000000).
  var LoggerSTMParams = new LoggerSTM.Params();
  LoggerSTMParams.stmChannelRangeMin = 100;
  LoggerSTMParams.stmChannelRangeMax = 128;
  var loggerSTM0 = LoggerSTM.create(LoggerSTMParams);
 
  // Configure which modules are to log 
  // events using the LoggerSTM instance that was created above.
  Main.common$.logger = loggerSTM0;
  Defaults.common$.logger = loggerSTM0;

  // Configure which event masks are enabled.
  Main.common$.Diags_USER1 = Diags.RUNTIME_ON;
  Main.common$.Diags_ANALYSIS = Diags.RUNTIME_ON;
  Diags.setMaskMeta("my.pkg.%", Diags.USER1, Diags.RUNTIME_ON);

The implementation of this logger is fast with minimal stack usage making it appropriate for a realtime application. This logger uses different STM channels for writing different numbers of parameters in order to avoid the need to have a header indicating the length in bytes of each event. 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 required.

If this logger is used in a preemptive environment, then an appropriate gate must be assigned to the module. By default, the xdc.runtime.Gate module's system gate is used. The following configuration script shows how to configure a different gate:

  var LoggerSTM = xdc.useModule('ti.uiactools.runtime.LoggerSTM');
  LoggerSTM.common$.gate = ...some gate instance...

enum LoggerSTM_TransferType