ETHREAD

The ETHREAD structure is the kernel’s representation of a thread object. For instance, if the ObReferenceObjectByHandle function successfully resolves a handle though directed to do so only if the object type is PsThreadType, then the pointer that the function produces for the object is a pointer to an ETHREAD.

Many functions that are exported from the kernel, e.g., for use by drivers, provide for referring to a thread object through a pointer to an ETHREAD. However, the pointer is intended just as an identifier: the structure itself is plainly meant to be opaque outside the kernel.

Variability

Since the ETHREAD structure is internal to the kernel, it should not surprise that the layout changes greatly between Windows versions and even between builds. Some sense of the variability can be gained just from the structure’s changing size. In the following table, different builds of the same version are distinguished as early, late and even very late because they are known to vary the structure even if they don’t change the size. These descriptions are then used as a shorthand throughout this article and its companions.

Layout

Offsets, types and names in the tables that follow, are from Microsoft’s symbol files for the kernel starting with Windows 2000 SP3. Since symbol files for earlier versions do not contain type information for the ETHREAD, Microsoft’s names and types are something of a guess from inspection of how the kernel in those versions uses the ETHREAD. Where use of a member corresponds closely with that of a version for which type information is available in Microsoft’s symbol files, it seems reasonable to suppose continuity. Some use, however, has no correspondence, the code having changed too much. Even where the use hasn’t changed so much, tracking down the correspondence exhaustively would be difficult, if not impossible, even with source code.

For all versions, it is well known that the ETHREAD starts with a KTHREAD. The latter is the Kernel Core’s representation of the thread object. It is itself a dispatcher object, which has the useful effect that a handle to an ETHREAD can be waited on. It gets signalled when the thread terminates.

Almost all the shifting of offsets of ETHREAD members between versions is explained by the KTHREAD being even more variable—indeed, much more variable—than the ETHREAD. The only known difference between Windows Server 2003 SP1 and SP2 for the 64-bit builds is that the KTHREAD shrank. To save space, “late 5.2” for the 32-bit builds stands for “v. late 5.2” also.

KTHREAD Tcb;

LARGE_INTEGER CreateTime;

union {
    LARGE_INTEGER CreateTime;
    struct { 
        UINT NestedFaultCount : 2;  // 0x00000003
        UINT ApcNeeded : 1;         // 0x00000004
    };
};

LARGE_INTEGER CreateTime;

In those builds that have CreateTime share space with bit fields, the CreateTime actually is in bits 3 to 63 as if it too is a bit field. It’s not that the low 3 bits are lost, but that the whole is shifted left by 3 bits.

union {
    LARGE_INTEGER ExitTime;
    LIST_ENTRY LpcReplyChain;
};

union {
    LARGE_INTEGER ExitTime;
    LIST_ENTRY LpcReplyChain;
    LIST_ENTRY KeyedWaitChain;
};

union {
    LARGE_INTEGER ExitTime;
    LIST_ENTRY KeyedWaitChain;
};

union {
    LONG ExitStatus;
    PVOID OfsChain;
};

LONG ExitStatus;

PVOID ChargeOnlySession;

LIST_ENTRY PostBlockList;

union {
    LIST_ENTRY PostBlockList;
    struct {
        /*  packed members, see below  */
    };
};

Take away the construction, and these are the members that are packed with PostBlockList:

PVOID ForwardLinkShadow;

PVOID StartAddress;

Yes, there is a plan to write something here.

LIST_ENTRY TerminationPortList;

union {
    TERMINATION_PORT *TerminationPort;
    ETHREAD *ReaperLink;
    PVOID KeyedWaitValue;
};

union {
    TERMINATION_PORT *TerminationPort;
    ETHREAD *ReaperLink;
    PVOID KeyedWaitValue;
    PVOID Win32StartParameter;
};

union {
    TERMINATION_PORT *TerminationPort;
    ETHREAD *ReaperLink;
    PVOID KeyedWaitValue;
};

KSPIN_LOCK ActiveTimerListLock;

LIST_ENTRY ActiveTimerListHead;

CLIENT_ID Cid;

The Cid holds the process and thread IDs that represent the thread in user mode, notably for API functions that let user-mode clients open a handle to a thread. For some measure of how these IDs were at least originally intended solely for client-level identification, consider that the kernel did not originally export functions that allow kernel-mode software to gets these IDs even for the current thread. The PsGetCurrentProcessId and PsGetCurrentThreadId functions do nothing but extract the IDs from the Cid for the current thread, but they are not exported until version 4.0 (and were not immediately documented). The same straightforward extraction but for an arbitrary thread is done by the PsGetThreadProcessId and PsGetThreadId functions, but these aren’t exported until version 5.1 (apparently still without documentation).

KSEMAPHORE LpcReplySemaphore;

union {
    KSEMAPHORE LpcReplySemaphore;
    KSEMAPHORE KeyedWaitSemaphore;
};

union {
    KSEMAPHORE KeyedWaitSemaphore;
    KSEMAPHORE AlpcWaitSemaphore;
};

union {
    PVOID LpcReplyMessage;
    PVOID LpcWaitingOnPort;
};

ULONG LpcReplyMessageId;

ULONG PerformanceCountLow;

TOKEN *Token;

BOOLEAN CopyOnOpen;

BOOLEAN EffectiveOnly;

BOOLEAN LpcExitThreadCalled;

SECURITY_IMPERSONATION_LEVEL ImpersonationLevel;

PS_IMPERSONATION_INFORMATION *ImpersonationInfo;

PS_CLIENT_SECURITY_CONTEXT ClientSecurity;

The names for the version 3.10 members Token, CopyOnOpen, EffectiveOnly and ImpersonationLevel are here duplicated from the structure that symbol files later name as a PS_IMPERSONATION_INFORMATION. In effect, version 3.10 has the whole of this structure where later versions have only a pointer to it. See, however, that version 3.10 doesn’t actually have the structure as a member, named or not, due to intrusion of the apparently unrelated LpcExitThreadCalled (which soon moves to nearly the end of the KTHREAD).

LIST_ENTRY IrpList;

ULONG_PTR TopLevelIrp;

DEVICE_OBJECT *DeviceToVerify;

ULONG ReadClusterSize;

BOOLEAN ForwardClusterOnly;

BOOLEAN DisablePageFaultClustering;

BOOLEAN DeadThread;

BOOLEAN HideFromDebugger;

BOOLEAN HasTerminated;

ULONG HasTerminated;

EEVENT_PAIR *EventPair;

The EventPair is the address of an event-pair object for a user-mode client and server to synchronise their work through the NTDLL functions NtSetLowWaitHighThread and NtSetHighWaitLowThread. That Microsoft used the name EventPair for this member is known from the USERKDX.DLL debugger extension for Windows NT 4.0. Type information in CRASHLIB.LIB from an SDK for Windows NT 4.0 not only names the member but its type.

ACCESS_MASK GrantedAccess;

KPROCESS *ThreadsProcess;

PVOID StartAddress;

LIST_ENTRY PostBlockList;

PSP_RATE_APC *RateControlApc;

PSP_CPU_QUOTA_APC *CpuQuotaApc;

union {
    PVOID Win32StartAddress;
    ULONG LpcReceivedMessageId;
};

PVOID Win32StartAddress;

BOOLEAN LpcExitThreadCalled;

BOOLEAN HardErrorsAreDisabled;

BOOLEAN LpcReceivedMsgIdValid;

BOOLEAN ActiveImpersonationInfo;

LONG PerformanceCountHigh;

PVOID ChargeOnlySession;

PVOID SparePtr0;

PVOID LegacyPowerObject;

LIST_ENTRY ThreadListEntry;

Appended for Windows XP

EX_RUNDOWN_REF RundownProtect;

EX_PUSH_LOCK ThreadLock;

ULONG LpcReplyMessageId;

ULONG ReadClusterSize;

ACCESS_MASK GrantedAccess;

LONG volatile MmLockOrdering;

LONG volatile CmLockOrdering;

Windows XP gathered seven booleans into bit fields in three sets, whose assignment of bits to functionality inevitably changes through successive versions:

union {
    ULONG CrossThreadFlags;
    struct {
        /*  bit fields, follow link  */
    };
};

union {
    ULONG SameThreadPassiveFlags;
    struct {
        /*  bit fields, follow link  */
    };
};

union {
    ULONG SameThreadApcFlags;
    struct {
        /*  bit fields, follow link  */
    };
};

For who knows what reason, two booleans weren’t changed to bit fields but were merely shifted to the structure’s end.

BOOLEAN ForwardClusterOnly;

BOOLEAN CacheManagerActive;

BOOLEAN DisablePageFaultClustering;

Appended for Windows Server 2003 SP1

For all that the build of version 5.2 for Windows Server 2003 SP1 rearranged the KTHREAD, it added just one byte beyond in the ETHREAD, and it anyway fits into alignment space. Indeed, through versions 5.1 and 5.2, the ETHREAD is in some sense very stable: that members shift and that the structure changes size is only because of the KTHREAD.

Even after this addition for Windows Server 2003 SP1, one byte of unnamed alignment space remained until Windows 7 found a use for it:

UCHAR ActiveFaultCount;

UCHAR LockOrderState;

Appended for Windows Vista

ULONG PerformanceCountLowReserved;

LONG PerformanceCountHighReserved;

ULONG_PTR AlpcMessageId;

union {
    PVOID AlpcMessage;
    ULONG AlpcReceiveAttributeSet;
};

LONG ExitStatus;

LIST_ENTRY AlpcWaitListEntry;

NTSTATUS ExitStatus;

ULONG CacheManagerCount;

Appended for Windows 7

ULONG IoBoostCount;

ULONG IoQoSBoostCount;

ULONG IoQoSThrottleCount;

ULONG KernelStackReference;

LIST_ENTRY BoostList;

LIST_ENTRY DeboostList;

KSPIN_LOCK BoostListLock;

KSPIN_LOCK IrpListLock;

PVOID ReservedForSynchTracking;

SINGLE_LIST_ENTRY CmCallbackListHead;

Appended for Windows 8

GUID const *ActivityId;

PVOID WnfContext;

SINGLE_LIST_ENTRY SeLearningModeListHead;

PVOID VerifierContext;

ULONG KernelStackReference;

See that for 64-bit Windows 8, the 32-bit KernelStackReference left the structure to end with four bytes of alignment padding. That Windows 8.1 followed with a pointer (see next) turned this padding into wasted space which the 1809 edition of Windows 10 reclaimed by moving the member to fill the alignment space that 64-bit Windows 8 also wasted immediately before the BoostList (above).

Appended for Windows 8.1

PVOID AdjustedClientToken;

ULONG UserFsBase;

ULONGLONG UserGsBase;

PVOID PicoContext;

Appended for Windows 10

PVOID WorkingOnBehalfClient;

PVOID WorkOnBehalfThread;

PS_PROPERTY_SET PropertySet;

PVOID PicoContext;

ULONG UserFsBase;

ULONG_PTR UserFsBase;

ULONG_PTR UserGsBase;

THREAD_ENERGY_VALUES *EnergyValues;

ULONG volatile CmCellReferences;

PVOID CmDbgInfo;

union {
    ULONG_PTR SelectedCpuSets;
    ULONG_PTR *SelectedCpuSetsIndirect;
};

ESILO *Silo;

EJOB *Silo;

Whether silos are their own type of object, as in the original Windows 10, or are special types of job object, the Silo member can have the special value -3 to mean that the thread is not itself attached to a silo but the thread’s process may be.

UNICODE_STRING *ThreadName;

CONTEXT *SetContextState;

ULONG ReadyTime;

PVOID SparePointer;

ULONG LastExpectedRunTime;

ULONG HeapData;

LIST_ENTRY OwnerEntryListHead;

ULONG_PTR DisownedOwnerEntryListLock;

LIST_ENTRY DisownedOwnerEntryListHead;

KLOCK_ENTRY *LockEntries [0x48];

PVOID CmDbgInfo;