PERFINFO_GROUPMASK

The PERFINFO_GROUPMASK describes the types of event that are enabled or are to be enabled in an NT Kernel Logger session.

Usage

Historically, and as far as anyone still might know from Microsoft’s documentation, the choice of events to enable in NT Kernel Logger sessions is managed from user mode through the EnableFlags member of the EVENT_TRACE_PROPERTIES structure. This is most of the input and output for such documented API functions as StartTrace and ControlTrace. Bits within the EnableFlags select types of event. The PERFINFO_GROUPMASK greatly extends this choice, by allowing for very many more bits, and thus types of event.

The modern and arguably cleanest way to use a PERFINFO_GROUPMASK is through the TraceQueryInformation and TraceSetInformation functions. The PERFINFO_GROUPMASK structure is what these functions produce as output or expect as input in their information buffer when given the information class TraceSystemTraceEnableFlagsInfo (0x04).

Beneath these user-mode API functions, the PERFINFO_GROUPMASK is part of the EVENT_TRACE_GROUPMASK_INFORMATION structure that is expected by the ZwQuerySystemInformation or NtQuerySystemInformation functions and the ZwSetSystemInformation or NtSetSystemInformation functions when given their information class SystemPerformanceTraceInformation (0x1F) if the first dword in the information buffer on input is EventTraceGroupMaskInformation (0x01).

Internally, the kernel keeps an array of PERFINFO_GROUPMASK structures, one for each possible NT Kernel Logger session (the present capacity being eight), and a single structure that acts as a union of the others for quickly reckoning which types of event are enabled in at least one session.

Documentation Status

The PERFINFO_GROUPMASK structure is not documented. Until relatively recently, it was known only from type information in public symbol files (in Windows Vista and higher). A C-language definition has been published by Microsoft in NTWMI.H from the Windows Driver Kit (WDK) for the original release of Windows 10 and for Version 1511. This disclosure is not repeated in subsequent editions and is here thought to be an oversight. Still, published it is, which means that this note uses Microsoft’s names throughout, notably for the many bits that Microsoft has yet defined for types of event that can be monitored through an NT Kernel Logger.

Layout

The PERFINFO_GROUPMASK structure is 0x20 bytes in both 32-bit and 64-bit Windows for all versions 5.2 and higher, but is 0x24 bytes in version 5.1. Symbol files for version 6.0 and higher show just the one member:

ULONG Masks [8];

The PERFINFO_GROUPMASK in version 5.1 certainly is nine dwords but the purpose of the last is not understood much beyond knowing that it is not treated just as an extra mask as if to allow for more types of event. That the last dword is formally separated from the Masks is mere supposition.

Masks

The first point to the PERFINFO_GROUPMASK is simply that its eight array elements allow 256 bits instead of the 32 that can be passed to and fro in the EnableFlags. A second point to the PERFINFO_GROUPMASK is that each ULONG is a group of bits for enabling similar types of events. It will often be wanted that multiple types of event in the one group are enabled concurrently. This is helped by adopting a conventional representation of each supported type of event by one 32-bit value in which the high 3 bits encode the group’s index within the array.

For instance, to enable the somewhat quirky tracing of what may be going wrong with the ERESOURCE structures that provide for synchronising exclusive and shared ownership of abstracted kernel-mode resources, the kernel needs to see that the 0x00020000 bit is set in Masks [1]. The conventional representation is the one symbol PERF_SYNC_OBJECTS whose numerical value is 0x20020000.

The merit of this convention is that values that have the same index—corresponding to types of events that are in the same group—are easily combined. For instance, two types of events for instrumenting spin locks are in the same group. Their numerical representations PERF_SPINLOCK (0x20010000) and PERF_SPINLOCK_CNTRS (0x20200000) can be combined as 0x20210000, for which Microsoft helpfully defines the symbol PERF_SPININSTR.

Macros in the semi-secret NTWMI.H provide the programmers of ETW clients with the easy means to set or clear the desired bit in the desired Masks element of their PERFINFO_GROUPMASK by supplying the address, of course, and just one symbol to select the bit. For the kernel’s programmers, the same header defines an inline routine that tests for the bit, again just from one symbol and the address.

Masks [0]

The first element arguably is the EnableFlags:

Indication of support for version 5.0 applies only to the bit in the EnableFlags. as the precursor to the PERFINFO_GROUPMASK.

Please note a general caution about versions that are indicated for any of these masks, above and below. This analysis is preliminary at best. That a version is indicated does mean that use is known in those versions. It does not mean that earlier versions have no support, just that I don’t know of it or that I haven’t yet recorded it here. It’s a rough indication only. If it ever seems that presenting it is not better than nothing, it will be withdrawn.

Masks [1]

Masks [2]

Masks [3]

Apparently, no flags are yet defined for mask number 3.

Masks [4]

Masks [5]

Masks [6]

Masks [7]