Understand how symbols are loaded

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:

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

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

set symbol-paths += /home/alice/project/a.out

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:

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:

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.