EVENT_TRACE_INFORMATION_CLASS

The EVENT_TRACE_INFORMATION_CLASS is an enumeration whose values are intended as the first dword in the information buffer when the ZwQuerySystemInformation (or NtQuerySystemInformation) and ZwSetSystemInformation (or NtSetSystemInformation) functions are given the information class SystemPerformanceTraceInformation (0x1F).

Documentation Status

The EVENT_TRACE_INFORMATION_CLASS enumeration is not documented but Microsoft has published a C-language definition in a header file named NTETW.H from the Enterprise edition of the Windows Driver Kit (WDK) for Windows 10 version 1511.

Were it not for this relatively recent and possibly unintended disclosure, much would anyway be known from type information in symbol files. Curiously though, type information for this structure has never appeared in any public symbol files for the kernel or for the obvious low-level user-mode DLLs. In the whole of Microsoft’s packages of public symbol files, at least to the original Windows 10, relevant type information is unknown before Windows 8 and appears in symbol files only for AppXDeploymentClient.dll, CertEnroll.dll (before Windows 10) and Windows.Storage.ApplicationData.dll.

Enumeration

Of the many defined cases, some can be used successfully only to query or only to set.

Numeric Value Symbolic Name Function Versions
0x00 EventTraceKernelVersionInformation query 6.0 and higher
0x01 EventTraceGroupMaskInformation query 6.0 and higher
set 6.2 and higher
0x02 EventTracePerformanceInformation query 6.0 and higher
0x03 EventTraceTimeProfileInformation query
set
6.0 and higher
0x04 EventTraceSessionSecurityInformation query late 6.0 and higher
0x05 EventTraceSpinlockInformation query
set
6.1 and higher (x64);
6.2 and higher (x86)
0x06 EventTraceStackTracingInformation query
set
6.1 and higher
0x07 EventTraceExecutiveResourceInformation query
set
6.1 and higher
0x08 EventTraceHeapTracingInformation query 6.1 and higher
0x09 EventTraceHeapSummaryTracingInformation query 6.1 and higher
0x0A EventTracePoolTagFilterInformation query
set
6.1 and higher
0x0B EventTracePebsTracingInformation set 6.2 and higher
0x0C EventTraceProfileConfigInformation set 6.2 and higher
0x0D EventTraceProfileSourceListInformation query 6.2 and higher
0x0E EventTraceProfileEventListInformation set 6.2 and higher
0x0F EventTraceProfileCounterListInformation set 6.2 and higher
0x10 EventTraceStackCachingInformation set 6.2 and higher
0x11 EventTraceObjectTypeFilterInformation set 6.2 and higher
0x04 (6.0);
0x05 (late 6.0);
0x0B (6.1);
0x12
MaxEventTraceInfoClass    

Plausibly EventTraceSpinlockInformation is defined for 32-bit Windows 7 but just isn’t used. Though the 64-bit kernel’s code for spin locks had been in C (or C++) from the start, i.e., for Windows Server 2003 SP1, the corresponding code in the 32-bit kernel is still in assembly language in Windows 7. Its evolution from Windows NT 3.1 had gone as far as adding hypervisor notifications and, for Windows 7, the maintenance of performance counters in the KPRCB, but there it was left. Not until Windows 8 does 32-bit Windows trace events for spin locks.

Behaviour

In its role as the first dword of input in the information buffer for ZwQuerySystemInformation and ZwSetSystemInformation when given the information class SystemPerformanceTraceInformation, the EVENT_TRACE_INFORMATION_CLASS enumeration subdivides the behaviour of these functions—which is as well picked up here. This review takes as understood all the general points and shorthands that are noted in the separate attempt at documenting the functions, and takes as granted that the information class is SystemPerformanceTraceInformation and that the information buffer is at least large enough for an EVENT_TRACE_INFORMATION_CLASS.

If the EVENT_TRACE_INFORMATION_CLASS on input is not listed above as valid for the function, then the function returns STATUS_NOT_IMPLEMENTED..

Each EVENT_TRACE_INFORMATION_CLASS is associated with a structure that is at least the start of what the function produces as its output or expects as input. Mostly, the structure has no other purpose. Rather than have a separate page for each information class and then another for the corresponding structure, the remainder of this page gives for each information class a brief description of the general behaviour, and then the meaning of whatever the function puts in the structure or inteprets in it is taken up, if at all, in the separate documentation of the structure.

A unified presentation of these cases is very much the sort of thing that isn’t well settled until all the cases have been examined. Of necessity this is a bit of an open-ended project, and commercial imperatives may mean the project must be abandoned. Please beware that the draft colour signifies rough notes and tentative thoughts that I offer only on the basis that they may (or may not) be better than nothing.

EventTraceKernelVersionInformation (0x00)

The information buffer must provide exactly an EVENT_TRACE_VERSION_INFORMATION structure.

EventTraceGroupMaskInformation (0x01)

The information buffer must provide exactly an EVENT_TRACE_GROUPMASK_INFORMATION structure.

EventTracePerformanceInformation (0x02)

The information buffer must provide exactly an EVENT_TRACE_PERFORMANCE_INFORMATION structure.

EventTraceTimeProfileInformation (0x03)

The information buffer must provide exactly an EVENT_TRACE_TIME_PROFILE_INFORMATION structure.

EventTraceSessionSecurityInformation (0x04)

The information buffer must provide at least an EVENT_TRACE_SESSION_SECURITY_INFORMATION structure.

EventTraceSpinlockInformation (0x05)

The information buffer must provide exactly an EVENT_TRACE_SPINLOCK_INFORMATION_V1 or EVENT_TRACE_SPINLOCK_INFORMATION structure.

EventTraceStackTracingInformation (0x06)

The information buffer must provide at least an EVENT_TRACE_SYSTEM_EVENT_INFORMATION structure up to but not including its HookId array.

When setting information, the excess over the bare minimum must provide exactly a whole number of array elements, else the function fails, returning STATUS_INVALID_PARAMETER.

EventTraceExecutiveResourceInformation (0x07)

The information buffer must provide at least an EVENT_TRACE_EXECUTIVE_RESOURCE_INFORMATION structure.

EventTraceHeapTracingInformation (0x08) and EventTraceHeapSummaryTracingInformation (0x09)

The information buffer must provide at least an EVENT_TRACE_HEAP_TRACING_INFORMATION structure.

EventTracePoolTagFilterInformation (0x0A)

The information buffer must provide at least an EVENT_TRACE_TAG_FILTER_INFORMATION structure up to but not including its Filter array.

When setting information, the excess over the bare minimum must provide exactly a whole number of array elements, but no more than 4, else the function fails, returning STATUS_INVALID_PARAMETER.

EventTracePebsTracingInformation (0x0B)

The information buffer must provide at least an EVENT_TRACE_SYSTEM_EVENT_INFORMATION structure up to but not including its HookId array.

If the excess over the bare minimum does not provide exactly 0 or 1 array element, the function fails, returning STATUS_INVALID_PARAMETER. Moreover, if an array element is provided, it must be 0x00000524.

If executing for a user-mode request, the caller must have SeSystemProfilePrivilege, else the function fails, returning STATUS_PRIVILEGE_NOT_HELD.

EventTraceProfileConfigInformation (0x0C)

The event buffer must provide at least an EVENT_TRACE_PROFILE_COUNTER_INFORMATION structure up to but not including its ProfileSource array.

EventTraceProfileSourceListInformation (0x0D)

The information buffer must provide at least an EVENT_TRACE_PROFILE_LIST_INFORMATION structure.

EventTraceProfileEventListInformation (0x0E)

The information buffer must provide at least an EVENT_TRACE_SYSTEM_EVENT_INFORMATION structure up to but not including its HookId array. If the excess over this bare minimum does not provide a whole number of array elements, the function fails, returning STATUS_INVALID_PARAMETER.

EventTraceProfileCounterListInformation (0x0F)

The information buffer must provide at least an EVENT_TRACE_PROFILE_COUNTER_INFORMATION structure up to but not including its ProfileSource array.

EventTraceStackCachingInformation (0x10)

The information buffer must provide exactly an EVENT_TRACE_STACK_CACHING_INFORMATION structure.

EventTraceObjectTypeFilterInformation (0x11)

The information buffer must provide at least an EVENT_TRACE_TAG_FILTER_INFORMATION structure up to but not including its Filter array. If the excess over the bare minimum does not provide exactly a whole number of array elements, but no more than 4, the function fails, returning STATUS_INVALID_PARAMETER.