docs/development/debugger/advanced.md

# Advanced topics

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

* [Debug a crash dump](#debug-crash-dump)
* [Download symbols](#download-symbols)
* [Attach to an existing process](#attach-process)

## Debug a crash dump {#debug-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][zxdb-tutorial-minidumps]

You can use the [`ffx debug core`](https://fuchsia.dev/reference/tools/sdk/ffx#core)
command to load a crash report, for example:

```none
ffx debug core {{ '<var>crash_dump_file</var>' }}
```

## Download symbols {#download-symbols}

Zxdb automatically searches servers registered in the
[symbol-index][ffx-debug-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:

```posix-terminal
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][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:

```none{: .devsite-terminal data-terminal-prefix="[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 {#attach-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][zxdb-readme-run].

You can attach to most running processes given the process’ koid (the
[kernel object ID][koid-concept]). 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:

Note: This command fails if you do not have an active Fuchsia device or
emulator. For additional ways to attach the debugger, see
[zxdb: The Fuchsia debugger][zxdb-readme].

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

```posix-terminal
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:

```none {: .devsite-terminal data-terminal-prefix="[zxdb]" }
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](/docs/concepts/kernel/concepts.md) 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](#attach-process)
* [Attach to processes in a specific job](#attach-job)

### Attach to a specific process {#attach-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`:

```none {: .devsite-terminal data-terminal-prefix="[zxdb]" }
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 {#attach-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`:

```none {: .devsite-terminal data-terminal-prefix="[zxdb]" }
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 {#attach-job-process}

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`:

```none {: .devsite-terminal data-terminal-prefix="[zxdb]" }
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]
```

<!-- Reference links -->

[koid-concept]: /docs/concepts/kernel/concepts.md#kernel_object_ids
[zxdb-readme]: /docs/development/debugger/README.md
[zxdb-readme-run]: /docs/development/debugger/README.md#run_zxdb
[zxdb-tutorial-minidumps]: /docs/development/debugger/tutorial-minidumps.md
[ffx-debug-symbol-index]: /docs/development/tools/ffx/workflows/register-debug-symbols.md
[about-symbol-settings]: symbols.md#about_symbol_settings