ETW_REGISTRATION_ENTRY

Right from its introduction for Windows 2000, before it even had its current name, Event Tracing for Windows (ETW) has parallel implementations in kernel and user modes. The practical difference is not just with where the code is but with where the trace buffers are managed. One aim of ETW is that events are written quickly into trace buffers which are then serviced independently from a logger thread, e.g., to flush full buffers to an Event Trace Log (ETL) file. In an important special case for programs that trace their own diagnostics, an event provider that executes as a user-mode process may be enabled into a tracing session that executes in the same process and chooses the user-mode ETW implementation. For such a tracing session, the trace buffers are managed in user mode and writing an event (to a trace buffer) avoids the delay of going to and from kernel mode. This of course requires a substantial user-mode implementation, while also retaining access to the kernel-mode implementation in case the same provider is also enabled into a tracing session in a different process. In this more general case for which writing an event to a trace buffer means sending it to the kernel, some substance is desirable in the user-mode implementation so that the expense of sending an event to the kernel is avoided if it can be known that the event isn’t wanted by any tracing session that has kernel-mode tracing buffers.

Thus does it happen that NTDLL keeps no small amount of its own state about each user-mode registration of an event provider in addition to the ETW_REG_ENTRY that the kernel keeps. The ETW_REGISTRATION_ENTRY structure is this user-mode state.

Documentation Status

The ETW_REGISTRATION_ENTRY structure is not documented. Neither is it known even from public symbol files. The only public disclosure that is yet known of this structure’s name by Microsoft is that the WMITRACE.DLL debugger extension knows to look for it to support its obsolete !regtable command. The suggestion is strong that the type information that WMITRACE needs for this is available only in private symbol files and even then only for Windows 7.

Layout

The ETW_REGISTRATION_ENTRY has been relatively stable. Windows 7 saw an insertion, which lengthened the structure. The only significant change and reordering came with Windows 8 and shows in the relevant API functions as a reinterpretation of the opaque REGHANDLE.

These sizes, and the offsets, types and names in the detailed layout below, come from inspection of the binaries for NTDLL. The user-mode registration entry has some points in common with the two kernel-mode structures ETW_REG_ENTRY and ETW_GUID_ENTRY which are known from public symbol files for the kernel, but the correspondence is not close enough even for suppositions of Microsoft’s names and types. A smattering of such names and types are inferred with reasonable certainty by matching known use with the names that WMITRACE seeks from private symbol files. Where the use continues to later versions, the corresponding names and types are assumed to too.

GUID ProviderGuid;

<unknown-type> RegistrationHandle;

PVOID Callback;

PVOID Context;

ULONG Type;

struct {
    /*  USHORT bit fields, see below  */
};

The Type takes its values from the ETW_NOTIFICATION_TYPE enumeration. Windows 8 narrows it to 16 bits and squeezes in a one-bit flag. Windows 10 slips in another.

USHORT Type : 15;

USHORT Type : 14;