hybrid_unwinder.hpp

Go to the documentation of this file.

// SPDX-FileCopyrightText: 2026 Jarosław Pelczar <jarek@jpelczar.com>
//
// SPDX-License-Identifier: BSD-2-Clause
 
#pragma once
 
#include "exception_frame.hpp"
#include "frame_pointer.hpp"
#include <type_traits>
#include <utility>
 
namespace microfmt {
 
template <typename Tag> struct exception_matcher_traits;
 
// ============================================================================
// Unified Unwind Frame Type
// ============================================================================
 
enum class frame_kind : uint8_t { standard = 0, trap_transition };
 
struct MICROFMT_API_CLASS hybrid_frame {
  uint32_t frame_index{0};
  uintptr_t fp{0};
  uintptr_t pc{0};
  frame_kind kind{frame_kind::standard};
  trap_context trap{}; // Valid when kind == frame_kind::trap_transition
};
 
// ============================================================================
// Exception Matcher Hook
// ============================================================================
 
class MICROFMT_API_CLASS RELOCO_POINTER exception_matcher_ref {
public:
  struct vtable {
    bool (*match_trap_frame)(const void *ctx, uintptr_t fp, uintptr_t pc, uintptr_t &out_trap_frame_addr) noexcept;
  };
 
  constexpr exception_matcher_ref() noexcept = default;
 
  template <typename Tag, typename Context, typename Traits = exception_matcher_traits<Tag>,
            std::enable_if_t<std::is_convertible_v<const Context *, const typename Traits::context_type *>, int> = 0>
  constexpr exception_matcher_ref(Tag, const Context &ctx RELOCO_LIFETIMEBOUND RELOCO_LIFETIME_CAPTURE_BY_THIS) noexcept
      : ctx_(&ctx), vtbl_(&s_vtbl<Tag>) {}
 
  template <typename Tag, typename Context, std::enable_if_t<!std::is_lvalue_reference_v<Context>, int> = 0>
  constexpr exception_matcher_ref(Tag, Context &&) = delete;
 
  template <typename Tag, typename Context, typename Traits = exception_matcher_traits<Tag>>
  [[nodiscard]] static constexpr exception_matcher_ref make(const Context &ctx RELOCO_LIFETIMEBOUND) noexcept {
    return exception_matcher_ref(Tag{}, ctx);
  }
 
  template <typename Tag, typename Context, std::enable_if_t<!std::is_lvalue_reference_v<Context>, int> = 0>
  static exception_matcher_ref make(Context &&) = delete;
 
  [[nodiscard]] bool match_trap_frame(uintptr_t fp, uintptr_t pc, uintptr_t &out_trap_frame_addr) const noexcept {
    if (!vtbl_)
      return false;
    return vtbl_->match_trap_frame(ctx_.get(), fp, pc, out_trap_frame_addr);
  }
 
  [[nodiscard]] constexpr explicit operator bool() const noexcept { return vtbl_ != nullptr; }
 
private:
  template <typename Tag>
  static constexpr vtable s_vtbl{[](const void *context, uintptr_t fp, uintptr_t pc, uintptr_t &out_addr) noexcept {
    using context_type = typename exception_matcher_traits<Tag>::context_type;
    const auto &typed_context = *static_cast<const context_type *>(context);
    return exception_matcher_traits<Tag>::match_trap_frame(value_ref<const context_type>(typed_context), fp, pc,
                                                           out_addr);
  }};
 
  value_ptr<const void> ctx_{};
  const vtable *vtbl_{nullptr};
};
 
template <typename Tag> class RELOCO_OWNER exception_matcher {
public:
  using traits_type = exception_matcher_traits<Tag>;
  using context_type = typename traits_type::context_type;
 
  constexpr explicit exception_matcher(context_type context) noexcept : context_(std::move(context)) {}
 
  [[nodiscard]] constexpr value_ref<context_type> context() & noexcept RELOCO_LIFETIMEBOUND {
    return value_ref<context_type>(context_);
  }
 
  [[nodiscard]] constexpr value_ref<const context_type> context() const & noexcept RELOCO_LIFETIMEBOUND {
    return value_ref<const context_type>(context_);
  }
 
  [[nodiscard]] constexpr exception_matcher_ref ref() const & noexcept RELOCO_LIFETIMEBOUND {
    return exception_matcher_ref(Tag{}, context_);
  }
 
  [[nodiscard]] constexpr operator exception_matcher_ref() const & noexcept RELOCO_LIFETIMEBOUND { return ref(); }
 
  value_ref<context_type> context() && = delete;
  value_ref<const context_type> context() const && = delete;
  exception_matcher_ref ref() const && = delete;
  operator exception_matcher_ref() const && = delete;
 
private:
  context_type context_;
};
 
// ============================================================================
// Hybrid Stack Unwinder (FP + Exception Frames)
// ============================================================================
 
class MICROFMT_API_CLASS hybrid_stack_unwinder {
public:
  constexpr hybrid_stack_unwinder(frame_unwinder_ref fp_unwinder, exception_frame_ref trap_decoder,
                                  exception_matcher_ref matcher, register_context_ref reg_ctx, uintptr_t initial_fp,
                                  uintptr_t initial_pc) noexcept
      : fp_unwinder_(fp_unwinder), trap_decoder_(trap_decoder), matcher_(matcher), reg_ctx_(reg_ctx),
        current_{0, initial_fp, initial_pc, frame_kind::standard, {}}, is_valid_(initial_fp != 0 || initial_pc != 0) {}
 
  [[nodiscard]] constexpr const hybrid_frame &operator*() const noexcept { return current_; }
  [[nodiscard]] constexpr const hybrid_frame *operator->() const noexcept { return &current_; }
 
  [[nodiscard]] constexpr bool has_value() const noexcept { return is_valid_; }
  [[nodiscard]] constexpr explicit operator bool() const noexcept { return is_valid_; }
 
  bool next() noexcept {
    if (!is_valid_)
      return false;
 
    // Check if the current frame is an exception trampoline
    uintptr_t trap_frame_addr = 0;
    if (matcher_ && matcher_.match_trap_frame(current_.fp, current_.pc, trap_frame_addr)) {
      current_.trap = {};
      if (trap_decoder_ && trap_decoder_.decode(trap_frame_addr, current_.trap)) {
        // Synthesize a trap transition frame
        current_.frame_index++;
        current_.kind = frame_kind::trap_transition;
        current_.fp = current_.trap.fp;
        current_.pc = current_.trap.pc;
        return true;
      }
    }
 
    // Normal FP unwind step
    uintptr_t next_fp = 0;
    uintptr_t next_pc = 0;
    if (!fp_unwinder_.step(reg_ctx_, current_.pc, next_fp, next_pc)) {
      is_valid_ = false;
      return false;
    }
 
    current_.frame_index++;
    current_.kind = frame_kind::standard;
    current_.fp = next_fp;
    current_.pc = next_pc;
    return true;
  }
 
  hybrid_stack_unwinder &operator++() noexcept {
    next();
    return *this;
  }
 
  template <typename Visitor> void for_each_frame(Visitor &&visitor, uint32_t max_depth = 64) noexcept {
    while (is_valid_ && current_.frame_index < max_depth) {
      if (!visitor(current_)) {
        break;
      }
      next();
    }
  }
 
private:
  frame_unwinder_ref fp_unwinder_{};
  exception_frame_ref trap_decoder_{};
  exception_matcher_ref matcher_{};
  register_context_ref reg_ctx_{};
  hybrid_frame current_{};
  bool is_valid_{false};
};
 
// ============================================================================
// Formattable Hybrid Backtrace View
// ============================================================================
 
class MICROFMT_API_CLASS RELOCO_POINTER hybrid_backtrace_view {
public:
  constexpr explicit hybrid_backtrace_view(hybrid_stack_unwinder &unwinder RELOCO_LIFETIMEBOUND,
                                           symbol_resolver_ref resolver,
                                           symbol_resolution_context &symbol_context RELOCO_LIFETIMEBOUND,
                                           uint32_t max_depth = 32) noexcept
      : unwinder_(&unwinder), resolver_(resolver), symbol_context_(&symbol_context), max_depth_(max_depth) {}
 
  [[nodiscard]] constexpr hybrid_stack_unwinder &unwinder() const noexcept RELOCO_LIFETIMEBOUND { return *unwinder_; }
  [[nodiscard]] constexpr symbol_resolver_ref resolver() const noexcept { return resolver_; }
  [[nodiscard]] constexpr symbol_resolution_context &symbol_context() const noexcept RELOCO_LIFETIMEBOUND {
    return *symbol_context_;
  }
  [[nodiscard]] constexpr uint32_t max_depth() const noexcept { return max_depth_; }
 
private:
  value_ptr<hybrid_stack_unwinder> unwinder_;
  symbol_resolver_ref resolver_{};
  value_ptr<symbol_resolution_context> symbol_context_{};
  uint32_t max_depth_{32};
};
 
template <> struct formatter<hybrid_backtrace_view> {
  char mode{'\0'};
 
  constexpr void parse(format_parse_context &ctx) noexcept {
    auto spec = ctx.spec();
    if (!spec.empty() && spec.front() == '#') {
      mode = '#';
    }
  }
 
  void format(const hybrid_backtrace_view &view, const sink &out) const noexcept {
    hybrid_stack_unwinder cursor = view.unwinder();
 
    bool first = true;
    cursor.for_each_frame(
        [&](const hybrid_frame &frame) noexcept -> bool {
          if (!first) {
            out.write("\n");
          }
          first = false;
 
          if (frame.kind == frame_kind::trap_transition) {
            out.write("  --- [Exception Boundary: ");
            if (frame.trap.is_user_mode) {
              out.write("User -> Kernel");
            } else {
              out.write("Nested Fault");
            }
            microfmt::format_to(out, " (vec {:#x})] ---\n", frame.trap.vector_or_reason);
          }
 
          microfmt::format_to(out, "  #{:<2} fp={:#x}  pc=", frame.frame_index, frame.fp);
 
          remote_fn_ptr fn_sym(frame.pc, view.resolver(), view.symbol_context());
          if (mode == '#') {
            microfmt::format_to(out, "{:#}", fn_sym);
          } else {
            microfmt::format_to(out, "{}", fn_sym);
          }
          return true;
        },
        view.max_depth());
  }
};
 
} // namespace microfmt