Get started with zxdb

Zxdb is an asynchronous debugger that allows the user to interact with the debugger while processes or threads are running or stopped.

Zxdb uses a noun, verb, and command model for typed commands. This document highlights the main functionality of the zxdb debugger.

Debugger model

When working with zxdb, you can perform most actions by combining a noun and a verb.

Noun

The possible nouns (and their abbreviations) are:

  • breakpoint (bp)

    Select or list breakpoints.

  • filter

    Select or list process filters.

  • frame (f)

    Select or list stack frames.

  • global (gl)

    Global override for commands.

  • process (pr)

    Select or list process contexts.

  • sym-server

    Select or list symbol servers.

  • thread (t)

    Select or list threads.

Listing nouns

If you type a noun by itself, it lists the available objects of that type. For example:

breakpoint

List all of the breakpoints in the session:

breakpoint
# scope  stop enabled type     Condition                       #addrs hit-count location
1 global all  true    software command_line.has_argv0 == false      1         0 ../../src/cobalt/bin/app/cobalt_main.cc:352

frame

List stack frames in the current thread:

frame
▶ 0 fxl::CommandLineFromIterators<const char *const *>() • command_line.h:203
  1 fxl::CommandLineFromArgcArgv() • command_line.h:224
  2 main() • main.cc:174

process

List attached processes:

process
  # State       Koid Name
▶ 1 Not running 3471 debug_agent_unit_tests.cm

thread

List threads in the current process:

thread
  # State   Koid Name
▶ 1 Blocked 1348 initial-thread
  2 Blocked 1356 some-other-thread

Selecting active nouns

You can select a noun and its respective index to make it the active noun for subsequent commands. When you set a new active noun, it returns information about the new active noun. For example:

thread

Select thread 3 to be the active noun for future commands:

thread 3
Thread 3 Blocked koid=9940 worker-thread

breakpoint

Select breakpoint 2 to be the active noun:

breakpoint 2
Breakpoint 2 (Software) on Global, Enabled, stop=All, @ MyFunction

Verbs

In zxdb, verbs are used in conjunction with nouns, which specify a zxdb object, to perform debugging actions. For a full list of zxdb verbs, see verbs.h.

By default, a verb such as run, next, print, etc... applies to the current active nouns (for more information on active nouns, see Selecting active nouns).

Data display verbs

  • Memory display verbs are covered in memory.
  • Register display verbs are covered in assembly.

Help

The zxdb debugger has a built-in help system:

help

You can also get help on a specific command. For example, to see the help of the step command:

help step

Attributes and settings

zxdb debugger objects have settings associated with them. You can specify some of these settings to personalize zxdb.

Retrieve

You can use the get verb to list the settings for a given object.

For example, you can get the attributes of the active process:

process get
  debug-stepping false
  display        <empty>
  show-stdout    true
  source-map     • /b/s/w/ir/x/w/fuchsia-third_party-rust=/usr/local/home/user/fuchsia/out/default/host_x64/../../../prebuilt/third_party/rust/linux-x64/lib/rustlib/src/rust
  vector-format  double

You can also use the get verb with a specific attribute to list the attribute and help associated with it.

For example, to get the help of the debug-stepping attribute:

process get debug-stepping
debug-stepping (bool)

  Enable very verbose debug logging for thread stepping.

  This is used by developers working on the debugger's internal thread
  controllers.

debug-stepping = false

Set

You can use the set verb to set the settings or attributes of a given object.

For example, you can set the show-stdout attribute of the active process to true:

process set show-stdout true
Set process 1 show-stdout = true

Some settings are hierarchical. A thread inherits settings from its process, which in turn inherits settings from the global scope. If you use the get verb without context or parameters, it lists the global settings and the specific settings for the current process and thread.

You can set a global setting to apply to all threads and processes without specific overrides, or override a specific context.

For example, you can set the show-stdout global setting to false:

set show-stdout false       # Applies to all processes with no override.
Set global show-stdout = false

Some settings are stored as lists. For example, you can use any of these examples to set your symbol-paths:

  • Use = to specify a new value:

    set symbol-paths = /tmp/symbols /fuchsia-settings/symbols "/fuchsia settings/symbols"
Set global symbol-paths =
  • /tmp/symbols
  • /fuchsia-settings/symbols
  • "/fuchsia settings/symbols"

  • Use += to append to the existing values:

    set symbol-paths += /tmp/symbols2
Set global symbol-paths =
  • /tmp/symbols
  • /fuchsia-settings/symbols
  • "/fuchsia settings/symbols"
  • /tmp/symbols2

Languages

zxdb evaluates expressions based on the programming language from the current stack frame. If the current frame's language is different, zxdb defaults to C++.

By default zxdb uses a language of auto. You can overwrite the default language with the set verb.

For example, to set the default language to rust:

set language rust
Set global language = rust