Using breakpoints in zxdb

Breakpoints stop execution when some code is executed. To create a breakpoint, use the break command (b for short) and give it a location:

```none {:.devsite-disable-click-to-copy} [zxdb] break main Breakpoint 3 (Software) on Global, Enabled, stop=All, @ main 180 ◉ 181 int main(int argc, char**argv) { 182 fbl::unique_fd dirfd;

  2. A location can be expressed in many different ways.
  4.   * Plain function name. This will match functions with the name in any namespace:
  6.     ```none {:.devsite-disable-click-to-copy}
  7.     [zxdb] break main

  • Member function or functions inside a specific namespace or class:

    none {:.devsite-disable-click-to-copy} [zxdb] break {{"<var>my_namespace</var>"}}::{{"<var>MyClass</var>"}}::{{"<var>MyFunction</var>"}} [zxdb] break ::{{"<var>OtherFunction</var>"}}

  • Source file + line number (separate with a colon):

    none {:.devsite-disable-click-to-copy} [zxdb] break mymain.cc:22

  • Line number within the current frame’s current source file (useful when stepping):

    none {:.devsite-disable-click-to-copy} [zxdb] break 23

  • Memory address:

    none {:.devsite-disable-click-to-copy} [zxdb] break 0xf72419a01

  • Expression: Prefixing with “*” will treat the following input as an expression that evaluates to an address. This is most often used with hardware breakpoints.

    none {:.devsite-disable-click-to-copy} [zxdb] break --type=write *&foo

To list all breakpoints:

```none {:.devsite-disable-click-to-copy} [zxdb] breakpoint

  2. > Note: this is the “breakpoint” noun (a noun by itself lists the things
  3. > associated with it). It is not plural.
  5. To clear a specific breakpoint, give that breakpoint index as the context for the clear command (see
  6. “Interaction model” above). Here’s we’re using the abbreviation for `breakpoint` (`bp`):
  8. ```none {:.devsite-disable-click-to-copy}
  9. [zxdb] bp 2 clear

Or you can clear the current breakpoint:

```none {:.devsite-disable-click-to-copy} [zxdb] clear

  2. Whenever you create or stop on a breakpoint, that breakpoint becomes the default automatically so
  3. `clear` always clears the one you just hit.
  5. `clear` can also take an optional location just like a `break` command. In this way, it will try to
  6. clear all breakpoints at that location and ignore the default breakpoint context.
  8. > Note for GDB users: `delete <index>` is mapped to `bp <index> clear`, while `clear <number>`
  9. > behaves the same in GDB and zxdb.
  11. Breakpoints can also be enabled or disabled:
  13. ```none {:.devsite-disable-click-to-copy}
  14. [zxdb] disable
  15. [zxdb] bp 4 enable

Other properties can be modified via the “get” and “set” commands.

```none {:.devsite-disable-click-to-copy} [zxdb] bp 1 set location = Frobulator::GetThing

  2. ### Hardware data breakpoints ("watchpoints")
  4. The processor can be set to break execution when it reads or writes certain addresses. This can be
  5. particularly useful to track down memory corruption. Create a hardware breakpoint by specifying
  6. "write", "execute" or "read-write" in the "type" for a break command (unlike in some other
  7. debuggers, hardware breakpoints are exposed as a type of breakpoint rather than as a separate
  8. "watchpoint" concept).
  10. ```none {:.devsite-disable-click-to-copy}
  11. [zxdb] break --type=read-write --size=4 0x12345670

As a shortcut, the “watch” command will take the contents of a variable or the result of an expression and set a data write breakpoint over its range:

```none {:.devsite-disable-click-to-copy} [zxdb] watch i [zxdb] watch foo[5]->bar

  2. Notes:
  4.   * CPUs only support a limited number of hardware watchpoints, typically around 4.
  6.   * The size of a watchpoint range is limited to 1, 2, 4, or 8 bytes and the address must be an even
  7.     multiple of the size.
  9.   * Unlike GDB, "watch" will evaluate the expression once and set a breakpoint on the result. It
  10.     won't re-evaluate the expression. In the above example, it will trigger when "bar" changes but
  11.     not if "foo[5]" changes to point to a different "bar".
  13.   * If you watch a variable on the stack and nobody touches it, you will often see it hit in
  14.     another part of the program when the stack memory is re-used. If you get a surprising breakpoint
  15.     hit, check that execution is still in the frame you expect.
  17. ### Programmatic breakpoints
  19. You can insert a hardcoded breakpoint in your code if you want to catch some specific condition.
  20. Clang has a builtin (it won't work in GCC Zircon builds):
  22. ```cpp
  23. __builtin_debugtrap();

If the debugger is already attached to the process, it will stop as if a normal breakpoint was hit. You can step or continue from there. If the debugger is not already attached, this will cause a crash.