ETW_REG_ENTRY

The ETW_REG_ENTRY structure (formally _ETW_REG_ENTRY) is the kernel’s representation of an event registration object. This can exist as a formal object, with handles and access control, or not. The typical case in which an instance is created as a formal object is when an event provider is registered from user mode. The object type is named EtwRegistration. Note that the kernel has no exported variable for this object type, presumably because only the kernel is ever involved in interpreting a handle that refers to such an object.

Documentation Status

The ETW_REG_ENTRY structure is not documented.

Layout

For a non-trivial structure that is plainly very much internal to the kernel, the ETW_REG_ENTRY has been relatively stable. There has been growth, inevitably, but the only rearrangement was that version 6.2 compacts a few members and moves them towards the end.

The preceding sizes, and the offsets, types and names in the table below are from Microsoft’s symbol files for the kernel starting with Windows Vista.

LIST_ENTRY RegList;

LIST_ENTRY GroupRegList;

ETW_GUID_ENTRY *GuidEntry;

ETW_GUID_ENTRY *GroupEntry;

USHORT Index;

USHORT Flags;

UCHAR EnableMask;

union {
    /*  changing members, see below  */
};

union {
    EPROCESS *Process;
    struct {
        PVOID Callback;
        PVOID CallbackContext;
    };
};

union {
    EPROCESS *Process;
    struct {
        PVOID CallbackContext;
        PVOID Callback;
    };
};

USHORT Index;

union {
    UCHAR Flags;
    struct {
        /*  bit fields, follow link  */
    };
};

union {
    USHORT Flags;
    struct {
        /*  bit fields, follow link  */
    };
};

UCHAR EnableMask;

UCHAR GroupEnableMask;

UCHAR HostEnableMask;

UCHAR HostGroupEnableMask;

BOOLEAN UseDescriptorType;

ETW_PROVIDER_TRAITS *Traits;

Any number of registrations can be opened to any one event provider. The ETW_REG_ENTRY structures for the registrations are linked through the RegList member to the RegListHead in the ETW_GUID_ENTRY that represents the provider (and whose address is the GuidEntry). There are also ETW_REG_ENTRY structures that exist only to support a notification mechanism. These reply objects are not associated with any provider. They have their own list, again linking through RegList, but with a head that is an internal variable in the kernel’s data.

Each registration allows that its holder can write events through the provider. On the other side, the provider can be accessed by as many as eight loggers, known more formally as event tracing sessions. The eight bits of the EnableMask track which of the possible loggers are enabled.

Reply Queue and Slot

Space for four pointers in the middle of the structure is used very differently in the different types of object.

ULONG SessionId;

ETW_REPLY_QUEUE *ReplyQueue;

ETW_REG_ENTRY *ReplySlot [4];

ETW_QUEUE_ENTRY *ReplySlot [4];

struct {
    PVOID Caller;
    ULONG SessionId;
};

The ReplyQueue is meaningful in a registration object that has DbgReplyRegistration set among the Flags to denote that it exists to support the retrieval of replies to a notification.

A registration object for which DbgUserRegistration is set can be sent notifications which may request replies. The ReplySlot array is how the replies are kept until their retrieval.

The SessionId and later the Caller are meaningful only for kernel-mode registrations, i.e., when DbgKernelRegistration is set. The Caller is in fact older but was kept separately from the ETW_REG_ENTRY as a member of the ETW_PROVIDER_TABLE_ENTRY.