symbol_resolver.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 "demangle.hpp"
#include <cstddef>
#include <cstdint>
#include <string_view>
#include <type_traits>
 
namespace microfmt {
 
// ============================================================================
// Raw Kernel / Platform Resolution Result
// ============================================================================
 
struct MICROFMT_API_CLASS RELOCO_POINTER raw_resolved_symbol {
  microfmt::string_view symbol_name{""};
  uintptr_t symbol_base{0};
  bool is_exact{false};
 
  microfmt::string_view image_name{""};
  uintptr_t image_load_base{0};
};
 
struct MICROFMT_API_CLASS RELOCO_POINTER resolved_symbol_info {
  microfmt::string_view symbol_name{""};
  uintptr_t symbol_base{0};
  uintptr_t offset_from_symbol{0};
  bool is_exact{false};
 
  microfmt::string_view image_name{""};
  uintptr_t image_load_base{0};
  uintptr_t offset_from_image{0};
 
  [[nodiscard]] constexpr bool has_symbol() const noexcept { return !symbol_name.empty(); }
 
  [[nodiscard]] constexpr bool has_image() const noexcept { return !image_name.empty(); }
};
 
struct MICROFMT_API_CLASS RELOCO_POINTER symbol_resolution_context {
  constexpr explicit symbol_resolution_context(span<char> string_scratch RELOCO_LIFETIMEBOUND = {}) noexcept
      : scratch(string_scratch) {}
 
  template <size_t N>
  constexpr explicit symbol_resolution_context(char (&string_scratch)[N]) noexcept : scratch(string_scratch, N) {}
 
  span<char> scratch{};
  raw_resolved_symbol raw{};
  resolved_symbol_info resolved{};
};
 
// ============================================================================
// Static Customization Point: symbol_resolver_traits
// ============================================================================
 
template <typename Tag> struct symbol_resolver_traits;
 
// ============================================================================
// Minimal-Stack Type-Erased Symbol Resolver (2 Words)
// ============================================================================
 
class RELOCO_POINTER symbol_resolver_ref {
public:
  struct vtable {
    bool (*resolve)(const void *ctx, uintptr_t addr, span<char> scratch,
                    raw_resolved_symbol &out_raw) noexcept = nullptr;
  };
 
  constexpr symbol_resolver_ref() noexcept = default;
 
  template <typename Tag, typename Traits = symbol_resolver_traits<Tag>,
            std::enable_if_t<std::is_void_v<typename Traits::context_type>, int> = 0>
  constexpr explicit symbol_resolver_ref(Tag) noexcept : ctx_(nullptr), vtbl_(&s_vtbl<Tag>) {}
 
  template <typename Tag, typename Context, typename Traits = symbol_resolver_traits<Tag>,
            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 symbol_resolver_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 symbol_resolver_ref(Tag, Context &&) = delete;
 
  template <typename Tag, typename Traits = symbol_resolver_traits<Tag>,
            std::enable_if_t<std::is_void_v<typename Traits::context_type>, int> = 0>
  [[nodiscard]] static constexpr symbol_resolver_ref make() noexcept {
    return symbol_resolver_ref(Tag{});
  }
 
  template <typename Tag, typename Context, typename Traits = symbol_resolver_traits<Tag>,
            std::enable_if_t<!std::is_void_v<typename Traits::context_type>, int> = 0>
  [[nodiscard]] static constexpr symbol_resolver_ref make(const Context &ctx RELOCO_LIFETIMEBOUND) noexcept {
    return symbol_resolver_ref(Tag{}, ctx);
  }
 
  template <typename Tag, typename Context, std::enable_if_t<!std::is_lvalue_reference_v<Context>, int> = 0>
  static symbol_resolver_ref make(Context &&) = delete;
 
  [[nodiscard]] bool resolve(uintptr_t addr, symbol_resolution_context &context) const noexcept {
    return resolve(addr, context.scratch, context.raw, context.resolved);
  }
 
  [[nodiscard]] bool resolve(uintptr_t addr, span<char> scratch, raw_resolved_symbol &raw_storage,
                             resolved_symbol_info &out_info) const noexcept {
    if (vtbl_ == nullptr)
      return false;
 
    raw_storage = {};
    if (!vtbl_->resolve(ctx_.get(), addr, scratch, raw_storage)) {
      return false;
    }
 
    out_info = {};
    out_info.symbol_name = raw_storage.symbol_name;
    out_info.symbol_base = raw_storage.symbol_base;
    out_info.is_exact = raw_storage.is_exact;
    out_info.image_name = raw_storage.image_name;
    out_info.image_load_base = raw_storage.image_load_base;
 
    if (raw_storage.symbol_base != 0 && addr >= raw_storage.symbol_base) {
      out_info.offset_from_symbol = addr - raw_storage.symbol_base;
    } else {
      out_info.offset_from_symbol = 0;
    }
 
    if (raw_storage.image_load_base != 0 && addr >= raw_storage.image_load_base) {
      out_info.offset_from_image = addr - raw_storage.image_load_base;
    } else {
      out_info.offset_from_image = 0;
    }
 
    return true;
  }
 
  [[nodiscard]] constexpr explicit operator bool() const noexcept { return vtbl_ != nullptr; }
 
private:
  template <typename Tag>
  static bool resolve_entry(const void *context, uintptr_t address, span<char> scratch,
                            raw_resolved_symbol &result) noexcept {
    using context_type = typename symbol_resolver_traits<Tag>::context_type;
    if constexpr (std::is_void_v<context_type>) {
      return symbol_resolver_traits<Tag>::resolve(address, scratch, result);
    } else {
      const auto &typed_context = *static_cast<const context_type *>(context);
      return symbol_resolver_traits<Tag>::resolve(value_ref<const context_type>(typed_context), address, scratch,
                                                  result);
    }
  }
 
  template <typename Tag> static constexpr vtable s_vtbl{&resolve_entry<Tag>};
 
  value_ptr<const void> ctx_{};
  const vtable *vtbl_{nullptr};
};
 
template <typename Tag, bool Stateless = std::is_void_v<typename symbol_resolver_traits<Tag>::context_type>>
class symbol_resolver;
 
template <typename Tag> class RELOCO_OWNER symbol_resolver<Tag, false> {
public:
  using traits_type = symbol_resolver_traits<Tag>;
  using context_type = typename traits_type::context_type;
 
  constexpr explicit symbol_resolver(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 symbol_resolver_ref ref() const & noexcept RELOCO_LIFETIMEBOUND {
    return symbol_resolver_ref(Tag{}, context_);
  }
 
  value_ref<context_type> context() && = delete;
  value_ref<const context_type> context() const && = delete;
  symbol_resolver_ref ref() const && = delete;
 
private:
  context_type context_;
};
 
template <typename Tag> class symbol_resolver<Tag, true> {
public:
  [[nodiscard]] static constexpr symbol_resolver_ref ref() noexcept { return symbol_resolver_ref(Tag{}); }
};
 
// ============================================================================
// Remote Symbol View & Formatter
// ============================================================================
 
class MICROFMT_API_CLASS RELOCO_POINTER remote_symbol_view {
public:
  constexpr remote_symbol_view() noexcept = default;
 
  constexpr remote_symbol_view(uintptr_t addr, symbol_resolver_ref resolver,
                               symbol_resolution_context &context RELOCO_LIFETIMEBOUND, bool demangle = true) noexcept
      : addr_(addr), resolver_(resolver), context_(&context), demangle_(demangle) {}
 
  [[nodiscard]] constexpr uintptr_t address() const noexcept { return addr_; }
  [[nodiscard]] constexpr symbol_resolver_ref resolver() const noexcept { return resolver_; }
  [[nodiscard]] constexpr symbol_resolution_context &context() const noexcept RELOCO_LIFETIMEBOUND { return *context_; }
  [[nodiscard]] constexpr bool demangle() const noexcept { return demangle_; }
 
private:
  uintptr_t addr_{0};
  symbol_resolver_ref resolver_{};
  value_ptr<symbol_resolution_context> context_{};
  bool demangle_{true};
};
 
template <> struct formatter<remote_symbol_view> {
  char mode{'\0'}; // '#' = verbose (image!symbol+off), '\0' = standard
 
  constexpr void parse(format_parse_context &ctx) noexcept {
    const auto spec = ctx.spec();
    if (!spec.empty() && spec.front() == '#') {
      mode = '#';
    }
  }
 
  void format(const remote_symbol_view &view, const sink &out) const noexcept {
    if (view.address() == 0) {
      out.write("(null)");
      return;
    }
 
    if (!view.resolver()) {
      microfmt::format_to(out, "{:#x}", view.address());
      return;
    }
 
    auto &context = view.context();
    context.raw = {};
    context.resolved = {};
    const bool ok = view.resolver().resolve(view.address(), context);
    const auto &info = context.resolved;
 
    // 1. Unresolved fallback
    if (!ok || (!info.has_symbol() && !info.has_image())) {
      microfmt::format_to(out, "<unknown@{:#x}>", view.address());
      return;
    }
 
    // Precise or nearest symbol matched
    if (info.has_symbol()) {
      if (mode == '#' && info.has_image()) {
        microfmt::format_to(out, "{}!", info.image_name);
      }
 
      if (view.demangle()) {
        microfmt::format_to(out, "{}", as_demangled(info.symbol_name));
      } else {
        out.write(info.symbol_name);
      }
 
      if (info.offset_from_symbol > 0) {
        microfmt::format_to(out, "+{:#x}", info.offset_from_symbol);
      }
      return;
    }
 
    // Module/Image known, but symbol stripped (e.g. nvgpu.ko+0x1420)
    if (info.has_image()) {
      microfmt::format_to(out, "{}+{:#x}", info.image_name, info.offset_from_image);
    }
  }
};
 
[[nodiscard]] constexpr auto make_remote_symbol(uintptr_t addr, symbol_resolver_ref resolver,
                                                symbol_resolution_context &context, bool demangle = true) noexcept {
  return remote_symbol_view(addr, resolver, context, demangle);
}
 
} // namespace microfmt