elf_enumerator.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 "../microfmt.hpp"
#include "../reloco.hpp"
#include <cstdint>
#include <string_view>
#include <type_traits>
#include <utility>
 
namespace microfmt {
 
template <typename Tag> struct elf_image_enumerator_traits;
template <size_t MaxImages> class multi_elf_registry_context;
template <size_t MaxImages = 16> struct multi_elf_registry_tag {};
 
// ============================================================================
// ELF Image Record with EXIDX and Module Boundaries
// ============================================================================
 
struct RELOCO_POINTER elf_image_info {
  microfmt::string_view image_name{""};
  uintptr_t load_base{0};
  uintptr_t image_size{0};
 
  uintptr_t exidx_start{0};
  uintptr_t exidx_end{0};
 
  uintptr_t debug_frame_start{0};
  uintptr_t debug_frame_end{0};
 
  [[nodiscard]] constexpr bool contains(uintptr_t addr) const noexcept {
    return addr >= load_base && addr < (load_base + image_size);
  }
 
  [[nodiscard]] constexpr bool has_exidx() const noexcept { return exidx_start != 0 && exidx_end > exidx_start; }
 
  [[nodiscard]] constexpr bool has_debug_frame() const noexcept {
    return debug_frame_start != 0 && debug_frame_end > debug_frame_start;
  }
};
 
// ============================================================================
// Type-Erased ELF Image Enumerator Handle
// ============================================================================
 
class MICROFMT_API_CLASS RELOCO_POINTER elf_image_enumerator_ref {
public:
  struct vtable {
    bool (*enumerate)(const void *ctx, span<elf_image_info> out_buffer, size_t &out_count) noexcept = nullptr;
    bool (*find_by_pc)(const void *ctx, uintptr_t pc, elf_image_info &out_info) noexcept = nullptr;
  };
 
  constexpr elf_image_enumerator_ref() noexcept = default;
 
  template <typename Tag, typename Context, typename Traits = elf_image_enumerator_traits<Tag>,
            std::enable_if_t<std::is_convertible_v<const Context *, const typename Traits::context_type *>, int> = 0>
  constexpr elf_image_enumerator_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 elf_image_enumerator_ref(Tag, Context &&) = delete;
 
  template <typename Tag, typename Context, typename Traits = elf_image_enumerator_traits<Tag>>
  [[nodiscard]] static constexpr elf_image_enumerator_ref make(const Context &ctx RELOCO_LIFETIMEBOUND) noexcept {
    return elf_image_enumerator_ref(Tag{}, ctx);
  }
 
  template <typename Tag, typename Context, std::enable_if_t<!std::is_lvalue_reference_v<Context>, int> = 0>
  static elf_image_enumerator_ref make(Context &&) = delete;
 
  [[nodiscard]] bool enumerate(span<elf_image_info> out_buffer, size_t &out_count) const noexcept {
    if (vtbl_ == nullptr)
      return false;
    return vtbl_->enumerate(ctx_.get(), out_buffer, out_count);
  }
 
  [[nodiscard]] bool find_by_pc(uintptr_t pc, elf_image_info &out_info) const noexcept {
    if (vtbl_ == nullptr)
      return false;
    return vtbl_->find_by_pc(ctx_.get(), pc, out_info);
  }
 
  [[nodiscard]] constexpr explicit operator bool() const noexcept { return vtbl_ != nullptr; }
 
private:
  template <typename Tag>
  static constexpr vtable s_vtbl{
      [](const void *context, span<elf_image_info> buffer, size_t &count) noexcept {
        using context_type = typename elf_image_enumerator_traits<Tag>::context_type;
        const auto &typed_context = *static_cast<const context_type *>(context);
        return elf_image_enumerator_traits<Tag>::enumerate(value_ref<const context_type>(typed_context), buffer, count);
      },
      [](const void *context, uintptr_t pc, elf_image_info &info) noexcept {
        using context_type = typename elf_image_enumerator_traits<Tag>::context_type;
        const auto &typed_context = *static_cast<const context_type *>(context);
        return elf_image_enumerator_traits<Tag>::find_by_pc(value_ref<const context_type>(typed_context), pc, info);
      }};
 
  value_ptr<const void> ctx_{};
  const vtable *vtbl_{nullptr};
};
 
template <typename Tag> class RELOCO_OWNER elf_image_enumerator {
public:
  using traits_type = elf_image_enumerator_traits<Tag>;
  using context_type = typename traits_type::context_type;
 
  constexpr explicit elf_image_enumerator(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 elf_image_enumerator_ref ref() const & noexcept RELOCO_LIFETIMEBOUND {
    return elf_image_enumerator_ref(Tag{}, context_);
  }
 
  [[nodiscard]] explicit constexpr operator elf_image_enumerator_ref() const & noexcept RELOCO_LIFETIMEBOUND {
    return ref();
  }
 
  value_ref<context_type> context() && = delete;
  value_ref<const context_type> context() const && = delete;
  elf_image_enumerator_ref ref() const && = delete;
  operator elf_image_enumerator_ref() const && = delete;
 
private:
  context_type context_;
};
 
// ============================================================================
// Concrete Fixed-Capacity Multi-ELF Registry Context (Zero Allocation)
// ============================================================================
 
template <size_t MaxImages> class RELOCO_OWNER multi_elf_registry_context {
public:
  constexpr multi_elf_registry_context() noexcept = default;
 
  constexpr bool register_image(const elf_image_info &info) noexcept {
    if (image_count_ >= MaxImages)
      return false;
    RELOCO_BEGIN_UNSAFE_BUFFER_USAGE;
 
    images_[image_count_++] = info;
 
    RELOCO_END_UNSAFE_BUFFER_USAGE;
 
    return true;
  }
 
  [[nodiscard]] constexpr bool enumerate(span<elf_image_info> out_buffer, size_t &out_count) const noexcept {
    size_t copy_count = (image_count_ < out_buffer.size()) ? image_count_ : out_buffer.size();
    for (size_t i = 0; i < copy_count; ++i) {
      RELOCO_BEGIN_UNSAFE_BUFFER_USAGE;
 
      out_buffer[i] = images_[i];
 
      RELOCO_END_UNSAFE_BUFFER_USAGE;
    }
    out_count = copy_count;
    return true;
  }
 
  [[nodiscard]] constexpr bool find_by_pc(uintptr_t pc, elf_image_info &out_info) const noexcept {
    RELOCO_BEGIN_UNSAFE_BUFFER_USAGE;
 
    for (size_t i = 0; i < image_count_; ++i) {
      if (images_[i].contains(pc)) {
        out_info = images_[i];
        return true;
      }
    }
 
    RELOCO_END_UNSAFE_BUFFER_USAGE;
 
    return false;
  }
 
  [[nodiscard]] constexpr size_t size() const noexcept { return image_count_; }
 
private:
  elf_image_info images_[MaxImages]{};
  size_t image_count_{0};
};
 
template <size_t MaxImages> struct elf_image_enumerator_traits<multi_elf_registry_tag<MaxImages>> {
  using context_type = multi_elf_registry_context<MaxImages>;
 
  static bool enumerate(value_ref<const context_type> context, span<elf_image_info> buffer, size_t &count) noexcept {
    return context->enumerate(buffer, count);
  }
 
  static bool find_by_pc(value_ref<const context_type> context, uintptr_t pc, elf_image_info &info) noexcept {
    return context->find_by_pc(pc, info);
  }
};
 
} // namespace microfmt