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.

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

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;
}

Related Information

Trace Facility in AIX Version 6.1 Kernel Extensions and Device Support Programming Concepts.

The CT_HOOKx and CT_GEN macros, CTFUNC_HOOKx Macros, and CTCS_HOOKx Macros.

The trcgenk and trcgenkt kernel services.

The trchook, trchook64, utrchook and utrchook64 subroutine.

The ras_register and ras_unregister exported kernel services.

The RAS_BLOCK_NULL Exported Data Structure in AIX Version 6.1 Technical Reference: Kernel and Subsystems Volume 1.

The Component Trace Facility.

[ Top of Page | Previous Page | Next Page | Index | Feedback ]