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
| Name | Type |
|---|
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.
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
| Name | Type |
|---|
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
| Name | Type |
|---|
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
| Name | Type |
|---|
Response
| Name | Type |
|---|---|
result |
ProcessLimbo_WatchProcessesWaitingOnException_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
|
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
|
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
|
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
|
GetFilters
Returns filters that are currently active within the limbo. If the limbo is inactive, it will return an empty vector.
Request
| Name | Type |
|---|
Response
| Name | Type |
|---|---|
filters |
vector<string>[32]
|
STRUCTS
ExceptionInfo
Defined in fuchsia.exception/handler.fidl
Basic exception information associated with a particular exception.
Maps to zx_exception_info_t.
| Name | Type | Description | Default |
|---|---|---|---|
process_koid |
zx/koid
|
No default | |
thread_koid |
zx/koid
|
No default | |
type |
ExceptionType
|
No default |
ProcessLimbo_WatchProcessesWaitingOnException_Response
generated
| Name | Type | Description | Default |
|---|---|---|---|
exception_list |
vector<ProcessExceptionMetadata>[32]
|
No default |
ProcessLimbo_RetrieveException_Response
generated
| Name | Type | Description | Default |
|---|---|---|---|
process_exception |
ProcessException
|
No default |
ProcessLimbo_ReleaseProcess_Response
generated
| Name | Type | Description | Default |
|---|
ProcessLimbo_AppendFilters_Response
generated
| Name | Type | Description | Default |
|---|
ProcessLimbo_RemoveFilters_Response
generated
| Name | Type | Description | Default |
|---|
ENUMS
ExceptionType
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
Defined in fuchsia.exception/handler.fidl
Generic wrapper over a thread exception. Mirrors closely the information given by an exception channel.
| Ordinal | Name | Type | Description |
|---|---|---|---|
| 1 | exception |
handle<exception>
|
|
| 2 | info |
ExceptionInfo
|
|
| 3 | process |
handle<process>
|
|
| 4 | thread |
handle<thread>
|
ProcessExceptionMetadata
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 | Name | 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_WatchProcessesWaitingOnException_Result
generated
| Name | Type | Description |
|---|---|---|
response |
ProcessLimbo_WatchProcessesWaitingOnException_Response
|
|
err |
zx/status
|
ProcessLimbo_RetrieveException_Result
generated
| Name | Type | Description |
|---|---|---|
response |
ProcessLimbo_RetrieveException_Response
|
|
err |
zx/status
|
ProcessLimbo_ReleaseProcess_Result
generated
| Name | Type | Description |
|---|---|---|
response |
ProcessLimbo_ReleaseProcess_Response
|
|
err |
zx/status
|
ProcessLimbo_AppendFilters_Result
generated
| Name | Type | Description |
|---|---|---|
response |
ProcessLimbo_AppendFilters_Response
|
|
err |
zx/status
|
ProcessLimbo_RemoveFilters_Result
generated
| Name | Type | Description |
|---|---|---|
response |
ProcessLimbo_RemoveFilters_Response
|
|
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 |ListProcessesWaitingOnException|. |
| MAX_FILTER_LENGTH |
32
|
uint64 |
|
| MAX_FILTERS_PER_CALL |
32
|
uint64 |