path: root/Libraries/LibUnwind/UnwindBase.h

/*
 * Copyright (c) 2020, Andrew Kaster <andrewdkaster@gmail.com>
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *
 * 1. Redistributions of source code must retain the above copyright notice, this
 *    list of conditions and the following disclaimer.
 *
 * 2. Redistributions in binary form must reproduce the above copyright notice,
 *    this list of conditions and the following disclaimer in the documentation
 *    and/or other materials provided with the distribution.
 *
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
 * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
 * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 */

#pragma once

#include <stdint.h>

// The following defintions and comments are largely pulled from the Itanium Exception handling ABI
// Reference: https://itanium-cxx-abi.github.io/cxx-abi/abi-eh.htm, version 1.22
// This header defines the methods, types, and constants outlined in Level I. Base ABI
// Also, from the Intel386 psABI version 1.1
// Reference: https://github.com/hjl-tools/x86-psABI/wiki/X86-psABI

// FIXME: Configure gcc and libgcc with --with-system-libunwind :^)

extern "C" {

/// Return code used by _Unwind family of methods
enum _Unwind_Reason_Code {
    _URC_NO_REASON = 0,                /// Forced unwind stop routine determined this isn't the correct frame
    _URC_FOREIGN_EXCEPTION_CAUGHT = 1, /// This indicates that a different runtime caught this exception.
                                       ///     Nested foreign exceptions, or rethrowing a foreign exception,
                                       ///     result in undefined behaviour.
    _URC_FATAL_PHASE2_ERROR = 2,       /// The personality routine encountered an error during phase 2,
                                       ///     for instance a stack corruption (call std::terminate())
    _URC_FATAL_PHASE1_ERROR = 3,       /// The personality routine encountered an error during phase 1,
                                       ///     other than the specific error codes defined.
    _URC_NORMAL_STOP = 4,              /// Exception handled(?) Spec doesn't say...
    _URC_END_OF_STACK = 5,             /// Reached the top of the stack without a handler :(
    _URC_HANDLER_FOUND = 6,            /// Success! End phase 1 lookup, continue to phase 2
    _URC_INSTALL_CONTEXT = 7,          /// Personality routine wants the context created
    _URC_CONTINUE_UNWIND = 8           /// Destructors etc called, keep walking up stack until we reach handler
};

// Forward declaration for cleanup method below
struct _Unwind_Exception;

/// Method that knows how to destroy a particualar exception. Called when handling a foreign exception
typedef void (*_Unwind_Exception_Cleanup_Fn)(_Unwind_Reason_Code reason, struct _Unwind_Exception* exc);

/// Exception object, language agnostic
/// @note: _Unwind_Exception must be double word aligned
/// @note: the private vars are different sizes on 64-bit...
struct _Unwind_Exception {
    uint64_t exception_class;                       ///< For identification. For c++, the four low bytes are "C++\0"
    _Unwind_Exception_Cleanup_Fn exception_cleanup; ///< Used if caught by a different runtime
    uint32_t private_1;                             ///< Private for system implementation
    uint32_t private_2;                             ///< Private for system implementation
    // Note that for C++, the language specific exception object will be located directly following this header
};

/// Opaque typedef to system unwinder implementation class
struct _Unwind_Context;

/// Raise an exception, nominally noreturn (i.e. if we return, we've got trouble)
/// @param exception_object Exception that was allocated by language specific runtime
///     It must have its exception_class and cleanup fields set
/// @returns One of the following reason codes:
///     * _URC_END_OF_STACK : No handler found during phase 1 lookup. (uncaught_exception())
///     * _URC_FATAL_PHASE1_ERROR: Stack corruption during phase 1 lookup. (terminate())
///
/// @note If the unwinder can't do phase 2 cleanup, it should return _URC_FATAL_PHASE2_ERROR
/// @note The caller of _Unwind_RaiseException can make no assumptions about the state of its stack or registers.
///
_Unwind_Reason_Code _Unwind_RaiseException(struct _Unwind_Exception* exception_object);

/// Resume propagation of an existing exception e.g. after executing cleanup code in a partially unwound stack.
/// A call to this routine is inserted at the end of a landing pad that performed cleanup, but did not resume normal
/// execution. It causes unwinding to proceed further.
///
/// @note  _Unwind_Resume should not be used to implement rethrowing. To the unwinding runtime,/
///     the catch code that rethrows was a handler, and the previous unwinding session was terminated before entering.
///     Rethrowing is implemented by calling _Unwind_RaiseException again with the same exception object.
///     This means that re-throwing an exception causes the exception handing process to begin again at phase 1.
/// @note This is the only routine in the unwind library which is expected to be called directly by generated code:
///     it will be called at the end of a landing pad in a "landing-pad" model.
///
void _Unwind_Resume(struct _Unwind_Exception* exception_object);

/// Deletes the given exception object.
/// If a given runtime resumes normal execution after catching a foreign exception, it will not know how to delete
/// that exception. Such an exception will be deleted by calling _Unwind_DeleteException.
/// This is a convenience function that calls the function pointed to by the exception_cleanup field of the exception
/// header.
///
void _Unwind_DeleteException(struct _Unwind_Exception* exception_object);

//-------------
// Context management routines
//
// Used for communicating information about the unwind context between the unwind library, personality routine,
// and compiler-generated landing pad.
// They include routines to read or set the context record images of registers in the stack frame corresponding
// to a given unwind context, and to identify the location of the current unwind descriptors and unwind frame.
//-------------

/// Get the 32-bit value of the given general register
/// The register is identified by its index in the DWARF register mapping
///
/// During the two phases of unwinding, no registers have a guaranteed value.
///
uint32_t _Unwind_GetGR(struct _Unwind_Context* context, int index);

/// Set the 32-bit value of the given register
/// The register identified by its index as for _Unwind_GetGR.
///
/// The behaviour is guaranteed only if the function is called during phase 2 of unwinding,
/// and applied to an unwind context representing a handler frame, for which the personality routine will return
/// _URC_INSTALL_CONTEXT. In that case, only registers %eax and %edx should be used.
/// These scratch registers are reserved for passing arguments between the personality routine and the landing pads.
///
void _Unwind_SetGR(struct _Unwind_Context* context, int index, uint32_t new_value);

/// Get the 32-bit value of the instruction pointer (IP).
///
/// During unwinding, the value is guaranteed to be the address of the instruction immediately following the call site
/// in the function identified by the unwind context. This value may be outside of the procedure fragment for
/// a function call that is known to not return (such as _Unwind_Resume).
///
uint32_t _Unwind_GetIP(struct _Unwind_Context* context);

/// Set the value of the instruction pointer (IP) for the routine identified by the unwind context.
///
/// The behaviour is guaranteed only when this function is called for an unwind context representing a handler frame,
/// for which the personality routine will return _URC_INSTALL_CONTEXT.
/// In this case, control will be transferred to the given address, which should be the address of a landing pad.
///
void _Unwind_SetIP(struct _Unwind_Context* context, uint32_t new_value);

/// Get language specific data area for the current stack frame.
/// Useful for retrieving information that was cached after finding the personality routine.
///
uint32_t _Unwind_GetLanguageSpecificData(struct _Unwind_Context* context);

/// Get the address of the beginning of the procedure or code fragment described by the current unwind descriptor
/// block.
///
/// This information is required to access any data stored relative to the beginning
/// of the procedure fragment. For instance, a call site table might be stored relative
/// to the beginning of the procedure fragment that contains the calls.
/// During unwinding, the function returns the start of the procedure fragment containing the call site in the current
/// stack frame.
///
uint32_t _Unwind_GetRegionStart(struct _Unwind_Context* context);

/// This function returns the 32-bit Canonical Frame Address which is defined as
/// the value of %esp at the call site in the previous frame. This value is guaranteed
/// to be correct any time the context has been passed to a personality routine or a
/// stop function.
uint32_t _Unwind_GetCFA(struct _Unwind_Context* context);

/// Personality routine
/// The personality routine is the function in the C++ (or other language) runtime library which serves
/// as an interface between the system unwind library and
/// language-specific exception handling semantics. It is specific to the code fragment
/// described by an unwind info block, and it is always referenced via the pointer in
/// the unwind info block, and hence it has no psABI-specified name.
/// @note Both GCC and Clang will generate .cfi_personality directives for __gxx_personality_v0
///     Unless we tell the compiler we're using setjump/longjump exceptions (ew, how 90's)
///
/// @param version Better be 1
/// @param actions See below
/// @param exceptionClass [ vendor ][ language ] e.g. "CLNGC++\0" "GNUCC++\0"
/// @param exceptionObject language-specific exception
/// @param context Opaque handle for personality routine + unwinder lib state
///
typedef _Unwind_Reason_Code (*__personality_routine)(int version,
    _Unwind_Action actions,
    uint64_t exceptionClass,
    struct _Unwind_Exception* exceptionObject,
    struct _Unwind_Context* context);

/// Action parameter type for personality routine during unwind. Will be a bit-wise OR of the __UnwindActions below
typedef int _Unwind_Action;

/// Which action(s) the personality routine should perform duing unwind
enum __UnwindActions {
    _UA_SEARCH_PHASE = 1,  /// The personality routine should check if the current frame contains a handler,
                           ///    and if so return _URC_HANDLER_FOUND, or otherwise return _URC_CONTINUE_UNWIND.
                           ///    _UA_SEARCH_PHASE cannot be set at the same time as _UA_CLEANUP_PHASE.
    _UA_CLEANUP_PHASE = 2, /// The personality routine should perform cleanup for the current frame.
                           ///     The personality routine can perform this cleanup itself, by calling nested
                           ///     procedures, and return _URC_CONTINUE_UNWIND. Alternatively, it can setup the
                           ///     registers (including the IP) for transferring control to a "landing pad", and
                           ///     return _URC_INSTALL_CONTEXT.
    _UA_HANDLER_FRAME = 4, /// During phase 2, indicates to the personality routine that the current frame is the one
                           ///     which was flagged as the handler frame during phase 1. The personality routine
                           ///     is not allowed to change its mind between phase 1 and phase 2, i.e. it must handle
                           ///     the exception in this frame in phase 2.
    _UA_FORCE_UNWIND = 8   /// During phase 2, indicates that no language is allowed to "catch" the exception.
                           ///     This flag is set while unwinding the stack for longjmp or during thread
                           ///     cancellation. User-defined code in a catch clause may still be executed, but the
                           ///     catch clause must resume unwinding with a call to _Unwind_Resume when finished.
};

/// Function that knows how to identify a stack frame to stop unwinding for forced unwinding
/// This is different from the usual personality routine query as it can only say yes or no to each frame
typedef _Unwind_Reason_Code (*_Unwind_Stop_Fn)(int version,
    _Unwind_Action actions,
    uint64_t exceptionClass,
    struct _Unwind_Exception* exceptionObject,
    struct _Unwind_Context* context,
    void* stop_parameter);

/// Raise an exception for forced unwinding, passing along the given exception object, which should have its
/// exception_class and exception_cleanup fields set. The exception object has been allocated by the language-specific
/// runtime, and has a language-specific format, except that it must contain an _Unwind_Exception struct.
///
/// Forced unwinding is a single-phase process (phase 2 of the normal exceptionhandling process). The stop and
/// stop_parameter parameters control the termination of the unwind process, instead of the usual personality routine
/// query. The stop function parameter is called for each unwind frame, with the parameters described for the usual
/// personality routine below, plus an additional stop_parameter.
///
/// When the stop function identifies the destination frame, it transfers control (according to its own, unspecified,
/// conventions) to the user code as appropriate without returning, normally after calling _Unwind_DeleteException.
/// If not, it should return an _Unwind_Reason_Code value as follows:
///     * _URC_NO_REASON: This is not the destination frame. The unwind runtime will
///         call the frame’s personality routine with the _UA_FORCE_UNWIND and
//          _UA_CLEANUP_PHASE flags set in actions, and then unwind to the next
///         frame and call the stop function again.
///     * _URC_END_OF_STACK: In order to allow _Unwind_ForcedUnwind to perform special processing
///         when it reaches the end of the stack, the unwind runtime will call it after the last frame is rejected,
///         with a NULL stack pointer in the context, and the stop function must catch this condition
///         (i.e. by noticing the NULL stack pointer). It may return this reason code if it cannot handle end-of-stack.
///     * _URC_FATAL_PHASE2_ERROR: The stop function may return this code for other fatal conditions, e.g. stack corruption.
/// @note: The main reason for this method is to support setjump/longjump exceptions
///
_Unwind_Reason_Code _Unwind_ForcedUnwind(struct _Unwind_Exception* exception_object, _Unwind_Stop_Fn stop, void* stop_parameter);

} // extern "C"