CTFUNC_HOOKx Macros

Purpose

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

Syntax

#include <sys/ras_trace.h>
CTFUNC_HOOK0(ras_block_t cb, char level, int mem_dest, ulong hw);
CTFUNC_HOOK1(ras_block_t cb, char level, int mem_dest, ulong hw, ulong d1);
CTFUNC_HOOK2(ras_block_t cb, char level, int mem_dest, ulong hw, ulong d1, ulong d2);
CTFUNC_HOOK3(ras_block_t cb, char level, int mem_dest, ulong hw, ulong d1, ulong d2, ulong d3);
CTFUNC_HOOK4(ras_block_t cb, char level, int mem_dest, ulong hw, ulong d1, ulong d2, ulong d3, ulong d4);
CTFUNC_HOOK5(ras_block_t cb, char level, int mem_dest, ulong hw, ulong d1, ulong d2, ulong d3, ulong d4, 
ulong d5);

Description

The CTFUNC_HOOKx macros record a trace hook. Theses macros are optimized to record events that are rarely recorded, such as error path tracing. The CTFUNC_HOOKx macros can be used with any types of trace serialization. Besides their optimization for rare events, the CTFUNC_HOOKx macros are equivalent to the CT_HOOKx macros.

All of the traces that the CTFUNC_HOOKx macros record are time-stamped.

If the cb input parameter contains a value of RAS_BLOCK_NULL, no tracing will be 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.
char level	The level parameter allows filtering of different trace entries. The higher this level is, the more this trace is considered as debug or detail information. This trace entry appears 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 the following 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. Otherwise, it is CT_LVL_MINIMAL) When you are porting an existing driver or subsystem from the existing system trace to component trace, existing entries should be traced at CT_LVL_DEFAULT.
int mem_dest	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, which means 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 all of the following conditions are true: The level condition of the system trace mode for this control block is satisfied. The system trace is running. The hook meets any additional criteria specified as part of the system trace. 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 can be used, but you can combine ORed with MT_SYSTEM. Otherwise, the trace entry duplicates in several memory buffers. The mem_dest parameter is not necessary for the CT_GEN macro because lightweight memory trace cannot accommodate generic entries. The CT_GEN macro checks the memory trace and system trace levels to determine whether the generic entry should enter the private memory buffer and the system trace buffers respectively.

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.

char level

The level parameter allows filtering of different trace entries. The higher this level is, the more this trace is considered as debug or detail information. This trace entry appears 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 the following 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. Otherwise, it is CT_LVL_MINIMAL)

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

int mem_dest

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, which means 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 all of the following conditions are true:

The level condition of the system trace mode for this control block is satisfied.
The system trace is running.
The hook meets any additional criteria specified as part of the system trace.

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 can be used, but you can combine ORed with MT_SYSTEM. Otherwise, the trace entry duplicates in several memory buffers.

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

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