CURRENT WORK ITEM - PREVIEW ONLY

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. Its only known public existence in anything like plain text is a C-language definition in a header file named NTETW.H that appears in some editions of the Windows Driver Kit (WDK) for Windows 10.

Enumeration

Of the many defined cases, some can be used successfully only to query or only to set. I don’t propose to examine all cases in all versions. This review is presently specific to the original release of Windows 10.

Numeric Value Symbolic Name Function
0x00 EventTraceKernelVersionInformation query
0x01 EventTraceGroupMaskInformation query
set
0x02 EventTracePerformanceInformation query
0x03 EventTraceTimeProfileInformation query
set
0x04 EventTraceSessionSecurityInformation query
0x05 EventTraceSpinLockInformation query
set
0x06 EventTraceStackTracingInformation query
set
0x07 EventTraceExecutiveResourceInformation query
set
0x08 EventTraceHeapTracingInformation query
0x09 EventTraceHeapSummaryTracingInformation query
0x0A EventTracePoolTagFilterInformation query
set
0x0B EventTracePebsTracingInformation set
0x0C EventTraceProfileConfigInformation set
0x0D EventTraceProfileSourceListInformation query
0x0E EventTraceProfileEventListInformation set
0x0F EventTraceProfileCounterListInformation set
0x10 EventTraceStackCachingInformation set
0x11 EventTraceObjectTypeFilterInformation set
0x12 MaxEventTraceInfoClass  

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.

EventTraceVersionInformation (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_SPIN_LOCK_INFORMATION_V1 or EVENT_TRACE_SPIN_LOCK_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.