Advanced topics

Once you are familiarized with the basic functionality of the Fuchsia debugger, zxdb, you may want to:

Debug a crash dump

Zxdb supports loading a minidump generated by a crash report. For a more detailed example of debugging a crash dump, see Tutorial: Debug minidumps using zxdb

You can use the ffx debug core command to load a crash report, for example:

ffx debug core crash_dump_file

Download symbols

Zxdb automatically searches servers registered in the symbol-index for symbols that are not found in any locally configured symbol directories. You can see the complete list of symbol servers registered in your symbol-index with the following command:

ffx debug symbol-index list -a

This recursively traverses and resolves all symbol-index files that are included in the global symbol-index. For more information see About symbol settings.

The servers that appear are used to download symbol files and load them to the debugger asynchronously. For particularly large debug info files, you may see output like this from sym-stat in zxdb:

sym-stat
...
    Base: 0xc37e9000
    Build ID: ba17ef8c43bccf5fb6bf84f9a8d83d9cf3be8976 (Downloading...)
    Symbols loaded: No
...

This indicates that a download is in progress. Once the file is downloaded, zxdb indexes the symbols from the newly downloaded file and debugging can continue.

Attach to an existing process

In most cases, you should not attach to a specific process unless you are automating a zxdb workflow. If you are using zxdb without automation, you should attach zxdb to a component identifier, see Run zxdb.

You can attach to most running processes given the process’ koid (the kernel object ID). zxdb provides a ps command to see the processes that are running on a Fuchsia device or emulator.

Before you try to run ps, make sure that you attach zxdb to a component, or at a minimum connect to the Fuchsia device:

For example, to connect to the core/starnix_runner component:

ffx component debug core/starnix_runner

Once the debugger is connected, you can run ps to see a listing of all of the active processes on the Fuchsia device or emulator:

ps
 j: 1033 root
   p: 1102 bin/component_manager
   j: 1662
     j: 1811 bootstrap/console fuchsia-boot:///console#meta/console.cm
       p: 1845 console.cm
...
     j: 66524 core/starnix_runner fuchsia-pkg://fuchsia.com/starnix#meta/starnix_runner.cm
▶      p: 66562 starnix_runner.cm
     j: 66763
       j: 66764 core/starnix_runner/kernels:RW3JlbU starnix_kernel#meta/starnix_kernel.cm
         p: 66797 starnix_kernel.cm
         p: 67333 init
     j: 88021
       p: 88084 debug_agent.cm
   j: 4227 zircon-shell
     p: 4608 sh:console

From the output above:

  • j indicates a job which is a container for processes.
  • p indicates a process.

The number that follows the job or process is the object's KOID. You can then:

Attach to a specific process

From the zxdb console, you can attach to a specific process. For example, to attach to the starnix_kernel.cm process which is listed with a KOID of 66797:

attach 66797
Attached Process 2 state=Running koid=66797 name=starnix_kernel.cm component=starnix_kernel.cm
Loading 15 modules for starnix_kernel.cm ....
[zxdb]

Attach to all processes in a specific job

From the zxdb console, you can attach to all the processes that are part of a job. For example, to attach to the core/starnix_kernels:RW3JlbU job which is listed with a KOID of 66764:

attach -j 66764
Waiting for process matching "job 66764".
Type "filter" to see the current filters.
Attached Process 2 state=Running koid=66797 name=starnix_kernel.cm component=starnix_kernel.cm
Attached Process 3 state=Running koid=67333 name=init component=starnix_kernel.cm
Loading 15 modules for starnix_kernel.cm .....Done.
Loading 17 modules for init Done.

Attach to a specific process in a job

From the zxdb console, you can attach to a specific process that is part of a job. For example, to attach to the starnix_kernel.cm process which is part of the job with a KOID of 66764:

attach -j 66764 starnix_kernel.cm
Waiting for process matching "starnix_kernel.cm".
Type "filter" to see the current filters.
Attached Process 2 state=Running koid=66797 name=starnix_kernel.cm component=starnix_kernel.cm
Attached Process 3 state=Running koid=67333 name=init component=starnix_kernel.cm
Loading 15 modules for starnix_kernel.cm .....Done.
Loading 17 modules for init Done.
[zxdb]