Harlequin RIP SDK
Harlequin SDK timing and profiling subsystem

The Harlequin RIP timing and profiling system is used to capture high frequency information about the internal operation of the Harlequin RIP, and to control profiling. It is not normally built into release RIPs. More...

Files

file  pprobelog.c
 Capture profiling information from RIP.
 
file  probelog.c
 Capture profiling information from RIP.
 

Macros

#define SKINKIT_TRACENAMES(macro_)
 Extended trace names for skinkit. More...
 
#define SKINKIT_TRACETYPES(macro_)
 Extended trace types for skinkit. More...
 

Enumerations

enum  { SKINKIT_TRACE_BASE = CORE_TRACE_N , SW_TRACE_PROBE , SW_TRACE_KCALLRASTERSTART , SW_TRACE_KCALLRASTERWRITEDATA , SW_TRACE_KCALLRASTERFINISH , SW_TRACE_KCALLRASTERJOBEND , SW_TRACE_KCALLRASTERREQUIREMENTSCALLBACK , SW_TRACE_KCALLRASTERDESTINATIONCALLBACK , SW_TRACE_KCALLPARAMCALLBACK , SW_TRACE_STOREBANDINCACHE , SW_TRACE_GETBANDFROMCACHE , SW_TRACE_TIMELINE , SW_TRACE_FILE_PROGRESS , SW_TRACE_JOB_STREAM_TL , SW_TRACE_JOB_CONFIG_TL , SW_TRACE_JOB_TL , SW_TRACE_INTERPRET_PAGE_TL , SW_TRACE_RENDER_PAGE_TL , SW_TRACE_RENDER_PARTIAL_TL , SW_TRACE_RENDER_CACHE_TL , SW_TRACE_RENDER_SEPARATION_TL , SW_TRACE_RR_SCANNING_TL , SW_TRACE_TRAP_PREPARATION_TL , SW_TRACE_TRAP_GENERATION_TL , SW_TRACE_PGB_TL , SW_TRACE_SKIN_TL , SW_TRACE_SKIN_JOB_TL , SW_TRACE_RASTER_WRITE , SW_TRACE_CORE_TL , SW_TRACE_SCALABLE_RIP_TL , SW_TRACE_SCALABLERIP_JOB_TL , SW_TRACE_HVD_OUTPUT_PAGE , SW_TRACE_HVD_OUTPUT_SHEET , SKINKIT_TRACE_N }
 Enumeration of trace names for skinkit. More...
 
enum  { SKINKIT_TRACETYPE_BASE = CORE_TRACETYPE_N , SW_TRACETYPE_TITLE , SW_TRACETYPE_PROGRESS , SW_TRACETYPE_EXTEND , SW_TRACETYPE_ENDING , SW_TRACETYPE_ABORTING , SKINKIT_TRACETYPE_N }
 Enumeration of trace types for skinkit. More...
 

Functions

void SwLeProbeLogInit (void)
 Initialise timing probe logging. More...
 
void SwLeProbeLogFilename (const char *pszLog)
 Set probe log file name. More...
 
void SwLeProbeLogFinish (void)
 Finish probe logging. More...
 
HqBool SwLeProbeOption (const char *argname, const char *arg)
 Set the probe handler function for the specified arg. More...
 
HqBool SwLeProfileOption (const char *argname, const char *arg)
 Set the profile handler function for the specified arg. More...
 
void SwLeProbeOptionUsage (void)
 Display the default probe usage information. More...
 
void SwLeSetTraceHandler (SwTraceHandlerFn *handler)
 Set a probe callback function to capture fine-grained tracing information. More...
 
void SwLeTraceEnable (int32 trace, HqBool enable)
 Enable a probe to capture fine-grained tracing information. More...
 
void SwLeProbe (int id, int type, intptr_t designator)
 Call the skinkit trace handler, if installed. More...
 

Detailed Description

The Harlequin RIP timing and profiling system is used to capture high frequency information about the internal operation of the Harlequin RIP, and to control profiling. It is not normally built into release RIPs.

Macro Definition Documentation

◆ SKINKIT_TRACENAMES

#define SKINKIT_TRACENAMES (   macro_)

Extended trace names for skinkit.

These are defined using a macro expansion, so the names can be re-used for other purposes (stringification, usage strings) without having maintainers having to modify every skin which uses the trace facility.

See also
Lightweight tracing API.

◆ SKINKIT_TRACETYPES

#define SKINKIT_TRACETYPES (   macro_)
Value:
macro_(TITLE) /* Timeline re-title. */ \
macro_(PROGRESS) /* Timeline progress. */ \
macro_(EXTEND) /* Timeline extend. */ \
macro_(ENDING) /* Timeline notified of end. */ \
macro_(ABORTING) /* Timeline notified of abort. */ \

Extended trace types for skinkit.

These are defined using a macro expansion, so the names can be re-used for other purposes (stringification, usage strings) without having maintainers having to modify every skin which uses the trace facility. The timeline types have special treatment in the skin so that the timeline reference can be used as the designator.

See also
Lightweight tracing API.

Enumeration Type Documentation

◆ anonymous enum

anonymous enum

Enumeration of trace names for skinkit.

See also
Lightweight tracing API.
Enumerator
SKINKIT_TRACE_BASE 

Base value for skin trace names.

◆ anonymous enum

anonymous enum

Enumeration of trace types for skinkit.

See also
Lightweight tracing API.
Enumerator
SKINKIT_TRACETYPE_BASE 

Base value for skinkit trace types.

Function Documentation

◆ SwLeProbe()

void SwLeProbe ( int  id,
int  type,
intptr_t  designator 
)

Call the skinkit trace handler, if installed.

Parameters
idA trace ID. This may be a core, skinkit or skin ID. It will be silently ignored if it is not a valid trace ID.
typeA trace type. This may be a core, skinkit or skin type. It will be silently ignored if it is not a valid trace type.
designatorA data value. The interpretation of the data value is dependent on the trace id. It is usually used for correlating objects, or supplying a value for an event.
See also
Lightweight tracing API.

◆ SwLeProbeLogFilename()

void SwLeProbeLogFilename ( const char *  pszLog)

Set probe log file name.

This should be called before any probes are issued, or it will not have any effect.

Parameters
pszLogFilename of output log.
See also
Lightweight tracing API.

◆ SwLeProbeLogFinish()

void SwLeProbeLogFinish ( void  )

Finish probe logging.

This call should come just before shutting the application down. It should be after the calls to start up and shutdown the SDK or RIP.

See also
Lightweight tracing API.

◆ SwLeProbeLogInit()

void SwLeProbeLogInit ( void  )

Initialise timing probe logging.

This call should come just after starting up the application. It should be before the calls to start up and shutdown the SDK or RIP.

See also
Lightweight tracing API.

◆ SwLeProbeOption()

HqBool SwLeProbeOption ( const char *  argname,
const char *  arg 
)

Set the probe handler function for the specified arg.

Parameters
argnameCommand line argument for usage display only.
argGroup name or probe name.
Return values
TRUEThe group or probe name was enabled.
FALSEThe group or probe name does not exist.
See also
Lightweight tracing API.

◆ SwLeProbeOptionUsage()

void SwLeProbeOptionUsage ( void  )

Display the default probe usage information.

See also
Lightweight tracing API.

◆ SwLeProfileOption()

HqBool SwLeProfileOption ( const char *  argname,
const char *  arg 
)

Set the profile handler function for the specified arg.

Parameters
argnameCommand line argument for usage display only.
argGroup name or probe name.
Return values
TRUEThe group or probe name was enabled.
FALSEThe group or probe name does not exist.
See also
Lightweight tracing API.

◆ SwLeSetTraceHandler()

void SwLeSetTraceHandler ( SwTraceHandlerFn handler)

Set a probe callback function to capture fine-grained tracing information.

Parameters
handlerTrace handler function, called by the RIP when enabled events occur.

This function will only have an effect on the core RIP if called before SwLeMemInit() and SwLeStart(). A pointer to the trace handler is retained by the skinkit for use by the SwLeProbe() function.

See also
Lightweight tracing API.

<Trace handler function is stored in probe_function. The trace function should match the SwTraceHandlerFn typedef from swtrace.h. The trace handler is called in some special builds to record profiling information.

<Terminator for array of SWSTART structures

<Trace handler function is stored in probe_function. The trace function should match the SwTraceHandlerFn typedef from swtrace.h. The trace handler is called in some special builds to record profiling information.

◆ SwLeTraceEnable()

void SwLeTraceEnable ( int32  trace,
HqBool  enable 
)

Enable a probe to capture fine-grained tracing information.

Parameters
traceThe trace name identifier. Individual traces should come from the SW_TRACE_* identifiers defined in swtrace.h.
enableIf true, enable the probe(s). If false, disable them.

The trace handler function must have been set using SwLeSetTraceHandler() before calling this function. This function is a trampoline to call the trace handler, which manages its own enable/disable state.

See also
Lightweight tracing API.