Breakpoints are used to stop the target process at certain points or when the target process reads, writes, or accesses certain addresses. Breakpoints that stop on read, write, or access are commonly called watchpoints.

Adding Breakpoints

Hardware vs. Software

There are several important differences between hardware and software breakpoints. It can be very helpful to use the correct one for the correct situation. The following table illustrates the differences and shows when you would want to use each type.

Creating/Modifying Breakpoints

Press OK to add the breakpoint.

Built-In Breakpoint Functions

• Do Nothing: Performs no action. Default for Prolog and Epilog. Parm is not used.
• Sys Beep: Beeps for Parm milliseconds.
• Single Step: Shows the Disassembler and allows the user to single step through the code. Default for Callback. Parm is not used.
• Set CF: If Parm is 0, this sets the CF flag to 0, otherwise it sets it to 1.
• Set PF: If Parm is 0, this sets the PF flag to 0, otherwise it sets it to 1.
• Set AF: If Parm is 0, this sets the AF flag to 0, otherwise it sets it to 1.
• Set ZF: If Parm is 0, this sets the ZF flag to 0, otherwise it sets it to 1.
• Set SF: If Parm is 0, this sets the SF flag to 0, otherwise it sets it to 1.
• Set OF: If Parm is 0, this sets the OF flag to 0, otherwise it sets it to 1.
• Script Function: Calls a script function where Parm is used to determine which script function to call. The function called will be named On_BP_Parm() where Parm in the function name is the number specified in Parm in the dialog box.
• Cur Proc Script Function: Same as above, except that the function called is in the format On_BP_CURPROC_EXE_Parm(), where CURPROC_EXE is the name of the current process (in all caps, with special characters replaced by underscores), and Parm is again the numeric value specified in the dialog. Because the name of the current process is in the script function, the script function will only be called for that process.
• Custom Function…: Not actually a function itself. Select this to open the Add Function dialog.

Script Function

You can call your own script functions when a breakpoint is hit. This is usually preferred over creating breakpoint-handling DLL’s because of the ease in writing the functions and calling them through breakpoints.

Script Events offer the same functionality as most of the 10 optional functions listed above. Use On_BeginDebug in place of the DLL function MHS_StartUp (or StartUp), and On_EndDebug in place of the DLL function MHS_CleanUp (or CleanUp). Use On_OpenProcess in place of MHS_ProcessAttach and On_CloseProcess in place of MHS_ProcessDetach, but note however that these functions are called regardless of whether the Debugger is active or not.

The script function has one of the following prototypes:

VOID On_BP_#( LPVOID lpvAddress, LPPROC_INFO_MHS lpProcInfo );
VOID On_BP_*_#( LPVOID lpvAddress, LPPROC_INFO_MHS lpProcInfo );

This parameters are exactly the same as with DLL breakpoint-handler functions, except that the PROC_INFO_MHS structure is passed as a reference to DLL functions but as a pointer to script functions.

This is an example of a script function used as a breakpoint handler:

INT g_iCount = 0;
VOID On_BP_10( LPVOID lpvAddress, LPPROC_INFO_MHS lpProcInfo ) {
    if ( g_iCount++ % 2 == 0 ) {
        lpProcInfo->pcContext->Eax |= 0x40;
        lpProcInfo->bSetContext = TRUE;
        //PrintF( "%X", lpProcInfo->pcContext->Eax );
    }
    else {
        lpProcInfo->pcContext->Eax |= 0x80;
        lpProcInfo->bSetContext = TRUE;
    }
}

As shown in this snippet, when changing registers via lpProcInfo->pcContext, set lpProcInfo->bSetContext to TRUE rather than calling SetThreadContext() directly. When lpProcInfo->bSetContext is set to TRUE, MHS will call SetThreadContext() itself after the function returns. This is slightly faster than calling SetThreadContext() from within the script.

NOTE: If possible, the breakpoint will put a lock on the script system. This lock allows the breakpoint to maintain a ready-to-go script thread that can directly execute the script function. Without locking the script system, a script thread must be allocated and initialized, and then the function address must be found from a table for the script thread to execute.
The lock is made when the script function already exists within the compiled scripts when the breakpoint is created. This is normally the case.
If a lock is made, the script function can be called roughly 10 times faster than without a lock. This improves the performance of the breakpoint—and thusly the Debugger—substantially.
However when the script system is locked it can not be recompiled. In order to recompile the scripts, the breakpoint must lose its lock on the script system. This can be achieved by setting the breakpoint function to Do Nothing temporarily. After recompiling the scripts you can set the breakpoint function back to Script Function. You will not need to modify the breakpoint Parm values.
The lock has no other effects on the script system.

Conditions

Miscellaneous

This section covers the miscellaneous issues regarding breakpoints.

• Software executable breakpoints modify one byte each of the RAM of the target process. If this is a dire problem, use hardware executable breakpoints instead.
• Software read/write breakpoints change page protections in the target process. If this is a dire problem, use hardware access/write breakpoints instead.
• The Debugger does not have to be enabled for breakpoints to be set, but does have to be enabled for breakpoints to be applied. If the Debugger is not active, no RAM is modified and no page properties are changed.
• Breakpoints are organized into layers. All breakpoints created by the user are loaded to the User Breakpoint Layer. Breakpoints created by the Auto-Hack feature are loaded to the Auto-Hack Layer. Only one breakpoint layer may be active at once. This means user breakpoints will not operate while the Auto-Hack feature is active. To enable user breakpoints again, stop the Auto-Hack session by opening the Helper window Auto-Hack tab and pressing Stop or Clear All.
• The current version of MHS does not offer 100% backwards compability with MHPB/MHBPL breakpoint files. Specifically, hardware read breakpoints no longer exist. All other features are compatible.
• While software read/write breakpoints are set, some features of MHS may not function 100% correctly. Specifically, the RAM Watcher and Hex Editor may flicker and some values in the main list may become “Unobtainable”. This behavior is normal; it is caused by the fact that software read/write breakpoints change the page properties in the target process to inaccessible. Inaccessible RAM appears red in the Hex Editor, N/A in the RAM Watcher, and Unobtainable in the main list. Flickering appears when the page of RAM is read or written, causing the page properties to be temporarily set back to normal and then set back to inaccessible.
• If the target process is a full-screen game, do not set breakpoints that cause single-stepping. This is a common problem shared between all ring-3 debuggers. When the breakpoint is hit the game will be completely paused and will be unable to minimize (because minimizing would require it to execute code, which, being completely paused, will not happen). If a breakpoint, or anything else, pauses the game, you will be forced to reboot your computer.