kit

cgtarget.h (19626B)

---

 #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"
 #include "cg/cgir.h"
 
 /* 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;
 
   /* The target represents values as untyped machine words (registers/stack
    * slots), so a same-width, same-register-class bitcast — pointer<->intptr,
    * pointer<->pointer — moves no bits and the cg layer may elide it by retyping
    * the value in place (api_cg_convert_kind). Set by the single-pass native
    * backend (NativeDirectTarget). Left 0 by the typed backends — the C-source
    * target needs the explicit cast to emit valid C, and the recording target
    * keeps the convert so the optimizer's own copy-propagation owns the call. */
   u8 untyped_values;
 
   /* ---- 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*);
 
   /* Optional. Reclaim the frame homes of transient compiler temporaries
    * (CG_LOCAL_TRANSIENT) that are now dead. cg calls this only at a statement
    * boundary where the value stack is empty (kit_cg_reclaim_temps), so no value
    * references any temp; the single-pass backend drops their cache entries and
    * recycles their slots, bounding the -O0 frame. NULL on the recording/C-source
    * targets, which own frame layout differently. */
   void (*reclaim_temps)(CgTarget*);
 
   /* ---- 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