module ti.uia.runtime.LogSnapshot

Snapshot Event logging manager for logging blocks of memory, strings in memory and names of dynamically created objects

C synopsis
Individual elements
DETAILS
EXAMPLES
Configuration settings
Individual elements

Snapshot events are used to log dynamic target state information in order to capture the execution context of the application at a particular moment in time. Types of information that can be logged include: [ more ... ]

C synopsis target-domain sourced in ti/uia/runtime/LogSnapshot.xdc

#include <ti/uia/runtime/LogSnapshot.h>

Functions
Void	LogSnapshot_doPrint// Render an event as text via `System_printf`(LogSnapshot_EventRec *er);
UInt32	LogSnapshot_getSnapshotId// returns a unique ID to use to group a set of snapshot event logs together();
macro Void	LogSnapshot_putMemoryRange// Unconditionally put the specified `Types` event. Supports both writeMemoryRange and writeString(Types_Event evt, Types_ModuleId mid, IArg fileName, IArg lineNum, UInt32 snapshotID, IArg fmt, IArg startAdrs, IArg lengthInMAUs);
macro Void	LogSnapshot_writeMemoryBlock// Generate a `LogSnapshot` event for a block of memory(UInt32 snapshotID, IArg fmt, Ptr pMemoryRange, UInt16 lengthInMAUs);
macro Void	LogSnapshot_writeMemoryBlockWithIdTag// Generate a `LogSnapshot` event for a block of memory(UInt16 idTag, UInt32 snapshotID, IArg fmt, Ptr pMemoryRange, UInt16 lengthInMAUs);
macro Void	LogSnapshot_writeNameOfReference// Used to log the contents of a dynamic string on the heap so that host-side tooling can display this string as the name of handle / reference ID(UInt32 refID, IArg fmt, Ptr pString, UInt16 lengthInMAUs);
macro Void	LogSnapshot_writeString// Generate a `LogSnapshot` event for a string in memory(UInt32 snapshotID, IArg fmt, Ptr pString, UInt16 lengthInMAUs);
macro Void	LogSnapshot_writeStringWithIdTag// Generate a `LogSnapshot` event for a string in memory(UInt16 idTag, UInt32 snapshotID, IArg fmt, Ptr pString, UInt16 lengthInMAUs);
Functions common to all target modules
	LogSnapshot_Module_getMask// Returns the diagnostics mask for this module, LogSnapshot_Module_hasMask// Test whether this module has a diagnostics mask, LogSnapshot_Module_heap// The heap from which this module allocates memory, LogSnapshot_Module_id// Get this module's unique id, LogSnapshot_Module_setMask// Set the diagnostics mask for this module, LogSnapshot_Module_startupDone// Test if this module has completed startup
Typedefs
typedef struct	LogSnapshot_EventRec// The target representation of a recorded event ...
Constants
extern const LoggerTypes_InjectIntoTraceFxn	LogSnapshot_injectIntoTraceFxn// Callback function that handles injection of info such as serial numbers of sync point events, context change events or snapshot events into a hardware trace stream. (e.g. GEM CPU Trace, System Trace, etc.);
extern const Bool	LogSnapshot_isTimestampEnabled// used to enable or disable logging the 64b local CPU timestamp at the start of each event;
extern const Ptr	LogSnapshot_loggerObj// handle of the logger that is to be used to log snapshot events;
extern const Int	LogSnapshot_maxLengthInMAUs// Maximum number of MAUs (miniumum addressable units, e.g. bytes) supported by `LogSnapshot` events;

DETAILS

Blocks of memory (using the LogSnapshot_writeMemoryBlock API)
Strings that reside in memory (using the LogSnapshot_writeString API)
Names of dynamically created objects (using the LogSnapshot_writeNameOfReference API)

The host-side tooling can be instructed to treat a series of LogSnapshot events as representing the state of the target at the same moment in time by using the same non-zero value in the snapshot ID parameter of each of the LogSnapshot events in the series.

Snapshot events are logged by a logger that implements the ILoggerSnapshot interface (e.g. LoggerCircBuf, LoggerStopMode, LoggerProbePoint). Rather than invoking the logger's APIs directly, the APIs are called indirectly via the LogSnapshot module's APIs so that different types of loggers can be used without having to recompile the source code that is logging the snapshot events.

EXAMPLES

Example 1: A simple 2-line configuration script

The following configuration script shows the simplest way to configure an application to use log snapshot events:

 var LoggingSetup = xdc.useModule('ti.uia.sysbios.LoggingSetup');
 var LogSnapshot   = xdc.useModule('ti.uia.runtime.LogSnapshot');

The first line causes the LoggingSetup module's .xs script to automatically create a 32K Byte logger and assign it to xdc.runtime.Main.common$.logger. It also sets any unconfigured Diags masks for the Main module to Diags.RUNTIME_ON, enabling the events to be logged.

The second line causes the LogSnapshot .xs script to run during the configuration process when building the application. The script detects that a logger has not been assigned to the LogSnapshot module, so it checks if a logger has been configured for either the Main module or the Defaults module. Since there is a logger for the Main module, the script configures the LogSnapshot module to log events to the same logger instance.

Example 2: Using a dedicated low priority logger for snapshot events

In some situations, the amount of data logged by the LogSnapshot APIs may exceed the ability of the target to move the event data out of the Main module's logger's circular buffer and up to the host. One way of ensuring that the other events that are logged are not dropped due to this type of situation is to configure the LogSnapshot module to write events to a separate lower priority logger.

The following is an example of a configuration script that configures a logger for use by the LogSnapshot module. This example uses a LoggerCircBuf logger, which is appropriate for uploading events in real-time as the target executes using either JTAG RunMode(C6X targets) or using a non-JTAG transport such as Ethernet. Assigning this logger a low priority causes the contents of this logger to be uploaded after higher priority events (e.g. sync point events, context change events, and error, warning, info events) have been uploaded.

 var Logger = xdc.useModule('ti.uia.runtime.LoggerCircBuf');
 var LogSnapshot   = xdc.useModule('ti.uia.runtime.LogSnapshot');

 // Create a low priority logger and use it for snapshot events
 var IUIATransfer = xdc.useModule('ti.uia.runtime.IUIATransfer');
 var loggerParams = new Logger.Params();
 loggerParams.priority = IUIATransfer.Priority_LOW;
 // set the logger buffer size in bytes
 loggerParams.transferBufSize = 32768;
 var snapshotLogger = Logger.create(loggerParams);
 snapshotLogger.instance.name = "SnapshotLog";
 LogSnapshot.common$.logger = snapshotLogger;

Using different types of loggers:

To upload events by JTAG when the target halts (JTAG StopMode), replace the first line in the example with

 Logger = xdc.useModule('ti.uia.runtime.LoggerStopMode');

To upload events by JTAG whenever an event is logged using probe point breakpoints (i.e. momentarily halting the target while the event is uploaded and then resuming execution), replace the first line in the example with

 Logger = xdc.useModule('ti.uia.runtime.LoggerProbePoint');

Example 3: Using Diags masks to control snapshot events

The generation of a 'Snapshot' event is controlled by a module's diagnostics mask, which is described in details in the CDoc for xdc.runtime.Diags. Each snapshot event is controlled using the Diags.ANALYSIS mask, and will only be logged when the diagnostics mask for the module that is logging the code has the Diags.ANALYSIS bit configured as either ALWAYS_ON or RUNTIME_ON.

The LogSnapshot function call sites are implemented in such a way that an optimizer can completely eliminate LogSnapshot code from the program if the module's ANALYSIS events have been disabled at configuration time. If the 'ANALYSIS' events are permanently turned on at configuration time, then the optimizer can eliminate all runtime conditional checking and simply invoke the 'LogSnapshot' functions directly. Runtime checking is performed only when the ANALYSIS events are configured to be runtime modifiable.

The following is an example of the configuration script used to configure the default mask for modules to have Analysis events such as the UIASnapshot events always on.

  // Configure all modules to always log Analysis events
  var Diags = xdc.useModule('xdc.runtime.Diags');
  var Defaults = xdc.useModule('xdc.runtime.Defaults');
  Defaults.common$.diags_ANALYSIS = Diags.ALWAYS_ON;

struct LogSnapshot_EventRec