kit

ir.h (27896B)

---

 #ifndef KIT_IR_H
 #define KIT_IR_H
 
 #include "abi/abi.h"
 #include "arch/native_target.h"
 #include "core/arena.h"
 #include "core/core.h"
 
 /* Optimizer-private physical/virtual operand model.
  *
  * The semantic CG API now exposes only CGLocal/Label/CgTarget concepts.
  * O1 still needs a mutable pseudo-register and frame-slot view for liveness,
  * allocation, and MIR. Keep those names local to src/opt by remapping the old
  * optimizer tokens after including the semantic headers. Do not move these
  * fields back into cg/cgtarget.h. */
 typedef NativeFrameSlot OptFrameSlot;
 #define FrameSlot OptFrameSlot
 #define FRAME_SLOT_NONE NATIVE_FRAME_SLOT_NONE
 
 typedef NativeFrameSlotKind OptFrameSlotKind;
 #define FrameSlotKind OptFrameSlotKind
 #define FS_LOCAL NATIVE_FRAME_SLOT_LOCAL
 #define FS_PARAM NATIVE_FRAME_SLOT_PARAM
 #define FS_SPILL NATIVE_FRAME_SLOT_SPILL
 #define FS_ALLOCA NATIVE_FRAME_SLOT_ALLOCA
 #define FS_OUTGOING NATIVE_FRAME_SLOT_OUTGOING
 #define FS_SAVE NATIVE_FRAME_SLOT_SAVE
 
 typedef NativeFrameSlotFlag OptFrameSlotFlag;
 #define FSF_ADDR_TAKEN NATIVE_FRAME_SLOT_ADDR_TAKEN
 #define FSF_MEMORY_REQUIRED NATIVE_FRAME_SLOT_MEMORY_REQUIRED
 #define FSF_FIXED_OFFSET NATIVE_FRAME_SLOT_FIXED_OFFSET
 #define FSF_VOLATILE (1u << 8)
 
 typedef NativeFrameSlotDesc OptFrameSlotDesc;
 #define FrameSlotDesc OptFrameSlotDesc
 
 typedef NativeKnownFrameDesc OptCGKnownFrameDesc;
 #define CGKnownFrameDesc OptCGKnownFrameDesc
 
 typedef NativeAllocClass RegClass;
 #define RC_INT NATIVE_REG_INT
 #define RC_FP NATIVE_REG_FP
 #define RC_VEC NATIVE_REG_VEC
 
 /* The single float-ABI-aware value register-class decision (defined in ir.c).
  * All optimizer passes route through it so their classifications agree. */
 u8 opt_value_reg_class(Compiler* c, KitCgTypeId ty);
 
 #define CG_REG_ALLOCABLE NATIVE_REG_ALLOCABLE
 #define CG_REG_CALLER_SAVED NATIVE_REG_CALLER_SAVED
 #define CG_REG_CALLEE_SAVED NATIVE_REG_CALLEE_SAVED
 #define CG_REG_ARG NATIVE_REG_ARG
 #define CG_REG_RET NATIVE_REG_RET
 #define CG_REG_RESERVED NATIVE_REG_RESERVED
 
 typedef NativePhysRegInfo OptCGPhysRegInfo;
 #define CGPhysRegInfo OptCGPhysRegInfo
 
 typedef enum OptOperandKind {
   OPT_OPK_IMM = OPK_IMM,
   OPT_OPK_LOCAL = OPK_LOCAL,
   OPT_OPK_GLOBAL = OPK_GLOBAL,
   OPT_OPK_INDIRECT = OPK_INDIRECT,
   OPT_OPK_REG = 0xf0u,
   /* Post-allocation rematerialization recipe: the value is the address of a
    * frame slot, not the scalar stored in that slot. Semantic HIR never carries
    * this kind; location MIR and native emission own it. */
   OPT_OPK_FRAME_ADDR = 0xf1u,
   /* Post-allocation scalar spill home. Unlike OPK_LOCAL (semantic frame
    * storage/lvalue), this denotes the value stored in the frame slot. */
   OPT_OPK_STACK = 0xf2u,
 } OptOperandKind;
 #define OPK_REG OPT_OPK_REG
 #define OPK_FRAME_ADDR OPT_OPK_FRAME_ADDR
 #define OPK_STACK OPT_OPK_STACK
 
 /* Location kinds for the components of an OPK_INDIRECT effective address.
  * HIR is zero-initialized and therefore remains register-only. MIR may name a
  * spilled pointer/index by its stable frame home, or retain a cheap frame
  * address rematerialization recipe, without inventing a scratch-register
  * value whose lifetime leaks across instructions. */
 typedef enum OptIndirectLocKind {
   OPT_INDIRECT_REG = 0,
   OPT_INDIRECT_FRAME = 1,
   OPT_INDIRECT_FRAME_ADDR = 2,
 } OptIndirectLocKind;
 
 typedef enum OptOperandFlag {
   /* Transient walker annotation, never stored in IR. It lets callbacks that
    * lower or classify recipes distinguish an embedded effective-address
    * component from a first-class scalar operand without changing the compact
    * callback ABI. */
   OPT_OPERAND_WALK_INDIRECT_PART = 1u << 0,
 } OptOperandFlag;
 
 /* Operand riders (O1-PATTERNS L7/L8). Default 0 = no rider, so every existing
  * operand and every backend that does not implement the fold keeps behaving as
  * before. The recognition passes only stamp a rider after the consuming
  * NativeTarget advertises the matching capability hook
  * (can_fold_shift_into_alu / can_fold_extend_into_addr), so a backend that
  * cannot emit the folded form never sees a rider it would have to drop. */
 typedef enum OptOpIndexExt {
   OPT_IDX_EXT_NONE = 0, /* index used at full width (X register) */
   OPT_IDX_EXT_SXTW = 1, /* index is a 32-bit value sign-extended to 64 (W,sxtw) */
   OPT_IDX_EXT_UXTW = 2, /* index is a 32-bit value zero-extended to 64 (W,uxtw) */
 } OptOpIndexExt;
 
 typedef struct OptOperand {
   u8 kind;
   u8 cls;
   /* L7 shift rider: when nonzero and kind == OPK_REG, the register value is
    * pre-shifted left by `shift` (1..4) before the consuming ALU op uses it,
    * emitted as the shifted-register form (`add xD,xA,xS,lsl #shift`). 0 = the
    * register is used as-is. Only stamped on a binop's second source operand. */
   u8 shift;
   u8 flags; /* OptOperandFlag; stored operands normally have no flags */
   KitCgTypeId type;
   union {
     i64 imm;
     Reg reg;
     FrameSlot frame_slot;
     CGLocal local;
     struct {
       ObjSymId sym;
       i64 addend;
     } global;
     struct {
       Reg base;
       Reg index;
       u8 log2_scale;
       /* L8 extend rider (OptOpIndexExt): when SXTW/UXTW, `index` names a 32-bit
        * value that the addressing mode widens to 64 bits with the recorded
        * extend (`[Xbase, Wm, sxtw #log2_scale]`). NONE = full-width X index. */
       u8 index_ext;
       /* OptIndirectLocKind for `base` and `index`. */
       u8 base_kind;
       u8 index_kind;
       i32 ofs;
       /* The component value types travel with location MIR. Spill-slot
        * coloring is intentionally allowed to reuse a physical frame slot for
        * unrelated values, so the slot descriptor cannot be used to recover a
        * spilled base/index type after allocation. HIR initializes these from
        * the source PRegs; MIR preserves them while changing only location. */
       KitCgTypeId base_type;
       KitCgTypeId index_type;
     } ind;
   } v;
 } OptOperand;
 #define Operand OptOperand
 
 typedef enum OptCGLocalStorageKind {
   CG_LOCAL_STORAGE_FRAME,
   CG_LOCAL_STORAGE_REG,
 } OptCGLocalStorageKind;
 
 typedef struct OptCGLocalStorage {
   u8 kind;
   u8 pad[3];
   union {
     Reg reg;
     FrameSlot frame_slot;
   } v;
 } OptCGLocalStorage;
 #define CGLocalStorage OptCGLocalStorage
 #define CGLocalStorageKind OptCGLocalStorageKind
 
 typedef struct OptCGABIPart {
   Operand op;
   u32 offset;
 } OptCGABIPart;
 #define CGABIPart OptCGABIPart
 
 typedef struct OptCGABIValue {
   KitCgTypeId type;
   const ABIArgInfo* abi;
   Operand storage;
   CGABIPart* parts;
   u32 nparts;
 } OptCGABIValue;
 #define CGABIValue OptCGABIValue
 
 typedef enum OptCGCallPlanMoveKind {
   CG_CALL_PLAN_REG,
   CG_CALL_PLAN_STACK,
   CG_CALL_PLAN_TAIL_STACK,
   CG_CALL_PLAN_SRC_VALUE,
   CG_CALL_PLAN_SRC_ADDR,
 } OptCGCallPlanMoveKind;
 
 typedef struct OptCGCallPlanMove {
   Operand src;
   Operand dst;
   MemAccess mem;
   u32 src_offset;
   u32 stack_offset;
   Reg dst_reg;
   u8 src_kind;
   u8 dst_kind;
   u8 cls;
   u8 pad;
 } OptCGCallPlanMove;
 #define CGCallPlanMove OptCGCallPlanMove
 
 typedef struct OptCGCallPlanRet {
   Operand dst;
   MemAccess mem;
   u32 dst_offset;
   Reg src_reg;
   u8 cls;
   u8 pad[3];
 } OptCGCallPlanRet;
 #define CGCallPlanRet OptCGCallPlanRet
 
 typedef struct OptCGCallPlan {
   Operand callee;
   CGCallPlanMove* args;
   CGCallPlanRet* rets;
   u32 nargs;
   u32 nrets;
   u32 stack_arg_size;
   u32 clobber_mask[NATIVE_REG_CLASS_COUNT];
   u16 flags;
   u8 has_sret;
   u8 is_variadic;
 } OptCGCallPlan;
 #define CGCallPlan OptCGCallPlan
 
 typedef struct OptCGParamDesc {
   u32 index;
   Sym name;
   KitCgTypeId type;
   u32 size;
   u32 align;
   u32 flags;
   SrcLoc loc;
   CGLocalStorage storage;
   const ABIArgInfo* abi;
   const CGABIPart* incoming;
   u32 nincoming;
 } OptCGParamDesc;
 #define CGParamDesc OptCGParamDesc
 
 typedef struct OptCGCallDesc {
   KitCgTypeId fn_type;
   Operand callee;
   CGABIValue* args;
   CGABIValue ret;
   u32 nargs;
   u16 flags;
   u8 tail_policy;
   u8 pad;
   KitCgInlinePolicy inline_policy;
   const ABIFuncInfo* abi;
 } OptCGCallDesc;
 #define CGCallDesc OptCGCallDesc
 
 typedef struct OptCGFuncDesc {
   ObjSymId sym;
   ObjSecId text_section_id;
   ObjGroupId group_id;
   KitCgTypeId fn_type;
   KitCgTypeId result_type; /* KIT_CG_TYPE_NONE/void == no result */
   const CGParamDesc* params;
   u32 nparams;
   SrcLoc loc;
   u32 flags;
   KitCgInlinePolicy inline_policy;
   u8 atomize;
   u8 pad[3];
   const ABIFuncInfo* abi;
 } OptCGFuncDesc;
 #define CGFuncDesc OptCGFuncDesc
 
 typedef struct OptCGScopeDesc {
   u8 kind;
   u8 pad[3];
   Label break_label;
   Label continue_label;
   Operand cond;
   KitCgTypeId result_type;
 } OptCGScopeDesc;
 #define CGScopeDesc OptCGScopeDesc
 
 /* SSA value id. VAL_NONE=0 is reserved as a sentinel. Recorded CG virtual
  * registers live in Func's pseudo-register table; before pseudo-reg SSA,
  * OPK_REG operands carry those mutable Reg ids. After pseudo-reg SSA, OPK_REG
  * operands carry Val ids. The mode is explicit on Func, not encoded in the
  * numeric id. */
 typedef u32 Val;
 #define VAL_NONE 0u
 
 typedef Reg PReg;
 #define PREG_NONE ((PReg)REG_NONE)
 
 typedef u32 InstId;
 #define INST_ID_NONE 0u
 
 /* IROps mirror the CGTarget surface 1:1 plus a handful of SSA-only ops
  * (IR_PHI, IR_CONST_I, IR_CONST_BYTES). Each CGTarget method records as
  * exactly one Inst, so level-1 replay is a flat walk that re-issues
  * each Inst as one wrapped target call. doc/OPT.md §1.1. */
 typedef enum IROp {
   IR_NOP,
   /* SSA-only constants (used by const-propagation; recording uses
    * load_imm/load_const which become IR_LOAD_IMM/IR_LOAD_CONST). */
   IR_CONST_I,
   IR_CONST_BYTES,
 
   /* Param/frame declarations recorded from CGTarget.param. The frame
    * slot id table lives separately on Func; this op records the
    * sequence point so replay can re-issue target->param in order. */
   IR_PARAM_DECL,
 
   /* Address-bearing data movement. */
   IR_LOAD_IMM,       /* opnds[0] dst REG; extra.imm = imm */
   IR_LOAD_CONST,     /* opnds[0] dst REG; extra.cbytes */
   IR_COPY,           /* opnds[0] dst REG, opnds[1] src REG */
   IR_LOAD,           /* opnds[0] dst REG, opnds[1] addr; extra.mem */
   IR_STORE,          /* opnds[0] addr, opnds[1] src REG|IMM; extra.mem */
   IR_ADDR_OF,        /* opnds[0] dst REG, opnds[1] lv (LOCAL|GLOBAL|INDIRECT) */
   IR_TLS_ADDR_OF,    /* opnds[0] dst REG; extra.aux = IRTlsAux */
   IR_AGG_COPY,       /* opnds[0] dst, opnds[1] src; extra.aux = IRAggAux */
   IR_AGG_SET,        /* opnds[0] dst, opnds[1] byte; extra.aux = IRAggAux */
   IR_BITFIELD_LOAD,  /* opnds[0] dst REG, opnds[1] record; extra.aux */
   IR_BITFIELD_STORE, /* opnds[0] record, opnds[1] src; extra.aux */
 
   /* Arithmetic / cmp / convert. opnds[0] dst REG, [1] a, optionally [2] b.
    * extra.imm carries the BinOp/UnOp/CmpOp/ConvKind tag. */
   IR_BINOP,
   IR_UNOP,
   IR_CMP,
   IR_CONVERT,
 
   /* Calls. extra.aux = IRCallAux (see below). defs = result OPK_REG ids:
    * PReg before opt_build_reg_ssa, Val after it. */
   IR_CALL,
 
   /* Phis. extra.aux = IRPhiAux. */
   IR_PHI,
 
   /* Control flow / scopes. */
   IR_BR,              /* unconditional. block.succ[0] = target block id. */
   IR_CONDBR,          /* opnds[0] cond REG; succ[0] = true, succ[1] = false. */
   IR_CMP_BRANCH,      /* fused. opnds = [a, b]; extra.imm = CmpOp;
                          succ[0] = taken, succ[1] = fallthrough. */
   IR_SWITCH,          /* multi-target structured switch. opnds[0] = selector;
                          extra.aux = IRSwitchAux; succ[0..ncases) = case
                          blocks, succ[ncases] = default block. */
   IR_INDIRECT_BRANCH, /* opnds[0] = addr REG; extra.aux = IRIndirectAux.
                          succ[0..nvalid) = the valid target blocks. */
   IR_LOAD_LABEL_ADDR, /* opnds[0] dst REG; extra.imm = target block id. */
   IR_LOCAL_STATIC_DATA_BEGIN,      /* extra.aux = CgIrLocalStaticBeginAux */
   IR_LOCAL_STATIC_DATA_WRITE,      /* extra.aux = CgIrLocalStaticWriteAux */
   IR_LOCAL_STATIC_DATA_LABEL_ADDR, /* extra.aux = CgIrLocalStaticLabelAux */
   IR_LOCAL_STATIC_DATA_END,
   IR_RET,         /* extra.aux = IRRetAux* (NULL for void). */
   IR_UNREACHABLE, /* control terminator; no operands, no successors. */
   IR_SCOPE_BEGIN, /* extra.aux = IRScopeAux. */
   IR_SCOPE_END,   /* extra.imm = scope id (Val). */
   IR_BREAK_TO,    /* extra.imm = scope id (Val). */
   IR_CONTINUE_TO, /* extra.imm = scope id (Val). */
 
   /* alloca / variadics. */
   IR_ALLOCA,   /* opnds = [dst REG, size]; extra.imm = align */
   IR_VA_START, /* opnds = [ap] */
   IR_VA_ARG,   /* opnds = [dst REG, ap]; extra.aux = KitCgTypeId*/
   IR_VA_END,   /* opnds = [ap] */
   IR_VA_COPY,  /* opnds = [dst, src] */
 
   /* Atomics. */
   IR_ATOMIC_LOAD,  /* opnds = [dst, addr]; extra.aux = IRAtomicAux */
   IR_ATOMIC_STORE, /* opnds = [addr, src]; extra.aux = IRAtomicAux */
   IR_ATOMIC_RMW,   /* opnds = [dst, addr, val]; extra.aux */
   IR_ATOMIC_CAS,   /* defs = [prior, ok] OPK_REG ids; extra.aux = IRCasAux */
   IR_FENCE,        /* extra.imm = KitCgMemOrder */
 
   /* Inline asm. extra.aux = IRAsmAux. */
   IR_ASM_BLOCK,
 
   /* Compiler intrinsics (see arch.h IntrinKind). extra.aux = IRIntrinAux. */
   IR_INTRINSIC,
 
   /* set_loc is *not* an IR op — SrcLoc is sticky on Inst.loc, applied at
    * recording time from the wrapper's pending_loc. */
 } IROp;
 
 /* ---- per-op aux structs ---- */
 
 typedef struct IRTlsAux {
   ObjSymId sym;
   i64 addend;
 } IRTlsAux;
 
 typedef struct IRSwitchAuxCase {
   u64 value;
   u32 block; /* successor block id */
 } IRSwitchAuxCase;
 
 typedef struct IRSwitchAux {
   KitCgTypeId selector_type;
   IRSwitchAuxCase* cases;
   u32 ncases;
   u32 default_block; /* if no default, this is the post-switch fallthrough */
   u8 has_default;    /* 1 if frontend supplied an explicit default */
   u8 hint;           /* KitCgSwitchHint */
   u8 pad[2];
 } IRSwitchAux;
 
 typedef struct IRIndirectAux {
   u32* targets; /* successor block ids; same as Block.succ[0..ntargets) */
   u32 ntargets;
 } IRIndirectAux;
 
 typedef struct IRAggAux {
   AggregateAccess access;
 } IRAggAux;
 
 typedef struct IRBitFieldAux {
   BitFieldAccess access;
 } IRBitFieldAux;
 
 #define OPT_REG_CLASSES NATIVE_REG_CLASS_COUNT
 #define OPT_MAX_HARD_REGS NATIVE_MAX_HARD_REGS
 
 /* One per-class clobber bitmask set; see Func.inst_clobbers. */
 typedef NativeRegMaskSet OptInstClobberMask;
 #define OPT_MAX_EMIT_TEMPS 4u
 
 typedef struct IRGepAux {
   KitCgTypeId base_type;
   u32 nindices;
   i64* indices;
 } IRGepAux;
 
 typedef struct IRPhiAux {
   u32 npreds;
   u32* pred_blocks;
   Val* pred_vals;
   u32 slot_id; /* 0 if not from mem2reg; else 1-based FrameSlot id */
   u32 reg_id;  /* 0 if not from mutable-pseudo SSA; else original Reg id */
 } IRPhiAux;
 
 #define IRF_NO_COALESCE (1u << 0)
 
 /* IR_CALL aux. The CGTarget interface is rich enough that we keep the
  * full descriptor for replay; SSA passes inspect args/results in their
  * Val form via the CGABIValue.storage.v.reg fields where applicable. */
 typedef struct IRCallAux {
   CGCallDesc desc;
   CGCallPlan plan;
   u8 plan_valid;
   u8 use_plan_replay;
   u8 pad[2];
   /* Result Vals (one per ABI-decomposed return part). 0 for void. */
   u32 nresults;
   Val* results;
   /* For SSA-aware passes: the call may have args that are REG operands
    * (carrying Val uses). They live in desc.args[i].storage.v.reg or
    * desc.args[i].parts[k].op.v.reg. */
 } IRCallAux;
 
 typedef struct IRRetAux {
   u8 present; /* 0 → void return; ret(NULL) at replay */
   CGABIValue val;
 } IRRetAux;
 
 typedef struct IRScopeAux {
   CGScopeDesc desc;
   u32 scope_id; /* 1-based; the CGScope handed back to the caller */
   /* The caller-supplied break/continue labels translated to block ids; if the
    * desc passed LABEL_NONE we leave 0 (unused — break_to/continue_to is
    * illegal in that case). */
   u32 loop_break_block;
   u32 loop_continue_block;
 } IRScopeAux;
 
 typedef struct IRAtomicAux {
   MemAccess mem;
   KitCgMemOrder mo;
   u8 op; /* KitCgAtomicOp; valid for IR_ATOMIC_RMW */
 } IRAtomicAux;
 
 typedef struct IRCasAux {
   MemAccess mem;
   KitCgMemOrder success;
   KitCgMemOrder failure;
 } IRCasAux;
 
 typedef struct IRAsmRegRequirement {
   /* A register constraint resolved once at the HIR -> native-policy boundary.
    * It remains an instruction-local placement request; regalloc never turns it
    * into a persistent MIR location. */
   u32 allowed_mask; /* 0 means any operand register in `cls` */
   i32 fixed_reg;    /* -1 means no fixed register */
   u8 cls;           /* RegClass */
   u8 present;       /* constraint requires a register */
   u8 pad[2];
 } IRAsmRegRequirement;
 
 typedef struct IRAsmAux {
   const char* tmpl;
   AsmConstraint* outs;
   AsmConstraint* ins;
   Sym* clobbers;
   Operand*
       out_ops;     /* nout slots; the wrapped target may fill in REG location */
   Operand* in_ops; /* nin slots; recorded by w_asm_block, xlat'd at replay */
   u32 nout, nin, nclob;
   /* KitCgAsmClobberAbiSet bits: an arch-neutral "clobbers the whole caller/
    * callee-saved set" the backend expands against its own register file. */
   u32 clobber_abi_sets;
   /* Filled by opt_machinize from backend register-name resolution. */
   u32 clobber_mask[OPT_REG_CLASSES];
   IRAsmRegRequirement* out_reg_reqs; /* nout */
   IRAsmRegRequirement* in_reg_reqs;  /* nin */
   u8 has_memory_constraint;
   u8 pad[3];
 } IRAsmAux;
 
 typedef struct IRIntrinAux {
   IntrinKind kind;
   Operand* dsts;    /* ndst */
   Operand* args;    /* narg */
   Val* result_vals; /* one per dst that's a REG, parallel to dsts */
   u32 ndst, narg;
 } IRIntrinAux;
 
 typedef struct IRParamDeclAux {
   CGParamDesc desc;
 } IRParamDeclAux;
 
 /* ---- frame slots / params ---- */
 
 typedef struct IRFrameSlot {
   FrameSlot id;
   KitCgTypeId type;
   Sym name;
   SrcLoc loc;
   u32 size;
   u32 align;
   /* Spill-traffic priority (O1.md W1.0). Aggregated from the allocator's final
    * spill-slot assignment: the saturating sum of the spill cost of every
    * coalesce group assigned to this (possibly reused) slot, where the per-group
    * cost is `2*use_freq + def_freq + live_across_call_freq + live_block_freq`
    * (pass_live.c). The known-frame emitter presents slots to the backend in
    * descending-priority order so the hottest spills get the smallest final frame
    * displacement (disp8 on x64, inside the scaled reach on aa64, inside the
    * +/-2KB imm12 window on rv64). 0 for homed/address-taken locals (v1). */
   u32 priority;
   u8 kind; /* FrameSlotKind */
   u8 pad;
   u16 flags; /* FrameSlotFlag */
 } IRFrameSlot;
 
 typedef struct IRParam {
   u32 index;
   Sym name;
   KitCgTypeId type;
   u32 size;
   u32 align;
   u32 flags; /* CGLocalFlag */
   CGLocalStorage storage;
   const ABIArgInfo* abi;
   SrcLoc loc;
 } IRParam;
 
 typedef struct IRLocal {
   u32 id;
   CGLocalDesc desc;
   CGLocalStorage storage;
   FrameSlot home_slot;
   u8 address_taken;
   u8 pad[3];
 } IRLocal;
 
 /* ---- Inst / Block / Func ---- */
 
 typedef struct Inst {
   u16 op;
   u16 flags;
   InstId id;
   SrcLoc loc; /* sticky from CGTarget.set_loc at recording */
   KitCgTypeId type;
   /* Primary and multi-result OPK_REG definitions. Before opt_build_reg_ssa,
    * these hold PReg ids matching destination operands. After opt_build_reg_ssa,
    * they hold Val ids. */
   Val def;
   u32 ndefs;
   Val* defs;
   /* Operands. We use Operand instead of Val so that the original
    * CGTarget call shape (IMM / LOCAL / GLOBAL / INDIRECT in addition to
    * REG) round-trips at replay. Before opt_build_reg_ssa, OPK_REG operands
    * are mutable PReg uses/defs; after it, they are Val uses/defs. */
   u32 nopnds;
   Operand* opnds;
   union {
     i64 imm;
     ConstBytes cbytes;
     MemAccess mem;
     void* aux;
   } extra;
 } Inst;
 
 typedef struct Block {
   u32 id;
   Inst* insts;
   u32 ninsts, cap;
   u32* preds;
   u32 npreds;
   /* Variable-length successor list. ir_block_new arena-allocates a
    * 2-slot array (large enough for ordinary terminators); ops with
    * more successors (IR_SWITCH, IR_INDIRECT_BRANCH) reallocate via
    * ir_block_set_nsucc before writing. nsucc names the prefix in use. */
   u32* succ;
   u32 nsucc;
   u32 succ_cap;
   u32 loop_depth;
   u32 frequency;
   /* MCLabel id pre-allocated by w_label_new for blocks created via
    * cg_label_new. Stable from recording through pass_emit. Blocks
    * created internally by opt (fallthroughs, scope-implicit blocks)
    * leave this at MC_LABEL_NONE; pass_emit's ensure_label mints one
    * on demand for those. */
   MCLabel mc_label;
 } Block;
 
 typedef struct MFunc {
   Block* blocks;
   u32 nblocks;
   u32 blocks_cap;
   u32 entry;
   u32* emit_order;
   u32 emit_order_n;
   u32 emit_order_cap;
 } MFunc;
 
 typedef enum OptAllocKind {
   OPT_ALLOC_NONE,
   OPT_ALLOC_HARD,
   OPT_ALLOC_SPILL,
 } OptAllocKind;
 
 typedef enum OptLocKind {
   OPT_LOC_NONE,
   OPT_LOC_HARD,
   OPT_LOC_STACK,
 } OptLocKind;
 
 typedef struct OptLoc {
   u8 kind;
   u8 cls;
   Reg hard_reg;
   FrameSlot spill_slot;
 } OptLoc;
 
 typedef struct OptPRegInfo {
   u32 first_pos;
   u32 last_pos;
   u32 live_length;
   u32 frequency; /* legacy aggregate priority score */
   u32 use_freq;
   u32 def_freq;
   u32 live_block_freq;
   u32 live_across_call_freq;
   u32 spill_cost;
   Reg hard_reg;
   FrameSlot spill_slot;
   u8 alloc_kind;         /* OptAllocKind */
   u8 cls;                /* RegClass */
   i8 preferred_hard_reg; /* soft hint for allocator; -1 = no hint */
   u8 pad[1];
   /* Authoritative correctness constraint. Bit r means this unsplit PReg may
    * not be allocated to hard register r because an instruction boundary in
    * its live range reserves or destroys that register. ABI placement
    * preferences are independent soft hints and never mutate this mask. */
   u32 forbidden_hard_regs;
 } OptPRegInfo;
 
 typedef enum OptUseKind {
   OPT_USE_OPERAND,
   OPT_USE_INDIRECT_BASE,
   OPT_USE_INDIRECT_INDEX,
   OPT_USE_PHI_INPUT,
 } OptUseKind;
 
 typedef struct OptUse {
   Val val;
   u32 block;
   u32 inst;
   InstId inst_id;
   u32 next_for_val;
   u32 operand_index;
   u32 phi_pred_index;
   Operand* operand;
   u8 kind; /* OptUseKind */
   u8 pad[3];
 } OptUse;
 
 typedef struct Func {
   Arena* arena;
   Compiler* c;
   CGFuncDesc desc; /* preserved for level-1 replay func_begin */
   ObjSymId name;   /* alias for desc.sym (kept for older callers) */
   KitCgTypeId type;
   Block* blocks;
   u32 nblocks, blocks_cap;
   u32 entry;
 
   IRFrameSlot* frame_slots;
   u32 nframe_slots, frame_slots_cap;
   IRParam* params;
   u32 nparams, params_cap;
   IRLocal* locals;
   u32 nlocals, locals_cap;
 
   /* Value table. Index 0 is VAL_NONE; first allocated Val is 1. */
   u32* val_def_block;
   u32* val_def_inst;
   KitCgTypeId* val_type;
   u8* val_cls; /* RegClass per Val, used by replay to reconstruct REG operands
                 */
   u32 nvals, vals_cap;
 
   /* Mutable pseudo-register table. Index 0 is unused so CG virtual Reg ids can
    * be used directly. During initial recording and O1, OPK_REG operands name
    * these persistent storage locations. O2 converts them to Val ids with
    * opt_build_reg_ssa before running SSA passes. */
   KitCgTypeId* preg_type;
   u8* preg_cls;
   u32 npregs, pregs_cap;
 
   /* Scope id table. Indexed by scope_id (1-based). Values map to
    * IRScopeAux entries (via the IR_SCOPE_BEGIN inst). Stored as a flat
    * pointer table for O(1) lookup during scope_end/break/continue
    * recording and replay. */
   Inst** scope_aux_inst;
   u32 nscopes, scopes_cap;
 
   /* Emit order: the sequence in which blocks first became `cur` during
    * recording. This is the natural order CG's emit cursor visited each
    * block, so replay must follow it (block-creation order can differ —
    * e.g. label_new(L) precedes cmp_branch but the cmp_branch's
    * fallthrough block is what physically follows the cmp_branch in
    * code). Blocks not present here are unreachable / unplaced; replay
    * skips them. */
   u32* emit_order;
   u32 emit_order_n, emit_order_cap;
 
   Target opt_target;
   u8 opt_has_target;
   u8 opt_rewritten;
   u8 opt_reg_ssa;
   u8 pad0;
   u16 opt_live_words;
   u32 opt_used_loc_words;
   u32 opt_alloc_hard_loc_words;
   u32 opt_alloc_stack_loc_words;
   u32 opt_alloc_stack_slots;
   u32 opt_position_count;
   u64 opt_alloc_hard_point_visits;
   u64 opt_alloc_stack_point_visits;
   u64 opt_alloc_hard_word_ors;
   u64 opt_alloc_stack_word_ors;
   u64 opt_alloc_hard_mark_points;
   u64 opt_alloc_stack_mark_points;
   u64 opt_rewrite_inserted_insts;
   u64 opt_rewrite_live_words_touched;
   u64 opt_dde_live_words_touched;
   u64 opt_coalesce_moves_seen;
   u64 opt_coalesce_candidates;
   u64 opt_coalesce_conflicts;
   u64 opt_coalesce_merge_attempts;
   u64 opt_coalesce_merges;
   InstId next_inst_id;
   /* Per-instruction fixed-register clobbers (one bitmask per reg class),
    * indexed by InstId, sized [next_inst_id]. Derived from the target's
    * machine_op_clobbers hook by opt_machinize_native, then refreshed at the
    * final pre-allocation HIR-shape boundary. Consulted by the allocator
    * (pass_lower) to keep values live across an instruction out of the registers
    * its encoding destroys (x86 idiv → rax/rdx, etc.). NULL when no instruction
    * clobbers. */
   OptInstClobberMask* inst_clobbers;
   u32 inst_clobbers_cap;
   OptPRegInfo* preg_info; /* indexed by the current allocation reg namespace */
   OptLoc* preg_locs;      /* canonical final allocation locations by PReg */
   MFunc* mir;             /* physical post-allocation IR; HIR stays virtual */
   u32* opt_coalesce_parent;
   u32* opt_coalesce_size;
   /* Set when the linear O1 move-coalescing pass (pass_coalesce.c,
    * opt_coalesce_linear) has populated opt_coalesce_parent in the no-SSA O1
    * regalloc path. Distinguishes "O1 with a union-find" from the parked O2
    * matrix coalescer (which also sets opt_coalesce_parent): the O1 immediate
    * fold-through-copy in pass_combine.c keys on this, not on the mere presence
    * of opt_coalesce_parent. */
   int opt_o1_coalescing;
 
   OptUse* opt_uses;
   u32 opt_nuses, opt_uses_cap;
   u32* opt_first_use_by_val; /* indexed by Val, OPT_USE_NONE if no uses */
   u32 opt_first_use_by_val_cap;
   u32 opt_valid_analyses;
 
   Reg opt_hard_regs[OPT_REG_CLASSES][OPT_MAX_HARD_REGS];
   u32 opt_hard_reg_count[OPT_REG_CLASSES];
   CGPhysRegInfo opt_phys_regs[OPT_REG_CLASSES][OPT_MAX_HARD_REGS];
   u32 opt_phys_reg_count[OPT_REG_CLASSES];
   Reg emit_temp_regs[OPT_REG_CLASSES][OPT_MAX_EMIT_TEMPS];
   u32 emit_temp_reg_count[OPT_REG_CLASSES];
   /* Backend-private inline-asm staging registers. Kept as a mask because MIR
    * verification only needs to enforce that they never become value
    * locations; final asm emission leases the ordered descriptor list. */
   u32 asm_temp_mask[OPT_REG_CLASSES];
   u32 opt_caller_saved[OPT_REG_CLASSES]; /* bit r set if hard reg r is
                                             caller-saved */
   u32 opt_callee_saved[OPT_REG_CLASSES];
   u32 opt_reserved_regs[OPT_REG_CLASSES];
   u32 opt_arg_regs[OPT_REG_CLASSES];
   u32 opt_ret_regs[OPT_REG_CLASSES];
 } Func;
 
 /* ---- API ---- */
 
 Func* ir_func_new(Compiler*, const CGFuncDesc*);
 
 u32 ir_block_new(Func*);
 FrameSlot ir_frame_slot_new(Func*, const FrameSlotDesc*);
 void ir_param_add(Func*, const CGParamDesc*);
 u32 ir_local_add(Func*, const CGLocalDesc*, CGLocalStorage);
 
 Val ir_alloc_val(Func*, KitCgTypeId, u8 cls);
 void ir_ensure_val(Func*, Val, KitCgTypeId, u8 cls);
 PReg ir_alloc_preg(Func*, KitCgTypeId, u8 cls);
 void ir_ensure_preg(Func*, PReg, KitCgTypeId, u8 cls);
 
 Inst* ir_emit(Func*, u32 block, IROp);
 InstId ir_inst_id_new(Func*);
 void ir_assign_inst_id(Func*, Inst*);
 
 /* Resize a block's successor array. Used by ops with >2 successors
  * (IR_SWITCH, IR_INDIRECT_BRANCH). Always sets nsucc to n. */
 void ir_block_set_nsucc(Func*, u32 block, u32 n);
 
 /* Append `block` to f->emit_order if not already present. Called by
  * the wrapper whenever cur transitions to a block. */
 void ir_note_emit(Func*, u32 block);
 /* Append Inst to block; caller fills op-specific fields. The Inst is
  * arena-resident; its address is stable until the Block.insts array is
  * reallocated by phi insertion (which fixes up references). */
 
 #endif