remote_diagnostics.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 "symbol_resolver.hpp"
#include <cstdint>
#include <string_view>
 
namespace microfmt {
 
// ============================================================================
// Diagnostic Formatter for Faults
// ============================================================================
 
inline void format_remote_fault(const sink &out, uintptr_t addr, symbol_resolver_ref resolver,
                                symbol_resolution_context &context) noexcept {
  if (addr == 0) {
    out.write("<fault:nullptr>");
    return;
  }
 
  if (resolver) {
    context.raw = {};
    context.resolved = {};
    if (resolver.resolve(addr, context) && ((context.resolved.has_symbol()) || context.resolved.has_image())) {
      const auto &info = context.resolved;
      out.write("<fault@");
 
      if (info.has_symbol()) {
        if (info.has_image()) {
          out.write(info.image_name);
          out.put('!');
        }
        microfmt::format_to(out, "{}", as_demangled(info.symbol_name));
        if (info.offset_from_symbol > 0) {
          out.write("+0x");
          detail::format_unsigned<detail::radix::hex>(out, static_cast<uint64_t>(info.offset_from_symbol), false, 0);
        }
      } else {
        // Module known, symbol stripped: e.g. "faulty_driver.ko+0x4200"
        out.write(info.image_name);
        out.write("+0x");
        detail::format_unsigned<detail::radix::hex>(out, static_cast<uint64_t>(info.offset_from_image), false, 0);
      }
 
      out.write(">");
      return;
    }
  }
 
  // Fallback raw hex address
  microfmt::format_to(out, "<fault:{:#x}>", addr);
}
 
// ============================================================================
// Symbolic Remote Function / Code Pointer View
// ============================================================================
 
class MICROFMT_API_CLASS RELOCO_POINTER remote_fn_ptr {
public:
  constexpr remote_fn_ptr() noexcept = default;
 
  constexpr remote_fn_ptr(uintptr_t addr, symbol_resolver_ref resolver,
                          symbol_resolution_context &context RELOCO_LIFETIMEBOUND) noexcept
      : addr_(addr), resolver_(resolver), context_(&context) {}
 
  [[nodiscard]] constexpr uintptr_t address() const noexcept { return addr_; }
  [[nodiscard]] constexpr bool is_null() const noexcept { return addr_ == 0; }
  [[nodiscard]] constexpr symbol_resolver_ref resolver() const noexcept { return resolver_; }
  [[nodiscard]] constexpr symbol_resolution_context &context() const noexcept RELOCO_LIFETIMEBOUND { return *context_; }
 
private:
  uintptr_t addr_{0};
  symbol_resolver_ref resolver_{};
  value_ptr<symbol_resolution_context> context_{};
};
 
template <> struct formatter<remote_fn_ptr> {
  char mode{'\0'};
 
  constexpr void parse(format_parse_context &ctx) noexcept {
    auto spec = ctx.spec();
    if (!spec.empty()) {
      mode = spec.front();
    }
  }
 
  void format(const remote_fn_ptr &fn, const sink &out) const noexcept {
    if (fn.is_null()) {
      out.write("(null)");
      return;
    }
 
    if (mode == 'x' || mode == 'p' || !fn.resolver()) {
      microfmt::format_to(out, "{:#x}", fn.address());
      return;
    }
 
    auto sym_view = remote_symbol_view(fn.address(), fn.resolver(), fn.context(), true);
    if (mode == '#') {
      microfmt::format_to(out, "{:#}", sym_view);
    } else {
      microfmt::format_to(out, "{}", sym_view);
    }
  }
};
 
// ============================================================================
// Diagnostics-Aware Remote Struct View
// ============================================================================
 
template <typename T> class RELOCO_POINTER remote_diag_ref {
public:
  constexpr remote_diag_ref(uintptr_t addr, address_space_ref space, symbol_resolver_ref resolver,
                            span<std::byte> scratch RELOCO_LIFETIMEBOUND,
                            symbol_resolution_context &symbol_context RELOCO_LIFETIMEBOUND) noexcept
      : addr_(addr), space_(space), resolver_(resolver), scratch_(scratch), symbol_context_(&symbol_context) {}
 
  [[nodiscard]] constexpr uintptr_t address() const noexcept { return addr_; }
  [[nodiscard]] constexpr bool is_null() const noexcept { return addr_ == 0; }
 
  [[nodiscard]] expected<T *, remote_load_error> load() const noexcept RELOCO_LIFETIMEBOUND {
    if (addr_ == 0)
      return unexpected(remote_load_error::null_address);
    if (scratch_.size() < sizeof(T))
      return unexpected(remote_load_error::scratch_too_small);
    if (reinterpret_cast<uintptr_t>(scratch_.data()) % alignof(T) != 0)
      return unexpected(remote_load_error::scratch_misaligned);
    if (!space_)
      return unexpected(remote_load_error::invalid_address_space);
 
    auto *out_ptr = static_cast<T *>(static_cast<void *>(scratch_.data()));
    if (!space_.read_bytes(addr_, out_ptr, sizeof(T)))
      return unexpected(remote_load_error::read_failed);
    return out_ptr;
  }
 
  [[nodiscard]] constexpr address_space_ref space() const noexcept { return space_; }
  [[nodiscard]] constexpr symbol_resolver_ref resolver() const noexcept { return resolver_; }
  [[nodiscard]] constexpr symbol_resolution_context &symbol_context() const noexcept RELOCO_LIFETIMEBOUND {
    return *symbol_context_;
  }
 
private:
  uintptr_t addr_{0};
  address_space_ref space_{};
  symbol_resolver_ref resolver_{};
  span<std::byte> scratch_{};
  value_ptr<symbol_resolution_context> symbol_context_{};
};
 
template <typename T> struct formatter<remote_diag_ref<T>> {
  microfmt::string_view spec_{""};
 
  constexpr void parse(format_parse_context &ctx) noexcept { spec_ = ctx.spec(); }
 
  void format(const remote_diag_ref<T> &view, const sink &out) const noexcept {
    if (view.is_null()) {
      out.write("(null)");
      return;
    }
 
    auto staged = view.load();
    if (!staged) {
      format_remote_fault(out, view.address(), view.resolver(), view.symbol_context());
      return;
    }
 
    formatter<T> elem_fmt;
    format_parse_context pctx(spec_);
    elem_fmt.parse(pctx);
    elem_fmt.format(**staged, out);
  }
};
 
} // namespace microfmt