DEV Community: bekoo

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

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