fuchsia.exception

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

NameType
exception handle<exception>
info ExceptionInfo

Response

NameType

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

NameType
active bool

Response

NameType

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

NameType

Response

NameType
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

NameType

Response

NameType
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

NameType
process_koid zx/koid

Response

NameType
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

NameType
process_koid zx/koid

Response

NameType
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

NameType
filters vector<string>[32]

Response

NameType
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

NameType
filters vector<string>[32]

Response

NameType
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

NameType

Response

NameType
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.

NameTypeDescriptionDefault
process_koid zx/koid No default
thread_koid zx/koid No default
type ExceptionType No default

ProcessLimbo_WatchProcessesWaitingOnException_Response

generated

NameTypeDescriptionDefault
exception_list vector<ProcessExceptionMetadata>[32] No default

ProcessLimbo_RetrieveException_Response

generated

NameTypeDescriptionDefault
process_exception ProcessException No default

ProcessLimbo_ReleaseProcess_Response

generated

NameTypeDescriptionDefault

ProcessLimbo_AppendFilters_Response

generated

NameTypeDescriptionDefault

ProcessLimbo_RemoveFilters_Response

generated

NameTypeDescriptionDefault

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.

NameValueDescription
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.

OrdinalNameTypeDescription
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.

OrdinalNameTypeDescription
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

NameTypeDescription
response ProcessLimbo_WatchProcessesWaitingOnException_Response
err zx/status

ProcessLimbo_RetrieveException_Result

generated

NameTypeDescription
response ProcessLimbo_RetrieveException_Response
err zx/status

ProcessLimbo_ReleaseProcess_Result

generated

NameTypeDescription
response ProcessLimbo_ReleaseProcess_Response
err zx/status

ProcessLimbo_AppendFilters_Result

generated

NameTypeDescription
response ProcessLimbo_AppendFilters_Response
err zx/status

ProcessLimbo_RemoveFilters_Result

generated

NameTypeDescription
response ProcessLimbo_RemoveFilters_Response
err zx/status

CONSTANTS

NameValueTypeDescription
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