WMI_BUFFER_HEADER

The WMI_BUFFER_HEADER structure begins each buffer that an event logger, or more formally an event tracing sesssion, uses for storing event data on the way to an Event Trace Log (ETL) file. Indeed, because such buffers are flushed as is, header and all, the structure is not only at the beginning of every ETL file but also recurs throughout.

The rest of each buffer, after the fixed-size WMI_BUFFER_HEADER, is a sequence of variable-size WMI data blocks. In the formulation for Windows Management Instrumentation (WMI), each data block begins with a fixed-size WNODE_HEADER. Event Tracing for Windows (ETW) repurposes the scheme so that each data block begins with one of several possible fixed-size Trace Headers.

Documentation Status

The WMI_BUFFER_HEADER structure is not documented. A C-language definition is published in the NTWMI.H header from some editions of the Windows Driver Kit (WDK) for Windows 10.

Layout

The WMI_BUFFER_HEADER is 0x48 bytes in both 32-bit and 64-bit Windows in all versions for which the structure is known. Offsets, names and types below are from type information for the structure in symbol files for the kernel. The modern layout has been very nearly stable since Windows 7. Earlier versions are dealt with far below.

Offset Definition Versions
0x00
ULONG BufferSize;
6.1 and higher
0x04
ULONG SavedOffset;
6.1 and higher
0x08
ULONG volatile CurrentOffset;
6.1 and higher
0x0C
LONG volatile ReferenceCount;
6.1 and higher
0x10
LARGE_INTEGER TimeStamp;
6.1 and higher
0x18
LONGLONG SequenceNumber;
6.1 and higher
0x20
union {
    ULONG Padding0 [2];
    SINGLE_LIST_ENTRY SlistEntry;
    WMI_BUFFER_HEADER *NextBuffer;
};
6.1 only
union {
    struct {
        ULONGLONG ClockType : 3;
        ULONGLONG Frequency : 61;
    };
    SINGLE_LIST_ENTRY SlistEntry;
    WMI_BUFFER_HEADER *NextBuffer;
};
6.2 and higher
0x28
ETW_BUFFER_CONTEXT ClientContext;
6.1 and higher
0x2C
ETW_BUFFER_STATE State;
6.1 and higher
0x30
ULONG Offset;
6.1 and higher
0x34
USHORT BufferFlag;
6.1 and higher
0x36
USHORT BufferType;
6.1 and higher
0x38
union {
    ULONG Padding1 [4];
    ETW_REF_CLOCK ReferenceTime;
    LIST_ENTRY GlobalEntry;
    struct {
        PVOID Pointer0;
        PVOID Pointer1;
    };
};
6.1 and higher

When a WMI_BUFFER_HEADER is saved in an ETL files, the BufferSize might as well be regarded as the offset in bytes to the next WMI_BUFFER_HEADER.

The NTWMI.H header tells us Microsoft’s names for the possible flags and types. Since these are defined by macros and thus do not pass into symbol files as type information, they would otherwise not be known.

Buffer Flag

The following are defined for the BufferFlag at offset 0x34:

Value Name
0x0000 ETW_BUFFER_FLAG_NORMAL
0x0001 ETW_BUFFER_FLAG_FLUSH_MARKER
0x0002 ETW_BUFFER_FLAG_EVENTS_LOST
0x0004 ETW_BUFFER_FLAG_BUFFER_LOST
0x0008 ETW_BUFFER_FLAG_RTBACKUP_CORRUPT
0x0010 ETW_BUFFER_FLAG_RTBACKUP
0x0020 ETW_BUFFER_FLAG_PROC_INDEX
0x0040 ETW_BUFFER_FLAG_COMPRESSED

I leave for another time the question of which versions introduced which flags.

Buffer Type

For the BufferType at offset 0x36:

Value Name
0x0000 ETW_BUFFER_TYPE_GENERIC
0x0001 ETW_BUFFER_TYPE_RUNDOWN
0x0002 ETW_BUFFER_TYPE_CTX_SWAP
0x0003 ETW_BUFFER_TYPE_REFTIME
0x0004 ETW_BUFFER_TYPE_HEADER
0x0005 ETW_BUFFER_TYPE_BATCHED
0x0006 ETW_BUFFER_TYPE_EMPTY_MARKER
0x0007 ETW_BUFFER_TYPE_DBG_INFO
0x0008 ETW_BUFFER_TYPE_MAXIMUM

Archaeology

The earliest that the WMI_BUFFER_HEADER structure is known from symbol files is for Windows XP SP3 and Windows Server 2003 SP2. It is recognisable, but the attempt to begin with the documented WNODE_HEADER leaves the layout so unwieldly that it seems better presented separately for anyone who cares for the history.

Offset Definition Versions
0x00
union {
    WNODE_HEADER Wnode;
    /*  structures, see below  */
};
5.1 from Windows XP SP3;
5.2 from Windows Server 2003 SP2
union {
    WNODE_HEADER Wnode;
    /*  structure, see below  */
};
6.0 only
0x30
ULONG Offset;
5.1 from Windows XP SP3;
5.2 from Windows Server 2003 SP2;
6.0 and higher
0x34
ULONG EventsLost;
5.1 from Windows XP SP3 only
USHORT BufferFlag;
5.2 from Windows Server 2003 SP2, and higher
0x36
USHORT BufferType;
5.2 from Windows Server 2003 SP2, and higher
0x38
union {
    GUID InstanceGuid;
    struct {
        PVOID LoggerContext;
        SINGLE_LIST_ENTRY GlobalEntry;
    };
};
5.1 from Windows XP SP3;
5.2 from Windows Server 2003 SP2
union {
    ULONG Padding1 [4];
    LARGE_INTEGER StartTime;
    LIST_ENTRY Entry;
    SINGLE_LIST_ENTRY SlistEntry;
    struct {
        WMI_BUFFER_HEADER *NextBuffer;
        SINGLE_LIST_ENTRY GlobalEntry;
    };
};
6.0 before Windows Vista SP1
union {
    ULONG Padding1 [4];
    LARGE_INTEGER StartTime;
    LIST_ENTRY Entry;
    struct {
        PVOID Padding2;
        SINGLE_LIST_ENTRY GlobalEntry;
    };
    struct {
        PVOID Pointer0;
        PVOID Pointer1;
    };
};
6.0 from Windows Vista SP1 and higher

Before version 6.0, the WNODE_HEADER is in union with two unnamed structures. The first was dropped when the two meaningful members, SlistEntry and Entry, were moved beyond the WNODE_HEADER to offset 0x38.

Offset Definition Versions
0x00
ULONGLONG Reserved1;
5.1 from Windows XP SP3;
5.2 from Windows Server 2003 SP2
0x08
ULONGLONG Reserved2;
5.1 from Windows XP SP3;
5.2 from Windows Server 2003 SP2
0x10
LARGE_INTEGER Reserved3;
5.1 from Windows XP SP3;
5.2 from Windows Server 2003 SP2
0x18
union {
    struct {
        PVOID Alignment;
        SINGLE_LIST_ENTRY SlistEntry;
    };
    LIST_ENTRY Entry;
};
5.1 from Windows XP SP3;
5.2 from Windows Server 2003 SP2

The second of the original structures in union with the WNODE_HEADER remained in union through all of version 6.0, by when most members had the positions and types they would retain when the union was discarded.

Offset Definition Versions
0x00
LONG ReferenceCount;
5.1 from Windows XP SP3;
5.2 from Windows Server 2003 SP2
ULONG BufferSize;
6.0 and higher
0x04
ULONG SavedOffset;
5.1 from Windows XP SP3;
5.2 from Windows Server 2003 SP2;
6.0 and higher
0x08
ULONG CurrentOffset;
5.1 from Windows XP SP3;
5.2 from Windows Server 2003 SP2
ULONG volatile CurrentOffset;
6.0 and higher
0x0C
ULONG UsePerfClock;
5.1 from Windows XP SP3;
5.2 from Windows Server 2003 SP2
LONG volatile ReferenceCount;
6.0 and higher
0x10
LARGE_INTEGER TimeStamp;
5.1 from Windows XP SP3;
5.2 from Windows Server 2003 SP2
union {
    LARGE_INTEGER TimeStamp;
    LARGE_INTEGER StartPerfClock;
};
6.0 only
0x18
GUID Guid;
5.1 from Windows XP SP3;
5.2 from Windows Server 2003 SP2
LONGLONG SequenceNumber;
6.0 and higher
0x20
ULONG Spare0;
ULONG Spare1;
6.0 before Windows Vista SP1
union {
    ULONG Padding0 [2];
    SINGLE_LIST_ENTRY SlistEntry;
    WMI_BUFFER_HEADER *NextBuffer;
};
6.0 from Windows Vista SP1 to 6.1
0x28
WMI_CLIENT_CONTEXT ClientContext;
5.1 from Windows XP SP3;
5.2 from Windows Server 2003 SP2
ETW_BUFFER_CONTEXT ClientContext;
6.0 and higher
0x2C
union {
    WMI_BUFFER_STATE State;
    ULONG Flags;
};
5.1 from Windows XP SP3;
5.2 from Windows Server 2003 SP2
union {
    ETW_BUFFER_STATE State;
    ULONG Flags;
};
6.0 and higher