Hardware breakpoints

 

 

A breakpoint is a mechanism to pause a program execution for further analysis during runtime to identify run-time errors. Pausing is required to examine the run-time values of variables. Examining these variables is possible only if they are valid in the current context. Various options will be provided for developer by debugger to examine the details of running program to identify run-time errors including CPU registers, call stack, memory dump and other debugger supported features.

x86 Hardware provided

x86 architecture provides interrupt INT 1, INT 3 and Debug registers which helps debuggers to implement breakpoints.

INT 1 – 0xCD01 :

Single step interrupt provided by x86, where program can be debugged single instruction at a time. This handler is implemented by operating system and provides high level API for debugger development.

To perform single step on process, debugger need to attach with admin privilege. Debugger need to set Trap Flag (TF) in EFLAGS register. By enabling this flag, debugger gets control from the CPU before executing each instruction. Debugger will give control to developer either in assembly instructions or source code level if it has debugging information. Debugger will give various options for developer for continuing the execution of code after examining the variable values.

Trap Flag(TF) is fully under control of Debugger, it can enable or disable this flag based on various options provided by debugger including software and conditional breakpoints.

INT 3 – 0xCC :

Break point interrupt is provided by x86, where debugger can place this anywhere inside the program execution. This opcode 0xCC can be placed by developer directly inside a program ( ex: __asm int 3 in a C/C++ code ), this instruction will be identified by CPU during execution of a program and transfers control to a debugger if its running. If the program is not running inside a program, operating system will execute default handler i.e to terminate the program.

Opcode 0xCC can be used by IDE debugger to implement software based breakpoints. If a developer inserts IDE based breakpoint, internally IDE can this one byte instruction in the code, once IDE gets control from CPU, it will remove this one byte instruction and replace with original instruction and allow developer to examine the program variables. One byte opcode will make easy to insert instruction anywhere in program without much difficulty.

Debugger Registers:

x86 provides 8 debug registers DB0 to DB7 and 2 model specific registers (MSR). These registers can store either memory address or I/O locations to break the execution for analysis of a program in a debugger. To perform action on these registers modifier code must be running kernel mode.

Only 4 registers can be used to store the memory location address to pause the execution i.e DRO to DR3, Each of these registers stores the memory address.  After the debugger assigns the memory address, based on the address CPU will automatically pause the execution and provide the control to the debugger to help developer to examine the state of the program.  These 4 registers functions based on flags set at DR6 and DR7 registers. DR6 is used as status register and DR7 is used as control register. DR6 flags will not be cleared by CPU, callback program need to clear the stack and this will happen only after exception handler gets the control.

DR6 has following flags:

1. Bit 0 to 3 (Breakpoint condition detected): Each of this bit indicated which DR register has triggered breakpoint. If bit 0 is set, it means breakpoint is set using DR0 register.
2. Bit 13 (Debug register detected): This bit indicates next instruction in the execution flow is going to access the debug registers from DR0 to DR7.
3. Bit 14 (Single Step): This bit indicates that debug exception has generated since Trap Flag (TF) is set in EFLAGS register.
4. Bit 15 (Task Switch): This bit indicates debug exception if triggered from a task switch where Trap Flag (TF) is set.

DR7 register is used as control register. This register will enable or disable breakpoints with breakpoint conditions. This register has following flags:

1. Bit 0, 2, 4 and 6 (Local Breakpoint): These bits enable the breakpoint for current task. After breakpoint exception, CPU will clear this flag to prevent breakpoint in other task.
2. Bit 1, 3, 5 and 7 (Global breakpoint): These bits enable the breakpoint in all tasks in the system, after breakpoint exception CPU will not clear this flag to break in any task globally.
3. Bit 13 (General detect enable): This bit enables debug register protection which causes a debug exception before executing MOV instruction to move data to debug registers.
4. Bit 16, 17, 20, 21, 24, 25, 28 and 29 (Read/Write): This flag specifies a condition for each breakpoint. Debug Extension (DE) flag in control register CR4 determines how to interpret these flags. DE flag has following types:
   1. 00 – Break on instruction execution only
   2. 01 – Break on data writes only
   3. 10 – Break on I/O reads or writes
   4. 11 – Break on data reads or writes but not instruction fetches
5. Bit 18, 19, 22, 23, 26, 27, 30 and 31 : These bits helps in identifying the size of memory location specified in debug registers with following options:
   1. 00 – 1 byte
   2. 01 – 2 byte
   3. 10 – undefined
   4. 11 – 4 byte

For details: http://www.yashks.com/2011/01/210/

 

 Introduction

I decided to write this article about hardware breakpoints for the following reasons:

• Visual C++ only supports write-only data breakpoints. You might want to trigger a break when data is read as well.
• You might not be using Visual C++, so chances are that your debugger uses some slow software-based mechanism.
• You might want to set/remove a breakpoint programmatically.
• You may be interested in low level CPU stuff!

Features

• Works for x86 and x64.
• Supports upto 4 hardware breakpoints per thread.

Debug Registers

x86/x64 contains a set of debug registers, named DR0, DR1, DR2, DR3, DR6, and DR7. These registers are 32-bit when in 32-bit mode, and 64-bit when in long mode. DR0, DR1, DR2, and DR3 contain the linear addresses of the breakpoint, and DR7 contains the bits explained here:

Bits	Meaning
0-7	Flags for each of the 4 debug registers (2 for each). The first flag is set to specify a local breakpoint (so the CPU resets the flag when switching tasks), and the second flag is set to specify a global breakpoint. In Windows, obviously, you can only use the first flag (although I haven't tried the second).
16-23	2 bits for each register, defining when the breakpoint will be triggered: 00b - Triggers when code is executed 01b - Triggers when data is written 10b - Reserved 11b - Triggers when data is read or written
24-31	2 bits for each register, defining the size of the breakpoint: 00b - 1 byte 01b - 2 bytes 10b - 8 bytes 11b - 4 bytes

We use SetThreadContext to set the necessary flags for the thread. After that, when the breakpoint is triggered, an exception of the value EXCEPTION_SINGLE_STEP is raised.

Setting the Breakpoint

HANDLE SetHardwareBreakpoint(HANDLE hThread,HWBRK_TYPE Type,HWBRK_SIZE Size,void* s);

• hThread - Handle to the thread for which the breakpoint is to be set.
• Type - Type of the breakpoint:
  • HWBRK_TYPE_CODE
  • HWBRK_TYPE_READWRITE
  • HWBRK_TYPE_WRITE
• Size - Size of the breakpoint:
  • HWBRK_SIZE_1
  • HWBRK_SIZE_2
  • HWBRK_SIZE_4
  • HWBRK_SIZE_8
• addr - The address of the breakpoint.

The function returns a handle to the breakpoint, to be used later in RemoveHardwareBreakpoint. It can return 0 if:

• You do not have access to the thread.
• You have set the maximum number of breakpoints for that thread (4).

Removing the Breakpoint

bool RemoveHardwareBreakpoint(HANDLE hBrk);

Removes the breakpoint, returning true on success.

Sample

int WinMain(HINSTANCE,HINSTANCE,LPSTR,int)
{
    char c1[100] = {0};
    lstrcpyA(c1,"Hello 1");
    HANDLE hX1 = 0;

    hX1 = SetHardwareBreakpoint(GetCurrentThread(), 
                                HWBRK_TYPE_READWRITE,HWBRK_SIZE_4,c1);
    __try
    {
        volatile char a1 = c1[2];
        // To ensure that it won't be optimized out.
    }
    __except(GetExceptionCode() == STATUS_SINGLE_STEP)
    {
        MessageBoxA(0,"Breakpoint hit!",0,MB_OK);
    }
    RemoveHardwareBreakpoint(hX1);
    return 0; 
} 

All source code down here:

hwbrk.h

#ifndef _HWBRK_H
#define _HWBRK_H

enum HWBRK_TYPE
{
    HWBRK_TYPE_CODE,
    HWBRK_TYPE_READWRITE,
    HWBRK_TYPE_WRITE,
};

enum HWBRK_SIZE
{
    HWBRK_SIZE_1,
    HWBRK_SIZE_2,
    HWBRK_SIZE_4,
    HWBRK_SIZE_8,
};

HANDLE SetHardwareBreakpoint(HANDLE hThread,HWBRK_TYPE Type,HWBRK_SIZE Size,void* s);
bool RemoveHardwareBreakpoint(HANDLE hBrk);


#endif 

hwbrk.cpp

 #define _WIN32_WINNT _WIN32_WINNT_WINXP
#include <windows.h>
#include "hwbrk.h"

class HWBRK
{
    public:
        void* a;
        HANDLE hT;
        HWBRK_TYPE Type;
        HWBRK_SIZE Size;
        HANDLE hEv;
        int iReg;
        int Opr;
        bool SUCC;

        HWBRK()
        {
            Opr = 0;
            a = 0;
            hT = 0;
            hEv = 0;
            iReg = 0;
            SUCC = false;
        }
};


void SetBits(DWORD_PTR& dw, int lowBit, int bits, int newValue)
{
    DWORD_PTR mask = (1 << bits) - 1; 
    dw = (dw & ~(mask << lowBit)) | (newValue << lowBit);
}

static DWORD WINAPI th(LPVOID lpParameter)
{
    HWBRK* h = (HWBRK*)lpParameter;
    int j = 0;
    int y = 0;

    j = SuspendThread(h->hT);
    y = GetLastError();

    CONTEXT ct = {0};
    ct.ContextFlags = CONTEXT_DEBUG_REGISTERS;
    j = GetThreadContext(h->hT,&ct);
    y = GetLastError();

    int FlagBit = 0;

    bool Dr0Busy = false;
    bool Dr1Busy = false;
    bool Dr2Busy = false;
    bool Dr3Busy = false;
    if (ct.Dr7 & 1)
        Dr0Busy = true;
    if (ct.Dr7 & 4)
        Dr1Busy = true;
    if (ct.Dr7 & 16)
        Dr2Busy = true;
    if (ct.Dr7 & 64)
        Dr3Busy = true;

    if (h->Opr == 1)
    {
        // Remove
        if (h->iReg == 0)
        {
            FlagBit = 0;
            ct.Dr0 = 0;
            Dr0Busy = false;
        }
        if (h->iReg == 1)
        {
            FlagBit = 2;
            ct.Dr1 = 0;
            Dr1Busy = false;
        }
        if (h->iReg == 2)
        {
            FlagBit = 4;
            ct.Dr2 = 0;
            Dr2Busy = false;
        }
        if (h->iReg == 3)
        {
            FlagBit = 6;
            ct.Dr3 = 0;
            Dr3Busy = false;
        }

        ct.Dr7 &= ~(1 << FlagBit);
    }
    else
    {
        if (!Dr0Busy)
        {
            h->iReg = 0;
            ct.Dr0 = (DWORD_PTR)h->a;
            Dr0Busy = true;
        }
        else
        if (!Dr1Busy)
        {
            h->iReg = 1;
            ct.Dr1 = (DWORD_PTR)h->a;
            Dr1Busy = true;
        }
        else
        if (!Dr2Busy)
        {
            h->iReg = 2;
            ct.Dr2 = (DWORD_PTR)h->a;
            Dr2Busy = true;
        }
        else
        if (!Dr3Busy)
        {
            h->iReg = 3;
            ct.Dr3 = (DWORD_PTR)h->a;
            Dr3Busy = true;
        }
        else
        {
            h->SUCC = false;
            j = ResumeThread(h->hT);
            y = GetLastError();
            SetEvent(h->hEv);
            return 0;
            }
        ct.Dr6 = 0;
        int st = 0;
        if (h->Type == HWBRK_TYPE_CODE)
            st = 0;
        if (h->Type == HWBRK_TYPE_READWRITE)
            st = 3;
        if (h->Type == HWBRK_TYPE_WRITE)
            st = 1;
        int le = 0;
        if (h->Size == HWBRK_SIZE_1)
            le = 0;
        if (h->Size == HWBRK_SIZE_2)
            le = 1;
        if (h->Size == HWBRK_SIZE_4)
            le = 3;
        if (h->Size == HWBRK_SIZE_8)
            le = 2;

        SetBits(ct.Dr7, 16 + h->iReg*4, 2, st);
        SetBits(ct.Dr7, 18 + h->iReg*4, 2, le);
        SetBits(ct.Dr7, h->iReg*2,1,1);
        }



    ct.ContextFlags = CONTEXT_DEBUG_REGISTERS;
    j = SetThreadContext(h->hT,&ct);
    y = GetLastError();

    ct.ContextFlags = CONTEXT_DEBUG_REGISTERS;
    j = GetThreadContext(h->hT,&ct);
    y = GetLastError();

    j = ResumeThread(h->hT);
    y = GetLastError();

    h->SUCC = true;

    SetEvent(h->hEv);
    return 0;
}

HANDLE SetHardwareBreakpoint(HANDLE hThread,HWBRK_TYPE Type,HWBRK_SIZE Size,void* s)
{
    HWBRK* h = new HWBRK;
    h->a = s;
    h->Size = Size;
    h->Type = Type;
    h->hT = hThread;


    if (hThread == GetCurrentThread())
    {
        DWORD pid = GetCurrentThreadId();
        h->hT = OpenThread(THREAD_ALL_ACCESS,0,pid);
    }

    h->hEv = CreateEvent(0,0,0,0);
    h->Opr = 0; // Set Break
    HANDLE hY = CreateThread(0,0,th,(LPVOID)h,0,0);
    WaitForSingleObject(h->hEv,INFINITE);
    CloseHandle(h->hEv);
    h->hEv = 0;

    if (hThread == GetCurrentThread())
    {
        CloseHandle(h->hT);
    }
    h->hT = hThread;

    if (!h->SUCC)
    {
        delete h;
        return 0;
    }


    return (HANDLE)h;
}






bool RemoveHardwareBreakpoint(HANDLE hBrk)
{
    HWBRK* h = (HWBRK*)hBrk;
    if (!h)
        return false;

    bool C = false;
    if (h->hT == GetCurrentThread())
    {
        DWORD pid = GetCurrentThreadId();
        h->hT = OpenThread(THREAD_ALL_ACCESS,0,pid);
        C = true;
    }

    h->hEv = CreateEvent(0,0,0,0);
    h->Opr = 1; // Remove Break
    HANDLE hY = CreateThread(0,0,th,(LPVOID)h,0,0);
    WaitForSingleObject(h->hEv,INFINITE);
    CloseHandle(h->hEv);
    h->hEv = 0;

    if (C)
    {
        CloseHandle(h->hT);
    }

    delete h;
    return true;
}

test.cpp

#include <windows.h>
#include "hwbrk.h"
#include <stdio.h>


const char* cH1 = "Breakpoint 1 hit!";
const char* cH2 = "Breakpoint 2 hit!";
const char* cH3 = "Breakpoint 3 hit!";
const char* cH4 = "Breakpoint 4 hit!";


void SomeFunc()
{
    Sleep(10);
    Sleep(50);
}

int __stdcall WinMain(HINSTANCE,HINSTANCE,LPSTR,int)
{
    char c1[100] = {0};
    char c2[100] = {0};
    lstrcpyA(c1,"Hello 1");
    lstrcpyA(c2,"Hello 2");
    HANDLE hX1 = 0,hX2 = 0,hX3 = 0,hX4 = 0;

    hX1 = SetHardwareBreakpoint(GetCurrentThread(),HWBRK_TYPE_READWRITE,HWBRK_SIZE_4,c1);
    hX2 = SetHardwareBreakpoint(GetCurrentThread(),HWBRK_TYPE_WRITE,HWBRK_SIZE_1,c2);
    hX3 = SetHardwareBreakpoint(GetCurrentThread(),HWBRK_TYPE_CODE,HWBRK_SIZE_1,SomeFunc);
    hX4 = SetHardwareBreakpoint(GetCurrentThread(),HWBRK_TYPE_WRITE,HWBRK_SIZE_8,c2);

    __try
    {
        volatile char a1 = c1[2];
    }
    __except(GetExceptionCode() == STATUS_SINGLE_STEP)
    {
        MessageBoxA(0,cH1,0,MB_OK);
    }

    __try
    {
        c2[0] = 'Z';
    }
    __except(GetExceptionCode() == STATUS_SINGLE_STEP)
    {
        MessageBoxA(0,cH2,0,MB_OK);
    }

    __try
    {
        SomeFunc();
    }
    __except(GetExceptionCode() == STATUS_SINGLE_STEP)
    {
        MessageBoxA(0,cH3,0,MB_OK);
    }


    __try
    {
        c2[2] = 'Z';
    }
    __except(GetExceptionCode() == STATUS_SINGLE_STEP)
    {
        MessageBoxA(0,cH4,0,MB_OK);
    }


    RemoveHardwareBreakpoint(hX4);
    RemoveHardwareBreakpoint(hX3);
    RemoveHardwareBreakpoint(hX2);
    RemoveHardwareBreakpoint(hX1);
} 

For details: http://www.codeproject.com/KB/debug/hardwarebreakpoint.aspx

Also another article and a C++wrapper: http://www.morearty.com/code/breakpoint/

#ifndef _BREAKPOINT_H_
#define _BREAKPOINT_H_

#ifdef _DEBUG

class CBreakpoint
{
public:
    CBreakpoint() { m_index = -1; }
    ~CBreakpoint() { Clear(); }

    // The enum values correspond to the values used by the Intel Pentium,
    // so don't change them!
    enum Condition { Write = 1, Read /* or write! */ = 3 };

    void Set(void* address, int len /* 1, 2, or 4 */, Condition when);
    void Clear();

protected:

    inline void SetBits(unsigned long& dw, int lowBit, int bits, int newValue)
    {
        int mask = (1 << bits) - 1; // e.g. 1 becomes 0001, 2 becomes 0011, 3 becomes 0111

        dw = (dw & ~(mask << lowBit)) | (newValue << lowBit);
    }

    int m_index; // -1 means not set; 0-3 means we've set that hardware bp
};

#endif // _DEBUG

#endif // _BREAKPOINT_H_ 

#include <windows.h>
#include <assert.h>
#include "breakpoint.h"

#ifdef _DEBUG

void CBreakpoint::Set(void* address, int len, Condition when)
{
    // make sure this breakpoint isn't already set
    assert(m_index == -1);

    CONTEXT cxt;
    HANDLE thisThread = GetCurrentThread();

    switch (len)
    {
    case 1: len = 0; break;
    case 2: len = 1; break;
    case 4: len = 3; break;
    default: assert(false); // invalid length
    }

    // The only registers we care about are the debug registers
    cxt.ContextFlags = CONTEXT_DEBUG_REGISTERS;

    // Read the register values
    if (!GetThreadContext(thisThread, &cxt))
        assert(false);

    // Find an available hardware register
    for (m_index = 0; m_index < 4; ++m_index)
    {
        if ((cxt.Dr7 & (1 << (m_index*2))) == 0)
            break;
    }
    assert(m_index < 4); // All hardware breakpoint registers are already being used

    switch (m_index)
    {
    case 0: cxt.Dr0 = (DWORD) address; break;
    case 1: cxt.Dr1 = (DWORD) address; break;
    case 2: cxt.Dr2 = (DWORD) address; break;
    case 3: cxt.Dr3 = (DWORD) address; break;
    default: assert(false); // m_index has bogus value
    }

    SetBits(cxt.Dr7, 16 + (m_index*4), 2, when);
    SetBits(cxt.Dr7, 18 + (m_index*4), 2, len);
    SetBits(cxt.Dr7, m_index*2,        1, 1);

    // Write out the new debug registers
    if (!SetThreadContext(thisThread, &cxt))
        assert(false);
}


void CBreakpoint::Clear()
{
    if (m_index != -1)
    {
        CONTEXT cxt;
        HANDLE thisThread = GetCurrentThread();

        // The only registers we care about are the debug registers
        cxt.ContextFlags = CONTEXT_DEBUG_REGISTERS;

        // Read the register values
        if (!GetThreadContext(thisThread, &cxt))
            assert(false);

        // Zero out the debug register settings for this breakpoint
        assert(m_index >= 0 && m_index < 4); // m_index has bogus value
        SetBits(cxt.Dr7, m_index*2, 1, 0);

        // Write out the new debug registers
        if (!SetThreadContext(thisThread, &cxt))
            assert(false);

        m_index = -1;
    }
}

 

This is a debugging helper class which lets you set breakpoints on the fly from within code. 
This is mainly useful for the case where you have a variable that you know is getting trashed, 
but you have no idea who is trashing it. You can cause the debugger to break in at the very moment the variable is changed. 
The really cool thing is that this makes use of the Intel Pentium's built-in debug registers, 
which means that it really will stop no matter what code is executing, 
even if it's down in the NT kernel, in a different thread, or whatever.
 
(Visual C++ has the ability to set a breakpoint when a variable's value changes, 
but these breakpoints can be very hard to use, especially on local variables.)
 
 
Usage
The class is called CBreakpoint. If, for example, you have a DWORD called "x" and 
you want to break the next time it's written to, do this:
DWORD x = 1;
   CBreakpoint bp;
   bp.Set(&x, sizeof(x), CBreakpoint::Write);
  
As your code continues to execute, if Visual C++ stops at a location where 
you didn't have a VC++ breakpoint set, it's possible that the CBreakpoint triggered. 
If it did, the assembly instruction immediately before the instruction pointer is the one that caused it to trigger.
 
The breakpoint will be cleared automatically when the CBreakpoint object
 falls out of scope.  Or, to clear it explicitly, do this:
    bp.Clear();
  
You can also break the moment any code even tries to read the value of the variable x! 
(Actually, this will break when someone tries to read or write it.)
    bp.Set(&x, sizeof(x), CBreakpoint::Read);
 
 
Notes
 
This code is Intel-specific.  It will run on Win95/98/ME and on WinNT/2000/XP, 
as long as the machine is running an Intel or compatible chip (e.g. not Alpha).
 
There are certain limitations when the breakpoint is triggered inside system code
 (these same limitations apply to hardware breakpoints set by Visual C++ or any other debugger):
 
 
·                On WinNT/2000/XP, some system code runs in ring 3 (with user privileges), and 

other system code runs in ring 0.  If a hardware breakpoint triggers inside ring 0 code, 

the debugger will stop, but not exactly when the data write happens -- 

it will stop after execution transitions back to ring 3 code.

  In practice, this is not a problem at all -- when the breakpoint triggers,

 it's usually quite easy to figure out what happened.




·                On Win95/98/ME, the situation is not as good.  All system code is treated by 

the debugger as untouchable.  Worse, whenever any hardware breakpoint triggers 

inside system code, you'll never see the breakpoint trigger. 

For example, if a call to strcpy() would cause your breakpoint to trigger, you'll see it, 

because strcpy() is just a regular part of your application. 

But if a call to lstrcpy() would cause your breakpoint to trigger, 

you won't see it, because lstrcpy() is system code.
·                 
 
You can do "bp.Clear()" from the QuickWatch dialog to clear a breakpoint from within the debugger.
 
The second parameter is the number of bytes to watch. This must be either 1, 2, or 4. 
Also, the variable being watched must be aligned appropriately (e.g. if you're watching 4 bytes, 
they must be DWORD-aligned).  If you don't do this, you'll get an error when you try to set the breakpoint. 
There is a limit of 4 hardware breakpoints. Because of this (and also because of common sense),
 don't check in code that uses breakpoints -- just write the code temporarily to find bugs,
 but delete it before checking in your source into your source control system.
 
It's important to pass in the address that you actually want to watch.
Consider these two similar but different cases:
 
 
long *my_array;
my_array = new long[3];
 
CBreakpoint bpArrayPtr, bpArrayFirstElement;
 
// break if someone changes the POINTER
bpArrayPtr.Set(&my_array, sizeof(long*), CBreakpoint::Write);
 
// break if someone changes the FIRST ELEMENT POINTED TO
bpArrayFirstElement.Set(&my_array[0], sizeof(long), CBreakpoint::Write);
 
 
How does it work?
 
The Intel x86 CPUs have some special registers which are intended for debugging use only.
By storing special values into these registers, a program can ask the CPU to execute
 an INT 1 (interrupt 1) instruction immediately whenever a specified memory location
 is read from or written to. 
 (They can also stop when a memory address is about to be executed as code,
 but my CBreakpoint class doesn't use that functionality.)
 
INT 1 also happens to be the interrupt that's executed by the CPU after
 a debugger asks the CPU to single-step one assembly line of the program.  
And by good fortune, when Visual C++ encounters an INT 1 that it wasn't expecting to see 
(as is the case when a CBreakpoint breakpoint is triggered), 
it responds gracefully, stopping the debugger at the appropriate instruction.