CT_HOOKx and CT_GEN macros

Purpose

Record a trace event into Component Trace, LMT or system trace buffers.

Syntax

The following set of macros is provided to record a trace entry:

#include <sys/ras_trace.h>
CT_HOOK0(ras_block_t cb, int level, int mem_dest,long hkwd);
CT_HOOK1(ras_block_t cb, int level, int mem_dest, long hkwd, long d1);
CT_HOOK2(ras_block_t cb, int level, int mem_dest, long hkwd, long d1, long d2);
CT_HOOK3(ras_block_t cb, int level, int mem_dest, long hkwd, long d1, long d2, long d3);
CT_HOOK4(ras_block_t cb, int level, \
int mem_dest, long hkwd, long d1, long d2, \
long d3, long d4);
CT_HOOK5(ras_block_t cb, int level, int mem_dest, \
long hkwd, long d1, long d2, long d3, \
long d4, long d5);
CT_GEN (ras_block_t cb, int level, long hkwd, long data, long len, void *buf);

Description

The CT_HOOKx macros allow you to record a trace hook. The "x" is the number of data words you want in this trace event.

The CT_GEN macro is used to record a generic trace hook.

All traces are timestamped.

Restriction: If the cb input parameter has a value of RAS_BLOCK_NULL, no tracing will be performed.

Parameters

Item	Description
ras_block_t cb	The cb parameter in the RAS control block that refers to the component that this trace entry belongs to.
int level	The level parameter allows filtering of different trace entries. The higher this level is, the more this trace will be considered as debug or detail information. In other words, this trace entry will appear only if the level of the trace entry is less than or equal to the level of trace chosen for memory or system trace mode. Ten levels of trace are available (CT_LEVEL_0 to CT_LEVEL_9, corresponding to value 0 to 9) with four special levels: minimal (CT_LVL_MINIMAL (=CT_LEVEL_1)) normal (CT_LVL_NORMAL (=CT_LEVEL_3)) detail (CT_LVL_DETAIL (=CT_LEVEL_7)) default (CT_LVL_DEFAULT = CT_LVL_NORMAL in AIX® 6.1 and above and CT_LVL_MINIMAL otherwise) When you are porting an existing driver or subsystem from the existing system trace to component trace, trace existing entries at CT_LVL_DEFAULT.
int mem_dest	For CT_HOOKx macros, the mem_dest parameter indicates the memory destination for this trace entry. It is an ORed value with the following possible settings: MT_RARE: the trace entry is saved in the rare buffer of lightweight memory trace if the level condition of the memory trace mode for this control block is satisfied, meaning that the current level of trace for the memory trace mode is greater than or equal to the level of this trace entry. MT_COMMON: the trace entry is saved in the common buffer of the lightweight memory trace if the level condition of the memory trace mode for this control block is satisfied. MT_PRIV: the trace entry is saved in the private memory buffer of the component if the level condition of the memory trace mode for this control block is satisfied. MT_SYSTEM: the trace entry is saved in the existing system trace if the level condition of the system trace mode for this control block is satisfied, if the system trace is running, and if the hook meets any additional criteria specified as part of the system trace. For example, if MT_SYSTEM is not set, the trace entry is not saved in the existing system trace. Only one of the MT_RARE, MT_COMMON and MT_PRIV values should be used, but you can combine ORed with MT_SYSTEM. Otherwise, the trace entry will be duplicated in several memory buffers. The mem_dest parameter is not needed for the CT_GEN macro because lightweight memory trace cannot accommodate generic entries. CT_GEN checks the memory trace and system trace levels to determine whether the generic entry should enter the private memory buffer and system trace buffers respectively.

Item

Description

ras_block_t cb

The cb parameter in the RAS control block that refers to the component that this trace entry belongs to.

int level

The level parameter allows filtering of different trace entries. The higher this level is, the more this trace will be considered as debug or detail information. In other words, this trace entry will appear only if the level of the trace entry is less than or equal to the level of trace chosen for memory or system trace mode.

Ten levels of trace are available (CT_LEVEL_0 to CT_LEVEL_9, corresponding to value 0 to 9) with four special levels:

minimal (CT_LVL_MINIMAL (=CT_LEVEL_1))
normal (CT_LVL_NORMAL (=CT_LEVEL_3))
detail (CT_LVL_DETAIL (=CT_LEVEL_7))
default (CT_LVL_DEFAULT = CT_LVL_NORMAL in AIX® 6.1 and above and CT_LVL_MINIMAL otherwise)

When you are porting an existing driver or subsystem from the existing system trace to component trace, trace existing entries at CT_LVL_DEFAULT.

int mem_dest

For CT_HOOKx macros, the mem_dest parameter indicates the memory destination for this trace entry. It is an ORed value with the following possible settings:

MT_RARE: the trace entry is saved in the rare buffer of lightweight memory trace if the level condition of the memory trace mode for this control block is satisfied, meaning that the current level of trace for the memory trace mode is greater than or equal to the level of this trace entry.
MT_COMMON: the trace entry is saved in the common buffer of the lightweight memory trace if the level condition of the memory trace mode for this control block is satisfied.
MT_PRIV: the trace entry is saved in the private memory buffer of the component if the level condition of the memory trace mode for this control block is satisfied.
MT_SYSTEM: the trace entry is saved in the existing system trace if the level condition of the system trace mode for this control block is satisfied, if the system trace is running, and if the hook meets any additional criteria specified as part of the system trace. For example, if MT_SYSTEM is not set, the trace entry is not saved in the existing system trace.

Only one of the MT_RARE, MT_COMMON and MT_PRIV values should be used, but you can combine ORed with MT_SYSTEM. Otherwise, the trace entry will be duplicated in several memory buffers.

The mem_dest parameter is not needed for the CT_GEN macro because lightweight memory trace cannot accommodate generic entries. CT_GEN checks the memory trace and system trace levels to determine whether the generic entry should enter the private memory buffer and system trace buffers respectively.

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

For the hookword, OR the hookID with a subhookID if needed. For the CT_HOOKx macro, the subhook is ORed into the hookword. For the CT_GEN macro, the subhook is the d1 parameter.