// Copyright 2019 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
@available(added=HEAD)
library fuchsia.exception;

using zx;

/// Protocol meant for clients interested in handling exceptions for a
/// particular service.
@discoverable
closed protocol Handler {
    /// Requests the exception handler to send a signal indicating the server is
    /// active and able to respond to requests.
    ///
    /// It's recommended clients call IsActive and wait for a response before
    /// sending an exception to the server with OnException because a
    /// zx.Handle:EXCEPTION can't be released by the client once it's sent
    /// across the channel.
    ///
    /// Note: a response guarantees the server was active when it sent the
    /// response, but doesn't preclcude the server being unresponsive after the
    /// reply was sent.
    strict IsActive() -> ();

    /// 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.
    strict OnException(resource struct {
        exception zx.Handle:EXCEPTION;
        info ExceptionInfo;
    }) -> ();
};

/// Basic exception information associated with a particular exception.
/// Maps to `zx_exception_info_t`.
// TODO(https://fxbug.dev/42157577): Currently there is no good support for tables within the
//                 llcpp bindings, which would make this API very cumbersome to
//                 use. When better support lands, move this to a table.
type ExceptionInfo = struct {
    // Process ID or pid.
    process_koid zx.Koid;

    // Thread ID or tid.
    thread_koid zx.Koid;

    type ExceptionType;
};

/// Generic wrapper over a thread exception. Mirrors closely the information
/// given by an exception channel.
/// Both |process| and |thread| will be valid if present.
type ProcessException = resource table {
    /// `exception` is guaranteed to be valid.
    1: exception zx.Handle:EXCEPTION;
    2: info ExceptionInfo;

    /// Both `process` and `thread` will be valid if present.
    3: process zx.Handle:PROCESS;

    /// The thread that generated the exception.
    /// The process may have other threads that are not reflected here.
    4: thread zx.Handle:THREAD;
};

/// 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.
// TODO(https://fxbug.dev/42158100): Once there is a way to better generate zx bindings, move this
//                 definitions to a common library.
type ExceptionType = strict enum : uint32 {
    GENERAL = 0x8;
    FATAL_PAGE_FAULT = 0x108;
    UNDEFINED_INSTRUCTION = 0x208;
    SW_BREAKPOINT = 0x308;
    HW_BREAKPOINT = 0x408;
    UNALIGNED_ACCESS = 0x508;
    THREAD_STARTING = 0x8008;
    THREAD_EXITING = 0x8108;
    POLICY_ERROR = 0x8208;
    PROCESS_STARTING = 0x8308;
};