This page lists common troubleshooting tips for zxdb
:
- Ensure that zxdb and
debug_agent
are built - Ensure that ffx can communicate with the device
- Ensure that the Fuchsia package server is running
- Diagnose problems with symbols
Ensure that ffx can communicate with the device
Make sure that ffx can discover the device, either a emulator or a hardware device, and RCS is started on the device.
$ ffx target list
NAME SERIAL TYPE STATE ADDRS/IP RCS
demo-emu <unknown> core.x64 Product [10.0.2.15, Y
fec0::90e:486e:b6b5:9780,
fec0::487b:fabd:20fa:43ee,
127.0.0.1]
Ensure that the Fuchsia package server is running
For most in-tree build configurations, the debug_agent
which is used by zxdb
is in the universe dependency set, but not in the base dependency set so won't
be on the Fuchsia target device before boot. This may lead you to see errors
similar to the following:
BUG: An internal command error occurred.
Error: Attempted to find protocol marker fuchsia.debugger.Launcher at '/core/toolbox' or '/core/debugger', but it wasn't available at either of those monikers.
Make sure the target is connected and otherwise functioning, and that it is configured to provide capabilities over the network to host tools.
1. This service dependency exists but connecting to it failed with error CapabilityConnectFailed. Moniker: /core/debugger. Capability name: fuchsia.debugger.Launcher
More information may be available in ffx host logs in directory:
If you see this type of error, make sure that fx serve
is running in a
separate terminal. For example:
fx serve
Diagnose problems with symbols
Debug symbols are registered
By default, zxdb obtains the locations of the debug symbols from the symbol index. The registrations of debug symbols from in-tree and most out-of-tree environments are automated.
In case symbol registration fails, zxdb has these command-line options to provide additional symbol lookup locations:
These options have settings that can be manipulated using set
or get
.
For example, to add a .build-id
directory, you can do either of the following:
set build-id-dirs
[zxdb] set build-id-dirs += some/other_location/.build-id
--build-id-dir
flag
ffx debug connect -- --build-id-dir some/other_location/.build-id
build-id-dir
Some builds produce a .build-id
directory. Symbol files in this directory are
indexed according to their build IDs. For example, the Fuchsia build makes a
.build-id
directory inside it's build directory, e.g., out/x64/.build-id
.
These directories can be added to zxdb through the build-id-dirs
setting or
the --build-id-dir
.
ids-txt
Instead of a .build-id
directory, some builds produce a file called ids.txt
that lists build IDs and local paths to the corresponding binaries. These files
can be added to zxdb through the ids-txts
setting or the --ids-txt
command-line flag.
symbol-path
The --symbol-path
flag can be used to add arbitrary files or directories to
the symbol index. If the path is pointing to a file, zxdb treats it as an ELF
file and adds it to the symbol index. If it's a directory, all binaries under
the given path are indexed.
Check symbol status
The sym-stat
command returns the status for symbols. If there is no running
process, it returns information on the different symbol locations that you have
specified. If your symbols aren't found, make sure this matches your
expectations.
To see the status of symbols, run sym-stat
:
[zxdb] sym-stat
Symbol index status
Indexed Source path
(folder) /home/alice/.build-id
(folder) /home/alice/build/out/x64
0 my_dir/my_file
If you see a 0
in the Indexed
column of Symbol index status
this indicates
that zxdb could not find the source of the symbols. If you cannot debug the
issue, file a zxdb bug.
Variable values are unavailable
Zxdb can return an issue around variable values, which in most cases is related to the optimization level of the program. For example:
Optimized out: This indicates that the program symbols declare a variable with the given name, but that it has no value or location. This indicates that the compiler has entirely optimized out the variable and the debugger can't display it. If you need to see the variable, use a less-optimized build setting.
Unavailable: This indicates that the variable is invalid at the current address, but that its value is known at other addresses. In optimized code, the compiler often re-uses registers, which can overwrite previous values, which then become unavailable.
For example, you can see the valid ranges for the my_variable
variable with
the sym-info
command:
[zxdb] sym-info my_variable
Variable: my_variable
Type: int
DWARF tag: 0x05
DWARF location (address range + DWARF expression bytes):
[0x3e0d0a3e05b, 0x3e0d0a3e0b2): 0x70 0x88 0x78
[0x3e0d0a3e0b2, 0x3e0d0a3eb11): 0x76 0x48 0x10 0xf8 0x07 0x1c 0x06
DWARF location
gives you a list of address ranges where the value of the
variable is known. The address range is inclusive at the beginning of the range
and non-inclusive at the end of the range.
DWARF expression bytes
indicate the internal instructions for finding the
variable.
You can also use the di
command to see the current address.
Source code location is correctly set up
The Fuchsia build generates symbols relative to the build directory. The
relative paths look like ../../src/my_component/file.cc
. The build directory
is usually provided by the symbol index, so that source files can be located.
If your source files are not being found, you need to manually set the source map setting.
For example, if the debugger can't find ./../../src/my_component/file.cc
, an
the file is located at /path/to/fuchsia/src/my_component/file.cc
, you need
to set the source_map
:
[zxdb] set source-map += ./../..=/path/to/fuchsia
Once you have set source-map
, zxdb looks for
/path/to/fuchsia/src/my_component/file.cc
.
Mismatched source lines
Sometimes the source file listings may not match the code. The most common reason is that the build is out-of-date and no longer matches the source. The debugger checks that the symbol file modification time is newer than the source file, but it only prints the warning the first time the file is displayed.
Some users have multiple checkouts. Use the -f
option with the list
command
to check the file name of the file that zxdb found. For example:
[zxdb] list -f
/home/alice/fuchsia/out/x64/../../src/foo/bar.cc
... <source code> ...
If zxdb is finding a file in the incorrect checkout, override the build-dirs
option as described in Debug symbols are registered.
You can set the show-file-paths
option to increase the information for file
paths. When this setting is set to true
:
- It shows the full resolved path in source listings as in
list -f
. - It shows the full path instead of just the file name.
To set show-file-paths
to true
:
[zxdb] set show-file-paths true
When setting breakpoints
You may notice a mismatch source line when setting a breakpoint on a specific line where the displayed breakpoint location doesn't match the line number you typed. In most cases, this is because this symbols did not identify any code on the specified line so zxdb used the next line. This can happen even in unoptimized builds, and is most common for variable declarations.
[zxdb] b file.cc:138
Breakpoint 1 (Software) @ file.cc:138
138 int my_value = 0; <- Breakpoint was requested here.
◉ 139 DoSomething(&my_value); <- But ended up here.
140 if (my_value > 0) {