kit

cgtarget.h (33533B)

---

 #ifndef KIT_CG_CGTARGET_H
 #define KIT_CG_CGTARGET_H
 
 #include <kit/cg.h>
 #include <kit/compile.h>
 
 #include "core/core.h"
 #include "obj/obj.h"
 
 typedef u32 CGLocal;
 #define CG_LOCAL_NONE 0u
 
 /* Vector / SIMD forward compat: vector ops will arrive as new variants in
  * the BinOp, UnOp, CmpOp, ConvKind families. Backend switches over these
  * enums must use `default:` (unreachable / panic) rather than exhaustive
  * case lists, so adding a new variant later does not silently mis-handle on
  * backends that haven't been taught about it. Vector loads/stores reuse the
  * existing load/store methods with vector-typed Operands and appropriate
  * MemAccess. */
 
 /* Integer/float binary ops. Edge-case semantics are fully defined (no undefined
  * behavior) in doc/IR.md: iadd/isub/imul (and UO_NEG) wrap modulo 2^width;
  * sdiv/udiv/srem/urem and the shifts have a portable default plus an opt-in
  * target-defined mode selected per instruction via CgIrInstFlag (src/cg/ir.h).
  * FP ops are strict IEEE-754 in the target's default rounding/exception
  * environment; there is no FP remainder op (the frontend calls fmod). */
 typedef enum BinOp {
   BO_IADD,
   BO_ISUB,
   BO_IMUL,
   BO_SDIV,
   BO_UDIV,
   BO_SREM,
   BO_UREM,
   BO_FADD,
   BO_FSUB,
   BO_FMUL,
   BO_FDIV,
   BO_AND,
   BO_OR,
   BO_XOR,
   BO_SHL,
   BO_SHR_S,
   BO_SHR_U,
 } BinOp;
 
 typedef enum UnOp {
   UO_NEG,
   UO_FNEG,
   UO_NOT,  /* logical: 0/1 */
   UO_BNOT, /* bitwise ~  */
 } UnOp;
 
 /* Compares producing i1. The 10 integer members (CMP_EQ..CMP_GE_U) are total
  * and 1:1 with KitCgIntCmpOp; on integers CMP_EQ/CMP_NE are plain equality.
  *
  * The 12 floating-point members form a disjoint block laid out *after* the
  * integer block, in the same order as the public KitCgFpCmpOp, and are
  * IEEE-complete: each predicate encodes ordered (NaN -> false) vs unordered
  * (NaN -> true) explicitly, so the distinction reaches every backend. The
  * identity used throughout the backends is unordered-R == NOT(ordered-not-R)
  * (e.g. ULT == !(OGE), UNE == !(OEQ)). CMP_OEQ_F is the FP boundary: an op is a
  * floating compare iff op >= CMP_OEQ_F. */
 typedef enum CmpOp {
   CMP_EQ,
   CMP_NE,
   CMP_LT_S,
   CMP_LE_S,
   CMP_GT_S,
   CMP_GE_S,
   CMP_LT_U,
   CMP_LE_U,
   CMP_GT_U,
   CMP_GE_U,
   /* Ordered FP relationals (NaN -> false). */
   CMP_OEQ_F,
   CMP_ONE_F,
   CMP_OLT_F,
   CMP_OLE_F,
   CMP_OGT_F,
   CMP_OGE_F,
   /* Unordered FP relationals (NaN -> true). */
   CMP_UEQ_F,
   CMP_UNE_F,
   CMP_ULT_F,
   CMP_ULE_F,
   CMP_UGT_F,
   CMP_UGE_F,
 } CmpOp;
 
 /* Conversions. Widths must order correctly (sext/zext widen, trunc narrows,
  * bitcast preserves byte size). itof, fext, and ftrunc round to nearest-even;
  * ftoi_s/ftoi_u round toward zero with a portable saturating out-of-range
  * default (NaN -> 0) and an opt-in target-defined mode
  * (CG_IR_INST_TARGET_FPTOINT_EDGES in src/cg/ir.h). Full rules in doc/IR.md. */
 typedef enum ConvKind {
   CV_SEXT,
   CV_ZEXT,
   CV_TRUNC,
   CV_ITOF_S,
   CV_ITOF_U,
   CV_FTOI_S,
   CV_FTOI_U,
   CV_FEXT,
   CV_FTRUNC,
   CV_BITCAST,
 } ConvKind;
 
 /* Atomic op kinds (KitCgAtomicOp) and memory orders (KitCgMemOrder) come
  * straight from the public API. Which orders are legal depends on the atomic
  * op: load excludes release/acq_rel; store excludes acquire/consume/acq_rel;
  * CAS failure order is one of relaxed/consume/acquire/seq_cst and no stronger
  * than success. See the Atomics edge-case rules in doc/IR.md (mirrored by
  * kit_cg_atomic_is_legal). */
 
 /* Compiler-intrinsic kinds dispatched through CgTarget.intrinsic and carried
  * on IR_INTRINSIC via IRIntrinAux.kind. The set is bounded: a backend
  * must know each one to choose inline-vs-libcall. Hint intrinsics
  * (EXPECT/TRAP/PREFETCH/ASSUME_ALIGNED) ride the same dispatch:
  * the backend decides whether they emit an instruction or a no-op.
  * `unreachable` is NOT here: it is a first-class control terminator with
  * its own CgTarget hook (see below), not an intrinsic.
  *
  * Not every C builtin lives here. Parser-evaluated builtins
  * (__builtin_offsetof, __builtin_constant_p, __builtin_choose_expr,
  * __builtin_types_compatible_p) fold at parse and never reach IR. Builtins
  * that already have dedicated CgTarget methods (alloca, va_*, atomics) keep
  * them. Returns-twice and no-return control intrinsics use this dispatch so
  * opt can preserve their CFG effects without growing backend vtable hooks. */
 typedef enum IntrinKind {
   INTRIN_NONE = 0,
 
   /* bit ops */
   INTRIN_POPCOUNT,
   INTRIN_CTZ,
   INTRIN_CLZ,
   INTRIN_BSWAP,
 
   /* memory. memcpy/memset are the dedicated copy_bytes/set_bytes hooks
    * (kit_cg_memcpy/_memset); only memmove flows through the intrinsic path. */
   INTRIN_MEMMOVE,
   INTRIN_PREFETCH,
   INTRIN_ASSUME_ALIGNED,
 
   /* hints */
   INTRIN_EXPECT,
   INTRIN_TRAP,
 
   /* OS trap: args[0] is the syscall number, args[1..6] are integer/pointer
    * payloads; dsts[0] receives the target long result. */
   INTRIN_SYSCALL,
 
   /* non-local control */
   INTRIN_SETJMP,
   INTRIN_LONGJMP,
 
   /* checked arith — multi-result (value, overflow_flag) */
   INTRIN_SADD_OVERFLOW,
   INTRIN_UADD_OVERFLOW,
   INTRIN_SSUB_OVERFLOW,
   INTRIN_USUB_OVERFLOW,
   INTRIN_SMUL_OVERFLOW,
   INTRIN_UMUL_OVERFLOW,
 
   /* baremetal CPU control — single-instruction, no operands unless noted.
    * dsts/args empty except IRQ_SAVE (dsts[0] = saved interrupt state) and
    * IRQ_RESTORE (args[0] = state to restore). Privileged forms (WFI/WFE/SEV
    * and the IRQ family) trap at user level; backends still emit the one
    * instruction and frontends gate any runtime use behind a capability test. */
   INTRIN_CPU_NOP,
   INTRIN_CPU_YIELD,
   INTRIN_WFI,
   INTRIN_WFE,
   INTRIN_SEV,
   INTRIN_ISB,
   INTRIN_DMB,
   INTRIN_DSB,
   INTRIN_IRQ_SAVE,
   INTRIN_IRQ_RESTORE,
   INTRIN_IRQ_ENABLE,
   INTRIN_IRQ_DISABLE,
 
   /* frame-pointer-chain introspection — value-producing, single immediate
    * operand (the constant level). args[0] is the level (OPK_IMM); dsts[0] is
    * the void* result. Lowered as an unrolled FP walk; modeled as an ordinary
    * frame-dependent memory read (IR_INTRINSIC is already conservatively
    * side-effecting in opt, so it is never hoisted, CSE'd, or eliminated). */
   INTRIN_FRAME_ADDRESS,
   INTRIN_RETURN_ADDRESS,
 } IntrinKind;
 
 typedef enum OpKind {
   OPK_IMM,
   OPK_LOCAL,    /* typed semantic local */
   OPK_GLOBAL,   /* address: symbol+addend, not a load */
   OPK_INDIRECT, /* [local + ofs], with optional indexed local */
 } OpKind;
 
 typedef enum CGLocalFlag {
   CG_LOCAL_FLAG_NONE = 0,
   CG_LOCAL_ADDR_TAKEN = 1u << 0,
   CG_LOCAL_MEMORY_REQUIRED = 1u << 1,
 } CGLocalFlag;
 
 typedef struct CGLocalDesc {
   KitCgTypeId type;
   Sym name;
   SrcLoc loc;
   u32 size;
   u32 align;
   u32 flags; /* CGLocalFlag */
 } CGLocalDesc;
 
 typedef enum MemFlag {
   MF_NONE = 0,
   MF_VOLATILE = 1u << 0,
   MF_ATOMIC = 1u << 1,
   MF_RESTRICT = 1u << 2,
   MF_READONLY = 1u << 3,
   MF_WRITEONLY = 1u << 4,
   MF_UNALIGNED = 1u << 5,
 } MemFlag;
 
 typedef enum AliasKind {
   ALIAS_UNKNOWN,
   ALIAS_LOCAL,
   ALIAS_GLOBAL,
   ALIAS_PARAM,
   ALIAS_HEAP,
   ALIAS_STRING,
 } AliasKind;
 
 typedef struct AliasRoot {
   u8 kind; /* AliasKind */
   u8 pad[3];
   union {
     i32 local_id;
     ObjSymId global;
     u32 param_idx;
     Sym string_id;
   } v;
 } AliasRoot;
 
 typedef struct MemAccess {
   KitCgTypeId type; /* codegen object type accessed */
   u32 size;         /* ABI byte size of this access (storage-unit size for a
                      * bit-field) */
   u32 align;        /* known byte alignment; 0 means unknown */
   u16 flags;        /* MemFlag */
   u16 addr_space;
   /* Bit-field rider: when bf_width != 0 this access is a bit-field, so `load`
    * extracts (shift+mask+extend) and `store` inserts (read-modify-write) within
    * the storage unit described by {type,size}. The CgTarget impls translate
    * this to the physical NativeTarget bitfield_load/store (or the recorder IR
    * op); the semantic CgTarget no longer carries a separate bit-field method.
    */
   u16 bf_offset; /* target-endian bit offset within the storage unit */
   u16 bf_width;  /* 0 => not a bit-field access */
   u8 bf_signed;  /* signed extraction on load */
   u8 bf_pad[3];
   AliasRoot alias;
 } MemAccess;
 
 typedef struct ConstBytes {
   KitCgTypeId type;
   const u8* bytes; /* ABI representation, little/big endian per target */
   u32 size;
   u32 align;
 } ConstBytes;
 
 typedef struct AggregateAccess {
   KitCgTypeId type;
   u32 size;
   u32 align;
   MemAccess mem;
 } AggregateAccess;
 
 typedef struct BitFieldAccess {
   KitCgTypeId field_type;
   MemAccess storage;
   u32 storage_offset; /* byte offset from record base */
   u16 bit_offset;     /* target-endian bit offset within storage unit */
   u16 bit_width;      /* may be 0 for zero-width layout barriers */
   u8 signed_;
   u8 pad[3];
 } BitFieldAccess;
 
 /* Reconstruct the BitFieldAccess a CgTarget impl needs from the bit-field
  * MemAccess that rides the generic load/store (bf_width != 0). The storage unit
  * is {m.type, m.size}; the bit geometry is the bf_* rider. */
 static inline BitFieldAccess bf_from_mem(MemAccess m) {
   BitFieldAccess bf = {0};
   bf.field_type = m.type;
   bf.storage = m;
   bf.storage.bf_offset = 0;
   bf.storage.bf_width = 0;
   bf.storage.bf_signed = 0;
   bf.bit_offset = m.bf_offset;
   bf.bit_width = m.bf_width;
   bf.signed_ = m.bf_signed;
   return bf;
 }
 
 typedef struct Operand {
   u8 kind;
   u8 pad[3];
   KitCgTypeId type;
   union {
     i64 imm;
     CGLocal local;
     struct {
       ObjSymId sym;
       i64 addend;
     } global;
     struct {
       CGLocal base;
       CGLocal index; /* CG_LOCAL_NONE when no index operand */
       u8 log2_scale; /* 0..3 -> 1/2/4/8 bytes; ignored when no index */
       i32 ofs;
     } ind;
   } v;
 } Operand;
 
 typedef struct CGParamDesc {
   u32 index;
   Sym name;
   KitCgTypeId type;
   u32 size;
   u32 align;
   u32 flags; /* CGLocalFlag */
   SrcLoc loc;
 } CGParamDesc;
 
 /* text_section_id and group_id are per-function so that -ffunction-sections,
  * __attribute__((section)) on functions, and COMDAT for C11 inline-with-
  * external-definition all work with no extra plumbing. Decl.section_id already
  * carries the user's request; CG/decl decides the section name policy
  * (default .text, vs .text.<sym> under -ffunction-sections, vs explicit
  * attribute). The backend just writes to the named section. */
 /* Phase 2 attribute-derived hints. The backends are free to ignore these;
  * they exist so the parser can communicate _Noreturn / __attribute__
  * info down to CG without forcing every backend to consult the Decl. */
 typedef enum CGFuncDescFlag {
   CGFD_NONE = 0,
   CGFD_NORETURN = 1u << 0,
 } CGFuncDescFlag;
 
 typedef struct CGFuncDesc {
   ObjSymId sym;
   ObjSecId text_section_id;
   ObjGroupId group_id; /* OBJ_GROUP_NONE if none */
   KitCgTypeId fn_type;
   KitCgTypeId result_type; /* KIT_CG_TYPE_NONE/void == no result */
   const CGParamDesc* params;
   u32 nparams;
   SrcLoc loc;
   u32 flags; /* CGFuncDescFlag */
   KitCgInlinePolicy inline_policy;
   u16 sym_bind; /* SymBind */
   u16 sym_kind; /* SymKind */
   u8 sym_vis;   /* SymVis */
   u8 atomize;
   u8 pad[2];
 } CGFuncDesc;
 
 typedef enum CGCallFlag {
   CG_CALL_NONE = 0,
   /* Sibling call. The target emits a tail-position call and does NOT emit a
    * return-style continuation. CG will not invoke target->ret afterwards.
    *
    * Realizability is verified before this flag is set: CG only sets it after
    * tail_call_unrealizable_reason() returns NULL for the same desc and call
    * state, so the target can emit the sibling call unconditionally. The
    * target may assert/compiler_panic if the flag is set on an unrealizable
    * desc, but that is an internal-consistency check — fallback and
    * diagnostics for unrealizable tail calls are CG's responsibility, not the
    * target's. */
   CG_CALL_TAIL = 1u << 0,
 } CGCallFlag;
 
 typedef struct CGCallDesc {
   KitCgTypeId fn_type;
   Operand callee;
   const CGLocal* args;
   CGLocal result; /* CG_LOCAL_NONE == void callee (no result) */
   u32 nargs;
   u16 flags;      /* CGCallFlag */
   u8 tail_policy; /* KitCgTailPolicy; meaningful when CG_CALL_TAIL is set.
                    * The opt recorder accepts every tail and preserves this so
                    * the replay can pick: emit tail (realizable), fall back to
                    * call+ret (ALLOWED), or diagnose (MUST). */
   u8 pad;
   KitCgInlinePolicy inline_policy;
 } CGCallDesc;
 
 typedef u32 Label;
 #define LABEL_NONE 0
 
 typedef enum ScopeKind {
   SCOPE_BLOCK, /* break exits forward */
   SCOPE_LOOP,  /* break exits forward; continue uses explicit target */
 } ScopeKind;
 
 typedef u32 CGScope;
 #define CG_SCOPE_NONE 0u
 
 typedef struct CGScopeDesc {
   u8 kind; /* ScopeKind */
   u8 pad[3];
   Label break_label; /* explicit target for break; LABEL_NONE => target creates
                         one */
   Label continue_label;    /* explicit target for continue; LABEL_NONE for
                               non-loops */
   KitCgTypeId result_type; /* reserved for structured expression results */
 } CGScopeDesc;
 
 typedef struct AsmConstraint {
   const char* str;  /* GCC-style: "r", "=&r", "+m", "i", "0" ... */
   Sym name;         /* GCC `[name]` symbolic operand; 0 if absent */
   KitCgTypeId type; /* codegen type of the bound expression (output lvalue or
                        input rvalue). Drives type width for the binder.
                        NULL only for hand-built test constraints (binder
                        falls back to a 64-bit int default). */
   Sym reg;          /* Explicit hard-register name ("r10"/"x8"/...) this operand
                        must occupy — a GNU local register variable bound as an
                        operand; 0 = unconstrained. Only the target's register
                        file resolves the name to a physical register. */
   u8 dir;           /* KitCgAsmDir */
   u8 pad[3];
 } AsmConstraint;
 
 typedef struct CGSwitchCase {
   /* Bit pattern matched against the selector; interpreted using
    * selector_type's width and signedness (signed comparison uses
    * sign-extension to selector_type's width). */
   u64 value;
   Label label;
 } CGSwitchCase;
 
 typedef struct CGSwitchDesc {
   Operand selector; /* OPK_LOCAL or OPK_IMM */
   KitCgTypeId selector_type;
   Label default_label; /* LABEL_NONE means "fall through past the switch" */
   const CGSwitchCase* cases;
   u32 ncases;
   u8 hint;      /* KitCgSwitchHint */
   u8 opt_level; /* 0/1/2; reads policy in cg_lower_switch_default */
   u8 pad[2];
 } CGSwitchDesc;
 
 typedef struct CGLocalStaticDataDesc {
   ObjSymId sym;
   KitCgTypeId type;
   KitCgDataDefAttrs attrs;
   u32 align;
 } CGLocalStaticDataDesc;
 
 typedef enum CGDebugLocKind {
   CG_DEBUG_LOC_NONE,
   CG_DEBUG_LOC_FRAME,
   CG_DEBUG_LOC_REG,
   CG_DEBUG_LOC_GLOBAL,
 } CGDebugLocKind;
 
 typedef struct CGDebugLoc {
   u8 kind; /* CGDebugLocKind */
   u8 pad[3];
   union {
     /* Offset in the same target-defined frame-base coordinate system that the
      * target/debugger pair uses to materialize frame-relative variables. CG
      * treats this as opaque target data and only maps it into the debug
      * producer's generic frame-location form. */
     i32 frame_ofs;
     u32 reg;
     ObjSymId global;
   } v;
 } CGDebugLoc;
 
 /* Forward-declared (same as arch/mc.h) so a CgTarget can carry an optional
  * Debug producer without this header depending on debug/debug.h. */
 typedef struct Debug Debug;
 
 typedef struct CgFinishPolicy {
   u8 output_kind;          /* KitCgOutputKind */
   u8 interposition_policy; /* KitCgInterpositionPolicy */
   u8 pad[2];
   const ObjSymId* preserved_symbols;
   u32 npreserved_symbols;
 } CgFinishPolicy;
 
 typedef struct CgTarget CgTarget;
 struct CgTarget {
   /* Typed IR lowering context. Subclasses extend. */
   Compiler* c;
   ObjBuilder* obj;
 
   /* Optional DWARF producer, created by the backend's `make` when
    * opts->debug_info is set (else NULL). The session reads this back into
    * its own g->debug to drive func/line/emit; the backend's MCEmitter
    * shares the same object for line-row emission. */
   Debug* debug;
 
   CgFinishPolicy finish_policy;
 
   /* ---- function lifecycle ---- */
   void (*func_begin)(CgTarget*, const CGFuncDesc*);
   void (*func_end)(CgTarget*);
 
   /* Symbol-aliasing hook. Optional (may be NULL). cg invokes this from
    * kit_cg_alias after the obj symbol-table mirror is wired so the
    * backend can emit any out-of-band representation it needs — e.g. the
    * C-source target writes
    *   `T alias_sym(...) __attribute__((alias("target")));`
    * because the alias relationship isn't expressible by sharing a
    * (section, value) pair the way a relocatable object can. Native
    * machine-code backends don't need this hook because obj_symbol_define
    * already aliases the bytes. `type` is the alias's CG type (function
    * or object), needed by the C target to render the prototype. */
   void (*alias)(CgTarget*, ObjSymId alias_sym, ObjSymId target_sym,
                 KitCgTypeId type);
 
   /* ---- locals ---- */
   CGLocal (*local)(CgTarget*, const CGLocalDesc*);
   void (*local_addr)(CgTarget*, Operand dst, const CGLocalDesc*, CGLocal);
   CGLocal (*param)(CgTarget*, const CGParamDesc*);
   /* Optional debug-info query after function frame layout is finalized.
    * Targets return a target-authored location for semantic local storage; CG
    * owns deciding which source locals/params get emitted and translating the
    * target-neutral CGDebugLoc into the debug producer API. */
   int (*local_debug_loc)(CgTarget*, CGLocal, CGDebugLoc*);
 
   /* ---- labels and control flow ---- */
   Label (*label_new)(CgTarget*);
   void (*label_place)(CgTarget*, Label);
   void (*jump)(CgTarget*, Label);
   /* Fused compare-and-branch. cg's preferred form: avoids materializing 0/1
    * for a normal `if (a < b)`. For an arbitrary i1 in a local, callers
    * synthesize cmp_branch(CMP_NE, val, IMM_ZERO, label). */
   void (*cmp_branch)(CgTarget*, CmpOp, Operand a, Operand b, Label);
 
   /* Structured switch dispatch.
    *
    * Optional: when NULL, cg's shared `cg_lower_switch_default` runs and
    * lowers in terms of cmp_branch / jump / indirect_branch / data ops —
    * the path every native arch uses. Backends override switch_ only when
    * they can express the construct natively: the C-source target emits
    * `switch (val) { case V: goto L_V; ... default: goto L_def; }`; a
    * future WASM target would emit `br_table`.
    *
    * The descriptor carries the full structured form (selector + paired
    * cases + default + frontend hint); density policy lives in
    * cg_lower_switch_default. */
   void (*switch_)(CgTarget*, const CGSwitchDesc*);
 
   /* Optional. When non-NULL and it returns 0, the target cannot realize a
    * jump-table dispatch built from a rodata table of code-label addresses
    * (Wasm: linear memory holds no code addresses and there is no computed
    * branch). kit_cg_switch then routes dense/forced-table plans through
    * `switch_` (e.g. br_table) instead of the label-table + indirect_branch
    * lowering. NULL means the label-table path is supported (every native
    * arch). */
   int (*supports_label_table)(CgTarget*);
 
   /* Indirect branch primitive: transfer control to the address in
    * `addr` (an OPK_LOCAL holding a function-local label address).
    *
    * Required on every native arch and used by:
    *   - kit_cg_computed_goto for direct-threaded dispatch
    *   - opt-level jump-table lowerings of IR_SWITCH (when implemented)
    *
    * `valid_targets[0..ntargets)` is the closed set of labels the address
    * can resolve to. Backends use it for branch-target hardening (BTI,
    * PAC, x86 CFG, IBT) and opt uses it to build the CFG; opt requires
    * ntargets > 0. */
   void (*indirect_branch)(CgTarget*, Operand addr, const Label* valid_targets,
                           u32 ntargets);
 
   /* Materialize the runtime address of a function-local label into
    * `dst`. The label must already exist (label_new); it does not
    * need to be placed yet. Backends emit the target's relative address
    * materialization:
    * x86_64 `lea L(%rip), %r`, aarch64 `adr X, L`, riscv `auipc/addi`.
    *
    * The resulting pointer is a function-local label address (per the
    * public kit_cg_push_label_addr contract) and must only be consumed
    * by indirect_branch inside the defining function's activation. */
   void (*load_label_addr)(CgTarget*, Operand dst, Label label);
 
   /* Optional source-backend hook for function-local static data definitions
    * that need function label scope, currently used for C `&&label`
    * dispatch-table initializers. Returning non-zero from begin means the
    * target consumes bytes/zeros/label addresses until end; ordinary object
    * data emission is skipped for that definition. */
   int (*local_static_data_begin)(CgTarget*, const CGLocalStaticDataDesc*);
   /* data == NULL means append len zero bytes. */
   void (*local_static_data_write)(CgTarget*, const u8* data, u64 len);
   void (*local_static_data_label_addr)(CgTarget*, Label target, i64 addend,
                                        u32 width, u32 address_space);
   void (*local_static_data_end)(CgTarget*);
 
   /* Optional. When non-NULL, kit_cg_data_label_addr panics with the
    * returned target-specific message before reaching object-data emission. Lets
    * targets that cannot resolve function-local label addresses in
    * static-data initializers (e.g. the Wasm backend) fail with a
    * recognizable, target-prefixed diagnostic. The returned string must remain
    * valid for the lifetime of the panic call (string literals are typical). */
   const char* (*data_label_addr_unsupported_msg)(CgTarget*);
 
   /* ---- structured control flow ----
    * Mirrors CG's scope ops. CG passes explicit break/continue targets so C
    * `for` continues can land on the increment expression rather than the loop
    * header. Real backends shim these onto label_new/label_place/jump.
    * The WASM backend consumes them natively to emit block/loop with
    * structurally-bounded br targets, which is what gives WASM its CFI.
    *
    * `result_type` is reserved for structured expression results on WASM (NULL
    * for the statement case used by C); other backends ignore it. */
   CGScope (*scope_begin)(CgTarget*, const CGScopeDesc*);
   void (*scope_end)(CgTarget*, CGScope);
   void (*break_to)(CgTarget*, CGScope);
   void (*continue_to)(CgTarget*, CGScope);
 
   /* ---- data movement (split, no overloading) ---- */
   void (*load_imm)(CgTarget*, Operand dst /*LOCAL*/, i64 imm);
   void (*load_const)(CgTarget*, Operand dst /*LOCAL*/, ConstBytes);
   void (*copy)(CgTarget*, Operand dst /*LOCAL*/, Operand src /*LOCAL*/);
   void (*load)(CgTarget*, Operand dst /*LOCAL*/,
                Operand addr /*LOCAL|GLOBAL|INDIRECT*/, MemAccess);
   void (*store)(CgTarget*, Operand addr /*LOCAL|GLOBAL|INDIRECT*/,
                 Operand src /*LOCAL|IMM*/, MemAccess);
   void (*addr_of)(CgTarget*, Operand dst /*LOCAL*/,
                   Operand lv /*LOCAL|GLOBAL|INDIRECT*/);
   /* Materializes the address of a thread-local symbol into `dst`. Distinct
    * from addr_of because TLS resolution can be a multi-instruction sequence
    * or a runtime call (e.g. GD model), not a cheap addressing mode. The
    * backend chooses the TLS model (LE/IE/LD/GD) from c->target and the
    * symbol's visibility. Subsequent accesses go through OPK_INDIRECT on the
    * resulting pointer; this lets opt hoist the materialization via LICM. */
   void (*tls_addr_of)(CgTarget*, Operand dst /*LOCAL*/, ObjSymId sym,
                       i64 addend);
   void (*copy_bytes)(CgTarget*, Operand dst_addr, Operand src_addr,
                      AggregateAccess);
   void (*set_bytes)(CgTarget*, Operand dst_addr, Operand byte_value,
                     AggregateAccess);
   /* Bit-fields are not a separate CgTarget method: a bit-field load/store rides
    * the generic `load`/`store` above with a bit-field MemAccess (bf_width !=
    * 0). Each CgTarget impl translates it (NativeDirectTarget -> NativeTarget's
    * bitfield_load/store; IrRecorder -> CG_IR_BITFIELD_LOAD/STORE). */
 
   /* ---- arithmetic, compare, convert ----
    * binop/unop/cmp accept OPK_LOCAL or OPK_IMM in source operand positions
    * (`a`, `b`); `dst` is always OPK_LOCAL. The backend chooses between an
    * imm-form encoding and materializing the literal into a scratch
    * local based on whether the value fits the instruction's imm
    * field. FP binops and UO_FNEG require local sources — FP literals reach the
    * value stack through load_const into OPK_LOCAL. cg and opt's machinize/emit
    * both rely on this contract to pass small constants through without
    * burning a value-stack local on materialization. */
   void (*binop)(CgTarget*, BinOp, Operand dst /*LOCAL*/,
                 Operand a /*LOCAL|IMM*/, Operand b /*LOCAL|IMM*/);
   void (*unop)(CgTarget*, UnOp, Operand dst /*LOCAL*/, Operand a /*LOCAL|IMM*/);
   void (*cmp)(CgTarget*, CmpOp, Operand dst /*LOCAL*/, Operand a /*LOCAL|IMM*/,
               Operand b /*LOCAL|IMM*/); /* materialize 0/1 */
   void (*convert)(CgTarget*, ConvKind, Operand dst, Operand src);
 
   /* ---- calls / return ----
    * CGCallDesc carries the type-checked signature, semantic callee operand,
    * local arguments, and local result destinations. The semantic target does
    * not expose calling-convention lowering; native targets derive physical
    * argument/return placement from fn_type and local metadata internally.
    * `result` is the single local destination, or CG_LOCAL_NONE for void. */
   void (*call)(CgTarget*, const CGCallDesc*);
   /* Pure query: can `d` be emitted as a sibling (tail) call on this target,
    * given the current target state? Returns NULL if yes; otherwise a short,
    * static, human-readable string naming the blocker, used verbatim in the
    * musttail diagnostic. Must not emit code and must not abort.
    *
    * Realizable means the target can transfer control to the callee while
    * preserving the source-level call/return semantics of this function. CG
    * verifies type compatibility before setting CG_CALL_TAIL; target-specific
    * blockers such as variadic lowering, frame teardown constraints, or
    * unavailable tail-call support are reported here.
    *
    * CG owns the tail policy: it calls this first and only sets CG_CALL_TAIL
    * when it returns NULL, so a NULL result must guarantee a later call() with
    * CG_CALL_TAIL can emit the sibling call. May itself be NULL, meaning the
    * target supports no tail calls at all. */
   const char* (*tail_call_unrealizable_reason)(CgTarget*, const CGCallDesc*);
   /* Return from the function. `value` is the single returned local, or
    * CG_LOCAL_NONE for a void return. */
   void (*ret)(CgTarget*, CGLocal value);
   /* Control terminator marking statically-unreachable code (the C
    * __builtin_unreachable point). Like ret/jump it ends the current basic
    * block: no fall-through successor is implied. Backends typically emit a
    * trap instruction (brk/ud2/ebreak), a Wasm `unreachable`, or a
    * `__builtin_unreachable()` in the C-source target; an interpreter faults.
    * Distinct from INTRIN_TRAP, which is an expression-level intrinsic that
    * does not terminate the block. */
   void (*unreachable)(CgTarget*);
 
   /* ---- alloca ----
    * Dynamic stack allocation. `size` is i64 bytes; `align` is the required
    * alignment of the returned pointer. Backend grows the (linear-memory or
    * native) shadow stack, returns the pointer in `dst`. v1 only emits this
    * via __builtin_alloca; C VLAs are not parsed (__STDC_NO_VLA__). */
   void (*alloca_)(CgTarget*, Operand dst /*LOCAL*/, Operand size, u32 align);
 
   /* ---- variadics ----
    * va_list type is per-arch (defined in <stdarg.h>); these methods
    * implement the four C macros after builtin substitution. ap is always
    * passed as &ap. */
   void (*va_start_)(CgTarget*, Operand ap_addr);
   void (*va_arg_)(CgTarget*, Operand dst /*LOCAL*/, Operand ap_addr,
                   KitCgTypeId t);
   void (*va_end_)(CgTarget*, Operand ap_addr);
   void (*va_copy_)(CgTarget*, Operand dst_ap_addr, Operand src_ap_addr);
 
   /* ---- atomics ---- */
   void (*atomic_load)(CgTarget*, Operand dst /*LOCAL*/, Operand addr, MemAccess,
                       KitCgMemOrder);
   void (*atomic_store)(CgTarget*, Operand addr, Operand src, MemAccess,
                        KitCgMemOrder);
   void (*atomic_rmw)(CgTarget*, KitCgAtomicOp,
                      Operand dst /*LOCAL: prior value*/, Operand addr,
                      Operand val, MemAccess, KitCgMemOrder);
   void (*atomic_cas)(CgTarget*, Operand prior /*LOCAL*/,
                      Operand ok /*LOCAL, i1*/, Operand addr, Operand expected,
                      Operand desired, MemAccess, KitCgMemOrder success,
                      KitCgMemOrder failure);
   void (*fence)(CgTarget*, KitCgMemOrder);
 
   /* ---- compiler intrinsics ----
    * Typed dispatch for builtins whose lowering is backend-relevant
    * (inline-vs-libcall, inline sequence selection) or whose semantics opt
    * cares about (hint pattern matching, exhaustiveness). The IR carries
    * IR_INTRINSIC + IRIntrinAux.kind; the wrapped target receives the same call
    * at lowering time with materialized operands.
    *
    * Operand shapes by IntrinKind:
    *   POPCOUNT/CTZ/CLZ/BSWAP*  : dsts[0] LOCAL result; args[0] LOCAL input
    *   MEMCPY/MEMMOVE           : dsts none; args = (dst_addr, src_addr, n)
    *   MEMSET                   : dsts none; args = (dst_addr, byte, n)
    *   PREFETCH                 : dsts none; args = (addr [, rw [, locality]])
    *   ASSUME_ALIGNED           : dsts[0] LOCAL; args = (ptr, align [, offset])
    *   EXPECT                   : dsts[0] LOCAL; args = (val, expected)
    *   TRAP                     : dsts none; args none
    *   SETJMP                   : dsts[0] LOCAL i32 result; args = (&buf)
    *   LONGJMP                  : dsts none; args = (&buf, val); no return
    *   ADD/SUB/MUL_OVERFLOW     : dsts[0] LOCAL result, dsts[1] LOCAL i1
    * overflow; args = (a, b)
    *
    * Backends that lack an inline sequence for a given kind may emit a
    * normal IR_CALL-shaped sequence to a runtime entry (e.g. memcpy) — the
    * IR records intent, the backend chooses mechanism. Hint kinds may be
    * lowered as no-ops where the arch has nothing to emit. */
   void (*intrinsic)(CgTarget*, IntrinKind, Operand* dsts, u32 ndst,
                     const Operand* args, u32 narg);
 
   /* ---- inline asm ----
    * Per-arch constraint binding + template assembly, packaged as one block.
    *   ins[i] are pre-evaluated input operands.
    *   out_ops[i] is filled by the arch with the location holding the result
    *     for outs[i]; the caller (cg) reads them out after the call.
    *   "=&r" early-clobber outputs must be allocated disjoint from any input.
    * opt_cgtarget records this as a single IR_ASM_BLOCK; the wrapped target
    * receives the same call at lowering time with materialized operands. */
   int (*asm_is_reg_constraint)(CgTarget*, const char* constraint);
   void (*asm_block)(CgTarget*, const char* tmpl, const AsmConstraint* outs,
                     u32 nout, Operand* out_ops, const AsmConstraint* ins,
                     u32 nin, const Operand* in_ops, const Sym* clobbers,
                     u32 nclob, u32 clobber_abi_sets);
 
   /* Optional: handle a top-level `__asm__("...")` block (file scope, not
    * inside a function). Backends that leave this NULL fall back to the
    * generic asm-parser path through KitCg.mc. Wasm overrides this to
    * diagnose-and-fail since the wasm module has no native asm parser. */
   void (*file_scope_asm)(CgTarget*, const char* src, size_t len);
 
   /* ---- source-location tracking ----
    * Sets the SrcLoc inherited by subsequent emit-side calls (binop/load/...).
    * opt_cgtarget stamps it on every recorded Inst. Sticky until the next
    * set_loc. */
   void (*set_loc)(CgTarget*, SrcLoc);
 
   /* ---- end-of-TU hook ----
    * No-op for plain target CGTargets. opt_cgtarget runs cross-function passes
    * (inlining + cleanup) and lowers all buffered IR functions into the
    * wrapped target CgTarget. Drivers must call this after the last func_end and
    * before reading from `obj` or calling debug_emit. */
   void (*finalize)(CgTarget*);
 
   void (*destroy)(CgTarget*);
 };
 
 /* Shared switch lowering. cg's kit_cg_switch installs this as the
  * default target->switch_ behavior; opt's pass_emit calls it when
  * replaying IR_SWITCH against a backend that doesn't override switch_.
  * Emits a cmp-and-branch chain over (target->cmp_branch + target->jump)
  * — fast at -O0 and the input shape an opt-level jump-table rewrite
  * starts from. */
 void cg_lower_switch_default(CgTarget* t, const CGSwitchDesc* desc);
 
 CgTarget* cgtarget_new(Compiler*, ObjBuilder*);
 void cgtarget_set_finish_policy(CgTarget*, const CgFinishPolicy*);
 void cgtarget_finalize(CgTarget*);
 void cgtarget_free(CgTarget*);
 
 /* A CGBackend is the unit the registry hands out: "give me a CgTarget for
  * this Compiler + ObjBuilder + emit options." */
 typedef struct CGBackend {
   const char* name;
   CgTarget* (*make)(Compiler*, ObjBuilder*, const KitCodeOptions*);
 } CGBackend;
 
 /* Pick the right CGBackend for a session given the compiler's target arch
  * and the per-emit CodeOptions. Returns NULL when no backend in this build can
  * serve the request. */
 const CGBackend* cg_backend_for_session(const Compiler*, const KitCodeOptions*);
 
 /* Human-readable arch name for diagnostics, independent of which backends
  * are compiled in (so it can name a target whose backend is disabled). */
 const char* arch_kind_name(KitArchKind);
 
 #endif