module ti.uia.runtime.LogSync

SyncPoint Event logging module for logging sync point events. Allows sync point events to use a different logger instance than used for other events

C synopsis
Individual elements
DETAILS
EXAMPLES
Configuration settings
Individual elements

SyncPoint events are used to log timestamp values for two timebases: the local CPU timestamp that is used to timestamp events from this CPU, and a 'global' timestamp value that can be accessed by two or more CPUs. By logging the current timestamp values from these two timebase sources, the sync point events provide correlation points between the two timebases. [ more ... ]

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

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

Functions
Bool	LogSync_disable// Disable logging of sync point events();
Bool	LogSync_enable// Enables logging of sync point events();
Void	LogSync_idleHook// Hook function that can be called by SysBios when the Idle function. Logs a sync point event if required in order to enable multicore event correlation. Allows multicore event correlation to be re-established after the target has been halted and then resumed execution. (e.g. after CIO operation or breakpoint)();
Bool	LogSync_isSyncEventRequired// Is Sync Event Required();
Void	LogSync_Params_init// Initialize this config-params structure with supplier-specified defaults before instance creation(LogSync_Params *params);
Void	LogSync_putSyncPoint// Unconditionally put the specified `Types` event();
Void	LogSync_timerHook// Hook function that can be called periodically by SysBios to enable correlation of CPU trace, STM trace and software instrumentation events(UArg arg);
macro Void	LogSync_writeSyncPoint// Log a sync point event along with global timestamp, local CPU frequency and sync point serial number();
Void	LogSync_writeSyncPointRaw// (Types_Timestamp64 cpuTS, Types_Timestamp64 globalTS, Types_FreqHz *globalTickFreq);
Functions common to all target instances
	LogSync_handle// Convert this instance structure pointer into an instance handle, LogSync_Handle_label// The label associated with this instance object, LogSync_Handle_name// The name of this instance object, LogSync_Object_count// The number of statically-created instance objects, LogSync_Object_first// The handle of the first dynamically-created instance object, or NULL, LogSync_Object_get// The handle of the i-th statically-created instance object (array == NULL), LogSync_Object_heap// The heap used to allocate dynamically-created instance objects, LogSync_Object_next// The handle of the next dynamically-created instance object, or NULL, LogSync_struct// Convert this instance handle into an instance structure pointer
Functions common to all target modules
	LogSync_Module_getMask// Returns the diagnostics mask for this module, LogSync_Module_hasMask// Test whether this module has a diagnostics mask, LogSync_Module_heap// The heap from which this module allocates memory, LogSync_Module_id// Get this module's unique id, LogSync_Module_setMask// Set the diagnostics mask for this module, LogSync_Module_startupDone// Test if this module has completed startup
Typedefs
typedef LogSync_Object *	LogSync_Handle// Client reference to an instance object;
typedef struct	LogSync_Object// Opaque internal representation of an instance object LogSync_Object;
typedef struct	LogSync_Params// Instance config-params structure ...
typedef struct	LogSync_Struct// Opaque client structure large enough to hold an instance object LogSync_Struct;
Constants
extern const UInt32	LogSync_cpuTimestampCyclesPerTick// The number of CPU cycles each tick of the global timestamp corresponds to. 0 if no relation between clocks;
extern const UInt32	LogSync_globalTimestampCpuCyclesPerTick// The number of CPU cycles each tick of the global timestamp corresponds to. 0 if no relation between clocks;
extern const LoggerTypes_InjectIntoTraceFxn	LogSync_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 Types_FreqHz	LogSync_maxGlobalClockFreq// The highest bus clock frequency used to drive the timer used for the global timestamp;

DETAILS

In order to allow sync point information to be injected into hardware trace streams, the LogSync module supports a configuration parameter named injectIntoTraceFxn that allows the user to hook in a function pointer to a function that handles the (ISA specific) details of injecting whatever information is required into the trace stream. For C64X+ full gem devices, the address of the ti.uia.family.c64p.GemTraceSync module's GemTraceSync_injectIntoTrace function should be used.

The sync point events are defined in the ti.uia.events.UIASync module (@see ti.uia.events.UIASync#syncPoint)

A unique 'serial number' is assigned to each sync point event that is logged. The same serial number is logged as a parameter for all UIASync events that are used to log information related to the sync point, allowing host-side tooling to treat these separate events coherently. The serial number can optionally be injected into device-specific trace streams (e.g. CPU trace, System Trace, etc.) in order to enable host-side tooling to correlate these separate streams with the CPU and global timestamp information logged with the sync point events.

EXAMPLES

Example 1: This is part of the XDC configuration file for the application that demonstrates a standard configuration using default settings. In this example, the Rta module internally handles the logging of the sync point events. A timestamp module that implements the IUIATimestampProvider interface is used for the global timestamp. Default values are used for the CPU maxCpuClockFreq (700 MHz).

 // By including Rta, Log records will be collected and sent to the
 // instrumentation host (once it is connected and started).  The Rta module
 // logs sync point events upon receiving either the start or stop command,
 // and prior to sending up a new event packet if
 // LogSync_isSyncPointEventRequired() returns true.
 var Rta  = xdc.useModule('ti.uia.services.Rta');

 // By default, the sync point events will be logged to a dedicated
 // LoggerCircBuf buffer named 'SyncLog' that is assigned to the LogSync
 // module.  Using a dedicated event logger buffer is recommended
 // in order to ensure that sufficient timing information
 // is captured to enable accurate multicore event correlation.
 // Configure LogSync.defaultSyncLoggerSize to specify a custom buffer size.
 var LogSync = xdc.useModule('ti.uia.runtime.LogSync');

 // For C64X+ and C66X devices that provide CPU trace hardware capabilities,
 // the following line will enable injection of correlation information into
 // the GEM CPU trace, enabling correlation of software events with the CPU
 // trace events.
 var GemTraceSync = xdc.useModule('ti.uia.family.c64p.GemTraceSync');

 // Configure a shared timer to act as a global time reference to enable
 // multicore correlation.  The TimestampC6472Timer module implements the
 // IUIATimestampProvider interface, so assigning this timer to
 // LogSync.GlobalTimestampProxy will configure the LogSync module's global
 // clock parameters automatically.  Exmaple 2 shows how to use other
 // types of timers.
 var TimestampC6472Timer =
    xdc.useModule('ti.uia.family.c64p.TimestampC6472Timer');
 LogSync.GlobalTimestampProxy = TimestampC6472Timer;

Example 2: Using a timer that does not implement the IUIATimestampProvider interface as the global timestamp timer. This example shows how to use, for example, timers that are provided by DSP/BIOS as the global timer source for event correlation 'sync point' timestamps.

 var LogSync = xdc.useModule('ti.uia.runtime.LogSync');
 var BiosTimer = xdc.useModule('ti.sysbios.family.c64p.TimestampProvider');
 LogSync.GlobalTimestampProxy = BiosTimer;

 // The following additional configuration code is required to use
 // a timer that does not implement the IUIATimeestampProvider interface
 // as the global timer for the LogSync module.  If the maxGlobalClockFreq
 // config option is not initialized, the following warning message will be displayed
 // at build time: "Warning: UIA Event correlation disabled.  Please
 // configure LogSync.globalClkFreq (.lo,.hi) to a non-zero value to enable."
 LogSync.maxGlobalClockFreq.lo = 700000000; // frequency in Hz - lower 32b
 LogSync.maxGlobalClockFreq.hi = 0;         // frequency in Hz - upper 32b

 // Configure the LogSync module with CPU timestamp clock frequency info
 // for clock frequencies other than the default (700MHz).
 LogSync.maxCpuClockFreq.lo = 1000000000; // 1GHz CPU freq. - lower 32b
 LogSync.maxCpuClockFreq.hi = 0;         // 1GHz CPU freq.- upper 32b

 // The globalTimestampCpuCyclesPerTick config option is optional.
 // It is used to convert global timestamp tick counts into CPU cycle counts
 // for devices where there is a fixed relationship between the global timer
 // frequency and the CPU clock.
 LogSync.globalTimestampCpuCyclesPerTick = 6;

Example 3: Disabling LogSync module at configuation time The logging of sync point events can be disabled by adding the following to the configuration script:

 LogSync.isEnabled = false;

Example 4: This is a part of the C code for an application that does not use the Rta module, and so needs to log the sync point events itself:

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

 // If the target has been suspended or halted
 // since the last time an event packet was sent to the
 // host, or the event transport has received a 'start' or
 // 'stop' command from the host, log a new sync point event to record
 // the current correlation info between the local
 // timestamp and the global timestamp.
 if ((LogSync_isSyncEventRequired())||([starting/stopping event transport])){
    LogSync_writeSyncPoint();
 }

<hr />

Example 5: The following configuration script snippet shows how to periodically log a sync point event. This allows System Analyzer to properly correlate UIA software instrumentation events with C6X CPU trace and STM (System Trace) events.

 //Configure a Timer to interrupt every 100ms and call the LogSync_timerHook
 // function to log a sync point event
 var Timer = xdc.useModule('ti.sysbios.hal.Timer');
 var timerParams = new Timer.Params();
 timerParams.startMode = Timer.StartMode_AUTO;
 timerParams.period = 100000;        // 100,000 uSecs = 100ms
 var timer0 = Timer.create(Timer.ANY, '&ti_uia_runtime_LogSync_timerHook', timerParams);

config LogSync_cpuTimestampCyclesPerTick // module-wide