PROTOCOLS
AgentIterator
Defined in fuchsia.debugger/debug_agent.fidl
GetNext
Request
<EMPTY>
Response
| Name | Type |
|---|---|
agents |
vector<Agent>
|
AttachedProcessIterator
Defined in fuchsia.debugger/debug_agent.fidl
GetNext
Request
<EMPTY>
Response
| Name | Type |
|---|---|
process_names |
vector<string:32>
|
DebugAgent
Defined in fuchsia.debugger/debug_agent.fidl
AttachTo
Use the given filter to attach to any existing or subsequently created components. This method will return the number of matches that were present at the time of calling this method. All attached processes will be detached when this agent is destroyed.
|filter| will be inspected for validity, with corresponding errors returned. If the filter is invalid, no attaches will occur and the filter will not be installed.
|num_matches| will contain the number of matches that were found immediately upon filter installation if there was no error, that is, the number of processes immediately within (or recursively in this realm, if the option is specified) this component's corresponding job. Note that filters may be installed before any components are actually resolved and matched, so this number may be 0. This return value may be safely ignored.
Invalid filters will return an error, see Filter above for details on how to construct a filter.
Request
| Name | Type |
|---|---|
pattern |
string
|
type |
FilterType
|
options |
FilterOptions
|
Response
| Name | Type |
|---|---|
payload |
DebugAgent_AttachTo_Result
|
Connect
Hand the DebugAgent a socket that connects it to the debugger. This will return ZX_ERR_ALREADY_BOUND if a connection already exists. When the socket is closed, the DebugAgent will exit.
Request
| Name | Type |
|---|---|
socket |
handle<socket>
|
Response
| Name | Type |
|---|---|
payload |
DebugAgent_Connect_Result
|
GetAttachedProcesses
Iterator over all processes that this agent is attached to. Note this is not the same as the set of installed filters, but rather the set of filters that matched and were later successfully attached.
Request
| Name | Type |
|---|---|
iterator |
server_end:AttachedProcessIterator
|
GetMinidumps
Collect minidumps for all attached processes. |options| may contain a filter to reduce the number of minidumps that are yielded by the iterator.
Request
| Name | Type |
|---|---|
options |
MinidumpOptions
|
iterator |
server_end:MinidumpIterator
|
Response
| Name | Type |
|---|---|
payload |
DebugAgent_GetMinidumps_Result
|
GetProcessInfo
The given server_end of the iterator will iterate over all threads, of all attached processes. The options parameter may be passed to filter the already attached processes and to express interest in what should be yielded by the iterator. Including a filter is recommended if DebugAgent is attached to a large number of processes. Note that this filter will not cause any new processes to be attached and will not be saved after this method returns. It is purely to reduce the bounds of the iterator. The threads will be suspended for the duration of information capture, which could be interrupted by other system processes, see |ProcessInfoIterator| for an example.
Request
| Name | Type |
|---|---|
options |
GetProcessInfoOptions
|
iterator |
server_end:ProcessInfoIterator
|
Response
| Name | Type |
|---|---|
payload |
DebugAgent_GetProcessInfo_Result
|
OnFatalException
Report exceptions to clients. If no debug_ipc clients are connected, the exception will be immediately released, which may result in the process crashing.
Response
| Name | Type |
|---|---|
payload |
DebugAgentOnFatalExceptionRequest
|
Launcher
Defined in fuchsia.debugger/debug_agent.fidl
GetAgents
Iterator over all DebugAgent instances.
Request
| Name | Type |
|---|---|
iterator |
server_end:AgentIterator
|
Launch
Launch a new instance of DebugAgent listening on |agent|. The DebugAgent will exit upon closing the corresponding client_end of this channel. Clients must not close the channel until the debugging session is completed.
Request
| Name | Type |
|---|---|
agent |
server_end:DebugAgent
|
Response
| Name | Type |
|---|---|
payload |
Launcher_Launch_Result
|
MinidumpIterator
Defined in fuchsia.debugger/debug_agent.fidl
An iterator that collects and returns a minidump for a set of processes. An empty VMO will be returned when there are no more processes.
GetNext
Request
<EMPTY>
Response
| Name | Type |
|---|---|
payload |
MinidumpIterator_GetNext_Result
|
ProcessInfoIterator
Defined in fuchsia.debugger/debug_agent.fidl
Collects details from all threads of all attached processes. The exact details that are yielded from the iterator are controlled via ThreadDetailsInterest passed to |GetProcessInfo|. The iterator will yield an empty vector after all attached process' threads have been iterated. It is an error if there are no processes supplied to this iterator, which could be from too restrictive of a filter passed to |GetProcessInfo| or DebugAgent is not attached to anything.
This iteration is inherently racy, there is no way for DebugAgent to prevent other system entities from causing a process or thread to disappear while we are traversing them, so it's possible for this iterator to return errors when those threads or processes have been destroyed. These are not fatal errors, but can happen multiple times in one iteration.
For example, take this process structure, and assume DebugAgent is attached to everything:
pr: "process-1" 1234 t: "pr1234-t1" 1 t: "pr1234-t2" 2 pr: "process-2" 2345 t: "pr2345-t1" 3
If "process-1" is killed after "pr1234-t1" is yielded, but before "pr1234-t2" is yielded, a THREAD_GONE error will be returned on the next |GetNext| call. Calling |GetNext| again will yield "pr2345-t1".
GetNext
Collects information about the next attached thread. There is no guarantee of order of processes, but all threads from a given process will be iterated before another process's threads.
Request
<EMPTY>
Response
| Name | Type |
|---|---|
payload |
ProcessInfoIterator_GetNext_Result
|
STRUCTS
Agent resource
Defined in fuchsia.debugger/debug_agent.fidl
| Field | Type | Description | Default |
|---|---|---|---|
name |
fuchsia.component/child_name
|
No default | |
client_end |
client_end:DebugAgent
|
No default |
DebugAgent_AttachTo_Response
Defined in fuchsia.debugger/debug_agent.fidl
| Field | Type | Description | Default |
|---|---|---|---|
num_matches |
uint32
|
No default |
DebugAgent_Connect_Response
Defined in fuchsia.debugger/debug_agent.fidl
<EMPTY>
DebugAgent_GetMinidumps_Response
Defined in fuchsia.debugger/debug_agent.fidl
<EMPTY>
DebugAgent_GetProcessInfo_Response
Defined in fuchsia.debugger/debug_agent.fidl
<EMPTY>
Filter
Defined in fuchsia.debugger/debug_agent.fidl
A filter that will apply to processes and components running now and in the future. Any component or process that matches the given pattern and type will be attached, thereafter allowing clients to query information about the program(s). A valid filter will always contain a non-empty pattern string, and a FilterType to discern what to compare the pattern against. Additional options may be specified via FilterOptions.
| Field | Type | Description | Default |
|---|---|---|---|
pattern |
string
|
A string pattern to be matched against the given |type|. An empty pattern will result in a NO_PATTERN error. |
No default |
type |
FilterType
|
How to interpret |pattern|. See FilterType. |
No default |
options |
FilterOptions
|
Additional options for this filter. See FilterOptions. |
No default |
Launcher_Launch_Response
Defined in fuchsia.debugger/debug_agent.fidl
<EMPTY>
MinidumpIterator_GetNext_Response resource
Defined in fuchsia.debugger/debug_agent.fidl
| Field | Type | Description | Default |
|---|---|---|---|
minidump |
handle<vmo>
|
No default |
ProcessInfo
Defined in fuchsia.debugger/debug_agent.fidl
| Field | Type | Description | Default |
|---|---|---|---|
process |
zx/Koid
|
No default | |
moniker |
string:4096
|
No default | |
thread |
zx/Koid
|
The koid of the thread that produced the information in |details|. |
No default |
details |
ThreadDetails
|
Details about the thread with |koid|, as specified in the ThreadDetailsInterest given to |GetProcessInfo|. |
No default |
ProcessInfoIterator_GetNext_Response
Defined in fuchsia.debugger/debug_agent.fidl
| Field | Type | Description | Default |
|---|---|---|---|
info |
vector<ProcessInfo>
|
No default |
ENUMS
FilterError flexible
Type: uint32
Defined in fuchsia.debugger/debug_agent.fidl
| Name | Value | Description |
|---|---|---|
NO_PATTERN |
1 |
Indicates that there was no pattern given in the filter. |
UNKNOWN_TYPE |
2 |
FilterType was either unspecified or an otherwise unknown type to this agent. |
INVALID_OPTIONS |
3 |
The set of options given in FilterOptions was not valid. |
FilterType flexible
Type: uint8
Defined in fuchsia.debugger/debug_agent.fidl
| Name | Value | Description |
|---|---|---|
URL |
0 |
Performs an exact match against a component's URL, sans hash values. e.g. pattern fuchsia-pkg://fuchsia.com/package#meta/component.cm will match fuchsia-pkg://fuchsia.com/package?hash=1234abcd#meta/component.cm. |
MONIKER |
1 |
Performs an exact match against a component's full moniker. |
MONIKER_PREFIX |
2 |
Matches any component moniker that includes the pattern as a prefix. |
MONIKER_SUFFIX |
3 |
Matches any component moniker that includes the pattern as a suffix. |
MinidumpError flexible
Type: uint32
Defined in fuchsia.debugger/debug_agent.fidl
| Name | Value | Description |
|---|---|---|
NO_PROCESSES |
1 |
No processes were yielded to the iterator. This could mean that the supplied filter did not match any attached processes, or DebugAgent is not attached to any processes. |
INTERNAL_ERROR |
2 |
An error occurred while generating the minidump. These errors are opaque to DebugAgent. |
ProcessInfoError flexible
Type: uint32
Defined in fuchsia.debugger/debug_agent.fidl
| Name | Value | Description |
|---|---|---|
NO_PROCESSES |
1 |
There were no attached processes to iterate over. |
PROCESS_GONE |
2 |
A process has died such that the iterator is invalid. |
THREAD_GONE |
3 |
A process's threads have been mutated such that the iterator is invalid. |
TABLES
DebugAgentOnFatalExceptionRequest
Defined in fuchsia.debugger/debug_agent.fidl
| Ordinal | Field | Type | Description |
|---|---|---|---|
1 |
thread |
zx/Koid
|
The faulting thread's koid. |
2 |
backtrace |
string
|
A stack trace from the faulting thread in symbolizer markup format. |
FilterOptions
Defined in fuchsia.debugger/debug_agent.fidl
| Ordinal | Field | Type | Description |
|---|---|---|---|
1 |
recursive |
bool
|
Whether or not to also match all child components in the matching component's realm. When true, the matching component's full moniker will be assumed to be the root of the realm, and all children components will be launched within this realm. This is mutually exclusive with |job_only|. If both are specified, a FilterError will be returned. |
2 |
job_only |
bool
|
Whether or not to attach directly to the parent job of the process matching the filter. When true, the parent job's standard exception channel will be bound, rather than the exception channel of the process. See https://fuchsia.dev/fuchsia-src/concepts/kernel/exceptions#exception_channel_types for more details. Note that this is not the same as the "Debugger" exception channel, which only delivers process starting "exceptions" but not architectural exceptions. Note that this is mutually exclusive with |recursive|. If both are specified, a FilterError will be returned. |
GetProcessInfoOptions
Defined in fuchsia.debugger/debug_agent.fidl
| Ordinal | Field | Type | Description |
|---|---|---|---|
1 |
filter |
Filter
|
A filter that will reduce the number of processes that are iterated over. This will not install any new filters and will not cause new processes to be attached. Instead, this filter will be applied to already attached processes, which can be useful if there are many processes currently attached. |
2 |
interest |
ThreadDetailsInterest
|
Clients should specify the data they are interested in being yielded from the iterator here. Any unspecified fields will be assumed to be false. See ThreadDetailsInterest for descriptions of possible data. |
MinidumpOptions
Defined in fuchsia.debugger/debug_agent.fidl
| Ordinal | Field | Type | Description |
|---|---|---|---|
1 |
filter |
Filter
|
This will not install any new filters and will not cause new processes to be attached. Rather, this filter will be applied to already attached processes. |
ThreadDetails
Defined in fuchsia.debugger/debug_agent.fidl
Details about a particular thread. The fields will be included as per the ThreadDetailsInterest supplied when creating the ProcessInfoIterator via |GetProcessInfo|.
| Ordinal | Field | Type | Description |
|---|---|---|---|
1 |
backtrace |
string
|
A stack trace from the current thread in symbolizer markup format. |
ThreadDetailsInterest
Defined in fuchsia.debugger/debug_agent.fidl
| Ordinal | Field | Type | Description |
|---|---|---|---|
1 |
backtrace |
bool
|
Produce a backtrace in symbolizer markup format for each thread. If this is unspecified, no backtrace will be included in the ThreadDetails yielded by ProcessInfoIterator. |
UNIONS
DebugAgent_AttachTo_Result strict
Defined in fuchsia.debugger/debug_agent.fidl
| Ordinal | Variant | Type | Description |
|---|---|---|---|
1 |
response |
DebugAgent_AttachTo_Response
|
|
2 |
err |
FilterError
|
|
3 |
framework_err |
internal
|
DebugAgent_Connect_Result strict
Defined in fuchsia.debugger/debug_agent.fidl
| Ordinal | Variant | Type | Description |
|---|---|---|---|
1 |
response |
DebugAgent_Connect_Response
|
|
2 |
err |
zx/Status
|
|
3 |
framework_err |
internal
|
DebugAgent_GetMinidumps_Result strict
Defined in fuchsia.debugger/debug_agent.fidl
| Ordinal | Variant | Type | Description |
|---|---|---|---|
1 |
response |
DebugAgent_GetMinidumps_Response
|
|
2 |
err |
FilterError
|
|
3 |
framework_err |
internal
|
DebugAgent_GetProcessInfo_Result strict
Defined in fuchsia.debugger/debug_agent.fidl
| Ordinal | Variant | Type | Description |
|---|---|---|---|
1 |
response |
DebugAgent_GetProcessInfo_Response
|
|
2 |
err |
FilterError
|
|
3 |
framework_err |
internal
|
Launcher_Launch_Result strict
Defined in fuchsia.debugger/debug_agent.fidl
| Ordinal | Variant | Type | Description |
|---|---|---|---|
1 |
response |
Launcher_Launch_Response
|
|
2 |
err |
zx/Status
|
|
3 |
framework_err |
internal
|
MinidumpIterator_GetNext_Result strict resource
Defined in fuchsia.debugger/debug_agent.fidl
| Ordinal | Variant | Type | Description |
|---|---|---|---|
1 |
response |
MinidumpIterator_GetNext_Response
|
|
2 |
err |
MinidumpError
|
ProcessInfoIterator_GetNext_Result strict
Defined in fuchsia.debugger/debug_agent.fidl
| Ordinal | Variant | Type | Description |
|---|---|---|---|
1 |
response |
ProcessInfoIterator_GetNext_Response
|
|
2 |
err |
ProcessInfoError
|