Zxdb should automatically set symbol settings by your environment.
This section explains how zxdb loads symbols. If you are looking for ways to troubleshoot common issues with zxdb's symbolizer, see Diagnose problems with symbols.
build IDs
Zxdb locates the symbols for a binary on a target device by using the binary's build ID.
For example, to see the build ID for a binary on Linux, dump the notes
for
the ELF binary:
$ readelf -n my_binary
... (some other notes omitted) ...
Displaying notes found in: .note.gnu.build-id
Owner Data size Description
GNU 0x00000014 NT_GNU_BUILD_ID (unique build ID bitstring)
Build ID: 18cec080fc47cdc07ec554f946f2e73d38541869
The sym-stat
zxdb command shows the build IDs for each binary and the library
that is currently loaded in the attached process. It also displays the
corresponding symbol file if found.
Symbol servers
Zxdb can load symbols for prebuilt libraries from Google servers or upstream
debuginfod
servers. This is the mechanism how symbols are delivered for SDK
users for anything that isn't built locally. For more information, see
Downloading symbols.
When working with large binaries, symbols can be several gigabytes so the
download process may take some time (usually in the range of several minutes).
The sym-stat
command displays Downloading...
while downloading symbols.
When zxdb downloads symbols, it stores them in the symbol cache. The
symbol-cache
setting contains the name of this directory.
For example:
[zxdb] get symbol-cache
symbol-cache = /home/me/.fuchsia/debug/symbol-cache
When zxdb downloads symbols from prebuilt binaries fetched from upstream packages, the debuginfo may not have a corresponding ELF binary (depending on the server and the package). When this happens, zxdb may display errors that look like:
...
binary for build_id 26820458adaf5d95718fb502d170fe374ae3ee70 not found on 5 servers
binary for build_id 53eaa845e9ca621f159b0622daae7387cdea1e97 not found on 5 servers
binary for build_id f3fd699712aae08bbaae3191eedba514c766f9d2 not found on 5 servers
binary for build_id 4286bd11475e673b194ee969f5f9e9759695e644 not found on 5 servers
binary for build_id 2d28b51427b49abcd41dcf611f8f3aa6a2811734 not found on 5 servers
binary for build_id 0401bd8da6edab3e45399d62571357ab12545133 not found on 5 servers
...
This indicates that the ELF binary file was not found on the debuginfod servers. When this happens, the ELF symbols are not available for this particular binary, which is typically fine for most debugging scenarios. The most commonly used ELF specific symbols that may be unavailable are PLT symbols.
You can use the sym-stat
command to verify that DWARF information has been
loaded:
libc.so.6
Base: 0x1c85fdc2000
Build ID: 0401bd8da6edab3e45399d62571357ab12545133
Symbols loaded: Yes
Symbol file: /home/alice/.fuchsia/debug/symbol-cache/04/01bd8da6edab3e45399d62571357ab12545133.debug
Source files indexed: 1745
Symbols indexed: 10130
.build-id directory symbol databases
Many build environments, including the main fuchsia.git
repository, add
symbolized binaries in a standard directory structure called .build-id
. This
directory contains subdirectories that are named according to the first two
characters of the binary's build ID. These subdirectories contain the symbol
files named according to the remaining characters of the build ID.
You can set one or more build ID directories on the command line or
interactively by using the build-id-dirs
setting which is a list of directory
paths.
For example, to add /home/alice/project/out/x64/.build-id
as a build-id-dirs
:
zxdb instance
[zxdb] set build-id-dirs += /home/alice/project/out/x64/.build-id
ffx
ffx debug symbol-index add --build-dir /home/alice/project/out/x64/.build-id
These directories are then annotated with (folder)
in the output of the
sym-stat
instead of the number of binaries that are contained in the directory.
These binaries are not displayed in the sym-stat --dump-index
output because
zxdb searches these directories on demand when searching for symbols rather than
enumerating them in advance.
Individual files and directories
If you have a single binary file without one of the other symbol database
formats, you can configure zxdb for that specific file. You can use configure
the symbol-paths
for a particular file by adding it to the list of paths.
For example, to add /home/alice/project/a.out
to the symbol-paths
setting:
File
[zxdb] set symbol-paths += /home/alice/project/a.out
Directory
[zxdb] set symbol-paths += /home/me/project/build/
You can see the status of the locations you configured with the sym-stat
command. For example:
[zxdb] sym-stat
Symbol index status
This command just refreshed the index.
Use "sym-stat --dump-index" to see the individual mappings.
Indexed Source path
1 /home/alice/a.out
2 /home/alice/project/build/
ids.txt symbol index
Some older internal Google projects generate a file called ids.txt
. This file
provides a mapping from a binary's build ID to the symbol path on the local
system. If your build produces such a file and it is not automatically loaded,
you can specify it for Zxdb with the ids-txts
setting (a list of file names):
For example, to add /home/alice/project/build/ids.txt
to the ids-txts
setting:
[zxdb] set ids-txts += /home/alice/project/build/ids.txt
The symbol files from ids.txt
files is also displayed when you run the
sym-stat
or the sym-stat --dump-index
commands.
Symbol settings
The settings described in Understand how Zxdb loads symbols section get automatically applied by your environment. This section describes how these settings are set.
The symbol-index-files
setting contains one or more JSON-format files that
are set by the development environment:
[zxdb] get symbol-index-files
symbol-index-files =
• /home/alice/.fuchsia/debug/symbol-index.json
This file can contain some global settings and reference other symbol-index
files. Typically each build environment that you are actively using has a
similar file that is referenced from this global file.
If you are switching between build environments and notice that symbols aren't
loading, make sure that your environment is registered with the
ffx debug symbol-index list
command.