KTRAP_FRAME (amd64)

The KTRAP_FRAME (formally a _KTRAP_FRAME) is a structure in which the kernel saves the state of execution that gets interrupted for diversion to the kernel, whether from external hardware, the processor itself (for a trap or fault) or by software executing an int or syscall instruction. The KTRAP_FRAME is highly specific to the processor architecture. This page concerns itself only with 64-bit Windows for the processor architecture that’s variously named amd64 or x64. The x86 KTRAP_FRAME is presented separately.

Because of the structure’s role in all ways in and out of the kernel, the KTRAP_FRAME may be the best known of all formally undocumented kernel-mode structures. Indeed, this article exists only for the occasional convenience of having the names and offsets for ready reckoning (and, for the historian, of tracking the strikingly few changes).

Documentation Status

Though the KTRAP_FRAME structure is not formally documented, the structure’s x64 implementation has a C-language definition in NTDDK.H from every applicable Device Driver Kit (DDK) or Windows Driver Kit (WDK).

Layout

The KTRAP_FRAME for 64-bit Windows is 0x0190 bytes in all known versions. Names, types and offsets in the following are from NTDDK.H in various driver kits, checked against the kernel’s symbol files.

ULONG64 P1Home;

ULONG64 P2Home;

ULONG64 P3Home;

ULONG64 P4Home;

ULONG64 P5;

KPROCESSOR_MODE PreviousMode;

KIRQL PreviousIrql;

UCHAR FaultIndicator;

UCHAR ExceptionActive;

ULONG MxCsr;

ULONG64 Rax;

ULONG64 Rcx;

ULONG64 Rdx;

ULONG64 R8;

ULONG64 R9;

ULONG64 R10;

ULONG64 R11;

union {
    ULONG64 GsBase;
    ULONG64 GsSwap;
};

M128A Xmm0;

M128A Xmm1;

M128A Xmm2;

M128A Xmm3;

M128A Xmm4;

M128A Xmm5;

union {
    ULONG64 FaultAddress;
    ULONG64 ContextRecord;
    ULONG64 TimeStamp;
};

union {
    ULONG64 FaultAddress;
    ULONG64 ContextRecord;
    ULONG64 TimeStampCKCL;
};

union {
    ULONG64 FaultAddress;
    ULONG64 ContextRecord;
};

ULONG64 Dr0;

ULONG64 Dr1;

ULONG64 Dr2;

ULONG64 Dr3;

ULONG64 Dr6;

ULONG64 Dr7;

union {
    struct {
        ULONG64 DebugControl;
        ULONG64 LastBranchToRip;
        ULONG64 LastBranchFromRip;
        ULONG64 LastExceptionToRip;
        ULONG64 LastExceptionFromRip;
    };
    struct {
        ULONG64 LastBranchControl;
        ULONG LastBranchMSR;
    };
};

struct {
    ULONG64 DebugControl;
    ULONG64 LastBranchToRip;
    ULONG64 LastBranchFromRip;
    ULONG64 LastExceptionToRip;
    ULONG64 LastExceptionFromRip;
};

USHORT SegDs;

USHORT SegEs;

USHORT SegFs;

USHORT SegGs;

ULONG64 TrapFrame;

ULONG64 Rbx;

ULONG64 Rdi;

ULONG64 Rsi;

ULONG64 Rbp;

union {
    ULONG64 ErrorCode;
    ULONG64 ExceptionFrame;
};

union {
    ULONG64 ErrorCode;
    ULONG64 ExceptionFrame;
    ULONG64 TimeStampKlog;
};

union {
    ULONG64 ErrorCode;
    ULONG64 ExceptionFrame;
};

ULONG64 Rip;

USHORT SegCs;

USHORT Fill1 [3];

UCHAR Fill0;

UCHAR Logging;

USHORT Fill1 [2];

ULONG EFlags;

ULONG Fill2;

ULONG64 Rsp;

USHORT SegSs;

USHORT Fill3 [1];

USHORT Fill3;

LONG CodePatchCycle;

ULONG Fill4;

The KTRAP_FRAME ends—from offset 0x0160 onwards—with items that the processor itself either does or may put on the stack before the kernel sees the interrupt. The structure’s formal layout has always provided that the kernel may squeeze in items of its own where the processor allows 8 bytes though only 16 or 32 bits are meaningful.

Note that the structure does not provide for saving all the general registers. The kernel does not itself use r12 to r15 during entry or exit, and does not save them in anticipation that code deeper into the handling may use them. The understanding is instead that all kernel-mode routines that use r12 to r15 (or xmm6 or xmm7) will do the saving and restoring themselves. In practice, of course, this knowledge is built into the compiler.