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