PROTOCOLS
Handler
Defined in fuchsia.exception/handler.fidl
Protocol meant for clients interested in handling exceptions for a particular service.
OnException
This exception mirrors closely the information provided by exception channels. The design is to have clients of this API behave as closely as possible to native exception handlers that are listening to an exception channel.
exception is an exception handle, which controls the exception's
lifetime. See exception zircon docs for more information.
info represents basic exception information as provided by the
exception channel.
Request
| Name | Type |
|---|---|
exception |
handle<exception>
|
info |
ExceptionInfo
|
Response
<EMPTY>
ProcessLimbo
Defined in fuchsia.exception/process_limbo.fidl
Protocol meant for clients interested in obtaining processes that are suspended waiting for an exception handler (in limbo). This is the core feature that enables Just In Time (JIT) debugging.
An example usage of this API would be having a debugger listen on limbo for new processes. Then another component (eg. a CLI tool) could activate the limbo, meaning that the system is now ready to capture crashing processes. As the debugger got a notification that the limbo is now active, it can correctly handle newly excepted processes and do its normal workflow.
AppendFilters
Adds filters to the limbo. Filters determine what processes the limbo will store when receiving an exception. Repeated filters will be ignored. Filters work by "filtering out" processes. It means that if a filter matches, that process won't get included.
Filters work by substring matching. This means that a process name has to have the filter as a substring in order to match it. Example:
Filter = "dev". Process = "process" won't match. Process = "devcoordinator" will match.
Adding filters is transactional: either all of them go in, or none at
all. The maximum amount of filters is determined by
MAX_FILTERS_PER_CALL. If the maximum is exceeded, ZX_ERR_NO_RESOURCES
is returned.
Changing filters have no effect on processes that are currently waiting on an exception, but rather which future processes that will remain in the limbo.
Returns ZX_ERR_UNAVAILABLE if limbo is not active.
Request
| Name | Type |
|---|---|
filters |
vector<string>[32]
|
Response
| Name | Type |
|---|---|
result |
ProcessLimbo_AppendFilters_Result
|
GetFilters
Returns filters that are currently active within the limbo. If the limbo is inactive, it will return an empty vector.
Request
<EMPTY>
Response
| Name | Type |
|---|---|
filters |
vector<string>[32]
|
ReleaseProcess
Removes the process from limbo, releasing the exception. This will make it "bubble up" beyond the scope of of this limbo, making it unretrievable in the future from here.
Request
| Name | Type |
|---|---|
process_koid |
zx/koid
|
Response
| Name | Type |
|---|---|
result |
ProcessLimbo_ReleaseProcess_Result
|
RemoveFilters
Removes filters to the limbo. Any filters that are not currently present on the limbo will be ignored.
Returns ZX_ERR_UNAVAILABLE if limbo is not active.
Request
| Name | Type |
|---|---|
filters |
vector<string>[32]
|
Response
| Name | Type |
|---|---|
result |
ProcessLimbo_RemoveFilters_Result
|
RetrieveException
Removes the process from limbo and retrieves the exception handle and associated metadata from an exception.
Use ListProcessesWaitingOnException to choose a process_koid from the
list of available exceptions.
Returns ZX_ERR_NOT_FOUND if the process is not waiting on an exception. Returns ZX_ERR_UNAVAILABLE if limbo is not active.
Request
| Name | Type |
|---|---|
process_koid |
zx/koid
|
Response
| Name | Type |
|---|---|
result |
ProcessLimbo_RetrieveException_Result
|
SetActive
Set the active state of the limbo. Will trigger the WatchActive event
if there was a change, meaning that any listening components will receive
a notification. This includes the caller of SetActive.
When a limbo is inactive, there will not be any processes waiting on it, meaning that any waiting processes will be freed upon deactivating the limbo.
Request
| Name | Type |
|---|---|
active |
bool
|
Response
<EMPTY>
WatchActive
Watchs for changes determining whether the limbo is currently active, using a Hanging Get pattern. An active limbo could be empty (not have any processes waiting on an exception). When a limbo is inactive, there will not be any processes waiting on it.
Request
<EMPTY>
Response
| Name | Type |
|---|---|
is_active |
bool
|
WatchProcessesWaitingOnException
Watch for processes that are waiting on exceptions, using a Hanging Get Pattern.
Returns information on all the processes currently waiting on an exception.
The information provided is intended to correctly identify an exception
and determine whether the caller wants to actually handle it.
To retrieve an exception, use the GetException call.
Returns ZX_ERR_UNAVAILABLE if limbo is not active. Returns ZX_ERR_CANCELED if there was an outstanding call and the limbo becomes inactive.
NOTE: The process and thread handle will only have the ZX_RIGHT_READ
right, so no modification will be able to be done on them.
Request
<EMPTY>
Response
| Name | Type |
|---|---|
result |
ProcessLimbo_WatchProcessesWaitingOnException_Result
|
STRUCTS
ExceptionInfo
Defined in fuchsia.exception/handler.fidl
Basic exception information associated with a particular exception.
Maps to zx_exception_info_t.
| Field | Type | Description | Default |
|---|---|---|---|
process_koid |
zx/koid
|
No default | |
thread_koid |
zx/koid
|
No default | |
type |
ExceptionType
|
No default |
ProcessLimbo_AppendFilters_Response
Defined in fuchsia.exception/process_limbo.fidl
<EMPTY>
ProcessLimbo_ReleaseProcess_Response
Defined in fuchsia.exception/process_limbo.fidl
<EMPTY>
ProcessLimbo_RemoveFilters_Response
Defined in fuchsia.exception/process_limbo.fidl
<EMPTY>
ProcessLimbo_RetrieveException_Response resource
Defined in fuchsia.exception/process_limbo.fidl
| Field | Type | Description | Default |
|---|---|---|---|
process_exception |
ProcessException
|
No default |
ProcessLimbo_WatchProcessesWaitingOnException_Response resource
Defined in fuchsia.exception/process_limbo.fidl
| Field | Type | Description | Default |
|---|---|---|---|
exception_list |
vector<ProcessExceptionMetadata>[32]
|
No default |
ENUMS
ExceptionType strict
Type: uint32
Defined in fuchsia.exception/handler.fidl
What type of exception was triggered.
Maps to the types defined in zx_excp_type_t.
If zircon/syscalls/exception.h changes, this needs to be updates as well to
reflect that.
| Name | Value | Description |
|---|---|---|
GENERAL |
8 |
|
FATAL_PAGE_FAULT |
264 |
|
UNDEFINED_INSTRUCTION |
520 |
|
SW_BREAKPOINT |
776 |
|
HW_BREAKPOINT |
1032 |
|
UNALIGNED_ACCESS |
1288 |
|
THREAD_STARTING |
32776 |
|
THREAD_EXITING |
33032 |
|
POLICY_ERROR |
33288 |
|
PROCESS_STARTING |
33544 |
TABLES
ProcessException resource
Defined in fuchsia.exception/handler.fidl
Generic wrapper over a thread exception. Mirrors closely the information given by an exception channel. Both |process| and |thread| will be valid if present.
| Ordinal | Field | Type | Description |
|---|---|---|---|
| 1 | exception |
handle<exception>
|
|
| 2 | info |
ExceptionInfo
|
|
| 3 | process |
handle<process>
|
Both |
| 4 | thread |
handle<thread>
|
The thread that generated the exception. The process may have other threads that are not reflected here. |
ProcessExceptionMetadata resource
Defined in fuchsia.exception/process_limbo.fidl
Intended to be read only metadada associated with an exception waiting in limbo. The handles provided will only have read-only access to the resource, so no modification can be done to them.
NOTE: Both process and thread will be valid if present.
| Ordinal | Field | Type | Description |
|---|---|---|---|
| 1 | info |
ExceptionInfo
|
|
| 2 | process |
handle<process>
|
Only has ZX_RIGHT_READ and ZX_RIGHT_GET_PROPERTY rights. |
| 3 | thread |
handle<thread>
|
The thread that generated the exception. The process may have other threads that are not reflected here. Only has ZX_RIGHT_READ and ZX_RIGHT_GET_PROPERTY rights. |
UNIONS
ProcessLimbo_AppendFilters_Result strict
Defined in fuchsia.exception/process_limbo.fidl
| Ordinal | |||
|---|---|---|---|
| Variant | Type | Description | |
| 1 | response |
ProcessLimbo_AppendFilters_Response
|
|
| 2 | err |
zx/status
|
ProcessLimbo_ReleaseProcess_Result strict
Defined in fuchsia.exception/process_limbo.fidl
| Ordinal | |||
|---|---|---|---|
| Variant | Type | Description | |
| 1 | response |
ProcessLimbo_ReleaseProcess_Response
|
|
| 2 | err |
zx/status
|
ProcessLimbo_RemoveFilters_Result strict
Defined in fuchsia.exception/process_limbo.fidl
| Ordinal | |||
|---|---|---|---|
| Variant | Type | Description | |
| 1 | response |
ProcessLimbo_RemoveFilters_Response
|
|
| 2 | err |
zx/status
|
ProcessLimbo_RetrieveException_Result strict resource
Defined in fuchsia.exception/process_limbo.fidl
| Ordinal | |||
|---|---|---|---|
| Variant | Type | Description | |
| 1 | response |
ProcessLimbo_RetrieveException_Response
|
|
| 2 | err |
zx/status
|
ProcessLimbo_WatchProcessesWaitingOnException_Result strict resource
Defined in fuchsia.exception/process_limbo.fidl
| Ordinal | |||
|---|---|---|---|
| Variant | Type | Description | |
| 1 | response |
ProcessLimbo_WatchProcessesWaitingOnException_Response
|
|
| 2 | err |
zx/status
|
CONSTANTS
| Name | Value | Type | Description |
|---|---|---|---|
| MAX_EXCEPTIONS_PER_CALL |
32
|
uint64 |
The maximum amount of exceptions that will be listed at any given time by a
call to |
| MAX_FILTERS_PER_CALL |
32
|
uint64 |
|
| MAX_FILTER_LENGTH |
32
|
uint64 |