# Using Breakpoints

This module assumes you know how to launch `termmines` in Ghidra using GDB and know where to find the basic Debugger GUI components.
If not, please refer to the previous modules.

This module will address the Breakpoints window in more depth.
While the breakpoint manager is able to deal with a system of targets, we will only deal with a single target at a time.

## Breakpoints

Most likely, this window is empty if you have been following the lesson.

![The breakpoints window](images/Breakpoints_EmptyAfterLaunch.png)

From here, you can toggle and delete existing breakpoints.
There are several ways to set a new breakpoint:

1. From any static or dynamic listing window, including Disassembly, Memory/Hex, and the Decompiler, right-click and select ![set breakpoint](images/breakpoint-enable.png) Set Breakpoint, press **`K`** on the keyboard, or double-click the margin.
1. From the Breakpoints window, use the **Set Breakpoint** dropdown to access the various breakpoint actions defined by GDB.
1. From the Terminal window, use the GDB command, e.g., `break main`.

The advantage of using the listings is that you can quickly set a breakpoint at any address.
The advantage of using the dropdown action or Terminal window is that you can specify something other than an address.
Often, those specifications still resolve to addresses, and Ghidra will display them.
Ghidra will memorize breakpoints by recording them as special bookmarks in the program database.
There is some iconography to communicate the various states of a breakpoint.
When all is well and normal, you should only see enabled ![enabled breakpoint](images/breakpoint-enable.png) and disabled ![disabled breakpoint](images/breakpoint-disable.png) breakpoints.
If the target is terminated (or not launched yet), you may also see ineffective ![ineffective breakpoint](images/breakpoint-enable-ineff.png) breakpoints.

## Examining Minesweeper Board Setup

Suppose we want to cheat at `termmines`.
We might like to understand how the mines are placed.
Knowing that the mines are placed randomly, we might hypothesize that it is using the `srand` and `rand` functions from the C standard library.
While we can test that hypothesis by examining the imports statically, we might also like to record some actual values, so we will approach this dynamically.
(This is the Debugger course, after all.)
The breakpoint on `srand` will allow us to capture the random seed.
The breakpoint on `rand` will help us find the algorithm that places the mines.

### Set the Breakpoints

In the Terminal, type the GDB commands to set breakpoints on `srand` and `rand`:

```gdb
break srand
break rand
```

The breakpoint window should now be updated:

![Populated breakpoints window](images/Breakpoints_PopAfterSRandRand.png)

For a single target, the lower panel of the Breakpoints window does not add much information, but it does have some.
We will start with the top panel.
This lists the *logical* breakpoints, preferring static addresses.

* The left-most column **State** indicates the breakpoint's state.
  Here, we see the inconsistent ![inconsistent](images/breakpoint-overlay-inconsistent.png) overlay, because Ghidra cannot save the breakpoint without a program database.
  That is because `srand` and `rand` are in a different module, and we have not yet imported it into Ghidra.
* The next column **Name** is the name of the breakpoint.
  This is for informational purposes only.
  You can rename a breakpoint however you like, and it will have no effect on the target nor back-end debugger.
* The next column **Address** gives the address of the breakpoint.
  Notice that the addresses were resolved, even though the breakpoints were specified by symbol.
  Typically, this is the *static* address of the breakpoint; however, if the module image is not imported, yet, this will be the *dynamic* address, subject to relocation or ASLR.
* The next column **Image** gives the name of the program database containing the breakpoint.
  Again, because the module has not been imported yet, this column is blank.
* The next column **Length** gives the length of the breakpoint.
  In GDB, this generally applies to watchpoints only.
* The next column **Kinds** gives the kinds of breakpoint.
  Most breakpoints are software execution breakpoints, indicated by "SW_EXECUTE."
  That is, they are implemented by patching the target's memory with a special instruction that traps execution &mdash; `INT3` on x86.
  There are also hardware execution breakpoints indicated by "HW_EXECUTE," and access breakpoints indicated by "HW_READ" and/or "HW_WRITE".
  **NOTE**: GDB would call access breakpoints *watchpoints*.
  An advantage to software breakpoints is that you can have a practically unlimited number of them. Some disadvantages are they can be detected easily, and they are limited to execution breakpoints.
* The next column **Locations** counts the number of locations for the breakpoint.
  For a single-target session, this is most likely 1.
* The final column **Sleigh** is only applicable to the emulator.
  It indicates that the breakpoint's behavior has been customized with Sleigh code.
  This is covered in [Emulation](B2-Emulation.md).

Now, we move to the bottom panel.
This lists the breakpoint locations, as reported by the back-end debugger(s).
The State, Address, and Sleigh columns are the same as the top, but for the individual *dynamic* addresses.

* The **Name** column is the name as designated by the back-end.
* The **Trace** column indicates which target contains the location.
  The text here should match one of the tabs from the Dynamic Listing panel.
* The **Comment** column is a user-defined comment.
* The **Expression** column is the expression given when specifying the breakpoint, e.g., `srand`.

### Toggling the Breakpoints

While there is no need to toggle the breakpoints right now, it is a good time to demonstrate the feature.
There are several ways to toggle a breakpoint:

1. In any listing, as in setting a breakpoint, right-click and select a toggle action, press **`K`** on the keyboard, or double-click its icon in the margin.
1. From the Model window, expand the *Breakpoints* node and double-click a breakpoint, or select one with the keyboard and press **`ENTER`**.
   For GDB, this must be done from the top-level *Breakpoints* node, not the one subordinate to the *inferior*.
1. From the Breakpoints window, single-click the breakpoint's status icon, right-click an entry and select a toggle action, or create a selection and use a toggling action from the local toolbar.
   Either panel works, but the top panel is preferred to keep the breakpoints consistent.
   The local toolbar also has actions for toggling all breakpoints in the session.
1. From the Terminal window, use the GDB commands, e.g., `disable 2`.

Practice toggling them.
Notice that no matter how you toggle the breakpoints, the display updates.
You might also type `info break` into the Terminal t