CT_HOOKx_PRIV, CTCS_HOOKx_PRIV, CT_HOOKx_COMMON, CT_HOOKx_RARE, and CT_HOOKx_SYSTEM Macros

Purpose

Record a trace event into Component Trace (CT), Lightweight Memory Trace (LMT), or system trace buffers.

Syntax

#include <sys/ras_trace.h>
CT_HOOK0_PRIV(ras_block_t cb, ulong hw);
CT_HOOK1_PRIV(ras_block_t cb, ulong hw, ulong d1);
CT_HOOK2_PRIV(ras_block_t cb, ulong hw, ulong d1, ulong d2);
CT_HOOK3_PRIV(ras_block_t cb, ulong hw, ulong d1, ulong d2, ulong d3);
CT_HOOK4_PRIV(ras_block_t cb, ulong hw, ulong d1, ulong d2, ulong d3, ulong d4);
CT_HOOK5_PRIV(ras_block_t cb, ulong hw, ulong d1, ulong d2, ulong d3, ulong d4, ulong d5);

#include <sys/ras_trace.h>
CTCS_HOOK0_PRIV(ras_block_t cb, ulong hw);
CTCS_HOOK1_PRIV(ras_block_t cb, ulong hw, ulong d1);
CTCS_HOOK2_PRIV(ras_block_t cb, ulong hw, ulong d1, ulong d2);
CTCS_HOOK3_PRIV(ras_block_t cb, ulong hw, ulong d1, ulong d2, ulong d3);
CTCS_HOOK4_PRIV(ras_block_t cb, ulong hw, ulong d1, ulong d2, ulong d3, ulong d4);
CTCS_HOOK5_PRIV(ras_block_t cb, ulong hw, ulong d1, ulong d2, ulong d3, ulong d4, ulong d5);

#include <sys/ras_trace.h>
CT_HOOK0_COMMON(ulong hw);
CT_HOOK1_COMMON(ulong hw, ulong d1);
CT_HOOK2_COMMON(ulong hw, ulong d1, ulong d2);
CT_HOOK3_COMMON(ulong hw, ulong d1, ulong d2, ulong d3);
CT_HOOK4_COMMON(ulong hw, ulong d1, ulong d2, ulong d3, ulong d4);
CT_HOOK5_COMMON(ulong hw, ulong d1, ulong d2, ulong d3, ulong d4, ulong d5);

#include <sys/ras_trace.h>
CT_HOOK0_RARE(ulong hw);
CT_HOOK1_RARE(ulong hw, ulong d1);
CT_HOOK2_RARE(ulong hw, ulong d1, ulong d2);
CT_HOOK3_RARE(ulong hw, ulong d1, ulong d2, ulong d3);
CT_HOOK4_RARE(ulong hw, ulong d1, ulong d2, ulong d3, ulong d4);
CT_HOOK5_RARE(ulong hw, ulong d1, ulong d2, ulong d3, ulong d4, ulong d5);

#include <sys/ras_trace.h>
CT_HOOK0_SYSTEM(ulong hw);
CT_HOOK1_SYSTEM(ulong hw, ulong d1);
CT_HOOK2_SYSTEM(ulong hw, ulong d1, ulong d2);
CT_HOOK3_SYSTEM(ulong hw, ulong d1, ulong d2, ulong d3);
CT_HOOK4_SYSTEM(ulong hw, ulong d1, ulong d2, ulong d3, ulong d4);
CT_HOOK5_SYSTEM(ulong hw, ulong d1, ulong d2, ulong d3, ulong d4, ulong d5);

Description

The CT_HOOKx_PRIV, CTCS_HOOKx_PRIV, CT_HOOKx_COMMON, CT_HOOKx_RARE, and CT_HOOKx_SYSTEM macros trace a trace event in to a specific trace facility. These macros are optimized for performance. Due to this optimization, no explicit checking is done to ensure the availability of a trace facility. In general, it is always safe to trace to either of the LMT buffer types or system source. Callers should use the rasrb_trace_privlevel() service to ensure that the selected Component Trace private buffer is available. Before calling routines that write to the private buffer of a Component Trace, checks should be made to ensure that the return value is not -1, and that the buffer is at the appropriate level required for tracing. Race conditions for infrastructure-serialized Component Trace macros are handled by the infrastructure. Component-serialized traces must ensure proper serialization between tracing and state changes made in the corresponding RAS callback.

The following table describes how macros are associated with a specific trace facility and includes notes about the macros.

Item	Description
Trace Facility	Macro	Notes
Component Trace private buffer	CT_HOOKx_PRIV	Can be used with both infrastructure and component serialized traces.
Component Trace private buffer	CTCS_HOOKx_PRIV	Can only be used with component serialized traces.
Lightweight Memory Trace common buffer	CT_HOOKx_COMMON
Lightweight Memory Trace rare buffer	CT_HOOKx_RARE
System Trace buffer	CT_HOOKx_SYSTEM

All traces are recorded with time stamps.

If the cb input parameter has a value of RAS_BLOCK_NULL, no tracing is performed.

Parameters

Item	Description
ras_block_t cb	The cb parameter is the RAS control block that refers to the component that this trace entry belongs to.

The hkwd, d1, d2, d3, d4, and d5 parameters are the same as those used for the existing TRCHKx macros. The TRCHKx refers to the TRCHKLnT macros where n is from 0 to 5. For example, TRCHKL1T (hkwd, d1).

Example

In the following example, the foo() function uses Component Trace private buffers with system trace in a performance optimized way. The foo() function uses component-serialization and traces only when the detail level is at or above the CT_LEVEL_NORMAL level (defined in sys/ras_trace.h).

void foo() {
	long ipl;
	char memtrc, systrc;

	ipl = disable_lock(INTMAX, <Component Trace lock>);
	memtrc = rasrb_trace_privlevel(rasb) >= CT_LVL_NORMAL ? 1 : 0;
	systrc = rasrb_trace_syslevel(rasb) >= CT_LVL_NORMAL ? 1 : 0;
	…
	if (memtrc) {
		CTCS_HOOK5_PRIV(…)
	}
	if (systrc) {
		__INFREQUENT();
		CT_HOOK5_SYSTEM(…)
	}
	…
	unlock_enable(ipl, <Component Trace lock>)
	return;
}