kit

native_target.h (52459B)

---

 #ifndef KIT_ARCH_NATIVE_TARGET_H
 #define KIT_ARCH_NATIVE_TARGET_H
 
 #include <string.h>
 
 #include "arch/mc.h"
 #include "cg/cgir.h"
 #include "cg/type.h"
 #include "core/core.h"
 #include "core/slice.h" /* Slice, for resolve_name */
 
 /* NativeTarget is the physical native-emission contract. It is driven after
  * semantic CG has been either direct-lowered by NativeDirectTarget or recorded,
  * optimized, machinized, and allocated. It must not speak in semantic CGLocal
  * ids except where a descriptor is carried for diagnostics or ABI queries. */
 
 typedef u32 NativeFrameSlot;
 #define NATIVE_FRAME_SLOT_NONE 0u
 
 typedef enum NativeFrameSlotKind {
   NATIVE_FRAME_SLOT_LOCAL,
   NATIVE_FRAME_SLOT_PARAM,
   NATIVE_FRAME_SLOT_SPILL,
   NATIVE_FRAME_SLOT_ALLOCA,
   NATIVE_FRAME_SLOT_OUTGOING,
   NATIVE_FRAME_SLOT_SAVE,
 } NativeFrameSlotKind;
 
 typedef enum NativeFrameSlotFlag {
   NATIVE_FRAME_SLOT_NONE_FLAG = 0,
   NATIVE_FRAME_SLOT_ADDR_TAKEN = 1u << 0,
   NATIVE_FRAME_SLOT_MEMORY_REQUIRED = 1u << 1,
   NATIVE_FRAME_SLOT_FIXED_OFFSET = 1u << 2,
   /* A recyclable single-pass temp slot. native_frame_slot_alloc serves such a
    * request from the per-(size,align) free list first, before bumping cum_off;
    * native_frame_release_slot returns the slot there when its temp dies at a
    * statement boundary. Bounds the -O0 frame to max-simultaneous-live temps. */
   NATIVE_FRAME_SLOT_TRANSIENT = 1u << 3,
 } NativeFrameSlotFlag;
 
 typedef struct NativeFrameSlotDesc {
   KitCgTypeId type;
   Sym name;
   SrcLoc loc;
   u32 size;
   u32 align;
   i32 fixed_offset;
   /* Spill-traffic priority (O1.md W1.0), copied from IRFrameSlot.priority. The
    * known-frame emitter (opt_emit_native) presents slot descs to the backend in
    * descending-priority order, so the bump allocator (native_frame_slot_alloc)
    * gives the hottest spills the smallest final displacement. The backend itself
    * ignores this field — it is purely an ordering signal for the emitter. */
   u32 priority;
   u8 kind; /* NativeFrameSlotKind */
   u8 pad;
   u16 flags; /* NativeFrameSlotFlag */
 } NativeFrameSlotDesc;
 
 typedef struct NativeKnownFrameDesc {
   const NativeFrameSlotDesc* slots;
   u32 nslots;
   u32 max_outgoing;
   u32 align;
   /* Callee-saved hard registers the allocator assigned, one bitmask per
    * NativeAllocClass (indexed by class id). The backend reserves a save slot
    * and emits the prologue save / epilogue restore for each — equivalent to a
    * reserve_callee_saves() call, but folded into the known-frame setup so the
    * full frame is fixed before the prologue is emitted. NULL / 0 means none. */
   const u32* callee_saved_used;
   u32 ncallee_classes;
   /* Union of the clobber register names of every inline-asm block in the body.
    * Inline-asm clobbers are invisible to the operand scan that builds
    * callee_saved_used, so the optimizer forwards the raw names here and the
    * backend resolves them with its own clobber parser, folding the callee-saved
    * ones into its save set (applying its ABI predicate, which excludes the
    * frame pointer and keeps any reserved-but-callee-saved scratch such as x64
    * rbx). The prologue/epilogue then preserve them, so the asm hook needs no
    * per-block spill — which on the known-frame path would request a frame slot
    * after the frame is already final. NULL / 0 when the body contains no inline
    * asm. */
   const Sym* asm_clobbers;
   u32 nasm_clobbers;
   /* Union of KitCgAsmClobberAbiSet bits over the body's inline-asm blocks: an
    * arch-neutral "clobbers the whole caller/callee-saved set" the backend
    * expands against its own register file, alongside the named asm_clobbers. */
   u32 asm_clobber_abi_sets;
   /* Whether the function body contains a dynamic alloca. The backend needs this
    * up front (before the body) to decide prologue/epilogue form, since with a
    * known frame the slim-epilogue eligibility is settled at func_begin. */
   u8 has_alloca;
   /* Whether the body has an operation that needs a backend-internal scratch
    * spill slot — on aa64, an atomic read-modify-write, whose retry loop spills
    * one scratch register. The backend reserves the slot up front so the body
    * never grows the frame after the prologue. */
   u8 needs_scratch_spill;
   /* Whether the function is a leaf — its body contains no call of any kind
    * (regular or sibling/tail). A leaf does not clobber the return-address
    * register or the stack below sp through a call, so backends can omit the
    * saved-frame record entirely (rv64 leaf tier) or skip the stack reservation
    * and keep locals in the red zone (x64 SysV red-zone tier) — but ONLY when
    * `has_asm` is also clear (see below). Conservatively false whenever any
    * IR_CALL is present. */
   u8 is_leaf;
   /* Whether the body contains an inline-asm block. Inline asm can clobber the
    * return-address register (rv64 ra) or write into the red zone / make a call
    * (x64) without the optimizer modelling it, so the frame-eliding
    * leaf/red-zone tiers must NOT fire when this is set — even for an
    * otherwise-leaf function. The single-pass and fat known-frame shapes always
    * save the return address and reserve their stack, so they are unaffected. */
   u8 has_asm;
   /* Whether the body reads its own frame-pointer chain via
    * __builtin_frame_address / __builtin_return_address (INTRIN_FRAME_ADDRESS /
    * INTRIN_RETURN_ADDRESS). Such a function must keep a valid frame record and
    * frame pointer, so the frameless-leaf tier (rv64 slim_prologue, which emits
    * no prologue and never anchors s0) must NOT fire. aa64/x64 keep the frame
    * record in every prologue shape, so they ignore this flag. */
   u8 reads_frame;
 } NativeKnownFrameDesc;
 
 typedef enum NativeAllocClass {
   NATIVE_REG_INT,
   NATIVE_REG_FP,
   NATIVE_REG_VEC,
   NATIVE_REG_CLASS_COUNT,
 } NativeAllocClass;
 
 #define NATIVE_MAX_HARD_REGS 32u
 
 typedef u32 NativeRegMaskSet[NATIVE_REG_CLASS_COUNT];
 
 typedef enum NativeRegFlag {
   NATIVE_REG_NONE = 0,
   NATIVE_REG_ALLOCABLE = 1u << 0,
   NATIVE_REG_CALLER_SAVED = 1u << 1,
   NATIVE_REG_CALLEE_SAVED = 1u << 2,
   NATIVE_REG_ARG = 1u << 3,
   NATIVE_REG_RET = 1u << 4,
   NATIVE_REG_RESERVED = 1u << 5,
   NATIVE_REG_TEMP_PREFERRED = 1u << 6,
 } NativeRegFlag;
 
 typedef struct NativePhysRegInfo {
   Reg reg;
   u8 cls;       /* NativeAllocClass */
   u8 abi_index; /* 0xff when not an ordered ABI arg/ret register */
   u16 flags;    /* NativeRegFlag */
   u16 spill_cost;
   u16 copy_cost;
 } NativePhysRegInfo;
 
 typedef struct NativeAllocClassInfo {
   u8 cls; /* NativeAllocClass */
   u8 pad[3];
 
   /* NativeDirectTarget (-O0) value-cache register policy. Optimized
    * allocation is described independently by NATIVE_REG_ALLOCABLE rows in
    * `phys`; neither path may infer its value bank from the other. */
   const Reg* ndt_allocable;
   u32 ndt_allocable_count;
 
   /* NativeDirectTarget (-O0) value-cache temporary policy only. Optimized
    * emission must not infer operand registers from this list; it owns the
    * independently declared, instruction-scoped `emit_temps` bank below. */
   const Reg* scratch;
   u32 nscratch;
 
   /* Registers owned exclusively by an -O1 native-emission instruction scope.
    * They are operand-facing temporaries, not MIR values and not backend-private
    * implementation registers. The set is explicit rather than inherited from
    * the -O0 cache's `scratch` policy: those two clients have different
    * lifetimes and may require disjoint banks (notably ARM32). */
   const Reg* emit_temps;
   u32 nemit_temps;
 
   /* Backend-internal registers that may be loaned specifically while binding
    * a register-only inline-asm block. They are otherwise unavailable to the
    * optimizer emitter. The asm staging planner uses them only when the block
    * has no memory constraint (whose address binder may need the same bank). */
   const Reg* asm_temps;
   u32 nasm_temps;
 
   /* Ordered register policy for operands self-allocated by the O0 direct
    * inline-asm binder. This is distinct from ndt_allocable and scratch: values
    * live for the complete asm block, and the order is an architecture policy.
    * Explicit hard-register pins are validated separately and need not appear
    * here. Selection itself is shared in cg/native_asm.c. */
   const Reg* direct_asm_allocable;
   u32 ndirect_asm_allocable;
 
   /* Subset of reserved optimizer emitter temps whose contents survive ordinary
    * backend hooks when they are not passed as operands or named by a clobber
    * effect. The native emitter may retain clean FS_SPILL values in these and
    * in dead O1 allocation registers whose ABI preservation is established
    * (caller-saved, or a callee-saved register present in the known frame)
    * across adjacent instructions; O1 allocation-register preservation is
    * governed by machine_op_clobbers below. */
   u32 emit_cache_mask;
 
   const NativePhysRegInfo* phys;
   u32 nphys;
 } NativeAllocClassInfo;
 
 typedef struct NativeRegInfo NativeRegInfo;
 struct NativeRegInfo {
   const NativeAllocClassInfo* classes;
   u32 nclasses;
 
   /* True when this register model's scratch + caller-saved NDT cache pool is
    * rich enough that the single-pass (-O0) NativeDirectTarget never needs to
    * fall back to a callee-saved register under pressure. When set, NDT is
    * enforced caller-saved-only (nd_scratch_acquire skips callee-saved regs;
    * nd_func_end asserts none were used), which lets the backend reserve only a
    * tiny tcc-style deferred-`sub` prologue region instead of a worst-case
    * callee-save area. When clear (the default), NDT keeps its historical
    * behavior: it may use callee-saved registers as extra scratch and the
    * prologue preserves them. Independent of the optimizer/-O1 path, which always
    * has full callee-save freedom. */
   u8 ndt_caller_saved_only;
 
   /* True when the ABI scalar-result register is clobbered ONLY at call
    * boundaries (where the -O0 cache already flushes), so a scalar call result
    * can be left cached in it across following ops instead of being moved into a
    * general cache register (saving the post-call `mov cachereg, retreg`). Set on
    * aarch64 (x0) and riscv64 (a0), whose div/mul/etc. take explicit operands.
    * Clear on x86-64, where RAX is an implicit div/mul operand and a result left
    * in it would be silently clobbered before its consumer. */
   u8 ndt_result_reg_stable;
 
   /* True when this backend honors MF_SEXT_LOAD by emitting a sign-extending
    * load that fills the whole register (aa64 ldrsb/ldrsh -> X), so the shared
    * Native codegen may record load_sext on the loaded local and elide the following
    * CV_SEXT. Clear (the default) on backends whose narrow load zero-extends
    * regardless of the flag (x86-64, riscv64 today): there the convert must run,
    * so the flag is a no-op and the extend is emitted normally. */
   u8 load_sext;
 
   /* Map a register name to its (Reg, class). `name` is the raw spelling
    * ("rax", "x8", "a7"); the caller resolves any Sym to its bytes first so this
    * stays pool-free. Returns 0 on success, non-zero for a non-register name. */
   int (*resolve_name)(const NativeRegInfo*, Slice name, Reg* out,
                       NativeAllocClass* cls_out);
   /* True when (cls, reg) is a valid hard-register home for an inline-asm value
    * operand. This is intentionally separate from allocator availability:
    * syscall idioms need ABI registers such as x8/a7, while stack/frame, zero,
    * link, platform, and backend scratch registers must stay unavailable even if
    * the assembler can name them. */
   int (*asm_operand_reg_ok)(const NativeRegInfo*, NativeAllocClass cls,
                             Reg reg);
   /* Optional target-specific register-constraint parser for inline asm. The
    * input is the constraint body after generic modifiers ('=', '+', '&') have
    * been stripped. Return non-zero only for constraints that name a register
    * class; set fixed_out to REG_NONE for a free class or to a physical register
    * when the constraint hard-wires the operand (x86 "a" -> rax). Set
    * allowed_mask_out to 0 for the whole class, or a physical-register bitmask
    * when the constraint names a restricted class subset. */
   int (*asm_constraint_reg)(const NativeRegInfo*, const char* body,
                             NativeAllocClass* cls_out, Reg* fixed_out,
                             u32* allowed_mask_out);
   const char* (*debug_name)(const NativeRegInfo*, NativeAllocClass, Reg);
   u32 (*dwarf_reg)(const NativeRegInfo*, NativeAllocClass, Reg);
 };
 
 /* Validate the target-independent NativeRegInfo contract. Both the direct and
  * optimized adapters call this at their boundary, so malformed physical rows,
  * role flags, or temporary banks fail identically at O0 and O1. */
 void native_reg_info_validate(Compiler* c, const NativeRegInfo* ri);
 
 /* Classes are identified by NativeAllocClass, not by their position in the
  * target's table. Keep the lookup policy shared by every register consumer. */
 const NativeAllocClassInfo* native_reg_info_class_info(
     const NativeRegInfo* ri, NativeAllocClass cls);
 
 /* Static register roles have one authority: NativePhysRegInfo.flags. Targets
  * with an OS-dependent preservation ABI override caller/callee masks through
  * NativeTarget below; all other role consumers derive their masks here. */
 u32 native_reg_info_flag_mask(const NativeRegInfo* ri, NativeAllocClass cls,
                               u16 flag);
 
 typedef enum NativeLocKind {
   NATIVE_LOC_NONE,
   NATIVE_LOC_REG,
   NATIVE_LOC_FRAME,
   NATIVE_LOC_STACK,
   NATIVE_LOC_IMM,
   NATIVE_LOC_GLOBAL,
   /* Address value of a concrete frame slot. Distinct from NATIVE_LOC_FRAME,
    * which is the scalar value stored in the slot, and NATIVE_LOC_ADDR, which
    * is the scalar value addressed by an effective-address expression. */
   NATIVE_LOC_FRAME_ADDR,
   NATIVE_LOC_ADDR,
 } NativeLocKind;
 
 typedef enum NativeAddrBaseKind {
   NATIVE_ADDR_BASE_NONE,
   /* Pointer value already held in a physical register. */
   NATIVE_ADDR_BASE_REG,
   /* Address of the frame slot itself: FP + slot offset. */
   NATIVE_ADDR_BASE_FRAME,
   /* Scalar pointer value stored in a frame slot. base_type is mandatory and
    * is the exact value type, independent of the colored slot descriptor. */
   NATIVE_ADDR_BASE_FRAME_VALUE,
   NATIVE_ADDR_BASE_GLOBAL,
 } NativeAddrBaseKind;
 
 typedef enum NativeAddrIndexKind {
   NATIVE_ADDR_INDEX_NONE,
   NATIVE_ADDR_INDEX_REG,
   /* Scalar index value stored in a frame slot. index_type is mandatory and is
    * the exact value type, independent of the colored slot descriptor. */
   NATIVE_ADDR_INDEX_FRAME_VALUE,
 } NativeAddrIndexKind;
 
 typedef enum NativeImmUse {
   NATIVE_IMM_MOVE,
   NATIVE_IMM_BINOP,
   NATIVE_IMM_CMP,
   NATIVE_IMM_ADDR_OFFSET,
 } NativeImmUse;
 
 /* Addressing-mode index extend (O1-PATTERNS L8). A backend that advertises
  * can_fold_extend_into_addr may receive a NATIVE_ADDR_INDEX_REG whose register
  * names a 32-bit value the addressing mode widens to 64 bits with this extend
  * (aa64 `[Xbase, Wm, sxtw/uxtw #log2_scale]`). NONE = full-width index, the
  * default; every other backend only ever sees NONE. */
 typedef enum NativeAddrIndexExt {
   NATIVE_ADDR_IDX_EXT_NONE = 0,
   NATIVE_ADDR_IDX_EXT_SXTW = 1,
   NATIVE_ADDR_IDX_EXT_UXTW = 2,
 } NativeAddrIndexExt;
 
 typedef struct NativeAddr {
   u8 base_kind;  /* NativeAddrBaseKind */
   u8 cls;        /* NativeAllocClass for base value */
   u8 index_kind; /* NativeAddrIndexKind */
   u8 index_cls;  /* NativeAllocClass for index value */
   u8 log2_scale;
   u8 index_ext; /* NativeAddrIndexExt */
   u8 pad[2];
   KitCgTypeId base_type;
   KitCgTypeId index_type;
   union {
     Reg reg;
     NativeFrameSlot frame;
     struct {
       ObjSymId sym;
       i64 addend;
     } global;
   } base;
   union {
     Reg reg;
     NativeFrameSlot frame;
   } index;
   i32 offset;
 } NativeAddr;
 
 typedef struct NativeLoc {
   u8 kind; /* NativeLocKind */
   u8 cls;  /* NativeAllocClass for register-like locations */
   /* Cached scalar-width descriptor, stamped once by the NDT at the
    * register-NativeLoc choke point (nd_loc_reg) so the per-arch binop/move/
    * convert/cmp hot path reads a byte instead of re-crossing the type bridge
    * via cg_type_size on `type`. Layout:
    *   bit0      SZINFO_VALID — set => the size field is authoritative
    *   bits 1..3 SZINFO_SIZE_LOG2 — log2(byte_size) clamped: 0=1,1=2,2=4,3=8,4=16
    * Each arch derives its own `is64` predicate from this cached size plus its
    * pointer/xlen rule (so the rv32 4-byte-pointer and i128 distinctions stay
    * correct per-arch) — the descriptor caches only the size, never a baked
    * width class. Left 0 (invalid) for cold locs (immediates, memory, unstamped
    * producers); the arch then falls back to the live cg_type_size query, so
    * partial adoption stays byte-identical. */
   u8 szinfo;
   /* L7 shift rider (O1-PATTERNS): when nonzero on a register NativeLoc passed
    * as the second source of a binop, the value is pre-shifted left by `shift`
    * (1..4) and the backend emits the shifted-register ALU form
    * (`add xD,xA,xS,lsl #shift`). 0 = use the register as-is. Only stamped when
    * the target advertised can_fold_shift_into_alu, so a backend without the
    * capability never sees it. */
   u8 shift;
   KitCgTypeId type;
   union {
     Reg reg;
     NativeFrameSlot frame;
     struct {
       NativeFrameSlot slot;
       i32 offset;
     } stack;
     i64 imm;
     struct {
       ObjSymId sym;
       i64 addend;
     } global;
     NativeAddr addr;
   } v;
 } NativeLoc;
 
 /* Narrow register-only operand descriptor for the -O0 NativeDirectTarget hot
  * path. NDT resolves every post-materialization binop/move/cmp/convert operand
  * to a hard register (or, for an arithmetic/compare RHS, a target-legal
  * immediate), then crosses into the per-arch NativeTarget. The fat 48 B
  * NativeLoc carries a union wide enough for memory/global/addr forms that these
  * ops never receive; passing it by value copies 48 B per operand (144 B/op)
  * only for the arch to unwrap a register number + the cached width. NativeRegLoc
  * carries exactly the fields the arch reads — register/immediate, class, the
  * §E.2 cached width descriptor, and the type for the cold width-fallback — in
  * 16 B. The narrow *_rr hooks below take it; they are byte-identical to the fat
  * hooks because native_loc_from_reg reconstructs the same NativeLoc the fat path
  * would have received. */
 typedef struct NativeRegLoc {
   u8 cls;    /* NativeAllocClass for the register/value */
   u8 szinfo; /* cached scalar-width descriptor, same encoding as NativeLoc */
   u8 is_imm; /* 1 => v.imm holds a target-legal immediate (RHS only); else reg */
   u8 pad;
   KitCgTypeId type;
   union {
     Reg reg;
     i64 imm;
   } v;
 } NativeRegLoc;
 
 typedef struct NativeInst NativeInst;
 
 typedef enum NativePatchKind {
   NATIVE_PATCH_FRAME_SIZE,
   NATIVE_PATCH_MAX_OUTGOING,
   NATIVE_PATCH_ARCH = 0x1000,
 } NativePatchKind;
 
 typedef struct NativePatch {
   u32 kind; /* NativePatchKind or arch-private */
   u32 section_id;
   u32 offset;
   u32 width;
   i64 addend;
   u64 value;
 } NativePatch;
 
 typedef struct NativeFramePatchState {
   u32 max_outgoing;
   u32 max_align;
 } NativeFramePatchState;
 
 /* A semantic machine operation, enough for the target to report the physical
  * registers its encoding clobbers as a side effect (e.g. x86 idiv writes
  * rax/rdx, variable shifts use cl, and a bitfield read-modify-write borrows
  * fixed temporaries). Built by the optimizer from an instruction; the
  * descriptor keeps the backend from depending on the optimizer IR. */
 typedef enum NativeMachineOpKind {
   NATIVE_MOP_BINOP,
   NATIVE_MOP_BITFIELD_LOAD,
   NATIVE_MOP_BITFIELD_STORE,
   NATIVE_MOP_VA_START,
   NATIVE_MOP_VA_ARG,
   NATIVE_MOP_ATOMIC_CAS,
   NATIVE_MOP_ATOMIC_RMW,
   NATIVE_MOP_INTRINSIC,
   /* A thread-local address materialization (IR_TLS_ADDR_OF). On targets whose
    * TLS access model uses fixed scratch/result registers or a resolver-thunk
    * call (e.g. Mach-O TLV descriptors → x0/x16/x17/lr), the encoding clobbers
    * those regs even though the IR op only declares its destination. Targets
    * whose TLS sequence touches only the destination register (ELF Local-Exec)
    * report no clobbers. */
   NATIVE_MOP_TLS_ADDR,
   NATIVE_MOP_COUNT,
 } NativeMachineOpKind;
 
 typedef struct NativeMachineOp {
   u8 kind;          /* NativeMachineOpKind */
   u8 binop;         /* BinOp, when kind == NATIVE_MOP_BINOP */
   u8 intrin;        /* IntrinKind, when kind == NATIVE_MOP_INTRINSIC */
   u8 second_is_reg; /* binop's second operand is a register (not an immediate)
                      */
   u8 result_is_fp;  /* result lands in an FP register (e.g. va_arg of a double)
                      */
 } NativeMachineOp;
 
 typedef struct NativeCallDesc {
   KitCgTypeId fn_type;
   NativeLoc callee;
   /* Each argument is a complete semantic value. REG/IMM carry scalar bits;
    * FRAME/STACK/ADDR name dereferenceable storage; GLOBAL/FRAME_ADDR are
    * scalar address values and must classify as one pointer-sized ABI part.
    * Backends use native_loc_addr_role plus the checked converters below rather
    * than inferring value-vs-storage semantics from union fields. */
   const NativeLoc* args;
   const NativeLoc* results;
   u32 nargs;
   u32 nresults;
   u16 flags;      /* CGCallFlag */
   u8 tail_policy; /* KitCgTailPolicy */
   u8 pad;
   KitCgInlinePolicy inline_policy;
 } NativeCallDesc;
 
 typedef enum NativeCallPhaseMoveKind {
   NATIVE_CALL_MOVE_NONE,
   NATIVE_CALL_MOVE_VALUE,
   NATIVE_CALL_MOVE_ADDR,
 } NativeCallPhaseMoveKind;
 
 typedef struct NativeCallPhaseMove {
   NativeLoc src;
   NativeLoc dst;
   MemAccess mem;
   u8 src_kind; /* NativeCallPhaseMoveKind */
   u8 dst_kind; /* NativeLocKind */
   u8 pad[2];
 } NativeCallPhaseMove;
 
 typedef struct NativeCallPhaseRet {
   NativeLoc src;
   NativeLoc dst;
   MemAccess mem;
 } NativeCallPhaseRet;
 
 typedef struct NativeCallPhase {
   NativeLoc callee;
   NativeCallPhaseMove* args;
   NativeCallPhaseRet* rets;
   u32 nargs;
   u32 nrets;
   u32 stack_arg_size;
   u16 flags; /* CGCallFlag */
   u8 has_sret;
   u8 is_variadic;
 } NativeCallPhase;
 
 typedef struct NativeTarget NativeTarget;
 struct NativeTarget {
   Compiler* c;
   ObjBuilder* obj;
   MCEmitter* mc;
   const NativeRegInfo* regs;
   u64 disabled_backend_features;
 
   NativeAllocClass (*class_for_type)(NativeTarget*, KitCgTypeId);
   int (*imm_legal)(NativeTarget*, NativeImmUse, u32 op, KitCgTypeId, i64);
   int (*addr_legal)(NativeTarget*, const NativeAddr*, MemAccess);
   /* Optional O1-PATTERNS rider capabilities. The target-agnostic recognition
    * passes (pass_combine / pass_addr_fold) only stamp an operand rider after
    * the consuming backend advertises the matching capability here, so a
    * backend that cannot emit the folded form never receives a rider it would
    * have to silently drop. NULL == not supported (the default for every
    * backend that has not opted in).
    *
    * can_fold_shift_into_alu (L7): the backend emits a single-use left shift
    * folded into a consuming IADD/ISUB/AND/ORR/EOR as the shifted-register form
    * (aa64 `add xD,xA,xS,lsl #k`), honoring OptOperand.shift on a binop's
    * second source operand.
    *
    * can_fold_extend_into_addr (L8): the backend emits a single-use sxtw/uxtw
    * of a load/store index folded into the addressing mode (aa64 `[Xb, Wm,
    * sxtw/uxtw #scale]`), honoring NativeAddr.index_ext. */
   int (*can_fold_shift_into_alu)(NativeTarget*);
   int (*can_fold_extend_into_addr)(NativeTarget*);
   /* Optional, but exhaustive when present. Report every optimizer-visible
    * physical register the target's encoding of `op` clobbers as a side effect
    * (not its declared operands/results), one bitmask per NativeAllocClass.
    * This includes registers that can be MIR hard homes and cache-enabled emit
    * temps whose retained spill value must be invalidated. Pure backend-private
    * temporaries are reserved, never cached, and do not appear here. This single
    * contract lets regalloc keep live values out of fixed clobbers and lets the
    * emitter retain clean spill values safely. Examples include x86 idiv
    * (rax/rdx), variable shift (rcx), bitfield RMW and atomics (rax/rcx/rdx),
    * and format-dependent TLS sequences. Return non-zero if any register is
    * clobbered, 0 otherwise. NULL promises no optimizer-visible fixed
    * clobbers. */
   int (*machine_op_clobbers)(NativeTarget*, const NativeMachineOp* op,
                              NativeRegMaskSet clobber_mask);
 
   void (*func_begin)(NativeTarget*, const CGFuncDesc*);
   void (*func_begin_known_frame)(NativeTarget*, const CGFuncDesc*,
                                  const NativeKnownFrameDesc*,
                                  NativeFrameSlot* out_slots);
   void (*note_frame_state)(NativeTarget*, const NativeFramePatchState*);
   /* Optional. Called once after func_begin and before frame-slot mapping, with
    * the set of callee-saved hard registers the allocator assigned (one bitmask
    * per NativeAllocClass, indexed by class id). The target reserves save slots
    * and emits the prologue save / epilogue restore for each. Register
    * allocation is complete before emission, so the caller knows the full set
    * up front. */
   void (*reserve_callee_saves)(NativeTarget*, const u32* used_by_class,
                                u32 nclasses);
   /* Optional live-ABI caller/callee-saved register masks for a class. Static
    * NativeAllocClassInfo masks describe the target register file, but some
    * targets vary preservation rules by OS ABI (x64 SysV vs Win64 XMM regs).
    * The optimizer and direct emission use these to keep allocation, call
    * clobbers, and prologue save sets aligned with the selected ABI. NULL falls
    * back to NativeAllocClassInfo.{caller,callee}_saved_mask. */
   u32 (*caller_saved_mask)(NativeTarget*, NativeAllocClass);
   u32 (*callee_saved_mask)(NativeTarget*, NativeAllocClass);
   /* Bytes of stack-passed arguments the fixed parameters of this function
    * signature use (the part beyond the register arg pools). Sets *variadic to
    * whether the signature is variadic and *nparams to the fixed parameter
    * count. Used to decide tail-call (sibling) realizability: the callee's
    * outgoing stack args must fit the area the caller itself received. Either
    * out-pointer may be NULL. May itself be NULL. */
   u32 (*signature_stack_bytes)(NativeTarget*, KitCgTypeId fn_type,
                                int* variadic, u32* nparams);
   /* Pure query: the outgoing stack-argument bytes a call with this descriptor
    * uses, rounded to the ABI's outgoing-area alignment. Reads only fn_type,
    * flags, nargs, and each args[i].type — never argument *locations* — so the
    * optimizer can call it in a frame-planning pre-pass, before any argument
    * marshalling is emitted, to size the outgoing area. Must equal the
    * stack_arg_size marshal_call computes for the same descriptor. May be NULL. */
   u32 (*call_stack_bytes)(NativeTarget*, const NativeCallDesc*);
   /* Integer hardware zero register, if the ISA has one (aa64 wzr/xzr, rv64
    * x0). When `has_store_zero_reg` is set, the emit path stores a constant 0
    * straight from `store_zero_reg` instead of materializing 0 into a scratch
    * with a mov/movz first. */
   u8 has_store_zero_reg;
   Reg store_zero_reg;
   void (*func_end)(NativeTarget*);
 
   NativeFrameSlot (*frame_slot)(NativeTarget*, const NativeFrameSlotDesc*);
   /* Optional. Return a recyclable single-pass temp slot (one previously handed
    * out for a NATIVE_FRAME_SLOT_TRANSIENT desc) to the frame's free list so a
    * later transient allocation of the same (size,align) reuses it instead of
    * growing the frame. Called by NativeDirectTarget's reclaim_temps at statement
    * boundaries. NULL means the backend does not recycle (frame still correct,
    * just larger). */
   void (*release_frame_slot)(NativeTarget*, NativeFrameSlot);
   /* Optional post-finalization query for a native frame slot's debug location.
    * Each arch owns the frame layout math and returns the coordinate system its
    * debugger/unwinder path can materialize. */
   int (*frame_slot_debug_loc)(NativeTarget*, NativeFrameSlot, CGDebugLoc*);
   /* Place the incoming parameter into `dst`. The caller (which has run register
    * allocation) chooses the destination: a hard register (NATIVE_LOC_REG) for a
    * register-allocated scalar param, a frame slot (NATIVE_LOC_FRAME) for an
    * address-taken / spilled / aggregate param. NATIVE_LOC_NONE means the param
    * is unused and only the ABI register/stack cursor must advance. Incoming arg
    * registers are never allocable, so reg destinations never alias an incoming
    * arg register and ordering across params is unconstrained. */
   void (*bind_param)(NativeTarget*, const CGParamDesc*, NativeLoc dst);
   /* Optional. Called once by the optimizer emit path after the last bind_param,
    * before the body. Lets a backend that defers register-destination param
    * binds (to resolve them as a parallel copy, since the allocator may rotate
    * params across the incoming arg registers — a permutation the naive
    * per-param move order cannot realize) flush them now. Backends that bind
    * eagerly leave this NULL. */
   void (*bind_params_end)(NativeTarget*);
 
   MCLabel (*label_new)(NativeTarget*);
   void (*label_place)(NativeTarget*, MCLabel);
   void (*jump)(NativeTarget*, MCLabel);
   void (*cmp_branch)(NativeTarget*, CmpOp, NativeLoc a, NativeLoc b,
                      MCLabel target);
   void (*indirect_branch)(NativeTarget*, NativeLoc addr,
                           const MCLabel* valid_targets, u32 ntargets);
   void (*load_label_addr)(NativeTarget*, NativeLoc dst, MCLabel target);
 
   void (*emit)(NativeTarget*, const NativeInst*);
   /* All instruction-emission hooks require caller-selected legal physical
    * value operands. In particular, dst values are NATIVE_LOC_REG and
    * arithmetic sources are NATIVE_LOC_REG or target-legal immediates.
    * NativeAddr may retain typed FRAME_VALUE base/index components; the backend
    * materializes those exact-width values only through its declared internal
    * registers. It must not allocate or expose a new IR-visible register. */
   void (*move)(NativeTarget*, NativeLoc dst_reg, NativeLoc src_reg);
   void (*load_imm)(NativeTarget*, NativeLoc dst_reg, i64 imm);
   void (*load_const)(NativeTarget*, NativeLoc dst_reg, ConstBytes);
   /* Address materialization must accept dst_reg aliasing a BASE_REG component
    * while still consuming any distinct index before the destination write.
    * The emitter never requests dst_reg aliasing the index itself. */
   void (*load_addr)(NativeTarget*, NativeLoc dst_reg, NativeAddr addr);
   /* A one-register scalar load from a plain BASE_REG address must accept
    * dst_reg aliasing that base: the effective address is consumed before the
    * destination is written. This lets the target-neutral emitter reuse an
    * instruction-leased address register under maximal temporary pressure. */
   void (*load)(NativeTarget*, NativeLoc dst_reg, NativeAddr addr, MemAccess);
   void (*store)(NativeTarget*, NativeAddr addr, NativeLoc src_reg, MemAccess);
   void (*tls_addr_of)(NativeTarget*, NativeLoc dst_reg, ObjSymId sym,
                       i64 addend);
   void (*copy_bytes)(NativeTarget*, NativeAddr dst, NativeAddr src,
                      AggregateAccess);
   void (*set_bytes)(NativeTarget*, NativeAddr dst, NativeLoc byte_value,
                     AggregateAccess);
   /* Like load(), a one-register bitfield load must consume a plain BASE_REG
    * address before writing dst_reg and accept those registers aliasing. */
   void (*bitfield_load)(NativeTarget*, NativeLoc dst_reg,
                         NativeAddr record_addr, BitFieldAccess);
   void (*bitfield_store)(NativeTarget*, NativeAddr record_addr,
                          NativeLoc src_reg, BitFieldAccess);
   void (*binop)(NativeTarget*, BinOp, NativeLoc dst_reg, NativeLoc a_reg,
                 NativeLoc b_reg_or_imm);
   void (*unop)(NativeTarget*, UnOp, NativeLoc dst_reg, NativeLoc src_reg);
   void (*cmp)(NativeTarget*, CmpOp, NativeLoc dst_reg, NativeLoc a_reg,
               NativeLoc b_reg_or_imm);
   void (*convert)(NativeTarget*, ConvKind, NativeLoc dst_reg,
                   NativeLoc src_reg);
   /* Narrow register-only entry points for the -O0 NativeDirectTarget hot path
    * (§E.3). Same semantics and byte output as the fat binop/move/cmp/convert,
    * but the operands cross as 16 B NativeRegLoc instead of 48 B NativeLoc. NDT
    * calls these when installed (always, for the native arch backends); the
    * fat hooks above remain for the opt/-O1 replay path, which is unchanged.
    * Optional: a backend that leaves them NULL keeps the fat path. */
   void (*binop_rr)(NativeTarget*, BinOp, NativeRegLoc dst, NativeRegLoc a,
                    NativeRegLoc b_reg_or_imm);
   void (*move_rr)(NativeTarget*, NativeRegLoc dst, NativeRegLoc src);
   void (*cmp_rr)(NativeTarget*, CmpOp, NativeRegLoc dst, NativeRegLoc a,
                  NativeRegLoc b_reg_or_imm);
   void (*convert_rr)(NativeTarget*, ConvKind, NativeRegLoc dst,
                      NativeRegLoc src);
   void (*alloca_)(NativeTarget*, NativeLoc dst_reg, NativeLoc size_reg,
                   u32 align);
 
   void (*spill)(NativeTarget*, NativeLoc src_reg, NativeFrameSlot, MemAccess);
   void (*reload)(NativeTarget*, NativeLoc dst_reg, NativeFrameSlot, MemAccess);
 
   /* Mutating ABI-marshalling phase. It may stage the callee, emit stack
    * arguments and register shuffles, and fill any remaining generic
    * moves/results in NativeCallPhase. The phase owns every populated ABI
    * argument destination and any staged callee until emit_call consumes it. */
   void (*marshal_call)(NativeTarget*, const NativeCallDesc*, NativeCallPhase*);
   void (*emit_call)(NativeTarget*, const NativeCallPhase*);
   /* The corresponding mutating return-marshalling phase. `value` is the
    * single returned local's location, or NULL for void; the hook may emit an
    * indirect-result copy and returns the ordered register moves in
    * out_rets/out_nrets. Completed destinations remain live through the phase. */
   void (*marshal_ret)(NativeTarget*, const CGFuncDesc*, const NativeLoc* value,
                       NativeCallPhaseRet** out_rets, u32* out_nrets);
   void (*ret)(NativeTarget*);
 
   /* Like load(), a one-register atomic load must consume a plain BASE_REG
    * address before writing dst and accept those registers aliasing. Backends
    * already materialize any stronger atomic addressing constraint into their
    * private scratch before the value load. */
   void (*atomic_load)(NativeTarget*, NativeLoc dst, NativeAddr addr, MemAccess,
                       KitCgMemOrder);
   void (*atomic_store)(NativeTarget*, NativeAddr addr, NativeLoc src, MemAccess,
                        KitCgMemOrder);
   void (*atomic_rmw)(NativeTarget*, KitCgAtomicOp, NativeLoc dst,
                      NativeAddr addr, NativeLoc val, MemAccess, KitCgMemOrder);
   void (*atomic_cas)(NativeTarget*, NativeLoc prior, NativeLoc ok,
                      NativeAddr addr, NativeLoc expected, NativeLoc desired,
                      MemAccess, KitCgMemOrder success, KitCgMemOrder failure);
   void (*fence)(NativeTarget*, KitCgMemOrder);
   /* Variadic support. The optimizer passes the va_list pointer opaquely as a
    * NativeLoc (a register or memory location holding the address of the
    * va_list object); va_arg additionally receives the argument type and a
    * destination location for the fetched value. All va_list layout knowledge
    * (pointer ABI vs register-save-area ABI, field offsets, sizes) lives behind
    * these hooks, which query the target ABI -- the optimizer makes no layout
    * assumptions. */
   void (*va_start_)(NativeTarget*, NativeLoc ap_ptr);
   void (*va_arg_)(NativeTarget*, NativeLoc dst, NativeLoc ap_ptr,
                   KitCgTypeId type);
   void (*va_end_)(NativeTarget*, NativeLoc ap_ptr);
   void (*va_copy_)(NativeTarget*, NativeLoc dst_ap_ptr, NativeLoc src_ap_ptr);
   /* Value arguments reach the backend as NATIVE_LOC_REG unless the backend
    * explicitly accepts an immediate for that intrinsic operand. The shared
    * target-sequence/control operands recognized by
    * native_intrinsic_arg_accepts_imm below also remain NATIVE_LOC_IMM when the
    * IR supplied a constant. Keeping this capability explicit prevents a
    * backend from accidentally decoding an immediate's union payload as a
    * register while allowing targets with private materialization registers to
    * avoid unnecessary pressure on the optimizer's operand-temp bank. */
   int (*intrinsic_arg_accepts_imm)(NativeTarget*, IntrinKind, u32 arg_index);
   void (*intrinsic)(NativeTarget*, IntrinKind, const NativeLoc* dsts, u32 ndst,
                     const NativeLoc* args, u32 narg);
   void (*asm_block)(NativeTarget*, const char* tmpl, const AsmConstraint* outs,
                     u32 nout, NativeLoc* out_locs, const AsmConstraint* ins,
                     u32 nin, const NativeLoc* in_locs, const Sym* clobbers,
                     u32 nclob);
   void (*file_scope_asm)(NativeTarget*, const char* src, size_t len);
   void (*patch_add)(NativeTarget*, const NativePatch*);
   void (*patch_apply)(NativeTarget*);
   void (*trap)(NativeTarget*);
   void (*set_loc)(NativeTarget*, SrcLoc);
   void (*finalize)(NativeTarget*);
   void (*destroy)(NativeTarget*);
 };
 
 static inline const NativeAllocClassInfo* native_target_class_info(
     const NativeTarget* t, NativeAllocClass cls) {
   return t ? native_reg_info_class_info(t->regs, cls) : NULL;
 }
 
 static inline u32 native_target_caller_saved_mask(NativeTarget* t,
                                                   NativeAllocClass cls) {
   if (t && t->caller_saved_mask) return t->caller_saved_mask(t, cls);
   return t ? native_reg_info_flag_mask(t->regs, cls,
                                        NATIVE_REG_CALLER_SAVED)
            : 0u;
 }
 
 static inline u32 native_target_callee_saved_mask(NativeTarget* t,
                                                   NativeAllocClass cls) {
   if (t && t->callee_saved_mask) return t->callee_saved_mask(t, cls);
   return t ? native_reg_info_flag_mask(t->regs, cls,
                                        NATIVE_REG_CALLEE_SAVED)
            : 0u;
 }
 
 static inline u32 native_target_arg_mask(const NativeTarget* t,
                                          NativeAllocClass cls) {
   return t ? native_reg_info_flag_mask(t->regs, cls, NATIVE_REG_ARG) : 0u;
 }
 
 static inline u32 native_target_ret_mask(const NativeTarget* t,
                                          NativeAllocClass cls) {
   return t ? native_reg_info_flag_mask(t->regs, cls, NATIVE_REG_RET) : 0u;
 }
 
 static inline u32 native_target_reserved_mask(const NativeTarget* t,
                                               NativeAllocClass cls) {
   return t ? native_reg_info_flag_mask(t->regs, cls, NATIVE_REG_RESERVED) : 0u;
 }
 
 /* Intrinsic operands whose immediate form is shared across every NativeTarget.
  * Other immediates are scalar values: the optimized emitter materializes them
  * unless the target explicitly advertises support through its capability
  * hook. */
 static inline int native_intrinsic_arg_accepts_imm(NativeTarget* t,
                                                    IntrinKind kind,
                                                    u32 arg_index) {
   switch (kind) {
     case INTRIN_MEMMOVE:
       return arg_index == 2u; /* constant byte count */
     case INTRIN_PREFETCH:
       return arg_index >= 1u; /* rw, locality */
     case INTRIN_ASSUME_ALIGNED:
       return arg_index >= 1u; /* alignment, offset */
     case INTRIN_EXPECT:
       return arg_index == 1u; /* expected value hint */
     case INTRIN_SYSCALL:
       /* Syscall hooks already use their target's parallel ABI-argument mover,
        * which accepts both registers and immediates and avoids requiring up to
        * seven simultaneous emitter-temp leases. */
       return 1;
     case INTRIN_DMB:
     case INTRIN_DSB:
       return arg_index == 0u; /* KitCgBarrierScope */
     case INTRIN_FRAME_ADDRESS:
     case INTRIN_RETURN_ADDRESS:
       return arg_index == 0u; /* constant frame-chain level */
     default:
       return t && t->intrinsic_arg_accepts_imm
                  ? t->intrinsic_arg_accepts_imm(t, kind, arg_index)
                  : 0;
   }
 }
 
 /* Location constructors. A designated compound literal initializes the named
  * fields and zero-fills the rest (so it is value-identical to the former
  * memset + field stores) but lets the compiler emit only the needed stores
  * instead of an out-of-line memset of the ~64-byte struct — these run on the
  * hottest per-operand codegen path. */
 static inline NativeLoc native_loc_none(void) {
   return (NativeLoc){.kind = NATIVE_LOC_NONE};
 }
 
 /* Target-neutral location constructors and scalar queries. These are
  * byte-identical across the native backends, so they live here as the single
  * source of truth. (loc_reg's register mask differs per arch and stays
  * per-backend.) */
 static inline NativeLoc native_loc_reg(KitCgTypeId type, NativeAllocClass cls,
                                        Reg reg) {
   return (NativeLoc){
       .kind = NATIVE_LOC_REG, .cls = (u8)cls, .type = type, .v.reg = reg};
 }
 
 static inline NativeLoc native_loc_stack(KitCgTypeId type, NativeFrameSlot slot,
                                          i32 offset) {
   return (NativeLoc){.kind = NATIVE_LOC_STACK,
                      .cls = NATIVE_REG_INT,
                      .type = type,
                      .v.stack = {.slot = slot, .offset = offset}};
 }
 
 /* A NativeLoc that structurally contains an address has one of two disjoint
  * semantic roles.  Storage locations are dereferenced to obtain a value;
  * address recipes are themselves scalar pointer values.  Keep the role in the
  * shared contract so ABI marshallers cannot accidentally turn `&slot` into a
  * load from slot (or turn a stored scalar into its address). */
 typedef enum NativeLocAddrRole {
   NATIVE_LOC_ADDR_ROLE_NONE,
   NATIVE_LOC_ADDR_ROLE_STORAGE,
   NATIVE_LOC_ADDR_ROLE_VALUE,
 } NativeLocAddrRole;
 
 static inline NativeLocAddrRole native_loc_addr_role(NativeLoc loc) {
   switch ((NativeLocKind)loc.kind) {
     case NATIVE_LOC_FRAME:
     case NATIVE_LOC_STACK:
     case NATIVE_LOC_ADDR:
       return NATIVE_LOC_ADDR_ROLE_STORAGE;
     case NATIVE_LOC_GLOBAL:
     case NATIVE_LOC_FRAME_ADDR:
       return NATIVE_LOC_ADDR_ROLE_VALUE;
     default:
       return NATIVE_LOC_ADDR_ROLE_NONE;
   }
 }
 
 /* Resolve storage that may be dereferenced. `offset` selects bytes within the
  * stored object (including an existing STACK/ADDR displacement). */
 static inline int native_loc_storage_addr(NativeLoc loc, i32 offset,
                                           NativeAddr* out) {
   NativeAddr addr = {0};
   if (!out || native_loc_addr_role(loc) != NATIVE_LOC_ADDR_ROLE_STORAGE)
     return 0;
   switch ((NativeLocKind)loc.kind) {
     case NATIVE_LOC_FRAME:
       addr.base_kind = NATIVE_ADDR_BASE_FRAME;
       addr.base.frame = loc.v.frame;
       addr.base_type = loc.type;
       break;
     case NATIVE_LOC_STACK:
       addr.base_kind = NATIVE_ADDR_BASE_FRAME;
       addr.base.frame = loc.v.stack.slot;
       addr.base_type = loc.type;
       addr.offset = loc.v.stack.offset;
       break;
     case NATIVE_LOC_ADDR:
       addr = loc.v.addr;
       break;
     default:
       return 0;
   }
   addr.offset += offset;
   *out = addr;
   return 1;
 }
 
 /* Resolve a scalar address recipe.  There is intentionally no part offset:
  * GLOBAL/FRAME_ADDR are one pointer value, not byte-addressable aggregate
  * storage.  A call marshaller that tries to split one must reject the shape. */
 static inline int native_loc_address_value(NativeLoc loc, NativeAddr* out) {
   NativeAddr addr = {0};
   if (!out || native_loc_addr_role(loc) != NATIVE_LOC_ADDR_ROLE_VALUE)
     return 0;
   switch ((NativeLocKind)loc.kind) {
     case NATIVE_LOC_FRAME_ADDR:
       addr.base_kind = NATIVE_ADDR_BASE_FRAME;
       addr.base.frame = loc.v.frame;
       addr.base_type = loc.type;
       break;
     case NATIVE_LOC_GLOBAL:
       addr.base_kind = NATIVE_ADDR_BASE_GLOBAL;
       addr.base.global.sym = loc.v.global.sym;
       addr.base.global.addend = loc.v.global.addend;
       addr.base_type = loc.type;
       break;
     default:
       return 0;
   }
   *out = addr;
   return 1;
 }
 
 /* Iterate the exact bytes carried by one ABI part as native load/store widths.
  * ABIArgPart.size is a semantic byte count, not the rounded size of its
  * register or stack carrier: a six-byte aggregate part must transfer 4+2
  * bytes, never one 8-byte access that can cross the source/destination object.
  *
  * Chunks are returned from low to high byte offsets, greedily choosing the
  * largest power-of-two width no greater than max_chunk. All native targets are
  * little-endian today, so the byte offset is also the register shift in bytes
  * when packing/unpacking a part. Physical ABI stack-slot sizing remains the
  * backend's separate responsibility. */
 typedef struct NativePartChunkIter {
   u32 total;
   u32 offset;
   u32 max_chunk;
 } NativePartChunkIter;
 
 static inline NativePartChunkIter native_part_chunks(u32 total,
                                                       u32 max_chunk) {
   NativePartChunkIter it;
   it.total = total;
   it.offset = 0;
   it.max_chunk = max_chunk;
   return it;
 }
 
 static inline int native_part_chunk_next(NativePartChunkIter* it,
                                          u32* offset_out, u32* size_out) {
   u32 chunk = 1u;
   u32 remaining;
   if (!it || !offset_out || !size_out || it->offset >= it->total ||
       it->max_chunk == 0u)
     return 0;
   remaining = it->total - it->offset;
   while (chunk <= remaining / 2u && chunk <= it->max_chunk / 2u) chunk <<= 1;
   *offset_out = it->offset;
   *size_out = chunk;
   it->offset += chunk;
   return 1;
 }
 
 /* Select the raw byte lane used for one ABI part of an immediate scalar.  The
  * complete value is only i64-wide, so bounds are explicit.  Offset zero keeps
  * the producer's signed numeric value (preserving established narrow-scalar
  * extension behavior); later parts are bit slices and are zero-extended. */
 static inline int native_loc_imm_part(NativeLoc loc, u32 offset, u32 size,
                                       i64* out) {
   u64 bits, mask;
   if (!out || loc.kind != NATIVE_LOC_IMM || size == 0u || size > 8u ||
       offset >= 8u || size > 8u - offset)
     return 0;
   if (offset == 0u) {
     *out = loc.v.imm;
     return 1;
   }
   bits = (u64)loc.v.imm >> (offset * 8u);
   mask = size == 8u ? ~(u64)0 : (((u64)1u << (size * 8u)) - 1u);
   *out = (i64)(bits & mask);
   return 1;
 }
 
 static inline int native_loc_is_fp(NativeLoc loc) {
   return (NativeAllocClass)loc.cls == NATIVE_REG_FP;
 }
 
 /* Narrow a register-or-immediate NativeLoc to the 16 B NativeRegLoc the §E.3
  * *_rr hooks take. Only NATIVE_LOC_REG / NATIVE_LOC_IMM forms reach these hooks
  * (the post-materialization contract), so this carries the register/immediate,
  * class, the cached width descriptor, and the type for the cold fallback. */
 static inline NativeRegLoc native_reg_loc_of(NativeLoc loc) {
   NativeRegLoc r;
   r.cls = loc.cls;
   r.szinfo = loc.szinfo;
   r.is_imm = (u8)(loc.kind == NATIVE_LOC_IMM);
   r.pad = 0;
   r.type = loc.type;
   if (loc.kind == NATIVE_LOC_IMM)
     r.v.imm = loc.v.imm;
   else
     r.v.reg = loc.v.reg;
   return r;
 }
 
 /* Reconstruct the full NativeLoc a fat binop/move/cmp/convert hook would have
  * received from a NativeRegLoc. Byte-identical by construction: the arch reads
  * only kind / cls / szinfo / type / v.{reg,imm}, all preserved here, and the
  * rest of the 48 B union is never consulted on this path. */
 static inline NativeLoc native_loc_from_reg(NativeRegLoc r) {
   NativeLoc loc;
   loc.kind = (u8)(r.is_imm ? NATIVE_LOC_IMM : NATIVE_LOC_REG);
   loc.cls = r.cls;
   loc.szinfo = r.szinfo;
   loc.shift = 0; /* O1-only L7 rider; the -O0 NDT fast path never sets it */
   loc.type = r.type;
   if (r.is_imm)
     loc.v.imm = r.v.imm;
   else
     loc.v.reg = r.v.reg;
   return loc;
 }
 
 /* NativeLoc.szinfo layout (see the field comment on NativeLoc). */
 #define NATIVE_SZINFO_VALID 0x01u
 #define NATIVE_SZINFO_SIZE_LOG2_SHIFT 1u
 #define NATIVE_SZINFO_SIZE_LOG2_MASK 0x07u
 
 /* size (bytes, 1..16) -> log2 bucket (0=1,1=2,2=4,3=8,4=16). */
 static inline u8 native_szinfo_log2(u32 size) {
   if (size <= 1u) return 0u;
   if (size <= 2u) return 1u;
   if (size <= 4u) return 2u;
   if (size <= 8u) return 3u;
   return 4u;
 }
 
 /* Stamp a register NativeLoc's cached width descriptor from its type, computing
  * cg_type_size exactly once. Called by the NDT at its register-loc choke point;
  * the arch backends then read loc.szinfo instead of re-querying. Only meaningful
  * for scalar (<=16B) reg locs; left invalid for a 0 type or an over-wide size so
  * the arch's own (panicking) query path runs. The mapped size is byte-identical
  * to native_type_size / aarch64's type_size32 for in-range scalars: a 0 type
  * maps to 8, a 0 size to 8 (the register-sized default both helpers apply). */
 static inline void native_loc_stamp_size(NativeTarget* t, NativeLoc* loc) {
   u64 n = loc->type ? cg_type_size(t->c, loc->type) : 8u;
   if (n == 0) n = 8u;
   /* Cache only exact-power-of-two scalar widths (1/2/4/8/16): the szinfo bucket
    * recovers the size exactly, so the cached value is bit-for-bit what
    * cg_type_size / native_type_size would return. Anything else (over-wide, or a
    * non-power-of-two aggregate that should never reach a register loc) is left
    * invalid and falls back to the live query. */
   if (n != 1u && n != 2u && n != 4u && n != 8u && n != 16u) return;
   loc->szinfo = (u8)(NATIVE_SZINFO_VALID | ((u32)native_szinfo_log2((u32)n)
                                             << NATIVE_SZINFO_SIZE_LOG2_SHIFT));
 }
 
 /* Byte size (1/2/4/8/16) recovered from a stamped szinfo descriptor. Only valid
  * when (szinfo & NATIVE_SZINFO_VALID). */
 static inline u32 native_szinfo_size(u8 szinfo) {
   u32 lg =
       ((u32)szinfo >> NATIVE_SZINFO_SIZE_LOG2_SHIFT) & NATIVE_SZINFO_SIZE_LOG2_MASK;
   return 1u << lg;
 }
 
 /* Scalar size/align, clamped to a usable register-sized default. Shared by the
  * backends whose scalars are at most pointer-width (x64, rv64); aa64 keeps its
  * own size query because it asserts on over-wide scalars. */
 /* Round v up to the next multiple of align (a power of two, or 0 → no-op).
  * Shared by every native backend's frame-layout math. */
 static inline u32 align_up_u32(u32 v, u32 align) {
   u32 mask = align ? align - 1u : 0u;
   return (v + mask) & ~mask;
 }
 
 static inline u32 native_type_size(NativeTarget* t, KitCgTypeId type) {
   u64 n = type ? cg_type_size(t->c, type) : 8u;
   if (n == 0) n = 8u;
   return (u32)n;
 }
 
 static inline u32 native_type_align(NativeTarget* t, KitCgTypeId type) {
   u64 n = type ? cg_type_align(t->c, type) : 8u;
   if (n == 0) n = 1u;
   if (n > 16u) n = 16u;
   return (u32)n;
 }
 
 static inline MemAccess native_mem_for_type(NativeTarget* t, KitCgTypeId type,
                                             u32 size) {
   MemAccess m;
   memset(&m, 0, sizeof m);
   m.type = type;
   m.size = size ? size : native_type_size(t, type);
   m.align = native_type_align(t, type);
   return m;
 }
 
 /* FP register class for a scalar type: a float value lives in an FP register
  * only when the hardware float ABI has a register that wide. flen comes from
  * the target float ABI (SINGLE->4, DOUBLE->8, SOFT->0); the DEFAULT/unset
  * sentinel maps to the pointer width, which preserves the historical "FP iff
  * float and <= 8 bytes" behavior for lp64d / x86-64 and yields the correct
  * rv32 soft-double result (double is 8 bytes > flen=4 on ilp32f, > 0 on ilp32,
  * so it is INT-class and never bit-cast through an FP register via fmv.d.x).
  * aa64 keeps its own (same predicate, distinct mem helper). */
 static inline NativeAllocClass native_class_for_type_fp_le8(NativeTarget* t,
                                                             KitCgTypeId type) {
   u32 flen;
   switch (t->c->target.float_abi) {
     case KIT_FLOAT_ABI_SINGLE:
       flen = 4u;
       break;
     case KIT_FLOAT_ABI_DOUBLE:
       flen = 8u;
       break;
     case KIT_FLOAT_ABI_SOFT:
       flen = 0u;
       break;
     default:
       flen = t->c->target.ptr_size;
       break; /* DEFAULT: historical */
   }
   if (type && flen && cg_type_is_float(t->c, type) &&
       cg_type_size(t->c, type) <= flen)
     return NATIVE_REG_FP;
   return NATIVE_REG_INT;
 }
 
 #endif