DEV Community: bekoo

Manipulating QEMU Hardwares with Bootkit

bekoo — Fri, 19 Jun 2026 19:54:34 +0000

Boot a fresh QEMU instance and run dmidecode -t 1 inside it:

System Information
    Manufacturer: QEMU
    Product Name: Standard PC (Q35 + ICH9, 2009)
    Version: pc-q35-8.2
    Serial Number: Not Specified
    UUID: ...
    Family: Not Specified

That output is not just cosmetic. Every piece of software that has a reason to know whether it is running inside a virtual machine reads exactly this table — EDRs, anti-cheat engines, sandbox detectors, hypervisor fingerprinting routines. The string "QEMU" in the Manufacturer field is, for most of them, a hard stop. Analysis terminates, behavior changes, the sample goes quiet.

The question is where this data comes from and whether it can be changed before any of those tools get a chance to read it. The answer to the second part is yes — and the mechanism is a DXE driver that runs inside the firmware, before the OS loader is even invoked. This is what makes it a bootkit in the strict sense: code that executes at the firmware level and shapes what the operating system inherits.

What SMBIOS Actually Is

SMBIOS — System Management BIOS — is a specification maintained by DMTF. It defines a standard format for firmware to expose hardware identity information to the operating system. The spec has nothing to do with BIOS in the sense of boot firmware. It is purely a data contract: a layout agreement that says "here is where we put the machine's identity, and here is the structure you use to read it."

At some point during POST, the firmware constructs a contiguous block of records in physical memory and registers its location in one of two places depending on the SMBIOS version. For versions below 3.0, a 32-bit entry point structure sits somewhere between 0xF0000 and 0xFFFFF** carrying the signature SM. For 3.0 and above, a 64-bit entry point with SM3 can sit anywhere in the low 4GB. The OS finds this entry point, pulls the table address out of it, and from that point on it has everything it needs.

The table itself is a flat list. No index, no hash map, no random access mechanism. Records sit in memory back to back, and the only way to find a specific one is to walk from the beginning.

Each record is called a structure, and each structure has a type number. Type 0 is BIOS information. Type 1 is system information — manufacturer, product name, serial number, UUID. Type 2 is baseboard. Type 4 is processor. The list goes on to Type 127, which is the End-of-Table marker. When you hit 127, you stop walking.

A Single Record's Memory Layout

Each structure has two distinct sections sitting contiguously in memory.

The first section is the formatted region: a fixed-length header followed by typed fields. The header is always four bytes — one byte for the type, one for the length of the formatted region, two for a handle that uniquely identifies this record. After the header come the actual fields, and their sizes and meanings are defined by the spec per type. For Type 1, the formatted region is 27 bytes total.

The second section is the string pool. Immediately after the last byte of the formatted region, the firmware writes a sequence of null-terminated ASCII strings back to back. The entire pool is terminated by a double null — an empty string that signals the end.

Here is the part that trips people up: the fields in the formatted region do not hold strings. They hold one-byte indices. The Manufacturer field in Type 1 is not "QEMU" — it is 0x00, meaning "first string in the pool." ProductName is 0x02. SerialNumber is 0x03. An index of zero means the field is not populated.

So in memory, QEMU's Type 1 record looks roughly like this:

[ Type=1 | Len=27 | Handle=0x0001 | Manufacturer=1 | ProductName=2 | Version=3 | ... ]
[ "QEMU\0" ][ "Standard PC (Q35 + ICH9, 2009)\0" ][ "pc-q35-8.2\0" ][ \0 ]

To read Manufacturer, you skip Len bytes from the start of the record to land in the string pool, then walk forward past (index - 1) null terminators to reach the target string. This is not an abstraction — this is literally what every tool that reads SMBIOS does at the bottom of its call stack.

Why This Structure Exists

The split between fixed fields and a string pool is not accidental. The fixed region has a known, spec-defined size per type, which means a parser can jump over any record it does not understand without reading its contents — it just takes Hdr.Length bytes, skips to the string pool terminator, and moves on. This forward-compatibility property is intentional. A parser written against SMBIOS 2.4 can safely traverse a 3.1 structure it has never seen before.

The string pool being variable-length and trailing means the spec does not have to reserve fixed-width character buffers inside the struct for every string field. Serial numbers vary. Product names vary. Packing them into the formatted region would either waste space with padding or impose arbitrary length limits. The trailing pool sidesteps both problems.

The Code

Now that the memory layout is clear, the driver makes considerably more sense.

#include <Uefi.h>

#include <IndustryStandard/SmBios.h>
#include <Library/BaseMemoryLib.h>
#include <Library/UefiBootServicesTableLib.h>
#include <Library/UefiLib.h>
#include <Protocol/Smbios.h>

#include "CloakProfile.h"

typedef struct {
  EFI_SMBIOS_HANDLE Handle;
  UINT8             StrNo;
  CONST CHAR8      *Val;
} CLOAK_STR;

#define CLOAK_MAX_STR 64
STATIC CLOAK_STR mStr[CLOAK_MAX_STR];
STATIC UINTN     mStrCount = 0;

#define CLOAK_PUSH(H, IDX, VAL)                                  \
  do {                                                           \
    if ((IDX) != 0 && mStrCount < CLOAK_MAX_STR) {               \
      mStr[mStrCount].Handle = (H);                              \
      mStr[mStrCount].StrNo  = (UINT8)(IDX);                     \
      mStr[mStrCount].Val    = (VAL);                            \
      mStrCount++;                                               \
    }                                                            \
  } while (0)

EFI_STATUS
EFIAPI
VmCloakDxeEntryPoint (
  IN EFI_HANDLE        ImageHandle,
  IN EFI_SYSTEM_TABLE *SystemTable
  )
{
  EFI_SMBIOS_PROTOCOL     *SmBios;
  EFI_STATUS               Status;
  EFI_SMBIOS_HANDLE        Handle;
  EFI_SMBIOS_TABLE_HEADER *Rec;
  SMBIOS_TABLE_TYPE1      *Type = NULL;

  Status = gBS->LocateProtocol (&gEfiSmbiosProtocolGuid, NULL, (VOID **)&SmBios);
  if (EFI_ERROR (Status)) {
    Print (L"Failed to locate SMBIOS protocol: %r\n", Status);
    return Status;
  }

  mStrCount = 0;
  Handle    = SMBIOS_HANDLE_PI_RESERVED;

  while (SmBios->GetNext (SmBios, &Handle, NULL, &Rec, NULL) == EFI_SUCCESS) {
    switch (Rec->Type) {
      case EFI_SMBIOS_TYPE_SYSTEM_INFORMATION:
        Type = (SMBIOS_TABLE_TYPE1 *)Rec;

        UINT8 Uuid[16] = CLOAK_SYS_UUID;
        CopyMem (&Type->Uuid, Uuid, sizeof (Uuid));

        CLOAK_PUSH (Handle, Type->Manufacturer, CLOAK_SYS_MANUFACTURER);
        CLOAK_PUSH (Handle, Type->ProductName,  CLOAK_SYS_PRODUCT);
        CLOAK_PUSH (Handle, Type->Version,      CLOAK_SYS_VERSION);
        CLOAK_PUSH (Handle, Type->SerialNumber, CLOAK_SYS_SERIAL);
        CLOAK_PUSH (Handle, Type->SKUNumber,    CLOAK_SYS_SKU);
        CLOAK_PUSH (Handle, Type->Family,       CLOAK_SYS_FAMILY);
        break;
    }
  }

  for (UINTN i = 0; i < mStrCount; i++) {
    EFI_SMBIOS_HANDLE h  = mStr[i].Handle;
    UINTN             sn = mStr[i].StrNo;
    SmBios->UpdateString (SmBios, &h, &sn, (CHAR8 *)mStr[i].Val);
  }

  // UpdateString may have reallocated — Type pointer is now stale. Re-fetch.
  Handle = SMBIOS_HANDLE_PI_RESERVED;
  while (SmBios->GetNext (SmBios, &Handle, NULL, &Rec, NULL) == EFI_SUCCESS) {
    if (Rec->Type == EFI_SMBIOS_TYPE_SYSTEM_INFORMATION) {
      Type = (SMBIOS_TABLE_TYPE1 *)Rec;
      break;
    }
  }

  if (Type != NULL) {
    CHAR8 *StrPtr = (CHAR8 *)Type + Type->Hdr.Length;
    UINT8  Idx    = Type->Manufacturer;
    for (UINT8 i = 1; i < Idx; i++) {
      while (*StrPtr) StrPtr++;
      StrPtr++;
    }
    Print (L"Manufacturer after update: %a\n", StrPtr);
  }

  return EFI_SUCCESS;
}

Locating the Protocol

Status = gBS->LocateProtocol (&gEfiSmbiosProtocolGuid, NULL, (VOID **)&SmBios);

The driver's first move is finding EFI_SMBIOS_PROTOCOL. This is the firmware's own interface for reading and modifying SMBIOS records at runtime — before the OS is handed control. LocateProtocol walks the installed protocol list and hands back a pointer to the implementation. If this call fails, there is nothing to work with and the driver bails immediately.

Walking the Table

Handle = SMBIOS_HANDLE_PI_RESERVED;
while (SmBios->GetNext (SmBios, &Handle, NULL, &Rec, NULL) == EFI_SUCCESS) {
  switch (Rec->Type) {
    case EFI_SMBIOS_TYPE_SYSTEM_INFORMATION:

SMBIOS_HANDLE_PI_RESERVED is the sentinel value that tells GetNext to start from the beginning of the table. Each call advances Handle to the next record and writes the record pointer into Rec. This is the same traversal described in the layout section — no shortcut exists, so the driver walks every record until it finds what it needs. The switch on Rec->Type means everything except Type 1 passes through untouched.

UUID vs. Strings — Two Different Problems

Inside the Type 1 handler, the driver deals with two categories of fields.

UUID is a binary field — 16 raw bytes embedded directly in the formatted region. It has no pool index, it does not live in the string section. The write is direct:

UINT8 Uuid[16] = CLOAK_SYS_UUID;
CopyMem (&Type->Uuid, Uuid, sizeof (Uuid));

CopyMem overwrites the bytes in place. No pool traversal, no protocol call needed.

String fields are a different problem. Manufacturer, ProductName, SerialNumber and the rest are one-byte indices into the string pool. To change what they resolve to, you cannot touch the index byte — it already points to the right slot. You have to rewrite the actual string sitting at that slot in the pool, which may be a different length than what was there before. That is UpdateString's job, and it is the reason the queue exists.

The Queue — Why Not Call UpdateString Immediately

When UpdateString replaces a string with one of a different length, it has to resize the record in memory. The firmware may reallocate the entire block. If it does, Type — the pointer the driver is currently holding — becomes stale. It points to an address the firmware has already moved on from.

The driver avoids this by never calling UpdateString during the traversal loop. Every pending update is queued into mStr instead:

#define CLOAK_PUSH(H, IDX, VAL)                                  \
  do {                                                           \
    if ((IDX) != 0 && mStrCount < CLOAK_MAX_STR) {               \
      mStr[mStrCount].Handle = (H);                              \
      mStr[mStrCount].StrNo  = (UINT8)(IDX);                     \
      mStr[mStrCount].Val    = (VAL);                            \
      mStrCount++;                                               \
    }                                                            \
  } while (0)

IDX != 0 guards against unpopulated fields — index zero means "not present" in the SMBIOS spec, and passing it to UpdateString is undefined territory. Everything else is pushed onto the queue with its handle, its string slot number, and the replacement value.

Once the traversal loop exits and Type is no longer being touched, the driver drains the queue:

for (UINTN i = 0; i < mStrCount; i++) {
  EFI_SMBIOS_HANDLE h  = mStr[i].Handle;
  UINTN             sn = mStr[i].StrNo;
  SmBios->UpdateString (SmBios, &h, &sn, (CHAR8 *)mStr[i].Val);
}

Reallocation can now happen freely. Nothing holds a live pointer into the record at this point.

Refreshing the Pointer and Verifying

After UpdateString runs, the old Type pointer cannot be trusted regardless of whether reallocation actually occurred — the driver has no way to determine that. So it runs GetNext again from scratch to obtain a fresh pointer to the Type 1 record, then manually traverses the string pool to confirm the write landed:

CHAR8 *StrPtr = (CHAR8 *)Type + Type->Hdr.Length;
UINT8  Idx    = Type->Manufacturer;
for (UINT8 i = 1; i < Idx; i++) {
  while (*StrPtr) StrPtr++;
  StrPtr++;
}
Print (L"Manufacturer after update: %a\n", StrPtr);

Type + Hdr.Length lands exactly at the start of the string pool — the formatted region ends there and strings begin immediately after. The loop skips forward (Manufacturer - 1) null terminators to reach the correct slot. The inner while (*StrPtr) StrPtr++ walks past the current string's characters; the StrPtr++ after it steps over the null terminator. What remains at StrPtr is the target string, read back directly from the record the firmware now holds.

Here's the result from the shell:

Or we can check out this in System information tool of Windows:

Although i'm poor, i've ROG STRIX :>

[My Debugger Journey] Managing Execution Modes with NASM

bekoo — Fri, 12 Jun 2026 07:40:16 +0000

Starting from Reset Vector

I've already documented Reset Vector in my blog. You can read this header from my blog in detail.

Every x86-64 processor starts its life in a mode that has more in common with an 8086 from 1978 than with the machine you're actually running. At power-on, the hardware enforces a rigid initialization contract: CS is loaded with a base of 0xFFFF0000, the instruction pointer sits at 0xFFF0, and the resulting physical address — 0xFFFFFFF0 — is the reset vector, the first fetch the processor will ever make. From that point, control belongs to firmware. (Vol. 3A, §9.1.4 — Processor State After Reset).

What makes this interesting from a systems perspective is that the processor isn't truly in Real Mode at this stage — it's in a transitional state where the CS descriptor cache holds a base of 0xFFFF0000, but the visible CS register still reads 0xF000. The first far jump drops A20–A31 and collapses the processor into the lower megabyte, at which point you're in conventional 16-bit Real Mode with the full segment:offset constraint: physical address = segment × 16 + offset, maximum addressable space 1MB. (Vol. 3A, §9.1 — Processor State After Reset; i386 Reference §10.2.3).

Here's a figure from the intel's volume:

We can only know the state of the processor via CR0 register.

Real-Address Mode and the Segmented Memory Model

Real-Address Mode predates Protected Mode entirely. Before the 80286 introduced hardware-level memory protection and privilege rings, it was the only execution mode available on x86 hardware. The addressing model has not changed since the 8086: a 16-bit segment register is shifted left by 4 bits and added to a 16-bit offset to produce a physical address.

Physical Address = (Segment × 16) + Offset

Since both values are 16-bit, the maximum expressible address is 0xFFFF × 16 + 0xFFFF = 0x10FFEF — but the address bus on the original 8086 was 20 bits wide, so anything above 0x000FFFFF wraps. The addressable range is effectively capped at 1MB.

As a concrete example: if CS holds 0x2000 and IP holds 0x1234, the physical address resolves as:

0x2000 × 16 = 0x20000
0x20000 + 0x1234 = 0x21234

This calculation applies to every segment register — CS, DS, ES, SS — and to every memory access the processor makes in Real Mode. There is no page table, no descriptor table, no privilege check. The segment value is a raw base, not an index into any structure.

Calculating 0xFFFF0000 Address

First step is to calculate the address.

In all x86 processors, Real-Address Mode exists for one reason: backward compatibility with the 8086. It predates Protected Mode entirely, and every x86 processor since has initialized into it — not because it is useful at boot, but because the architecture requires it. The addressing model is unchanged from 1978: a 16-bit segment register is shifted left by 4 bits and added to a 16-bit offset, producing a 20-bit physical address. The addressable range is capped at 0x000FFFFF — the first 1MB.

This creates an immediate contradiction. The reset vector sits at 0xFFFFFFF0, the top of the 32-bit address space — well outside what Real Mode addressing can express. A processor that is both in Real Mode and fetching from 0xFFFFFFF0 should not be possible under the standard model.

The resolution is in the segment register's hidden descriptor cache:

Here's the trick: : Upon reset, the CS register’s Visible Selector is set to 0xF000, but the processor forcibly sets the CS Hidden Base Address to FFFF_0000 (Don’t forget Real Mode’s Segment:Offset addresses).

At reset, the visible CS register holds 0xF000, but the processor loads the cache with a base of 0xFFFF0000 rather than the value the normal shift-and-add calculation would produce. This base is hardwired into the reset state and bypasses the Real Mode formula entirely.

Therefore, the processor calculates the Reset Vector by combining the Hidden Base of CS with the value of EIP:

CS Base (0xFFFF0000) + EIP (0xFFF0) = 0xFFFFFFF0

We can also see this in QEMU:

After the reset, Paging (Bit 31) is disabled and Protection (Bit 0) is not enabled. If this Protection bit were 1, then it would indicate that the processer is in Protection Mode. Also we can see the result of CR0 in GDB:

Now the important section will come.

Fetching Instruction from the Reset Vector

Once the processor resolves 0xFFFFFFF0 and places it on the address bus, it has no knowledge of what backs that address. The processor issues the fetch; where it lands is entirely the chipset's decision.

The chipset — historically the Southbridge, on modern platforms the PCH (Platform Controller Hub) — sits between the processor and every peripheral on the board and monitors every address the processor puts on the bus. When it sees a request targeting the high-memory range around 0xFFFFFFF0, it does not forward that request to DRAM. DRAM has not been initialized at this point and would return garbage. Instead, the chipset routes the request to the SPI flash ROM carrying the BIOS or UEFI firmware.

The mechanism that governs this routing is a chipset configuration register: FWH_DEC_EN1 (Firmware Hub Decode Enable 1), located in the LPC (Low Pin Count) Interface Bridge register space. Its function is straightforward — it defines which physical memory ranges the chipset should redirect to the Firmware Hub rather than system RAM. At power-on, this register is preset by hardware to cover the reset vector region, so the very first fetch the processor issues is silently redirected to ROM before any software has had a chance to configure anything. The Intel 5 Series / 3400 Series Chipset datasheet documents this at page 487:

The mechanism works as follows:

Decoding Ranges: The FWH_DEC_EN1 register contains specific bits (like Bit 7, Bit 6, etc.) that correspond to different memory segments at the top of the 4GB address space (e.g., the range FFFF_0000h to FFFF_FFFFh).

Redirection: When the system resets, the hardware defaults for these bits are typically set to “Enabled”. This ensures that when the CPU requests 0xFFFFFFF0, the chipset instantly recognizes this address falls within the “BIOS Range.”

Fetching: Instead of sending the request to the DRAM controller, the chipset asserts the LPC (or SPI) bus signals, activating the Flash ROM chip.

Here's a diagram:

In short, the area the processor wants to read (0xFFFFFF0) is actually located in the BIOS chip, not in RAM, and the instruction is taken from this address in the BIOS chip within the Reset Vector and given to the processor.

Switching from Real Mode to Protection Mode

0x0 - A20 Gate

The 8086 had a 20-bit address bus — lines A0 through A19. This imposed a hard ceiling of 2²⁰ bytes, or exactly 1MB, on the physical address space. There was no 21st line. Any address calculation that produced a value above 0xFFFFF would silently lose bit 20, causing the address to wrap back into the bottom of the memory map. This was not a bug in the 8086 — it was a physical constraint of the hardware.

The problem surfaced with the 80286. Its address bus was 24 bits wide, meaning bit 20 now had a real wire behind it and addresses above 0xFFFFF resolved correctly. Wraparound no longer happened. This broke a class of DOS-era software that had come to depend on it — specifically, programs that constructed segment:offset pairs deliberately producing addresses just above 0x100000, relying on the wraparound to land back in low memory. On the 80286, those same addresses resolved to their actual targets above 1MB instead, and the programs failed.

The hardware fix was the A20 gate: a logic circuit, originally wired through the 8042 keyboard controller, that could force address line 20 to zero regardless of what the processor put on the bus. With the gate closed, bit 20 was always 0, wraparound was preserved, and legacy software ran correctly. With the gate open, bit 20 propagated normally and the full address space above 1MB became accessible.

We can simply open this gate with NASM:

; 0x92 - A20
in al,0x92  ; Get the current value 
or al,0x02  ; Open A20
and al,0xFE
out 0x92,al ; Write the bit again

This is required for Protection Mode.

0x1 - GDT and Switching to Protected Mode

With A20 open, the next requirement before touching CR0.PE is a valid Global Descriptor Table. In Real Mode, segment registers hold raw base values. In Protected Mode, they become selectors — 16-bit indices into the GDT — and the processor uses the descriptor at that index to determine the segment's base address, limit, and access rights. Attempting to set CR0.PE without a loaded GDT means the first segment register access in Protected Mode will reference garbage, producing a #GP or a silent wrong-base calculation.

The GDT used here defines five descriptors:

gdt_start:
    dq 0                                    ; 0x00 null (required)
    dw 0xFFFF, 0x0000
    db 0x00, 10011010b, 11001111b, 0x00     ; 0x08 code32
    dw 0xFFFF, 0x0000
    db 0x00, 10010010b, 11001111b, 0x00     ; 0x10 data32
    dw 0xFFFF, 0x0000
    db 0x00, 10011010b, 10101111b, 0x00     ; 0x18 code64  (L=1)
    dw 0xFFFF, 0x0000
    db 0x00, 10010010b, 11001111b, 0x00     ; 0x20 data64
gdt_end:

The null descriptor at offset 0 is mandatory — the processor reserves it and any selector that resolves to it raises #GP. The 32-bit code and data descriptors (0x08, 0x10) have D/B=1, placing the processor in 32-bit default operand and address size when CS holds 0x08. The 64-bit code descriptor at 0x18 has L=1 and D/B=0 — this is the bit that tells the processor to decode instructions as 64-bit after the final far jump.

The descriptor table is loaded into GDTR with lgdt, then CR0.PE is set and control transfers immediately to the 32-bit code selector:

lgdt [gdt_desc]

mov eax, cr0
or  eax, 1
mov cr0, eax
jmp 0x08:pMode32

The far jump is not optional. Setting CR0.PE does not flush the prefetch queue. Instructions fetched under Real Mode decode rules may still be in the pipeline, and executing them in Protected Mode produces undefined behavior. The far jump serializes the processor and reloads CS from the GDT, putting the descriptor cache into a consistent state for Protected Mode operation.

0x2 - Paging and the Transition to Long Mode

Protected Mode with paging disabled gives a flat 32-bit physical address space — useful for setup, but insufficient for Long Mode. The architecture requires paging to be active before Long Mode can be enabled, and it requires PAE (Physical Address Extension) specifically, since Long Mode uses 4-level page tables with 64-bit entries.

The page table structure is built at fixed physical addresses before any control register is touched:

mov edi, 0x13000
mov ecx, 0x3000 / 4
xor eax, eax
rep stosd            ; zero PML4 + PDPT + PD (3 × 4KB)

mov dword [0x13000], 0x14003  ; PML4[0] → PDPT (present + writable)
mov dword [0x14000], 0x15003  ; PDPT[0] → PD   (present + writable)

The Page Directory is filled with 512 entries, each mapping a 2MB physical region:

    ; [...]
    mov edi, 0x15000
    mov eax, 0x83           ; P=1, W=1, PS=1 (2MB page)
    mov ecx, 512

.pd:
    mov dword [edi],   eax
    mov dword [edi+4], 0
    add eax, 0x200000
    add edi, 8
    loop .pd

The PS bit (bit 7) in a Page Directory entry signals a 2MB huge page, bypassing the Page Table level entirely. The result is a flat identity map covering the first 1GB of physical memory — virtual address equals physical address throughout. This keeps all subsequent absolute references valid without any address fixup.

With the page tables in place, the Long Mode activation sequence:

mov eax, 0x13000
mov cr3, eax            ; point CR3 at PML4

mov eax, cr4
or  eax, (1 << 5)
mov cr4, eax            ; CR4.PAE = 1

mov ecx, 0xC0000080     ; IA32_EFER MSR
rdmsr
or  eax, (1 << 8)
wrmsr                   ; EFER.LME = 1

mov eax, cr0
or  eax, (1 << 31)
mov cr0, eax            ; CR0.PG = 1 → hardware sets EFER.LMA

jmp 0x18:lmode64        ; CS = 0x18 (L=1) → 64-bit decode active

The order is strictly enforced by the hardware. Setting EFER.LME before CR4.PAE is set raises #GP. Setting CR0.PG last is the trigger that causes the processor to atomically assert EFER.LMA — Long Mode Active. Until the far jump loads the 0x18 descriptor with L=1, the processor is technically in compatibility mode: Long Mode paging is active, but instruction decode is still 32-bit. The far jump is what makes it 64-bit.

0x3 - IDT and Exception Handling

The IDT in Long Mode serves the same purpose as the IVT in Real Mode, but the mechanism is entirely different. Each entry is 16 bytes, encoding a 64-bit handler address split across three fields, a code segment selector, an IST index, and a type/attribute byte. The processor locates the IDT through IDTR, loaded with lidt.

The IDT is placed at physical 0x10000. All 256 entries are first populated with a CatchAll handler that does nothing but iretq, then vector 1 — the #DB (Debug Exception) vector — is overwritten with the actual handler address:

IDT_BASE equ 0x10000

setup_idt:
    mov rdi, IDT_BASE
    mov rcx, (256 * 16) / 8
    xor rax, rax
    rep stosq               ; zero the entire IDT

    mov rcx, 256
    mov rdi, IDT_BASE
.fill:
    call .write_gate        ; write CatchAll to every entry
    add  rdi, 16
    loop .fill

    mov rdi, IDT_BASE + (1 * 16)
    mov rax, DbHandler
    call .write_gate_rax    ; overwrite vector 1 with DbHandler

    mov word  [idt_limit],    (256 * 16) - 1
    mov qword [idt_base_addr], IDT_BASE
    lidt [idt_limit]
    ret

Each gate is written with selector 0x18 (the 64-bit code descriptor), IST index 0, and type byte 0x8E: Present, DPL=0, 64-bit interrupt gate. The interrupt gate type means the processor clears IF on entry, preventing nested interrupts from arriving while the handler is running.

[My Debugger Journey] Working on Debug Registers with NASM

bekoo — Wed, 10 Jun 2026 07:00:24 +0000

Debug Registers

Both X86 and X64 architectures provide debug registers. In the processor, the debug registers can be accessed through DR0 - DR7 registers and also through MSR's.

Debug registers are different from another registers. Debug registers hold the address of memory and I/O locations - or we can say them 'breakpoints' and we can set a breakpoint with these registers. To put it more simply,

Here's a figure from the intel's volume:

Especially, in our case, DR6 and DR7 are really important. We will see them in detail.

DR0–DR3 Registers: These are the breakpoint address registers. Each holds a 64-bit linear address defining one hardware breakpoint slot. The processor supports up to four concurrent hardware breakpoints, one per slot. These registers are read/write and can be updated at any privilege level when CR4.DE is clear, or restricted to ring 0 when it is set.

DR4 and DR5 Registers These registers are legacy aliases. When CR4.DE is clear, accessing DR4 or DR5 silently redirects to DR6 and DR7 respectively. When CR4.DE is set, the access raises an #UD exception. In practice, DR4 and DR5 should be considered non-existent on modern systems.

DR6 Register: DR6 is the debug status register. The processor writes to it when a #DB exception fires, encoding the reason for the exception. Software reads DR6 to determine which breakpoint triggered and why. Critically, the processor never clears DR6 — the exception handler is responsible for zeroing it before returning, otherwise stale bits from a previous exception can cause misdiagnosis.

DR7 Register: DR7 is the debug control register. It arms or disarms each of the four breakpoint slots and defines, per slot, two properties: the trigger condition (instruction execution, data write, or data read/write) and the operand width to match (1, 2, 4, or 8 bytes). DR7 is the primary interface through which a debugger configures hardware breakpoints.

Detecting Breakpoints

When a memory address is written to DR0–DR3, the processor halts execution upon reaching it — not through software polling, but via a dedicated hardware comparator circuit operating autonomously at the silicon level.

The internal design of this circuit is not publicly documented in modern processors, but Intel's US Patent 5,694,589 (filed 1995, granted 1997) provides a detailed architectural description of its Pentium-era implementation, and serves as the primary reference for this section.

The patent addresses a scaling problem specific to superscalar execution. When multiple instructions are decoded in parallel each clock cycle, the conventional design requires one comparator per decode pipeline — each performing the identical comparison against DR0–DR3. The patent resolves this by moving the comparison upstream to the instruction fetch stage, where a single comparator unit covers all decode pipelines regardless of dispatch width.

In the patent, figure 2 shows the problem:

FIG. 2 lays out the problem directly. Each decode pipeline — ID₁ through IDₙ — carries its own breakpoint detection block, each one housing M comparators wired against DR0–DR3. To make this concrete: the IFU fetches a 16-byte aligned block from the instruction cache. That block is handed to the Instruction Length Decoder, which splits it into individual instructions and distributes them across N decode pipelines. Each pipeline then performs its own independent comparison:

Fetch block @ 0x00401000  (16 bytes)
┌──────────────────────────────────────────────┐
│ instr₁       instr₂       instr₃   ...  instrₙ│
│ 0x00401000   0x00401003   0x00401006    ...    │
└──────────────────────────────────────────────┘
        │             │            │
        ▼             ▼            ▼
    BPDET₁        BPDET₂       BPDET₃
  0x00401000    0x00401003   0x00401006
  == DR0–DR3?   == DR0–DR3?  == DR0–DR3?

For a processor dispatching N instructions per cycle, that means N identical comparison circuits firing every cycle against the same four registers. The hardware cost scales with dispatch width, not with any architectural necessity.

Figure 3 in the patent shows the invention:

FIG. 3 eliminates the redundancy at its source. Block 200, the breakpoint detection logic, is pulled out of the decode stage and repositioned adjacent to the IFU, operating directly on the Fetch IP. The comparison happens once, upstream, before the instruction stream has been split across decode pipelines. The patent does this by comparing only the upper 28 bits of the Fetch IP against DR0–DR3 — the lower 4 bits are then expanded through a 4:16 decoder to identify which byte within the 16-byte fetch block carries the breakpoint:

DR0          = 0x00401000
               ├── upper 28-bit ──┤ ├─ lower 4 ─┤
                  0x0040100            0x0

Fetch IP     = 0x00401000
               ├── upper 28-bit ──┤
                  0x0040100            → match

Lower 4-bit  = 0x0  →  4:16 decoder  →  bit 0
                                         │
                                         ▼
                              0x00401000 is the first byte
                              of the fetch block → #DB
                              before decode pipelines

A MUX sits between the detection block and the Instruction Length Decoder — if the fetch address matches a debug register, the signal is resolved there. The decode pipelines in FIG. 3 have no breakpoint logic under them at all.

To put it more simply, the address written to DR0–DR3 is not a hint or a flag — it is a direct input to the comparator circuit. The moment mov dr0, rax executes, that address is live in hardware. Every subsequent fetch is checked against it.

The IFU fetches a 16-byte aligned block from the instruction cache. The Instruction Length Decoder determines the boundary of each instruction within that block — x86 instructions are variable-length, anywhere from 1 to 15 bytes — and distributes them across the decode pipelines. Each pipeline takes one instruction and converts it from binary opcode into micro-operations:

Fetch block @ 0x00401000:
[48 89 C8]  [48 83 EC 08]  [FF D0]
   3 byte        4 byte      2 byte

ID₁ → 0x00401000 → mov rax, rcx
ID₂ → 0x00401003 → sub rsp, 8
ID₃ → 0x00401007 → call rax

In FIG. 2, each pipeline checks its own instruction address against DR0–DR3 independently. ID₁ compares 0x00401000, ID₂ compares 0x00401003, ID₃ compares 0x00401007 — the same four registers, checked N times per cycle.

In FIG. 3, the check is pulled upstream to the fetch boundary. The upper 28 bits of the Fetch IP are compared against DR0–DR3 before the block reaches the length decoder. The lower 4 bits identify which byte within the 16-byte block is armed, resolved through a 4:16 decoder:

DR0 = 0x00401003
      ├─ upper 28-bit ─┤ ├─ lower 4 ─┤
         0x0040100          0x3

Fetch IP = 0x00401000
           ├─ upper 28-bit ─┤
              0x0040100          → match

Lower 4-bit = 0x3  →  4:16 decoder  →  bit 3
                                         │
                                         ▼
                              0x00401003 is the fourth byte
                              of the fetch block → #DB
                              before decode pipelines

By the time an instruction reaches any decode unit, the hardware has already decided whether that address is armed. The #DB is not generated at dispatch or at execution — it is generated at fetch. The instruction never advances further. No instruction is modified, no execution path is altered, no software layer is consulted. The comparator either matches or it does not, and that determination is made before anything downstream has a chance to observe the instruction at all.

Of course, things are quite different with modern processors today, but I’ve used this resource solely as a reference to help us understand the basic background.

Generating #DB Exception

CPU generates #DB when a breakpoint is triggered. This #DB, in fact, is an exception from IDT (Interrupt descriptor table).

When the CPU encounters a breakpoint condition — whether from a hardware debug register match, a single-step TF flag, or a data watchpoint — it vectors through IDT vector 1 to the #DB handler. The descriptor at IDT[1] holds the gate type, DPL, and the handler's segment:offset. Before transferring control, the processor pushes the exception frame onto the stack: RFLAGS, CS, RIP, and — since #DB is a fault/trap hybrid — optionally an error code, though #DB itself carries none.

What makes #DB interesting architecturally is its dual nature. It is simultaneously a fault (for instruction breakpoints: RIP points at the faulting instruction) and a trap for the breakpoins.

Adding our Handler into IDT

Here's nasm assembly project that adds our handler into IDT[1]:

IDT_BASE equ 0x10000
idt_limit:      dw 0
idt_base_addr:  dq 0

setup_idt:
    ; Clear the IDT
    mov rdi,IDT_BASE
    mov rcx,(256 * 16) / 8 
    xor rax,rax
    rep stosq 

    mov rcx,256
    mov rdi,IDT_BASE

.fill: 
    call .write_gate
    add rdi,16
    loop .fill

    ; Now we can write our handle to IDT
    mov rdi,IDT_BASE + (1 * 16)
    mov rax,DbHandler
    call .write_gate_rax

    mov word [idt_limit], (256 * 16) - 1
    mov qword [idt_base_addr], IDT_BASE
    lidt [idt_limit]
    ret

.write_gate:
    push rax
    mov  rax, CatchAll
    call .write_gate_rax
    pop  rax
    ret

.write_gate_rax:
    push rbx
    push rax
    mov  rbx, rax
    mov  [rdi+0],  bx            ; offset[15:0]
    mov  word [rdi+2], 0x18      ; code64 selector
    mov  byte [rdi+4], 0x00      ; IST=0
    mov  byte [rdi+5], 0x8E      ; P=1 DPL=0 64-bit interrupt gate
    shr  rbx, 16
    mov  [rdi+6],  bx            ; offset[31:16]
    shr  rbx, 16
    mov  [rdi+8],  ebx           ; offset[63:32]
    pop  rax
    pop  rbx
    ret

Here's a diagram for this project:

After clearing the IDT and filling all 256 entries with the catch-all handler, the code installs the actual #DB handler at IDT[1] — vector 1 being the architecturally reserved slot for debug exceptions:

mov rdi, IDT_BASE + (1 * 16)
mov rax, DbHandler
call .write_gate_rax

Each IDT entry in 64-bit mode is 16 bytes. The * 16 offset lands rdi exactly at the second descriptor slot.

The .write_gate_rax routine constructs the descriptor manually, field by field, conforming to the 64-bit interrupt gate format defined in the SDM Vol. 3A 6.14:

mov  [rdi+0],  bx          ; offset[15:0]
mov  word [rdi+2], 0x18    ; segment selector
mov  byte [rdi+4], 0x00    ; IST = 0
mov  byte [rdi+5], 0x8E    ; type/attr byte
shr  rbx, 16
mov  [rdi+6],  bx          ; offset[31:16]
shr  rbx, 16
mov  [rdi+8],  ebx         ; offset[63:32]

The handler's 64-bit address is split across three non-contiguous fields — [0:1], [6:7], [8:11] — because the descriptor format inherited its layout from the original protected mode design and extended it in place rather than redesigning it.

0x18 at offset +2 is the code segment selector. In a typical GDT layout this is the third descriptor (index 3, 3 * 8 = 0x18), a 64-bit code segment. The processor loads CS from this field on gate entry, which determines the privilege level and addressing mode of the handler.

Lastly, LIDT expects a 10-byte memory operand: a 2-byte limit followed immediately by an 8-byte linear base address:

mov word  [idt_limit],     (256 * 16) - 1
mov qword [idt_base_addr], IDT_BASE
lidt [idt_limit]

The limit is always (n * 16) - 1 for n descriptors — off-by-one because the limit is the last valid byte offset, not the count. If the CPU receives a vector whose offset exceeds the limit, it generates a #GP(vector*8+2) rather than dispatching the handler, so undersizing the limit is a hard fault condition.

Triggering a Breakpoint with DR7 Register

DR6 and DR7 registers are the major player in a debugger. If you want to set a condition for a breakpoint, you need to use DR7. If you check the result of a trigger, you need to check the result of DR6.

There are many condition to trigger a breakpoint. Here are them:

Execution breakpoint (fetch): The processor triggers #DB when the instruction pointer reaches the address stored in a DR slot. This is the closest hardware equivalent to a traditional software breakpoint (int3), with one critical difference: the target instruction is never modified. The condition code for this type is 00b in the DR7 condition field.

Data write breakpoint: The processor monitors the specified address for write operations. When any instruction writes to that address — regardless of which register or addressing mode is used — #DB fires after the write completes. Condition code: 01b. I/O read/write breakpoint. When CR4.DE is set, the processor can watch a specific I/O port address. Any IN or OUT instruction targeting that port raises #DB. This condition is only available when CR4.DE is enabled; without it, the encoding is reserved. Condition code: 10b

Data read/write breakpoint. The broadest condition. #DB fires on any read or write to the watched address, whether the access is a load, store, or read-modify-write. Instruction fetches are explicitly excluded — the processor does not trigger on fetch even if the instruction pointer passes through the watched region. Condition code: 11b.

One constraint applies across all conditions: The breakpoint address in DR0–DR3 must be aligned to the access width defined in DR7. A 4-byte watchpoint on an unaligned address produces undefined behavior on some microarchitectures and silently fails to trigger on others.

We can also benefit from the intel's volume:

Using DR7 in NASM Assembly

We can simply trigger a breakpoint with NASM Assembly:

BITS 64
lmode64:
    ; [...]

    call setup_idt

    mov rsi,msgIDTOK
    call serial_print

    ; Write DebugTarget function to DR0
    mov rax,DebugTarget
    mov dr0,rax

    ; Add 0x00000001 value to DR7 (Execution)
    mov rax,0x00000001
    mov dr7,rax

    ; Trigger the breakpoint 
    call DebugTarget

    hlt

As you can see, we just configure the IDT table, write the function address (DebugTarget) to DR0 register, prepare condition for the breakpoint in DR7 register. 0x00000001 means "trigger the breakpoint if the address is executed".

My DbHandler:


msgHello  db "I love bare-metal coding :>", 13, 10, 0

DbHandler:
    push rax
    push rbx
    push rcx
    push rdx
    push rsi
    push rdi
    push rbp
    push r8
    push r9
    push r10
    push r11
    push r12
    push r13
    push r14
    push r15

    mov rsi,msgHello
    call serial_print

    xor rax,rax 
    mov dr7,rax

Exit:
    pop r15
    pop r14
    pop r13
    pop r12
    pop r11
    pop r10
    pop r9
    pop r8
    pop rbp
    pop rdi
    pop rsi
    pop rdx
    pop rcx
    pop rbx
    pop rax
    iretq

In the handler, just a message is printed and reset the value of DR7 register.

Here's the result:

This is simple using of DR7 register.

Setting the Writing Condition to a Breakpoint

We can continue to take advantage of the DR7's features.

DR7 isn't a single-bit register. The 0x00000001 we used earlier is the minimal configuration — it only enables the local breakpoint condition for DR0.

Each debug register (DR0–DR3) has its own enable bit pair and condition field. This means four independent breakpoints can be active simultaneously, each with a different address, type, and access width.

Condition Encoding (R/W bits): The R/W field for each breakpoint slot controls what kind of access triggers the exception:

; R/W = 00 → execution breakpoint (instruction fetch)
; R/W = 01 → write watchpoint
; R/W = 10 → I/O read/write (CR4.DE must be set)
; R/W = 11 → read/write watchpoint (not on execution)

LEN Fields: For execution breakpoints, LEN must always be 00. For data watchpoints, LEN encodes the access width:

LEN = 00 → 1 byte
LEN = 01 → 2 bytes
LEN = 10 → 8 bytes (64-bit mode only)
LEN = 11 → 4 bytes

Now here's an example:

watch_var:  dd 0, 0

BITS 64
lmode64:
    ; [...]

    call setup_idt

    mov rsi,msgIDTOK
    call serial_print

    ; DR1 = write watchpoint on a data address
    mov rax,watch_var
    mov dr1, rax

    ; DR7 encoding:
    ; L0=1 (enable DR0 local), R/W0=00, LEN0=00  → bits [0], [17:16], [19:18]
    ; L1=1 (enable DR1 local), R/W1=01, LEN1=11  → bits [2], [21:20], [23:22]
    ;
    ; L0   = bit 0  = 1
    ; L1   = bit 2  = 1
    ; R/W1 = bits [21:20] = 01
    ; LEN1 = bits [23:22] = 11
    ;
    ; 0000 0000 1101 0000 0000 0000 0000 0101

    mov rax, 0x00D00005
    mov dr7, rax

    ; Now trigger the breakpoint
    mov rax,0x1
    mov qword [watch_var],rax


    hlt

The flow is same. We prepare DR1 and DR7 registers and trigger the breakpoint. Here's the result:

Conclusion

The examples covered here represent only the surface of what the debug register architecture exposes. DR0–DR3 accept any linear address — code, data, or I/O — and DR7 encodes the full condition space: execution, write, read/write, access width, local and global scope, all independently configurable per register. The hardware does the rest without kernel involvement, without modifying the target code, and without observable overhead.

For anyone going deeper, Intel's Software Developer's Manual Volume 3, Chapter 19 (CHAPTER 19 - DEBUG, BRANCH PROFILE, TSC AND INTEL® RESOURCE DIRECTOR) is the authoritative reference — it covers the full DR7 encoding, DR6 status semantics, interaction with single-step mode, and the edge cases that matter when building anything serious on top of this mechanism.

[My Debugger Journey] Building a Disassembler with NASM

bekoo — Sun, 07 Jun 2026 09:20:06 +0000

How a Disassembler Reads Machine Code

Have you ever wondered how a CPU sees and executes your code? Not the high-level abstractions, not the compiler output — the raw bytes sitting in memory. Let's go deep.

Instruction Encodings

In x64 and IA-32 architectures, every instruction is a sequence of bytes following a specific format. An instruction consists of Instruction Prefixes, Opcode, ModR/M, SIB, Displacement and Immediate. We will cover each one.

Here's the figure directly from Intel's Volume 2:

Not every instruction uses all of these fields. Some instructions are a single byte. Others stretch to 15. The decoder has to figure out where one instruction ends and the next begins — purely from the byte stream, with no delimiters, no markers.

Instruction Prefixes

A prefix modifies the behavior of the following instruction without being an instruction itself. Intel groups them into four groups.

Group 1 — Lock and Repeat: The LOCK prefix (F0) forces exclusive access to shared memory. In a multiprocessor environment, two cores can read and write the same address simultaneously, corrupting data. LOCK holds the memory bus until the operation completes. F2 and F3 are the repeat prefixes — REPNE/REPNZ and REP/REPE/REPZ respectively, typically used with string operations.

Group 2 — Segment Override: Redirects memory access to a specified segment register. 2E overrides to CS, 36 to SS, 3E to DS, 26 to ES, 64 to FS, and 65 to GS. Largely irrelevant in 64-bit mode where segmentation is mostly flat, but the decoder still has to consume and skip them.

Group 3 — Operand Size Override: 66 switches the operand size between 16-bit and 32-bit. In a 32-bit context, prefixing an instruction with 66 narrows the operand to 16-bit — this is how mov ax, 1 and mov eax, 1 share the same opcode but differ by a single prefix byte.

Group 4 — Address Size Override: 67 switches the address size between 32-bit and 64-bit. Rarely used in practice but the decoder must handle it — a disassembler that ignores 67 will miscalculate the size of any displacement or memory operand that follows.

In 64-bit mode, the REX prefix (0x40–0x4F) follows these four groups. REX.W=1 promotes the operand to 64-bit. That 0x48 byte you see before most 64-bit instructions is exactly this — it tells the CPU to treat the following instruction as a 64-bit operation.

Opcode

A primary opcode can be 1, 2, or 3 bytes in length. Most common instructions fit in a single byte — 0x90 is NOP, 0xC3 is RET, 0x89 is MOV. The problem is that x86 only has 256 possible values in a single byte, and that space filled up quickly.

When Intel ran out of room, they introduced escape sequences. 0x0F is the most common — it tells the decoder "don't treat this as an opcode, read the next byte too." So 0x0F 0xA3 together means BT (Bit Test), a two-byte opcode. The 0x0F byte itself carries no instruction — it's purely a table switch.

0x89        →  MOV   (1-byte opcode)
0x0F 0xA3   →  BT    (2-byte opcode, 0x0F is the escape)

But, we cannot escape with these information :>

Mandatory Prefix and Escape Prefix

An opcode also can consist of a mandatory prefix and Escape Prefix:

Mandatory Prefix: A prefix that is part of the opcode itself, not a modifier. Unlike Group 1-4 prefixes which change behavior, a mandatory prefix changes the identity of the instruction entirely.

Escape Prefix: A byte that switches the decoder into an extended opcode table. 0x0F is the most common — alone it unlocks a second table of 256 opcodes. When that table also fills up, a second escape byte follows: 0x0F 0x38 and 0x0F 0x3A open two additional tables.

For example, an opcode can start with these values (CVTDQ2PD):

CVTDQ2PD: F3 0F E6

CVTDQ2PD instruction is one of the instructions that requires a mandatory prefix and begins with 0xF3. This is the mandatory prefix, while the value 0x0F is the escape prefix. Finally, 0xE6 is the command itself.

By the way, the mandatory prefix can also be 0x66 and 0xF2.

But there are instructions that don't requires Mandatory Prefix. Here are a few examples:

0F 28   →  MOVAPS   (move aligned packed single-precision floats)
0F 58   →  ADDPS    (add packed single-precision floats)
0F 54   →  ANDPS    (bitwise AND of packed floats)
0F 59   →  MULPS    (multiply packed single-precision floats)

As you can see, they start with 0x0F (escape prefix).

I've prepared a nasm project that shows the differences between SIMD, AVX2 and X64 instructions:

BITS 64

section .data
    align 16
    xmm_a   dd 1.0, 2.0, 3.0, 4.0
    xmm_b   dd 10.0, 20.0, 30.0, 40.0

    align 32
    avx_a   dd 1, 2, 3, 4, 5, 6, 7, 8
    avx_b   dd 10, 20, 30, 40, 50, 60, 70, 80

section .text
global _start

_start:
    ; X64 Register -> Prefix is 0x48
    mov rax,0x5000000000

    ; Mandatory Prefix Instruction: 0xF3 
    cvtdq2pd xmm1, xmm1

    ; Non-Mandatory Prefix: 0x0F
    movaps xmm0, [xmm_a]   ; xmm0 = [1.0, 2.0, 3.0, 4.0]

    ; AVX2 Register (256-bytes) Prefix: 0xC5
    vmovdqu ymm0, [avx_a]

There are X64, SIMD and AVX2 registers, so we can see the different. Let's see the instructions with objdump:

Focus on the first bytes. They have different prefix.

ModR/M

After the opcode, many instructions include a ModR/M byte. Not all — NOP, RET, HLT need no operands and carry no ModR/M. But any instruction that needs to specify "which register" or "which memory location" requires one.

The ModR/M byte encodes three fields packed into 8 bits:

 7   6   5   4   3   2   1   0
┌───────┬───────────┬───────────┐
│  Mod  │    Reg    │    R/M    │
│  2bit │   3bit    │   3bit    │
└───────┴───────────┴───────────┘

Mod (bits 7:6) — tells the decoder how to interpret R/M:

Mod	Meaning
00	memory, no displacement
01	memory + 1-byte displacement
10	memory + 4-byte displacement
11	register direct, no memory

Reg (bits 5:3) — encodes the register operand index (0–7, extended to 8–15 via REX.R).

R/M (bits 2:0) — encodes the second operand. When Mod=11, it's a register index. When Mod≠11, it encodes the base register for a memory access — or triggers SIB when R/M=4.

A concrete example

Take the instruction mov rbp, rsp. In memory it looks like this:

48  89  E5

0x48 — REX prefix, W=1, meaning 64-bit operand
0x89 — opcode: MOV r/m, reg
0xE5 — ModR/M byte

Breaking down 0xE5 value:

E5 = 1110 0101
     ^^  ^^^  ^^^
     11  100  101
     Mod  Reg  R/M
     =3   =4   =5

Mod=3 → register direct, no memory access, no displacement.

Reg=4 → RSP (source).

R/M=5 → RBP (destination).

Combined with 0x89 (MOV r/m ← reg) and REX.W=1 (64-bit), the decoder produces: mov rbp, rsp.

Building a Disassembler with NASM

As you can see before the chapter, creating a disassembler is really tough task. This means that we can't determine the opcodes with just increasing the bytes. There can be different byte for the instruction. And we must extract them.

In this chapter, i've shared a piece code of my nasm project. This is simple disassembler function, which determines opcodes and instruction for mov rbp,rsp. In this way, we can understand the basic of a disassembler:

; ...

; Messages
str_mov        db "found mov in opcode!", 13, 10, 0
str_mod_reg    db "found reg in ModRM!", 13, 10, 0 
str_mod_disp8  db " [mem+disp8]", 0
str_mod_disp32 db " [mem+disp32]", 0
str_mod_mem    db " [mem]", 0
str_newline    db 13, 10, 0

opcodes db 0x48, 0x89, 0xE5   ; mov rbp, rsp
        db 0x90               ; nop
        db 0x48, 0x31, 0xC0   ; xor rax, rax
        db 0xC3               ; ret

BITS 64
_start64:
    mov  ax, 0x20
    mov  ds, ax
    mov  es, ax
    mov  fs, ax
    mov  gs, ax
    mov  ss, ax
    mov  rsp, 0x90000

    ; ... 

    xor rcx, rcx
    mov rbx, opcodes

.loop:
    mov al, byte [rbx + rcx]

    cmp al, 0x48
    jz .prefix_found

    cmp al, 0xC3
    jz .exit

    cmp al, 0x89
    jz .mov_found

    ; unknown opcode — skip and continue
    inc rcx
    jmp .loop

.mov_found:
    mov rsi, str_mov
    call serial_print

    inc rcx
    mov al, [rbx + rcx]

    mov r8b, al
    shr al, 6
    cmp al, 3
    je .mod_reg

    cmp al, 1
    je .mod_disp8

    cmp al, 2
    je .mod_disp32

    mov rsi, str_mod_mem
    call serial_print
    inc rcx
    jmp .done_print

.mod_reg:
    mov rsi, str_mod_reg
    call serial_print
    inc rcx
    jmp .done_print

.mod_disp8:
    mov rsi, str_mod_disp8
    call serial_print
    add rcx, 2
    jmp .done_print

.mod_disp32:
    mov rsi, str_mod_disp32
    call serial_print
    add rcx, 5
    jmp .done_print

.done_print:
    mov rsi, str_newline
    call serial_print
    jmp .loop

.prefix_found:
    inc rcx
    jmp .loop

.exit:
    movzx rax, byte [rbx + rcx]
    call serial_hex64

.halt:
    hlt
    jmp .halt

And the output:

As you can see, we can determine mov instruction and its registers.

This is really simple disassembler. Let's enhance it with this plan: Remember that we saw Prefixes and escape bytes. In the disassembler we will extract them. i've updated the opcodes variable:

opcodes db 0x48, 0x89, 0xE5 ; mov rbp, rsp
        db 0x90 ; nop
        db 0x48, 0x31, 0xC0 ; xor rax, rax
        db 0xf3, 0x0f, 0xe6, 0xc9 ; cvtdq2pd xmm1,xmm1
        db 0x0f, 0x28, 0x04, 0x25, 0x00, 0x20, 0x40, 0x00 ; movaps xmm0,XMMWORD PTR ds:0x402000
        db 0xC3 ; ret

Now we have different prefixes to extract the opcode. We can handle it with this way:

.loop:
    mov al, byte [rbx + rcx]

    ; Check the mandatory prefix
    cmp al,0xF3 
    jz .found_mandatory

    ; Check the Escape Byte
    cmp al,0x0F
    jz .found_escape

.continue:
    cmp al,0x48
    jz .prefix_found

    cmp al,0xC3
    jz .exit

    cmp al,0x89
    jz .mov_found

    ; unknown opcode — skip and continue
    inc rcx
    jmp .loop

.found_mandatory:
    mov rsi,str_mandatory
    call serial_print

    ; We need to check the escape byte
    inc rcx
    mov al,byte [rbx + rcx]
    cmp al,0x0F
    jz .found_escape

    ; if it is not escape byte, then find the opcode
    jmp .continue

.found_escape:
    mov rsi,str_escape
    call serial_print

    ; Now we can find the instruction
    inc rcx
    mov al,byte [rbx + rcx]

    jmp .continue

Here's the output:

As you can see, there are two messages found escape byte (0x0F). Because two instruction contains 0x0F value:

; cvtdq2pd xmm1,xmm1
db 0xf3, 0x0f, 0xe6, 0xc9 

; movaps xmm0,XMMWORD PTR ds:0x402000
db 0x0f, 0x28, 0x04, 0x25, 0x00, 0x20, 0x40, 0x00

In this way, we can handle them.

Conclusion

There are many possibilities for a disassembler.

What I’ve shown you here are all very simple examples. As you can see from the first heading, there are many prefix groupings and so on, and as a debugger developer, we need to extract through them. Doing this with languages like NASM is tedious, but it makes the job much easier.

[My Debugger Journey] Working on Single-Step Breakpoints in a Debugger

bekoo — Wed, 03 Jun 2026 22:50:54 +0000

Introduction

Single-step breakpoints are fundamental debugging mechanism that allows execution to pause after every single instruction. Unlike hardware breakpoints which trigger at a specific address, single-step mode traces every instruction sequentially.

In this post, we will see these breakpoints in detail with NASM + QEMU.

Single-Step Breakpoints and Trap Flag

A debugger can determine single-step breakpoints with DR6 register. DR6 register holds BS (Single-Step Bit) and a debugger can use this bit. BS is 14 bit of DR6 register:

But that's not all. This bit just shows the breakpoint is triggered in 'single-step progress'. We can't change if we want 'single-step'.

TF (Trap Flag) is the real mechanism behind single-step execution. It lives at bit 8 of the RFLAGS register and cannot be set directly with a MOV instruction. Instead, we manipulate it indirectly through the stack.

When a #DB exception occurs, the CPU pushes the current RFLAGS onto
the stack as part of the exception frame. This saved copy is what IRETQ will restore when returning from the handler. By modifying bit 8 of this saved RFLAGS before executing IRETQ, we control whether single-step continues after the handler returns.

The CPU automatically clears TF before delivering the #DB exception. This is by design — without this behavior, the handler itself would be single-stepped, causing an infinite recursive exception loop. By clearing TF on entry and only restoring it in the saved RFLAGS, we ensure single-step applies only to the code being debugged, not to the handler.

Simple Project in NASM

Here's an example from my NASM Project:

DbHandler:
    push rax
    push rbx
    push rcx
    push rdx
    push rsi
    push rdi
    push rbp
    push r8
    push r9
    push r10
    push r11
    push r12
    push r13
    push r14
    push r15

    mov rbx, dr6

    ; Start single-step progress
    test rbx, (1 << 0)
    jnz .hw_bp_hit

    ; BS set → single-step fired
    ; After the first execution of #DB (with TF=1),
    ; CPU will set BS bit of DR6
    test rbx, (1 << 14)
    jnz .single_step


    jmp Exit

.hw_bp_hit:
    xor  rax, rax
    mov  dr6, rax
    xor  rax, rax
    mov  dr7, rax

    ; Enable TF flag and exit (CPU will generate #DB again)
    or   qword [rsp + 136], (1 << 8)
    jmp  Exit

.single_step:
    ; In each single-step, write the value of RIP 
    mov rax, [rsp + 120]
    call serial_hex64

    dec qword [step_count]
    jz .stop_stepping

    ; Pass 1 to TF (for Single-Step)
    or qword [rsp + 136], (1 << 8)
    jmp Exit

.stop_stepping:
    ; Pass 0 to stop
    and qword [rsp + 136], ~(1 << 8)
    xor rax, rax
    mov dr6, rax
    jmp Exit

Exit:
    pop r15
    pop r14
    pop r13
    pop r12
    pop r11
    pop r10
    pop r9
    pop r8
    pop rbp
    pop rdi
    pop rsi
    pop rdx
    pop rcx
    pop rbx
    pop rax
    iretq

The idea is simple: In the first execution of #DB exception, we set TF flag to 1 and exit from the handler. Then CPU generates #DB exception with BS=1. In the handler, we check this bit:

; After the first execution of #DB (with TF=1),
; CPU will set BS bit of DR6
test rbx, (1 << 14)
jnz .single_step

In the .single-step, we just print the value of RIP, decrease the step_count and pass 1 to TF flag:

.single_step:
    ; In each single-step, write the value of RIP 
    mov rax, [rsp + 120]
    call serial_hex64

    ; step_count = 0x5
    dec qword [step_count]
    jz .stop_stepping

    ; Pass 1 to TF (for Single-Step)
    or qword [rsp + 136], (1 << 8)
    jmp Exit

As we can see, the idea is simple. Here's the result:

I assigned the value 0x5 to the step_count variable, so each step is performed based on this value. Also my breakpoint is based on DebugTarget function:

DebugTarget:
    mov  rax, 0x1
    mov  rbx, 0x2
    add  rax, rbx
    mov  rcx, rax
    mov  rdx, 0x0
    ret

UEFI to Windows Communication via NVRAM Variables

bekoo — Sun, 20 Jul 2025 21:19:28 +0000

In this article, we will discuss how to establish communication between a UEFI driver and a Windows driver. Specifically, we’ll explore how to use NVRAM-based UEFI variables to exchange data between the two environments.

What is NVRAM?

NVRAM (Non-Volatile RAM) is a key component in UEFI-based systems, used to store persistent configuration and system state data. Unlike regular RAM, NVRAM retains its contents across reboots and power-offs, making it essential for managing firmware-level settings.

In UEFI, NVRAM is organized into variables—structured key-value pairs that include metadata (attributes) defining how and when they can be accessed. These variables are used for critical system functions such as boot management, secure boot key storage, hardware configuration, and OEM-specific settings.

UEFI Variables

UEFI Variables is specified with a combination of a GUID and Unicode String. The GUID of a variable can prevent name collisions between different vendors.

The Boot Manager Chapter of UEFI Specification defines the EFIGLOBAL_VARIABLE_GUID, also known gEfiGlobalVariableGuid in EDK II. If we want to use a global variable, such as SecureBoot Status in our UEFI Driver, we need to benefit from the gEfiGlobalVariableGuid. Here are some global variable list from EDK II Repo:

EFI_PLATFORM_LANG_CODES_VARIABLE_NAME L"PlatformLangCodes"
EFI_BOOT_CURRENT_VARIABLE_NAME L"BootCurrent"
EFI_SIGNATURE_SUPPORT_NAME L"SignatureSupport"

[...]

Each UEFI Variable has attributes that the describe visibility persistence. Here's list of the attributes:

BOOTSERVICE_ACCESS

The variable has permissions for write and read access at the pre-boot before ExitBootServices() called, which means that the variable is not available after called ExitBootServices() and the contents of the variable will be deleted on the next system reset.

BOOTSERVICE_ACCESS | RUNTIME_ACCESS

The variable has permissions for write and read access before ExitBootServices() called, but its contents will remain as read-only when ExitBootServices() called, also the contents will be deleted on the next system reboot.

NON_VOLATILE | BOOTSERVICE_ACCESS

The variable has permissions for write and read access before ExitBootServices() called and its contents are persistent through system reset.

NON_VOLATILE | BOOTSERVICE_ACCESS | RUNTIME_ACCESS

The variable has permissions for write and read in both pre-boot and OS Runtime environment. Its contents are persistent through system reset.

Access UEFI Variables with Services

When a UEFI Driver store configuration information via UEFI Variables, it can access them with services provided by EFI_HII_CONFIG_ACCESS_PROTOCOL The Services SetVariable() and GetVariable() are used to set and get configuration information. We will see these two services through the article.

1 - SetVariable()

SetVariable() service sets the contents of the variable, also it can be used to create a new variable, modify the variable or to delete an existing variable. Here are parameters of the service:

 typedef
 EFI_STATUS
 SetVariable (
   IN CHAR16            *VariableName,
   IN EFI_GUID          *VendorGuid,
   IN UINT32            Attributes,
   IN UINTN             DataSize,
   IN VOID              *Data
);

Let's create a project for SetVariable:

#include <Uefi.h>
#include <Library/UefiApplicationEntryPoint.h>
#include <Library/UefiLib.h>
#include <Library/PcdLib.h>
#include <Library/UefiBootServicesTableLib.h>
#include <Library/UefiRuntimeServicesTableLib.h>

EFI_STATUS EFIAPI UefiMain(EFI_HANDLE ImageHandle, EFI_SYSTEM_TABLE *SystemTable) {
  CHAR16 *VariableName = L"MyUEFIVar";
  EFI_GUID VendorGuid = { 0xa1b2c3d4, 0x1234, 0x5678, {0x9a,0xbc,0xde,0xf1,0x23,0x45,0x67,0x89} };
  UINT8 ContentOfVariable[4] = { 0xDE, 0xAD, 0xBE, 0xEF };
  UINTN DataSize = sizeof(ContentOfVariable);
  EFI_STATUS Status = EFI_SUCCESS;

  UINT32 Attributes = EFI_VARIABLE_NON_VOLATILE |
                      EFI_VARIABLE_BOOTSERVICE_ACCESS |
                      EFI_VARIABLE_RUNTIME_ACCESS;


  Status = gRT->SetVariable(
      VariableName,
      &VendorGuid,
      Attributes,
      DataSize,
      &ContentOfVariable
  );
  if (EFI_ERROR(Status)) {
      Print(L"Write Operation Failed!\n");
      return Status;
  }
  Print(L"The content successfully written!\n");

  return EFI_SUCCESS;
}

In the code, we wrote the content of ContentOfVariable. Firstly, we created a variable name, GUID and values for UEFI Variable, then we executed the SetVariable. As a result of these processes, our UEFI Variable has these information:

UEFI Variable Name: MyUEFIVar
GUID: A1B2C3D4-1234-5678-9ABC-DEF123456789
Content: 0xDEADBEEF

Here's result:

Now we can access it with these information.

2 - GetVariable()

GetVariable() service get content of the variable. Here are parameters of the service:

typedef
EFI_STATUS
GetVariable (
  IN CHAR16           *VariableName,
  IN EFI_GUID         *VendorGuid,
  OUT UINT32          *Attributes OPTIONAL,
  IN OUT UINTN        *DataSize,
  OUT VOID            *Data OPTIONAL
 );

Now let's develop the project with GetVariable service:

#include <Uefi.h>
#include <Library/UefiApplicationEntryPoint.h>
#include <Library/UefiLib.h>
#include <Library/PcdLib.h>
#include <Library/UefiBootServicesTableLib.h>
#include <Library/UefiRuntimeServicesTableLib.h>

EFI_STATUS EFIAPI UefiMain(EFI_HANDLE ImageHandle, EFI_SYSTEM_TABLE *SystemTable) {
  CHAR16 *VariableName = L"MyUEFIVar";
  EFI_GUID VendorGuid = { 0xa1b2c3d4, 0x1234, 0x5678, {0x9a,0xbc,0xde,0xf1,0x23,0x45,0x67,0x89} };
  UINT8 ContentOfVariable[4] = { 0xDE, 0xAD, 0xBE, 0xEF };
  UINTN DataSize = sizeof(ContentOfVariable);
  EFI_STATUS Status = EFI_SUCCESS;

  UINT32 Attributes = EFI_VARIABLE_NON_VOLATILE |
                      EFI_VARIABLE_BOOTSERVICE_ACCESS |
                      EFI_VARIABLE_RUNTIME_ACCESS;


  Status = gRT->SetVariable(
      VariableName,
      &VendorGuid,
      Attributes,
      DataSize,
      &ContentOfVariable
  );
  if (EFI_ERROR(Status)) {
      Print(L"Failed to write!\n");
      return Status;
  }
  Print(L"The content successfully written!\n");

  UINT8 Content[4] = { 0 };
  DataSize = sizeof(Content);
  Status = gRT->GetVariable(
      VariableName,
      &VendorGuid,
      &Attributes,
      &DataSize,
      &Content
  );
  if (EFI_ERROR(Status)) {
    Print(L"Failed to read the variable!\n");
    return Status;
  }

  for (int x = 0; x < DataSize; x++) {
    Print(L"Content: 0x%02x\n", Content[x]);
  }
  return EFI_SUCCESS;
}

After SetVariable called, we called GetVariable service to get content of the our UEFI Variable, then we printed the result. Here's the result:

And now we can focus our Windows Driver.

Coding Windows Driver

Essentially there's a routine which we can use for our purpose in ntoskrnl. ExGetFirmwareEnvironmentVariable can be used to read UEFI Variables. So coding of the windows driver will not be difficult. We can call this routine with UEFI Variable information:

#include <ntddk.h>

NTSTATUS DriverUnload(PDRIVER_OBJECT DriverObject)
{
    UNREFERENCED_PARAMETER(DriverObject);
    DbgPrint("Driver unloaded.\n");

    return STATUS_SUCCESS;
}

NTSTATUS DriverEntry(PDRIVER_OBJECT DriverObject, PUNICODE_STRING RegistryPath)
{
    UNREFERENCED_PARAMETER(RegistryPath);
    DriverObject->DriverUnload = DriverUnload;

    UNICODE_STRING VariableName = RTL_CONSTANT_STRING(L"MyUEFIVar");
    UINT8 Content[4] = { 0 };
    ULONG BufferSize = sizeof(Content);
    GUID VendorGuid = {
        0xa1b2c3d4, 0x1234, 0x5678, {0x9a,0xbc,0xde,0xf1,0x23,0x45,0x67,0x89}
    };
    NTSTATUS Status = STATUS_SUCCESS;

    Status = ExGetFirmwareEnvironmentVariable(&VariableName, &VendorGuid, &Content, &BufferSize, NULL);
    if (!NT_SUCCESS(Status)) {
        DbgPrintEx(0, 0, "Failed to Read Data!\n");
        return Status;
    }

    for (ULONG x = 0; x < BufferSize; x++) {
        DbgPrintEx(0, 0, "The value from UEFI Variable: 0x%02x\n", Content[x]);
    }

    return STATUS_SUCCESS;
}

In the project, we accessed the content of the our UEFI Variable with ExGetFirmwareEnvironmentVariable routine. Here's result:

When ExGetFirmwareEnvironmentVariable called, The following routines are called after the routine:

First of all it calls ExpGetFirmwareEnvironmentVariable:

And then the parameters of the ExGetFirmwareEnvironmentVariable are passed to IoGetEnvironmentVariableEx:

Creating UEFI Variable from Windows Driver

Also we can create and set UEFI Variable from Windows Driver. ExSetFirmwareEnvironmentVariable can be used for these purpose:

#include <ntddk.h>
#pragma warning(disable: 4057)

#define EFI_VARIABLE_NON_VOLATILE        0x00000001
#define EFI_VARIABLE_BOOTSERVICE_ACCESS  0x00000002
#define EFI_VARIABLE_RUNTIME_ACCESS      0x00000004

NTSTATUS DriverUnload(PDRIVER_OBJECT DriverObject)
{
    UNREFERENCED_PARAMETER(DriverObject);
    DbgPrintEx(0, 0, "Driver unloaded.\n");

    return STATUS_SUCCESS;
}

NTSTATUS DriverEntry(PDRIVER_OBJECT DriverObject, PUNICODE_STRING RegistryPath)
{
    UNREFERENCED_PARAMETER(RegistryPath);
    DriverObject->DriverUnload = DriverUnload;

    UNICODE_STRING VariableName = RTL_CONSTANT_STRING(L"YUPIIIIIII");
    WCHAR Buffer[] = L"HELLOOO from Windows!!";
    ULONG BufferSize = sizeof(Buffer);
    GUID VendorGuid = {
        0xa1b2c3d4, 0x1234, 0x5678, {0x9a,0xbc,0xde,0xf1,0x23,0x45,0x67,0x89}
    };
    NTSTATUS Status = STATUS_SUCCESS;

    UINT32 Attributes = EFI_VARIABLE_NON_VOLATILE | EFI_VARIABLE_BOOTSERVICE_ACCESS | EFI_VARIABLE_RUNTIME_ACCESS;

    Status = ExSetFirmwareEnvironmentVariable(&VariableName, &VendorGuid, &Buffer, BufferSize, Attributes);
    if (!NT_SUCCESS(Status)) {
        DbgPrintEx(0, 0, "Failed to write the value! Error Code: 0x%x\n", Status);
        return Status;
    }
    DbgPrintEx(0, 0, "Done!\n");


    return STATUS_SUCCESS;
}

And UEFI Driver:

#include <Uefi.h>
#include <Library/UefiApplicationEntryPoint.h>
#include <Library/UefiLib.h>
#include <Library/PcdLib.h>
#include <Library/UefiBootServicesTableLib.h>
#include <Library/UefiRuntimeServicesTableLib.h>

EFI_STATUS EFIAPI UefiMain(EFI_HANDLE ImageHandle, EFI_SYSTEM_TABLE *SystemTable) {
  CHAR16 *VariableName = L"YUPIIIIIII";
  EFI_GUID VendorGuid = { 0xa1b2c3d4, 0x1234, 0x5678, {0x9a,0xbc,0xde,0xf1,0x23,0x45,0x67,0x89} };
  CHAR16 Buffer[32];
  UINTN DataSize = sizeof(Buffer);
  EFI_STATUS Status = EFI_SUCCESS;

  UINT32 Attributes = EFI_VARIABLE_NON_VOLATILE |
                      EFI_VARIABLE_BOOTSERVICE_ACCESS |
                      EFI_VARIABLE_RUNTIME_ACCESS;

  Status = gRT->GetVariable(VariableName, &VendorGuid, &Attributes, &DataSize, &Buffer);
  if (EFI_ERROR(Status)) {
      Print(L"Failed to read the data!\n");
      return Status;
  }
  Print(L"The Content: %s\n", Buffer);

  return EFI_SUCCESS;
}

Here's result:

Conclusion

In this article, we demonstrated how UEFI and Windows drivers can communicate with each other using NVRAM variables. By leveraging SetVariable and GetVariable in UEFI, and ExGetFirmwareEnvironmentVariable / ExSetFirmwareEnvironmentVariable in Windows, we established a persistent and reliable data channel between the two environments.

This method enables developers to build seamless integrations between firmware and the OS, allowing for flexible configurations, feature toggles, or telemetry mechanisms across reboots.

DEV Community: bekoo

Manipulating QEMU Hardwares with Bootkit

What SMBIOS Actually Is

A Single Record's Memory Layout

Why This Structure Exists

The Code

Locating the Protocol

Walking the Table

UUID vs. Strings — Two Different Problems

The Queue — Why Not Call UpdateString Immediately

Refreshing the Pointer and Verifying

[My Debugger Journey] Managing Execution Modes with NASM

Starting from Reset Vector

Real-Address Mode and the Segmented Memory Model

Calculating 0xFFFF0000 Address

Fetching Instruction from the Reset Vector

Switching from Real Mode to Protection Mode

0x0 - A20 Gate

0x1 - GDT and Switching to Protected Mode

0x2 - Paging and the Transition to Long Mode

0x3 - IDT and Exception Handling

[My Debugger Journey] Working on Debug Registers with NASM

Debug Registers

Detecting Breakpoints

Generating #DB Exception

Adding our Handler into IDT

Triggering a Breakpoint with DR7 Register

Using DR7 in NASM Assembly

Setting the Writing Condition to a Breakpoint

Conclusion

[My Debugger Journey] Building a Disassembler with NASM

How a Disassembler Reads Machine Code

Instruction Encodings

Instruction Prefixes

Opcode

Mandatory Prefix and Escape Prefix

ModR/M

A concrete example

Building a Disassembler with NASM

Conclusion

[My Debugger Journey] Working on Single-Step Breakpoints in a Debugger

Introduction

Single-Step Breakpoints and Trap Flag

Simple Project in NASM

UEFI to Windows Communication via NVRAM Variables

What is NVRAM?

UEFI Variables

Access UEFI Variables with Services

1 - SetVariable()

2 - GetVariable()

Coding Windows Driver

Creating UEFI Variable from Windows Driver

Conclusion

References