kit

arch.h (23425B)

---

 #ifndef KIT_INTERNAL_ARCH_H
 #define KIT_INTERNAL_ARCH_H
 
 #include <kit/arch.h>
 #include <kit/compile.h>
 #include <kit/disasm.h>
 
 #include "abi/abi.h"
 #include "arch/mc.h"
 #include "cg/cgtarget.h"
 #include "core/core.h"
 #include "obj/obj.h"
 
 /* Generic ArchImpl.register_at body: adapt a per-arch register_iter_get (which
  * yields a DWARF index + a C-string name) into the public KitArchReg out
  * struct. Each arch's register_at is a one-line wrapper delegating here with
  * its own iter_get, so the conversion lives in exactly one place. */
 static inline int arch_register_at_public(uint32_t idx, KitArchReg* out,
                                           int (*iter_get)(uint32_t, uint32_t*,
                                                           const char**)) {
   const char* nm = NULL;
   int rc;
   if (!out) return 1;
   rc = iter_get(idx, &out->dwarf_idx, &nm);
   if (rc == 0) out->name = kit_slice_cstr(nm);
   return rc;
 }
 
 typedef struct AsmDriver AsmDriver;
 
 typedef struct ArchAsm ArchAsm;
 struct ArchAsm {
   void (*insn)(ArchAsm*, AsmDriver*, Sym mnemonic);
   void (*destroy)(ArchAsm*);
 };
 
 /* ---- Disassembler hook ----
  * Bytes -> records, not frontend-driven lowering, so this is a separate
  * hook from CgTarget/MCEmitter. The internal implementation may share
  * encoding tables with the per-arch backend (sequencing concern, not an
  * interface concern). Constructed for c->target.
  *
  * arch_disasm_decode returns the number of bytes consumed, or 0 if input
  * is too short or undecodable (in which case the public iterator advances
  * by the arch's minimum unit). ArchDisasm owns the mnemonic / operands /
  * annotation string buffers placed into *out; they are valid until the
  * next decode or arch_disasm_free, whichever comes first. */
 typedef struct ArchDisasm ArchDisasm;
 struct ArchDisasm {
   u32 (*decode)(ArchDisasm*, const u8* bytes, size_t len, u64 vaddr,
                 KitInsn* out);
   void (*destroy)(ArchDisasm*);
 };
 
 #define KIT_DECODE_MAX_OPERANDS 6u
 
 typedef enum KitDecodeFlag {
   KIT_DECODE_TERMINATOR = 1u << 0,
   KIT_DECODE_BRANCH = 1u << 1,
   KIT_DECODE_CALL = 1u << 2,
   KIT_DECODE_RET = 1u << 3,
   KIT_DECODE_MEMORY = 1u << 4,
   KIT_DECODE_TRAP = 1u << 5,
 } KitDecodeFlag;
 
 typedef enum KitDecodedOperandKind {
   KIT_DECOP_NONE,
   KIT_DECOP_REG,
   KIT_DECOP_IMM,
   KIT_DECOP_MEM,
   KIT_DECOP_PCREL,
   KIT_DECOP_SYSREG,
 } KitDecodedOperandKind;
 
 typedef struct KitDecodedOperand {
   u8 kind;
   u8 width_bits;
   u16 flags;
   u32 reg;
   u32 index_reg;
   i64 imm;
   u8 scale;
   u8 pad[7];
 } KitDecodedOperand;
 
 typedef struct KitDecodedInsn {
   u64 pc;
   const u8* bytes;
   u8 nbytes;
   u8 noperands;
   u16 flags;
   u32 opcode;      /* Arch-owned stable opcode id. */
   u32 encoding_id; /* Optional row/table id for formatting. */
   KitDecodedOperand operands[KIT_DECODE_MAX_OPERANDS];
   u64 arch[2]; /* Small arch-private payload. */
 } KitDecodedInsn;
 
 typedef struct ArchInsnFormatter ArchInsnFormatter;
 typedef struct KitCg KitCg;
 typedef struct EmuCPUState EmuCPUState;
 typedef struct EmuLiftCtx EmuLiftCtx;
 typedef struct EmuProcess EmuProcess;
 typedef struct EmuThread EmuThread;
 struct ArchInsnFormatter {
   KitStatus (*format)(ArchInsnFormatter*, const KitDecodedInsn*, KitInsn* out);
   void (*destroy)(ArchInsnFormatter*);
 };
 
 typedef struct ArchDecodeOps {
   u8 min_insn_len;
   u8 max_insn_len;
 
   KitStatus (*decode_one)(Compiler*, const u8* bytes, size_t len, u64 pc,
                           KitDecodedInsn* out);
   KitStatus (*decode_block)(Compiler*, const u8* bytes, size_t len, u64 pc,
                             KitDecodedInsn* out, u32 cap, u32* n_out);
 
   ArchInsnFormatter* (*formatter_new)(Compiler*);
   KitStatus (*format)(ArchInsnFormatter*, const KitDecodedInsn*, KitInsn* out);
   void (*formatter_destroy)(ArchInsnFormatter*);
 } ArchDecodeOps;
 
 typedef struct ArchEmuOps {
   EmuCPUState* (*cpu_new)(Compiler*, u64 initial_pc, u64 initial_sp);
   KitCgTypeId (*block_fn_type)(Compiler*);
   KitStatus (*lift_block)(Compiler*, KitCg*, const KitDecodedInsn*, u32 n,
                           const EmuLiftCtx*);
   u64 (*get_gpr)(EmuThread*, u32 reg);
   void (*set_gpr)(EmuThread*, u32 reg, u64 value);
   u64 (*get_syscall_no)(EmuThread*);
   u64 (*get_syscall_arg)(EmuThread*, u32 index);
   void (*set_syscall_result)(EmuThread*, u64 value);
   u64 (*get_sp)(EmuThread*);
   void (*set_sp)(EmuThread*, u64 value);
   u64 (*get_tp)(EmuThread*);
   void (*set_tp)(EmuThread*, u64 value);
   u64 (*signal_context_size)(EmuProcess*, EmuThread*);
   KitStatus (*save_signal_context)(EmuProcess*, EmuThread*, u8* dst, u64 size);
   KitStatus (*restore_signal_context)(EmuProcess*, EmuThread*, const u8* src,
                                       u64 size);
   KitStatus (*set_signal_handler_args)(EmuProcess*, EmuThread*, int signo,
                                        u64 siginfo, u64 ucontext);
   u64 (*signal_stack_align)(EmuProcess*, EmuThread*);
   u32 import_thunk_size;
   KitStatus (*emit_import_thunk)(EmuProcess*, u64 thunk_vaddr);
   void* (*resolve_runtime_helper)(void* emu, KitSlice name);
 } ArchEmuOps;
 
 typedef struct LinkArchDesc LinkArchDesc;
 
 typedef struct ArchDwarfOps {
   /* DWARF .debug_line minimum instruction length and maximum operations per
    * instruction. Fixed-width ISAs normally use their instruction width; x86_64
    * uses 1 because line-program PC advances are byte granular. */
   u8 min_inst_len;
   u8 max_ops_per_inst;
   u8 pad[2];
 } ArchDwarfOps;
 
 typedef struct ArchTargetFeature {
   const char* name;
 } ArchTargetFeature;
 
 #define ARCH_DBG_MAX_TRAP_BYTES 8u
 #define ARCH_DBG_MAX_INSN_BYTES 15u
 
 typedef struct ArchDbgInsn {
   u64 pc;
   u8 bytes[ARCH_DBG_MAX_INSN_BYTES];
   u32 len;
 } ArchDbgInsn;
 
 typedef struct ArchDbgOps {
   u32 min_insn_len;
   u32 max_insn_len;
 
   KitStatus (*breakpoint_patch)(u8* out, u32 cap, u32* len_out);
   u64 (*breakpoint_addr_from_fault_pc)(u64 fault_pc);
 
   KitStatus (*decode_insn)(const u8* bytes, u32 len, u64 pc, ArchDbgInsn* out);
   KitStatus (*build_displaced_shim)(const ArchDbgInsn* insn,
                                     void* scratch_write, u64 scratch_runtime,
                                     u32 scratch_cap, u32* sentinel_off,
                                     u64* fallthrough_pc);
   int (*is_call)(const ArchDbgInsn* insn);
   KitStatus (*direct_call_target)(const ArchDbgInsn* insn, u64* target_out);
   KitStatus (*direct_jump_target)(const ArchDbgInsn* insn, u64* target_out);
   KitStatus (*link_register_return_address)(const KitUnwindFrame* frame,
                                             u64* target_out);
 } ArchDbgOps;
 
 /* ---- textual-assembly operand syntax (printer <-> parser) ----------------
  *
  * How a relocated operand is spelled in `cc -S` output. The shape selects
  * which part of the disassembled operand text the symbolizer rewrites; the
  * prefix/suffix are the relocation-modifier spelling for the target object
  * format (e.g. aarch64 ELF `:lo12:sym` is a prefix; Mach-O `sym@PAGEOFF` is a
  * suffix). At most one of prefix/suffix is non-empty for a given (kind, fmt).
  * This is the inverse of the arch assembler's operand reloc-modifier parser. */
 typedef enum ArchRelocSurg {
   ARCH_RELOC_SURG_NONE = 0, /* not symbolizable here; keep numeric operand */
   ARCH_RELOC_SURG_TAIL, /* replace last comma component (or whole operand) */
   ARCH_RELOC_SURG_MEM,  /* rewrite the offset inside [...]  (aarch64 ldst) */
   ARCH_RELOC_SURG_RIP,  /* insert sym before disp(%rip)     (x86-64 RIP-rel) */
   /* RISC-V `%pcrel_lo`/`%lo` low-half operand. A single reloc kind covers two
    * disassembled shapes: a register-immediate ADDI (printed as `mv rd, rs`
    * when the immediate is 0) where the modifier becomes a new trailing
    * operand (`mv rd, rs, %pcrel_lo(L)`, which the assembler folds back into
    * ADDI), and a `disp(base)` load/store where the modifier replaces the
    * displacement (`%pcrel_lo(L)(base)`). The shape is picked from the operand
    * text: a trailing `(...)` group selects the memory form. */
   ARCH_RELOC_SURG_RV_LO12,
 } ArchRelocSurg;
 
 typedef struct ArchRelocOperand {
   ArchRelocSurg surg;
   const char* prefix; /* e.g. ":lo12:" (ELF); "" if none */
   const char* suffix; /* e.g. "@PAGEOFF" / "@GOTPCREL"; "" if none */
   /* Added to the relocation's stored addend before spelling `sym[+/-N]`. Undoes
    * an instruction-encoding bias so the printed offset is the *symbol* offset:
    * 0 for aarch64; +4 for x86-64 rel32 (PC32/PLT32/GOTPCREL store addend-4). */
   int addend_bias;
   /* hi/lo anchor pairing (RISC-V `%pcrel_hi`/`%pcrel_lo`). A high-half reloc
    * (AUIPC `%pcrel_hi(sym)`) sets `emit_anchor` so the symbolizer defines a
    * unique local label at this instruction. The paired low-half reloc
    * (`%pcrel_lo`) sets `ref_anchor`: its operand references that synthesized
    * anchor label (the nearest preceding anchor) instead of the reloc's own
    * symbol — matching the RISC-V ABI, where `%pcrel_lo` names the AUIPC's
    * label, not the target symbol. Other arches leave both 0. */
   u8 emit_anchor;
   u8 ref_anchor;
 } ArchRelocOperand;
 
 typedef struct ArchAsmOps {
   /* Map (reloc kind, target object format) to the operand syntax the cc -S
    * symbolizer must emit (and that this arch's .s parser accepts back).
    * Returns 1 and fills *out when the kind is symbolizable for fmt; 0
    * otherwise (printer keeps the numeric operand). The symbolizer picks the
    * surgery site from the operand text (an `(%rip)` operand always uses RIP
    * surgery regardless of `out->surg`), so a single reloc kind can serve both
    * a branch target and a RIP-relative memory operand (x86-64 R_PC32). */
   int (*reloc_operand)(u16 reloc_kind, KitObjFmt fmt, ArchRelocOperand* out);
   /* 1 if `mnemonic` is an intra-section local branch whose un-relocated
    * numeric target the symbolizer should replace with a synthesized label
    * (aarch64 b/b.cc/cbz/...; x86-64 jmp/jcc). Calls are excluded — they carry
    * relocations. NULL hook = no local-branch symbolization for the arch. */
   int (*is_local_branch)(KitSlice mnemonic);
   /* Fuse a relocation that the disassembler renders as a 2-instruction pair
    * back into a single relocated pseudo-instruction line. RISC-V R_RV_CALL
    * sits on an AUIPC whose JALR partner carries no reloc; the canonical `.s`
    * spelling is a single `call`/`tail sym`. When `kind` names such a reloc,
    * the hook returns 1 and sets *mnemonic_out to the fused mnemonic — the
    * symbolizer then emits "<mnemonic>\t<sym[+addend]>" in place of BOTH
    * instructions (skipping the partner). `pair_mnemonic`/`pair_ops` are the
    * SECOND instruction's disassembled text (the JALR), used to disambiguate
    * (e.g. call vs tail by its link register). Returns 0 to leave the pair
    * un-fused (per-instruction operand symbolization applies). NULL hook = no
    * pair fusion for the arch. */
   int (*reloc_call_pair)(u16 reloc_kind, KitSlice pair_mnemonic,
                          KitSlice pair_ops, const char** mnemonic_out);
   /* 1 if this arch tags function symbols with a low-bit (LSB) ISA-state
    * marker, the way the 32-bit ARM EABI distinguishes Thumb entry points: a
    * defined function symbol carries value|1, the `.thumb_func` directive marks
    * the next/named label as such, and `.size SYM, . - SYM` masks that bit back
    * off before differencing. The standalone assembler keys all of this Thumb
    * bookkeeping off this flag instead of switching on arch identity. 0 for
    * every arch with no ISA-state symbol bit (aarch64, x86-64, RISC-V, …),
    * which yields the plain "value = offset, no LSB" behavior. */
   unsigned thumb_function_symbols : 1;
 } ArchAsmOps;
 
 typedef struct ArchImpl {
   /* First field, so `(const CGBackend*)&arch_impl_x` is the arch's backend
    * view. Every machine-code arch is a CGBackend by composition; c_target
    * is a standalone CGBackend with no ArchImpl. */
   CGBackend backend;
 
   KitArchKind kind;
   const char* name;
 
   /* Low-level CgTarget constructor: caller supplies the MCEmitter. Tests use
    * this directly via the cgtarget_new() wrapper; the arch's `backend.make`
    * also calls it after creating an MCEmitter internally. */
   CgTarget* (*cgtarget_new)(Compiler*, ObjBuilder*, MCEmitter*);
   ArchAsm* (*asm_new)(Compiler*);
   ArchDisasm* (*disasm_new)(Compiler*);
   int (*apply_label_fixup)(Compiler*, const ArchLabelFixup*);
 
   const ArchDecodeOps* decode;
   const ArchEmuOps* emu;
   const LinkArchDesc* link;
   const ArchDwarfOps* dwarf;
   const ArchDbgOps* dbg;
   const ArchAsmOps*
       asm_ops; /* textual-asm operand syntax; NULL = keep numeric */
 
   const KitPredefinedMacro* predefined_macros;
   u32 npredefined_macros;
   const ArchTargetFeature* target_features;
   u32 ntarget_features;
   void (*target_feature_defaults)(const Target*, u64* words, u32 nwords);
   KitStatus (*target_feature_apply_isa)(const Target*, KitSlice isa, u64* words,
                                         u32 nwords);
   /* Apply a CPU/core selector (-mcpu=) onto the feature words, the same way
    * target_feature_apply_isa applies -march=. A CPU typically pins an ISA
    * profile plus extensions (e.g. ARM cortex-m4 -> armv7e-m + dsp). Returns
    * KIT_OK on success, KIT_UNSUPPORTED for an unknown CPU. NULL hook means the
    * arch has no CPU axis (arch_target_feature_apply_cpu no-ops to KIT_OK). */
   KitStatus (*target_feature_apply_cpu)(const Target*, KitSlice cpu, u64* words,
                                         u32 nwords);
 
   const char* (*register_name)(uint32_t dwarf_idx);
   int (*register_index)(const char* name, uint32_t* idx_out);
   uint32_t (*register_count)(void);
   int (*register_at)(uint32_t idx, KitArchReg* out);
 
   /* DWARF CFI defaults per psABI, used by the CIE the .eh_frame
    * producer emits. cfi_cfa_init_{reg,offset} describe the at-entry
    * CFA state — before any cfi_def_cfa override — so an unwinder can
    * recover the caller's stack pointer at the very first instruction. */
   u32 cfi_return_addr_reg;
   i32 cfi_code_align_factor;
   i32 cfi_data_align_factor;
   u32 cfi_cfa_init_reg;
   i32 cfi_cfa_init_offset;
 
   /* === Generic-layer capability queries =====================================
    * Let generic (non-backend) code in src/cg and src/link decide by capability
    * instead of by arch identity (target.arch == KIT_ARCH_*). Each backend
    * declares its answer here once. */
 
   /* Backend codegen capability bitmask (KitCgBackendFeatureFlag). Per-arch
    * constant: the x86 family sets UNALIGNED_MEMORY|RED_ZONE|SIMD, every other
    * arch sets STRICT_ALIGNMENT. Read via kit_cg_target_backend_features. */
   u64 backend_features;
 
   /* Largest power-of-two byte width this arch lowers as a lock-free native
    * atomic: 8 for aa64/x64/rv64/wasm, 4 for rv32 (no lr.d/sc.d/amo*.d). The
    * single source of truth for kit_cg_atomic_is_lock_free and the C front-end's
    * __atomic_always_lock_free. */
   u32 atomic_lock_free_max;
 
   /* 1 if call convention `cc` is selectable for this compiler's (arch, os).
    * Today the only convention is KIT_CG_CC_TARGET_C (the target's C ABI); a
    * backend that grows a real variant convention reports it here. May read
    * c->target.os (a property, not arch identity). Read via
    * kit_cg_target_supports_call_conv. */
   int (*supports_call_conv)(const Compiler* c, KitCgCallConv cc);
 
   /* 1 if this arch has a legal lowering for `intrin`. Kept in sync with the
    * backend's IntrinKind lowering switch (x64_intrinsic / aa_intrinsic /
    * rv_intrinsic / wasm_intrinsic). Read via kit_cg_target_supports_intrinsic.
    */
   int (*supports_intrinsic)(const Compiler* c, KitCgIntrinsic intrin);
 
   /* Resolve & validate the float ABI for the target being constructed, given
    * the explicit -mabi string (`abi`, empty for none) and the already-resolved
    * -march feature bits (`feature_words`/`nfeature_words`). On success returns
    * KIT_OK with `spec->float_abi` set to the chosen KitFloatAbi. On a bad/
    * mismatched ABI returns KIT_INVALID and writes a NUL-terminated message into
    * `err` (capacity `errcap`) for the caller to surface as a diagnostic. NULL
    * hook means the arch has no float-ABI axis: leave spec->float_abi at
    * KIT_FLOAT_ABI_DEFAULT (the arch_resolve_float_abi wrapper no-ops). Set for
    * RISC-V (handles rv32 + rv64); read via arch_resolve_float_abi. */
   KitStatus (*resolve_float_abi)(const struct ArchImpl* impl,
                                  KitTargetSpec* spec, const u64* feature_words,
                                  u32 nfeature_words, KitSlice abi, char* err,
                                  size_t errcap);
 
   /* Float-ABI-dependent predefined macros for the resolved target. A single
    * static `predefined_macros` table cannot encode both the soft and the
    * hard-float profiles, yet the preprocessor must agree with the codegen ABI:
    * rt/lib/coro keys on __riscv_flen to decide whether a context switch saves
    * the FP registers, and user code branches on __riscv_float_abi_*. RISC-V
    * sets this hook to emit __riscv_float_abi_{soft,single,double} (plus
    * __riscv_flen / __riscv_fdiv / __riscv_fsqrt for the hard cases) keyed on
    * spec->float_abi, so those macros stay out of the static table. NULL means
    * the arch has no float-ABI axis and its static table is complete. The
    * returned entries are static-lifetime. Read via arch_float_predefines. */
   u32 (*float_predefines)(const struct ArchImpl* impl, const KitTargetSpec* spec,
                           const KitPredefinedMacro** out);
 
   /* Feature-keyed predefined macros for the resolved target, selected from the
    * resolved -march/-mcpu/-mattr feature words (`words`/`nwords`) and the spec
    * (so an arch may also key on spec->float_abi here). The same single-static-
    * table limitation that motivates float_predefines applies to any macro that
    * varies by extension (e.g. ARM's __ARM_ARCH_7M__ vs __ARM_ARCH_7EM__ and
    * __ARM_FEATURE_DSP). An arch must return a STATIC-lifetime table selected
    * among precomputed `static const` tables per discrete config; the returned
    * entries are borrowed. NULL hook means the arch's static `predefined_macros`
    * table is complete. ARM folds its float macros into this hook (and leaves
    * float_predefines NULL) because they share the feature words. Read via
    * arch_feature_predefines. */
   u32 (*feature_predefines)(const struct ArchImpl* impl,
                             const KitTargetSpec* spec, const u64* words,
                             u32 nwords, const KitPredefinedMacro** out);
 } ArchImpl;
 
 const ArchImpl* arch_lookup(KitArchKind);
 const ArchImpl* arch_for_compiler(const Compiler*);
 int arch_target_feature_index(const ArchImpl*, KitSlice name, u32* idx_out);
 void arch_target_feature_defaults(const ArchImpl*, const Target*, u64* words,
                                   u32 nwords);
 KitStatus arch_target_feature_apply_isa(const ArchImpl*, const Target*,
                                         KitSlice isa, u64* words, u32 nwords);
 KitStatus arch_target_feature_apply_cpu(const ArchImpl*, const Target*,
                                         KitSlice cpu, u64* words, u32 nwords);
 
 /* Resolve & validate `spec->float_abi` from the explicit -mabi string and the
  * resolved -march feature bits, dispatching to `impl->resolve_float_abi`. When
  * `impl` is NULL or the arch sets no hook this is a no-op returning KIT_OK and
  * leaving spec->float_abi untouched (KIT_FLOAT_ABI_DEFAULT) — exactly the old
  * "non-RISC-V arches leave the float ABI at default" behavior. On a bad ABI the
  * hook returns KIT_INVALID and fills `err` (NUL-terminated, capacity `errcap`).
  * Header-only thin dispatch: the matching `arch_reloc_*` wrappers live in
  * src/arch/registry.c, but float-ABI resolution runs during target
  * construction (no Compiler yet), so this wrapper takes the ArchImpl directly.
  */
 static inline KitStatus arch_resolve_float_abi(const ArchImpl* impl,
                                                KitTargetSpec* spec,
                                                const u64* feature_words,
                                                u32 nfeature_words, KitSlice abi,
                                                char* err, size_t errcap) {
   if (!impl || !impl->resolve_float_abi) return KIT_OK;
   return impl->resolve_float_abi(impl, spec, feature_words, nfeature_words, abi,
                                  err, errcap);
 }
 
 /* Float-ABI-dependent predefined macros for `spec` (see ArchImpl.float_predefines).
  * Sets *out to a borrowed static-lifetime array and returns its length; 0 (with
  * *out=NULL) when the arch sets no hook. */
 static inline u32 arch_float_predefines(const ArchImpl* impl,
                                         const KitTargetSpec* spec,
                                         const KitPredefinedMacro** out) {
   if (out) *out = NULL;
   if (!impl || !impl->float_predefines) return 0;
   return impl->float_predefines(impl, spec, out);
 }
 
 /* Feature-keyed predefined macros for `spec` + resolved feature `words`/`nwords`
  * (see ArchImpl.feature_predefines). Sets *out to a borrowed static-lifetime
  * array and returns its length; 0 (with *out=NULL) when the arch sets no hook. */
 static inline u32 arch_feature_predefines(const ArchImpl* impl,
                                           const KitTargetSpec* spec,
                                           const u64* words, u32 nwords,
                                           const KitPredefinedMacro** out) {
   if (out) *out = NULL;
   if (!impl || !impl->feature_predefines) return 0;
   return impl->feature_predefines(impl, spec, words, nwords, out);
 }
 
 /* Spelling for a relocated operand in `cc -S` text, for the compiler's target
  * arch+format. Returns 1 and fills *out when symbolizable, 0 to keep numeric
  * (also when the arch provides no asm_ops). Thin dispatch over ArchAsmOps. */
 int arch_reloc_operand(const Compiler* c, u16 reloc_kind,
                        ArchRelocOperand* out);
 
 /* 1 if `mnemonic` is an intra-section local branch for the compiler's target
  * arch (so cc -S synthesizes a label at its un-relocated target). 0 when the
  * arch has no asm_ops/is_local_branch hook. */
 int arch_is_local_branch(const Compiler* c, KitSlice mnemonic);
 
 /* 1 if `reloc_kind` names a 2-instruction call pair the symbolizer should fuse
  * into a single pseudo line (RISC-V R_RV_CALL -> `call`/`tail`), with
  * *mnemonic_out set to the fused mnemonic. `pair_*` are the partner (second)
  * instruction's disassembled text. 0 when not fused / no hook. Thin dispatch
  * over ArchAsmOps.reloc_call_pair. */
 int arch_reloc_call_pair(const Compiler* c, u16 reloc_kind,
                          KitSlice pair_mnemonic, KitSlice pair_ops,
                          const char** mnemonic_out);
 
 ArchDisasm* arch_disasm_new(Compiler*);
 u32 arch_disasm_decode(ArchDisasm*, const u8* bytes, size_t len, u64 vaddr,
                        KitInsn* out);
 void arch_disasm_free(ArchDisasm*);
 KitStatus arch_decode_one(Compiler*, const u8* bytes, size_t len, u64 pc,
                           KitDecodedInsn* out);
 KitStatus arch_decode_block(Compiler*, const u8* bytes, size_t len, u64 pc,
                             KitDecodedInsn* out, u32 cap, u32* n_out);
 ArchInsnFormatter* arch_insn_formatter_new(Compiler*);
 KitStatus arch_format_insn(ArchInsnFormatter*, const KitDecodedInsn*,
                            KitInsn* out);
 void arch_insn_formatter_free(ArchInsnFormatter*);
 
 #endif