Record a trace event into Component Trace (CT), Lightweight Memory Trace (LMT), or system trace buffers.
#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);
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.
| 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).
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;
}
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.