dwarf_abi.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 "dwarf_registers.hpp"
#include "gdb_registers.hpp"
#include "register_context.hpp"
#include <cstddef>
#include <cstdint>
#include <type_traits>
#include <utility>
 
namespace microfmt {
 
// ============================================================================
// ARM / Thumb (32-bit EABI)
// ============================================================================
 
struct MICROFMT_API_CLASS arm_abi_traits {
  using register_type = uint32_t;
  using register_traits = dwarf::arm32::register_traits;
  using gdb_register_traits = gdb::register_traits<gdb::tags::arm32>;
  static constexpr size_t pointer_size = 4;
 
  static constexpr uint32_t sp_reg = dwarf::arm32::sp; // R13
  static constexpr uint32_t lr_reg = dwarf::arm32::lr; // R14
  static constexpr uint32_t ra_reg = lr_reg;
  static constexpr uint32_t fp_reg = dwarf::arm32::fp; // R11 (Traditional ARM)
 
  // Frame pointer layout offsets relative to current FP, for @ref
  // fp_unwinder_tag's naive FP-chain walking (as opposed to the
  // EXIDX-bytecode-driven `arm_exidx_unwinder_tag`, which needs no static
  // offset assumption at all).
  //
  // These describe GCC's *ARM (A32)* `-O0` prologue convention only:
  // `push {..., fp, lr}` (any earlier callee-saved scratch registers, e.g.
  // r4, may also be pushed) followed by `add fp, sp, <#pushed-bytes-1..2
  // registers>`, which always lands `fp` exactly on the saved-LR word
  // (`fp+0`), with the saved caller FP immediately below it (`fp-4`) --
  // verified against real arm-linux-gnueabi-gcc output; this holds
  // regardless of how many extra registers are pushed alongside {fp, lr}
  // since fp/lr are always the last two (adjacent, ascending-register-number
  // order) entries of the push list.
  //
  // Thumb/Thumb-2 mode (R7 frame pointer) does NOT follow a fixed offset:
  // GCC emits `mov r7, sp` (or `add r7, sp, #0`) *after* allocating the
  // local-variable area when any extra scratch register is pushed alongside
  // {r7, lr}, so r7 ends up pointing at the locals base rather than at the
  // {r7, lr} pair, and the true offset then depends on the (per-function,
  // frame-size-dependent) local allocation size. There is no single constant
  // that describes this, so `fp_unwinder_tag<arm_abi_traits>` is reliable
  // only while executing in ARM (A32) state; treat Thumb-state fallback
  // results as unreliable (prefer `arm_exidx_unwinder_tag`, which decodes
  // the real bytecode/CFI instead of guessing a fixed layout).
  static constexpr ptrdiff_t fp_slot_offset = -4; // Saved FP is at [FP - 4]
  static constexpr ptrdiff_t ra_slot_offset = 0;  // Saved LR is at [FP + 0]
 
  [[nodiscard]] static constexpr bool is_return_address_register(uint32_t reg) noexcept { return reg == lr_reg; }
  [[nodiscard]] static constexpr bool is_frame_pointer_register(uint32_t reg) noexcept {
    return reg == fp_reg || reg == 7; // Support both R11 and R7 (Thumb frame pointer)
  }
 
  [[nodiscard]] static constexpr uintptr_t normalize_pc(uintptr_t raw_ra) noexcept {
    // Clear the Thumb-2 mode bit (bit 0)
    return raw_ra & ~static_cast<uintptr_t>(1);
  }
 
  [[nodiscard]] static uint32_t resolve_fp_reg(register_context_ref reg_ctx) noexcept {
    uint32_t cpsr = 0;
    if (reg_ctx && reg_ctx.read(dwarf::arm32::cpsr, cpsr)) {
      constexpr uint32_t thumb_bit = 0x20U; // CPSR.T
      return (cpsr & thumb_bit) != 0U ? 7U : fp_reg;
    }
    return fp_reg;
  }
 
  [[nodiscard]] static bool resolve_frame_slot_offsets(register_context_ref reg_ctx, ptrdiff_t &out_fp_slot_offset,
                                                       ptrdiff_t &out_ra_slot_offset) noexcept {
    uint32_t cpsr = 0;
    if (reg_ctx && reg_ctx.read(dwarf::arm32::cpsr, cpsr)) {
      constexpr uint32_t thumb_bit = 0x20U; // CPSR.T
      if ((cpsr & thumb_bit) != 0U)
        return false;
    }
    out_fp_slot_offset = fp_slot_offset;
    out_ra_slot_offset = ra_slot_offset;
    return true;
  }
};
 
// ============================================================================
// AArch64 (64-bit ARM)
// ============================================================================
 
struct MICROFMT_API_CLASS aarch64_abi_traits {
  using register_type = uint64_t;
  using register_traits = dwarf::aarch64::register_traits;
  using gdb_register_traits = gdb::register_traits<gdb::tags::aarch64>;
  static constexpr size_t pointer_size = 8;
 
  static constexpr uint32_t sp_reg = dwarf::aarch64::sp; // X31 / SP
  static constexpr uint32_t ra_reg = dwarf::aarch64::lr; // X30 (LR)
  static constexpr uint32_t fp_reg = dwarf::aarch64::fp; // X29 (FP)
 
  static constexpr ptrdiff_t fp_slot_offset = 0; // Saved FP is at [FP + 0]
  static constexpr ptrdiff_t ra_slot_offset = 8; // Saved LR is at [FP + 8]
 
  [[nodiscard]] static constexpr bool is_return_address_register(uint32_t reg) noexcept { return reg == ra_reg; }
  [[nodiscard]] static constexpr bool is_frame_pointer_register(uint32_t reg) noexcept { return reg == fp_reg; }
 
  [[nodiscard]] static constexpr uintptr_t normalize_pc(uintptr_t raw_ra) noexcept {
    if constexpr (sizeof(uintptr_t) < sizeof(uint64_t))
      return raw_ra & ~static_cast<uintptr_t>(1);
 
    const uint64_t pc = static_cast<uint64_t>(raw_ra) & ~UINT64_C(1);
 
    // Check if it's a kernel-space address (higher-half check: top bit set)
    const bool is_kernel = (pc & (UINT64_C(1) << 63)) != 0;
 
    if (is_kernel) {
      return static_cast<uintptr_t>((pc & UINT64_C(0x0000FFFFFFFFFFFF)) | UINT64_C(0xFFFF000000000000));
    } else {
      // User-space PAC masking
      return static_cast<uintptr_t>(pc & UINT64_C(0x0000FFFFFFFFFFFF));
    }
  }
};
 
// ============================================================================
// RISC-V 32-bit (RV32)
// ============================================================================
 
struct MICROFMT_API_CLASS riscv32_abi_traits {
  using register_type = uint32_t;
  using register_traits = dwarf::riscv::register_traits;
  using gdb_register_traits = gdb::register_traits<gdb::tags::riscv32>;
  static constexpr size_t pointer_size = 4;
 
  static constexpr uint32_t sp_reg = dwarf::riscv::sp; // x2
  static constexpr uint32_t ra_reg = dwarf::riscv::ra; // x1
  static constexpr uint32_t fp_reg = dwarf::riscv::fp; // x8 (s0/fp)
 
  // Standard RISC-V convention (saves s0/fp and ra in the frame):
  // [FP + 0] -> saved frame pointer (s0 / x8)
  // [FP + 4] -> saved return address (ra / x1)
  static constexpr ptrdiff_t fp_slot_offset = 0;
  static constexpr ptrdiff_t ra_slot_offset = 4;
 
  [[nodiscard]] static constexpr bool is_return_address_register(uint32_t reg) noexcept { return reg == ra_reg; }
  [[nodiscard]] static constexpr bool is_frame_pointer_register(uint32_t reg) noexcept { return reg == fp_reg; }
 
  [[nodiscard]] static constexpr uintptr_t normalize_pc(uintptr_t raw_ra) noexcept { return raw_ra; }
};
 
// ============================================================================
// RISC-V 64-bit (RV64)
// ============================================================================
 
struct MICROFMT_API_CLASS riscv64_abi_traits {
  using register_type = uint64_t;
  using register_traits = dwarf::riscv::register_traits;
  using gdb_register_traits = gdb::register_traits<gdb::tags::riscv64>;
  static constexpr size_t pointer_size = 8;
 
  static constexpr uint32_t sp_reg = dwarf::riscv::sp; // x2
  static constexpr uint32_t ra_reg = dwarf::riscv::ra; // x1
  static constexpr uint32_t fp_reg = dwarf::riscv::fp; // x8 (s0/fp)
 
  static constexpr ptrdiff_t fp_slot_offset = 0; // Saved FP (s0) is at [FP + 0]
  static constexpr ptrdiff_t ra_slot_offset = 8; // Saved RA is at [FP + 8]
 
  [[nodiscard]] static constexpr bool is_return_address_register(uint32_t reg) noexcept { return reg == ra_reg; }
  [[nodiscard]] static constexpr bool is_frame_pointer_register(uint32_t reg) noexcept { return reg == fp_reg; }
 
  [[nodiscard]] static constexpr uintptr_t normalize_pc(uintptr_t raw_ra) noexcept { return raw_ra; }
};
 
// ============================================================================
// x86 (32-bit IA-32)
// ============================================================================
 
struct MICROFMT_API_CLASS x86_abi_traits {
  using register_type = uint32_t;
  using register_traits = dwarf::x86::register_traits;
  using gdb_register_traits = gdb::register_traits<gdb::tags::x86>;
  static constexpr size_t pointer_size = 4;
 
  static constexpr uint32_t sp_reg = dwarf::x86::sp; // ESP (Register 4)
  static constexpr uint32_t ra_reg = dwarf::x86::pc; // EIP (Register 8)
  static constexpr uint32_t fp_reg = dwarf::x86::fp; // EBP (Register 5)
 
  // On 32-bit x86:
  // [EBP + 0] -> stores the saved previous EBP (Frame Pointer)
  // [EBP + 4] -> stores the return address (EIP)
  static constexpr ptrdiff_t fp_slot_offset = 0;
  static constexpr ptrdiff_t ra_slot_offset = 4;
 
  [[nodiscard]] static constexpr bool is_return_address_register(uint32_t reg) noexcept { return reg == ra_reg; }
  [[nodiscard]] static constexpr bool is_frame_pointer_register(uint32_t reg) noexcept { return reg == fp_reg; }
 
  [[nodiscard]] static constexpr uintptr_t normalize_pc(uintptr_t raw_ra) noexcept { return raw_ra; }
};
 
// ============================================================================
// x86-64 (AMD64 / x86_64)
// ============================================================================
 
struct MICROFMT_API_CLASS x86_64_abi_traits {
  using register_type = uint64_t;
  using register_traits = dwarf::x86_64::register_traits;
  using gdb_register_traits = gdb::register_traits<gdb::tags::x86_64>;
  static constexpr size_t pointer_size = 8;
 
  static constexpr uint32_t sp_reg = dwarf::x86_64::sp; // RSP (Register 7)
  static constexpr uint32_t ra_reg = dwarf::x86_64::pc; // RIP (Register 16)
  static constexpr uint32_t fp_reg = dwarf::x86_64::fp; // RBP (Register 6)
 
  static constexpr ptrdiff_t fp_slot_offset = 0; // Saved RBP is at [RBP + 0]
  static constexpr ptrdiff_t ra_slot_offset = 8; // Saved RIP is at [RBP + 8]
 
  [[nodiscard]] static constexpr bool is_return_address_register(uint32_t reg) noexcept { return reg == ra_reg; }
  [[nodiscard]] static constexpr bool is_frame_pointer_register(uint32_t reg) noexcept { return reg == fp_reg; }
 
  [[nodiscard]] static constexpr uintptr_t normalize_pc(uintptr_t raw_ra) noexcept { return raw_ra; }
};
 
namespace detail {
 
template <typename AbiTraits, typename = void> struct has_resolve_fp_reg : std::false_type {};
 
template <typename AbiTraits>
struct has_resolve_fp_reg<AbiTraits,
                          std::void_t<decltype(AbiTraits::resolve_fp_reg(std::declval<register_context_ref>()))>>
    : std::true_type {};
 
template <typename AbiTraits, typename = void> struct has_resolve_frame_slot_offsets : std::false_type {};
 
template <typename AbiTraits>
struct has_resolve_frame_slot_offsets<
    AbiTraits, std::void_t<decltype(AbiTraits::resolve_frame_slot_offsets(
                   std::declval<register_context_ref>(), std::declval<ptrdiff_t &>(), std::declval<ptrdiff_t &>()))>>
    : std::true_type {};
 
} // namespace detail
 
template <typename AbiTraits> [[nodiscard]] uint32_t resolve_fp_register(register_context_ref reg_ctx) noexcept {
  if constexpr (detail::has_resolve_fp_reg<AbiTraits>::value) {
    return AbiTraits::resolve_fp_reg(reg_ctx);
  } else {
    return AbiTraits::fp_reg;
  }
}
 
template <typename AbiTraits>
[[nodiscard]] bool resolve_frame_slot_offsets(register_context_ref reg_ctx, ptrdiff_t &out_fp_slot_offset,
                                              ptrdiff_t &out_ra_slot_offset) noexcept {
  if constexpr (detail::has_resolve_frame_slot_offsets<AbiTraits>::value) {
    return AbiTraits::resolve_frame_slot_offsets(reg_ctx, out_fp_slot_offset, out_ra_slot_offset);
  } else {
    out_fp_slot_offset = AbiTraits::fp_slot_offset;
    out_ra_slot_offset = AbiTraits::ra_slot_offset;
    return true;
  }
}
 
template <typename Traits> struct validate_abi_traits {
  static_assert(sizeof(typename Traits::register_type) == Traits::pointer_size,
                "AbiTraits error: register_type size must exactly match pointer_size!");
 
  static_assert(Traits::pointer_size == 4 || Traits::pointer_size == 8,
                "AbiTraits error: pointer_size must be either 4 (32-bit) or 8 (64-bit)!");
 
  static constexpr bool value = true;
};
 
// Enforce validation checks for all built-in traits at compile time
static_assert(validate_abi_traits<arm_abi_traits>::value, "");
static_assert(validate_abi_traits<aarch64_abi_traits>::value, "");
static_assert(validate_abi_traits<riscv32_abi_traits>::value, "");
static_assert(validate_abi_traits<riscv64_abi_traits>::value, "");
static_assert(validate_abi_traits<x86_abi_traits>::value, "");
static_assert(validate_abi_traits<x86_64_abi_traits>::value, "");
 
} // namespace microfmt