frame_pointer.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 "address_space.hpp"
#include "register_context.hpp"
#include "remote_diagnostics.hpp"
#include "symbol_resolver.hpp"
#include <cstddef>
#include <cstdint>
#include <type_traits>
 
namespace microfmt {
 
// ============================================================================
// Stack Frame Record
// ============================================================================
 
struct MICROFMT_API_CLASS stack_frame {
  uint32_t frame_index{0};
  uintptr_t fp{0};
  uintptr_t pc{0};
 
  [[nodiscard]] constexpr bool is_null() const noexcept { return fp == 0 && pc == 0; }
};
 
// ============================================================================
// Customization Traits Point
// ============================================================================
 
template <typename ArchTag> struct frame_unwinder_traits;
 
// ============================================================================
// Type-Erased Unwinder Handle (2 Words)
// ============================================================================
 
class RELOCO_POINTER frame_unwinder_ref {
public:
  struct vtable {
    bool (*step)(const void *ctx, register_context_ref reg_ctx, uintptr_t current_pc, uintptr_t &next_fp,
                 uintptr_t &next_pc) noexcept;
  };
 
  constexpr frame_unwinder_ref() noexcept = default;
 
  template <typename ArchTag, typename Traits = frame_unwinder_traits<ArchTag>,
            std::enable_if_t<std::is_void_v<typename Traits::context_type>, int> = 0>
  constexpr explicit frame_unwinder_ref(ArchTag) noexcept : ctx_(nullptr), vtbl_(&s_vtbl<ArchTag>) {}
 
  template <typename ArchTag, typename Context, typename Traits = frame_unwinder_traits<ArchTag>,
            std::enable_if_t<!std::is_void_v<typename Traits::context_type> &&
                                 std::is_convertible_v<const Context *, const typename Traits::context_type *>,
                             int> = 0>
  constexpr frame_unwinder_ref(ArchTag,
                               const Context &ctx RELOCO_LIFETIMEBOUND RELOCO_LIFETIME_CAPTURE_BY_THIS) noexcept
      : ctx_(&ctx), vtbl_(&s_vtbl<ArchTag>) {}
 
  template <typename ArchTag, typename Context, std::enable_if_t<!std::is_lvalue_reference_v<Context>, int> = 0>
  constexpr frame_unwinder_ref(ArchTag, Context &&) = delete;
 
  template <typename ArchTag, typename Traits = frame_unwinder_traits<ArchTag>,
            std::enable_if_t<std::is_void_v<typename Traits::context_type>, int> = 0>
  [[nodiscard]] static constexpr frame_unwinder_ref make() noexcept {
    return frame_unwinder_ref(ArchTag{});
  }
 
  template <typename ArchTag, typename Context, typename Traits = frame_unwinder_traits<ArchTag>,
            std::enable_if_t<!std::is_void_v<typename Traits::context_type>, int> = 0>
  [[nodiscard]] static constexpr frame_unwinder_ref make(const Context &ctx RELOCO_LIFETIMEBOUND) noexcept {
    return frame_unwinder_ref(ArchTag{}, ctx);
  }
 
  template <typename ArchTag, typename Context, std::enable_if_t<!std::is_lvalue_reference_v<Context>, int> = 0>
  static frame_unwinder_ref make(Context &&) = delete;
 
  [[nodiscard]] bool step(register_context_ref reg_ctx, uintptr_t current_pc, uintptr_t &next_fp,
                          uintptr_t &next_pc) const noexcept {
    if (!vtbl_)
      return false;
    return vtbl_->step(ctx_.get(), reg_ctx, current_pc, next_fp, next_pc);
  }
 
  [[nodiscard]] constexpr explicit operator bool() const noexcept { return vtbl_ != nullptr; }
 
private:
  template <typename ArchTag>
  static bool step_entry(const void *context, register_context_ref registers, uintptr_t current_pc, uintptr_t &next_fp,
                         uintptr_t &next_pc) noexcept {
    using context_type = typename frame_unwinder_traits<ArchTag>::context_type;
    if constexpr (std::is_void_v<context_type>) {
      return frame_unwinder_traits<ArchTag>::step(registers, current_pc, next_fp, next_pc);
    } else {
      const auto &typed_context = *static_cast<const context_type *>(context);
      return frame_unwinder_traits<ArchTag>::step(value_ref<const context_type>(typed_context), registers, current_pc,
                                                  next_fp, next_pc);
    }
  }
 
  template <typename ArchTag> static constexpr vtable s_vtbl{&step_entry<ArchTag>};
 
  value_ptr<const void> ctx_{};
  const vtable *vtbl_{nullptr};
};
 
template <typename Tag, bool Stateless = std::is_void_v<typename frame_unwinder_traits<Tag>::context_type>>
class frame_unwinder;
 
template <typename Tag> class RELOCO_OWNER frame_unwinder<Tag, false> {
public:
  using traits_type = frame_unwinder_traits<Tag>;
  using context_type = typename traits_type::context_type;
 
  constexpr explicit frame_unwinder(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 frame_unwinder_ref ref() const & noexcept RELOCO_LIFETIMEBOUND {
    return frame_unwinder_ref(Tag{}, context_);
  }
 
  value_ref<context_type> context() && = delete;
  value_ref<const context_type> context() const && = delete;
  frame_unwinder_ref ref() const && = delete;
 
private:
  context_type context_;
};
 
template <typename Tag> class frame_unwinder<Tag, true> {
public:
  [[nodiscard]] static constexpr frame_unwinder_ref ref() noexcept { return frame_unwinder_ref(Tag{}); }
};
 
// ============================================================================
// Type-Erased Frame Pointer Iterator / Cursor
// ============================================================================
 
class MICROFMT_API_CLASS frame_pointer_iterator {
public:
  constexpr frame_pointer_iterator() noexcept = default;
 
  constexpr frame_pointer_iterator(frame_unwinder_ref unwinder, register_context_ref reg_ctx, uintptr_t initial_fp,
                                   uintptr_t initial_pc) noexcept
      : unwinder_(unwinder), reg_ctx_(reg_ctx), frame_{0, initial_fp, initial_pc},
        is_valid_(initial_fp != 0 && initial_pc != 0) {}
 
  [[nodiscard]] constexpr const stack_frame &operator*() const noexcept RELOCO_LIFETIMEBOUND { return frame_; }
  [[nodiscard]] constexpr const stack_frame *operator->() const noexcept RELOCO_LIFETIMEBOUND { return &frame_; }
 
  [[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;
 
    uintptr_t next_fp = 0;
    uintptr_t next_pc = 0;
 
    if (!unwinder_.step(reg_ctx_, frame_.pc, next_fp, next_pc)) {
      is_valid_ = false;
      return false;
    }
 
    frame_.frame_index++;
    frame_.fp = next_fp;
    frame_.pc = next_pc;
    return true;
  }
 
  frame_pointer_iterator &operator++() noexcept {
    next();
    return *this;
  }
 
  template <typename Visitor> void for_each_frame(Visitor &&visitor, uint32_t max_depth = 64) noexcept {
    while (is_valid_ && frame_.frame_index < max_depth) {
      if (!visitor(frame_)) {
        break;
      }
      next();
    }
  }
 
private:
  frame_unwinder_ref unwinder_{};
  register_context_ref reg_ctx_{};
  stack_frame frame_{};
  bool is_valid_{false};
};
 
// ============================================================================
// Backtrace View Formatter
// ============================================================================
 
class MICROFMT_API_CLASS RELOCO_POINTER remote_backtrace_view {
public:
  constexpr remote_backtrace_view(frame_pointer_iterator iter, symbol_resolver_ref resolver,
                                  symbol_resolution_context &symbol_context RELOCO_LIFETIMEBOUND,
                                  uint32_t max_depth = 16) noexcept
      : iter_(iter), resolver_(resolver), symbol_context_(&symbol_context), max_depth_(max_depth) {}
 
  [[nodiscard]] constexpr frame_pointer_iterator iterator() const noexcept { return iter_; }
  [[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:
  frame_pointer_iterator iter_{};
  symbol_resolver_ref resolver_{};
  value_ptr<symbol_resolution_context> symbol_context_{};
  uint32_t max_depth_{16};
};
 
template <> struct formatter<remote_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 remote_backtrace_view &view, const sink &out) const noexcept {
    frame_pointer_iterator cursor = view.iterator();
 
    bool first = true;
    cursor.for_each_frame(
        [&](const stack_frame &frame) noexcept -> bool {
          if (!first) {
            out.write("\n");
          }
          first = false;
 
          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