kit

link_internal.h (27580B)

---

 #ifndef KIT_LINK_INTERNAL_H
 #define KIT_LINK_INTERNAL_H
 
 /* Shared private definitions for the linker (link.c, link_layout.c,
  * link_reloc.c, link_elf.c, link_jit.c). Not part of any public surface;
  * not included by anything outside src/link/. */
 
 #include "core/core.h"
 #include "core/hashmap.h"
 #include "core/segvec.h"
 #include "link/link.h"
 #include "obj/obj.h"
 #include "obj/symresolve.h"
 
 /* Per-input mapping built during link_resolve. ObjSymId / ObjSecId are
  * scoped to a single ObjBuilder, so the linker maintains an explicit
  * lookup from each input's id space into the global LinkSymId /
  * LinkSectionId space. Indices are dense (0..count-1 within the input);
  * the array is sized to the input's nsymbols / nsections at allocation
  * time. Index 0 of each id space is the "none" sentinel and maps to the
  * matching LINK_*_NONE. */
 typedef struct InputMap {
   LinkSymId* sym; /* size = ObjBuilder.nsymbols */
   u32 nsym;
   LinkSectionId* section; /* size = ObjBuilder.nsections */
   u32 nsection;
   LinkSectionId* atom; /* size = ObjBuilder.natoms */
   u32 natom;
   ObjAtomId* sym_atom;   /* size = nsym; ObjSymId -> ObjAtomId */
   ObjAtomId* reloc_atom; /* size = obj_reloc_total(input) */
   u32 nreloc;
   u8* section_has_atoms;   /* size = nsection */
   u32* section_atom_first; /* size = nsection; index into section_atom_ids */
   u32* section_atom_count; /* size = nsection */
   ObjAtomId* section_atom_ids; /* active atoms grouped by section */
   u32 nsection_atom_ids;
   /* COMDAT discard mask, size = nsection. Set by link_resolve_symbols
    * for COFF/PE SELECTANY: when an input's COMDAT section conflicts
    * with an earlier definition, the duplicate section is marked here
    * so link_gc_compute and link_layout_sections skip it. */
   u8* comdat_discarded;
 } InputMap;
 
 void link_input_map_alloc(LinkImage*, InputMap*, ObjBuilder*, u32 nsym_slots);
 
 static inline ObjAtomId link_input_sym_atom(const InputMap* m, ObjSymId sym) {
   return (m && m->sym_atom && sym < m->nsym) ? m->sym_atom[sym] : OBJ_ATOM_NONE;
 }
 
 static inline ObjAtomId link_input_reloc_atom(const InputMap* m,
                                               u32 reloc_index) {
   return (m && m->reloc_atom && reloc_index < m->nreloc)
              ? m->reloc_atom[reloc_index]
              : OBJ_ATOM_NONE;
 }
 
 static inline int link_input_section_has_atoms(const InputMap* m,
                                                ObjSecId sid) {
   return m && m->section_has_atoms && sid < m->nsection &&
          m->section_has_atoms[sid];
 }
 
 static inline void link_input_section_atoms(const InputMap* m, ObjSecId sid,
                                             u32* first, u32* count) {
   if (m && sid < m->nsection && m->section_atom_first &&
       m->section_atom_count) {
     *first = m->section_atom_first[sid];
     *count = m->section_atom_count[sid];
   } else {
     *first = 0;
     *count = 0;
   }
 }
 
 static inline LinkSectionId link_input_reloc_section(const InputMap* m,
                                                      const Reloc* r,
                                                      u32 reloc_index) {
   if (!m || !r || r->section_id == OBJ_SEC_NONE || r->section_id >= m->nsection)
     return LINK_SEC_NONE;
   if (link_input_section_has_atoms(m, r->section_id)) {
     ObjAtomId aid = link_input_reloc_atom(m, reloc_index);
     if (aid == OBJ_ATOM_NONE || aid >= m->natom) return LINK_SEC_NONE;
     return m->atom[aid];
   }
   return m->section[r->section_id];
 }
 
 static inline LinkSectionId link_input_symbol_section(const InputMap* m,
                                                       const ObjSym* s,
                                                       ObjSymId sym) {
   if (!m || !s || s->section_id == OBJ_SEC_NONE || s->section_id >= m->nsection)
     return LINK_SEC_NONE;
   if (link_input_section_has_atoms(m, s->section_id)) {
     ObjAtomId aid = link_input_sym_atom(m, sym);
     if (aid == OBJ_ATOM_NONE || aid >= m->natom) return LINK_SEC_NONE;
     return m->atom[aid];
   }
   return m->section[s->section_id];
 }
 
 /* ---- ObjSym classification (single source of truth) ---------------------
  *
  * The linker's three lanes (AOT exe/shared in link_resolve.c, `-r`
  * relocatable in link_relocatable.c, in-process JIT in link_jit.c) all
  * classify input symbols the same way. These predicates are the one
  * authority; every lane routes through them. */
 
 /* Resolution policy now lives in obj/symresolve.h so the LTO staging merge can
  * reuse it. These keep the historical link_* spellings (every lane routes
  * through them) as thin wrappers over the shared definitions. */
 static inline int link_bind_strength(u16 bind) {
   return symresolve_bind_strength(bind);
 }
 static inline int link_sym_is_def(const ObjSym* s) {
   return symresolve_sym_is_def(s);
 }
 static inline int link_sym_is_spurious_undef(const ObjSym* s) {
   return symresolve_sym_is_spurious_undef(s);
 }
 
 /* In-section byte count for an input section: BSS/NOBITS report their
  * zero-fill size, everything else its emitted byte total
  * (link_layout.c / link_jit.c). */
 static inline u32 link_section_size_for_link(const Section* s) {
   return (s->sem == SSEM_NOBITS || s->kind == SEC_BSS) ? s->bss_size
                                                        : s->bytes.total;
 }
 
 /* Open-addressed name -> LinkSymId hash for global / weak definitions
  * and lookups (kit_jit_lookup, entry-symbol resolution). Locals never
  * land in this table. Sym 0 is the empty-slot sentinel (it's also the
  * "none" id per core.h:42 and never appears as a real name). */
 
 static inline u32 link_sym_hash_(Sym s) { return hash_u32((u32)s); }
 HASHMAP_DEFINE(SymHash, Sym, LinkSymId, link_sym_hash_);
 
 /* Convenience wrappers: the existing call sites pass LinkSymId by value
  * (LINK_SYM_NONE on miss) and use insert-if-absent semantics. */
 static inline void symhash_init(SymHash* h, Heap* heap) {
   SymHash_init(h, heap);
 }
 static inline void symhash_reserve(SymHash* h, u32 n) { SymHash_reserve(h, n); }
 static inline void symhash_fini(SymHash* h) { SymHash_fini(h); }
 static inline LinkSymId symhash_get(const SymHash* h, Sym name) {
   LinkSymId* hit = SymHash_get(h, name);
   return hit ? *hit : LINK_SYM_NONE;
 }
 static inline void symhash_set(SymHash* h, Sym name, LinkSymId id) {
   (void)SymHash_set(h, name, id);
 }
 static inline int symhash_insert(SymHash* h, Sym name, LinkSymId id,
                                  LinkSymId* existing_out) {
   return SymHash_try_insert(h, name, id, existing_out);
 }
 
 struct KitJit; /* forward; see link_jit.c */
 
 /* Archive ingestion state. Members are eagerly parsed into ObjBuilders
  * at link_add_archive_bytes time; the demand/whole-archive decision is
  * deferred to link_resolve, where matching members are transferred into
  * Linker.inputs. ObjBuilder ownership: while `included` is 0 the archive
  * owns the builder (freed in linker_release); on inclusion the pointer
  * moves into a LinkInput slot and `obj` is nulled to avoid double-free. */
 typedef struct LinkArchiveMember {
   Sym name; /* interned member name; 0 if anonymous */
   ObjBuilder* obj;
   u8 included;
   u8 pad[7];
 } LinkArchiveMember;
 
 typedef struct LinkArchive {
   Sym name;
   LinkArchiveMember* members;
   u32 nmembers;
   u32 order;
   u8 whole_archive;
   u8 link_mode;
   u8 group_id;
   u8 pad;
 } LinkArchive;
 
 SEGVEC_DEFINE(LinkInputs, LinkInput, 4); /* 16 entries per segment */
 SEGVEC_DEFINE(LinkArchives, LinkArchive, 4);
 
 struct Linker {
   Compiler* c;
   Heap* heap;
   LinkInputs inputs; /* LinkInputId = slot index + 1 */
   LinkArchives archives;
   u32 next_input_order;
   Sym entry_name;
   /* Set by link_set_script. NULL: layout takes the existing default
    * bucket-based path. Non-NULL: layout_sections_scripted walks the
    * script's output sections in declaration order. Borrowed; the
    * script and every sub-object must outlive link_resolve. */
   const KitLinkScript* script;
   /* -Ttext override of the static ET_EXEC image base. text_base_set==0 leaves
    * the default IMAGE_BASE_STATIC; ignored on PIE/shared/scripted layouts. */
   int text_base_set;
   u64 text_base;
   int gc_sections;
   int strip_debug;
   int allow_undefined;
   /* Set by kit_link_exe before link_resolve.  When 1, layout_iplt
    * synthesizes a .init_array entry pointing at __kit_ifunc_init so
    * the emitted ET_EXEC binary fills its IFUNC slots at startup.  The
    * JIT path leaves this 0 — slots are pre-resolved in-process by
    * link_jit.c, no ctor needed. */
   int emit_static_exe;
   /* In-process JIT lane (set by kit_link_jit).  Currently used to
    * tolerate undef `__tlv_bootstrap` on Mach-O inputs — the JIT image
    * has no dyld, descriptor[+0] is rewritten to kit's thunk during
    * kit_jit_from_image, so the symbol's resolved value doesn't
    * matter.  Without this, clang-produced .o files (which emit
    * `__tlv_bootstrap` as a plain non-weak undef) would panic at
    * link_resolve_undefs. */
   int jit_mode;
   /* Shared-library / DSO output. Shares dynamic ELF layout with PIE
    * executables, but has no required entry point and no PT_INTERP. */
   int emit_shared;
   /* PIE / ET_DYN output. Set by kit_link_exe when opts->pie or any
    * DSO input is present. Triggers layout_dyn (Phase 4) and the
    * dynamic ELF emit path (Phase 6). */
   int emit_pie;
   u16 pe_subsystem;
   /* RISC-V psABI e_flags accumulated from object inputs selected for this
    * link. Float-ABI/RVE conflicts are rejected while registering inputs;
    * RVC/TSO feature-presence bits are OR-merged. */
   u32 elf_e_flags;
   Sym elf_e_flags_source;
   u8 have_elf_e_flags;
   /* Caller-supplied PT_INTERP. layout_dyn falls back to a target-
    * derived default when this is 0. */
   Sym interp_path;
   /* ---- Flags/policy plumbed from KitLinkSessionOptions by src/api/link.c
    * (the kernel-C "linker flags and policy" + strict-validation work). The
    * arrays are borrowed; they must outlive link_resolve. ---- */
   const KitLinkDefsym* defsyms; /* --defsym NAME=EXPR */
   u32 ndefsyms;
   const KitLinkSectionStart* section_starts; /* --section-start / -Tdata/-Tbss */
   u32 nsection_starts;
   KitSlice soname;
   const KitSlice* rpaths;
   u32 nrpaths;
   const KitSlice* runpaths;
   u32 nrunpaths;
   u8 orphan_handling; /* KitLinkOrphanHandling */
   int fatal_warnings; /* --fatal-warnings */
   int freestanding_strict; /* strict freestanding link validation */
   LinkExternResolver resolver;
   void* resolver_user;
   /* Borrowed JIT host. Set by kit_link_jit before link_resolve so the
    * layout/reloc passes can read execmem->page_size and the JIT mapper
    * can reach the host's reserve/protect/tls hooks without rummaging
    * through Compiler.ctx (which no longer carries those). NULL on the
    * AOT exe/shared lanes. */
   const KitJitHost* jit_host;
   CompilerCleanup* deferred; /* registered by link_new */
 };
 
 /* ---- GC liveness (link_resolve.c) ---------------------------------------- */
 
 typedef struct GcLive {
   u8**
       marks; /* marks[input_idx][obj_sec_id] for implicit whole-section units */
   u8** atom_marks; /* atom_marks[input_idx][obj_atom_id] for explicit atoms */
   u32* nsec;       /* obj_section_count per input */
   u32* natom;      /* obj_atom_count per input */
   u32 ninputs;
 } GcLive;
 
 typedef struct GcQueue {
   u64* items; /* hi32=input_idx, low31=id, bit31=set for atom */
   u32 n;
   u32 cap;
 } GcQueue;
 
 /* ---- Cross-file helpers (link_layout.c → link_reloc_layout.c) ------------ */
 
 /* Four-bucket segment partitioning by permission (defined in link_layout.c). */
 typedef enum SegBucket {
   SEG_RX = 0,  /* SF_ALLOC | SF_EXEC                  */
   SEG_R = 1,   /* SF_ALLOC, no EXEC, no WRITE          */
   SEG_RW = 2,  /* SF_ALLOC | SF_WRITE (incl. BSS)      */
   SEG_TLS = 3, /* SF_ALLOC | SF_TLS (.tdata + .tbss)   */
   SEG_NBUCKETS = 4,
 } SegBucket;
 
 /* section_kept: 1 for allocatable progbits/nobits sections (link_layout.c). */
 int link_section_kept(const Section* s);
 /* section_kept_fileonly: 1 for non-allocatable .debug_* sections that the
  * AOT ELF path carries through as file-only sections (link_layout.c). */
 int link_section_kept_fileonly(const Section* s);
 /* bucket_for: map section flags to SegBucket (link_layout.c). */
 SegBucket link_bucket_for(u16 flags);
 /* layout_page_size: page size for segment alignment (link_layout.c). */
 u64 link_layout_page_size(Linker* l);
 
 /* Append a fresh symbol slot and return its id (link_layout.c). */
 LinkSymId link_append_symbol(LinkImage* img, const LinkSymbol* tmpl);
 /* Append a fresh reloc slot and return it (link_layout.c). */
 LinkRelocApply* link_append_reloc_slot(LinkImage* img);
 
 /* Emit or upsert a synthetic global boundary symbol (link_layout.c). */
 void link_emit_boundary_sym(Linker* l, LinkImage* img, const char* name,
                             u64 vaddr);
 void link_emit_section_boundary_sym(Linker* l, LinkImage* img, const char* name,
                                     LinkSectionId section_id, u64 value);
 
 /* Detect __start_<X> / __stop_<X> with <X> a valid C identifier.
  * Defined in link_resolve.c; used by link_reloc_layout.c. */
 int link_gc_split_start_stop(const char* s, size_t n, size_t* out_off,
                              size_t* out_len, int* out_is_start);
 
 /* GC liveness helpers (link_resolve.c). */
 int link_gc_live_get(const GcLive* g, u32 ii, ObjSecId j);
 int link_gc_atom_live_get(const GcLive* g, u32 ii, ObjAtomId j);
 
 /* Segment/section growth helpers for iplt (link_reloc_layout.c). */
 u32 link_iplt_alloc_segments(LinkImage* img, u32 nseg);
 u32 link_iplt_alloc_sections(LinkImage* img, u32 nsec);
 
 /* Append one fixed-size synthetic region to the image: a fresh
  * page-aligned PT_LOAD segment plus its single covering section, sized
  * `size` with permissions `perms` (SF_* flags) and section semantics
  * `sem`. The region is placed at page-align(max segment end) so it never
  * overlaps existing content. A zero-filled byte buffer of `size` bytes is
  * allocated for the segment; *out_vaddr receives the image-relative base
  * and *out_bytes the buffer. `sec_align` sets the section's alignment
  * (the segment always aligns to the page). Returns the new section's id.
  * Backs the GOT / JIT-call-stub / IPLT layout passes
  * (link_reloc_layout.c). */
 LinkSectionId link_synth_region(LinkImage* img, Linker* l, Sym name, u16 perms,
                                 u16 sem, u64 size, u32 sec_align,
                                 u64* out_vaddr, u8** out_bytes);
 
 /* Append one fixed 8-byte ABS64 reloc-apply record targeting `target` at
  * `offset` within synthetic section `lsid` (write_vaddr == its file
  * offset, as every synthetic region is identity-mapped at layout time).
  * Backs the GOT / IPLT / JIT-slot fills (link_reloc_layout.c). */
 void link_emit_internal_abs64(LinkImage* img, LinkSectionId lsid, u32 offset,
                               u64 write_vaddr, LinkSymId target);
 
 /* ---- Public entries (link_resolve.c) --------------------------------------
  */
 void link_ingest_archives(struct Linker*);
 void link_merge_elf_e_flags(struct Linker*, ObjBuilder*, KitSlice label);
 /* PE/COFF only: synthesize a tiny ObjBuilder providing the mingw CRT
  * `__CTOR_LIST__` / `__CTOR_END__` / `__DTOR_LIST__` / `__DTOR_END__`
  * boundary symbols.  See link_resolve.c for the contract. */
 void link_synth_coff_ctor_dtor_list(struct Linker*);
 void link_resolve_symbols(struct Linker*, LinkImage*);
 void link_resolve_undefs(struct Linker*, LinkImage*);
 void link_gc_compute(struct Linker*, LinkImage*, GcLive*);
 void link_gc_live_alloc(GcLive* g, struct Linker* l, Heap* h);
 void link_gc_live_free(GcLive* g, Heap* h);
 void link_gc_drop_dead_globals(struct Linker*, LinkImage*, const GcLive*);
 LinkImage* link_image_alloc(Compiler*);
 
 /* ---- Public entries (link_layout.c) ---------------------------------------
  */
 void link_layout_sections(struct Linker*, LinkImage*, const GcLive*);
 void link_layout_commons(struct Linker*, LinkImage*);
 void link_emit_segment_bytes(struct Linker*, LinkImage*);
 /* Carry .debug_* sections through as file-only sections + populate the
  * debug registry (link_layout.c). AOT ELF path only; gated by the
  * caller on !strip_debug / !jit_mode / ELF target. */
 void link_layout_debug(struct Linker*, LinkImage*);
 /* Byte buffer for a file-only debug LinkSection, or NULL if `id` is not
  * a registered file-only section (link_layout.c). */
 u8* link_fileonly_bytes(LinkImage*, LinkSectionId);
 
 /* ---- Public entries (link_reloc_layout.c) ---------------------------------
  */
 void link_assign_symbol_vaddrs(struct Linker*, LinkImage*);
 void link_emit_array_boundaries(struct Linker*, LinkImage*);
 void link_emit_tls_boundaries(struct Linker*, LinkImage*);
 void link_emit_encoding_section_boundaries(struct Linker*, LinkImage*);
 void link_layout_jit_stubs(struct Linker*, LinkImage*, u32 map_size,
                            LinkSymId** stub_map_out);
 void link_layout_got(struct Linker*, LinkImage*, u32 map_size,
                      LinkSymId** got_map_out);
 void link_layout_iplt(struct Linker*, LinkImage*);
 void link_emit_relocations(struct Linker*, LinkImage*, const LinkSymId* got_map,
                            const LinkSymId* stub_map);
 void link_resolve_entry(struct Linker*, LinkImage*);
 
 /* Defined in link.c. Walks the Linker's inputs and records each input's
  * ObjBuilder on the LinkImage so the JIT debug view can reach its
  * .debug_* sections after link_free runs.  LINK_INPUT_OBJ_BYTES
  * builders are moved (the LinkInput's obj pointer is nulled so
  * linker_release skips them); LINK_INPUT_OBJ builders are borrowed
  * (the caller still owns).  DSO / TBD inputs are skipped. */
 void link_capture_debug_inputs(struct Linker*, LinkImage*);
 
 /* Default PE/COFF ImageBase for executables.  Mirrored in link_coff.c
  * (the emitter writes this into the optional header).  Exposed here so
  * link_layout can synthesize the `__ImageBase` symbol at the same
  * vaddr, before resolve_undefs runs. */
 #define LINK_PE_IMAGE_BASE 0x140000000ULL
 
 /* Define / upsert a synthetic global symbol resolved to `vaddr`.
  * Satisfies any prior undef ref (e.g. _DYNAMIC from Scrt1.o,
  * __dso_handle from libc_nonshared.a) and fans out across per-input
  * duplicate name slots so emit_reloc_records sees the resolved
  * vaddr.  Implemented in link_layout.c. */
 void link_define_boundary(struct Linker*, LinkImage*, const char* name,
                           u64 vaddr);
 
 /* SegVec instances for image-owned tables. Pointers returned by *_at /
  * *_push remain valid for the LinkImage's lifetime. */
 SEGVEC_DEFINE(LinkSyms, LinkSymbol, 6);       /*  64 entries per segment */
 SEGVEC_DEFINE(LinkRelocs, LinkRelocApply, 7); /* 128 entries per segment */
 
 /* ---- Dynamic-link synthesis state (Phase 4) ----
  *
  * The ELF linker's dynamic-link working state (.dynsym / .dynstr / .gnu.hash
  * / .rela.* / .plt / .got.plt / .dynamic) and its wire-format records live in
  * the ELF-only header src/obj/elf/link_dyn.h. LinkImage holds it as an opaque
  * `LinkDynState* dyn` so the COFF/Mach-O linkers never see the ELF field
  * names; only the ELF linker dereferences it. */
 typedef struct LinkDynState LinkDynState;
 
 struct LinkImage {
   Compiler* c;
   Heap* heap;
   CompilerCleanup* deferred; /* registered by link_resolve */
   /* Borrowed back-pointer set by link_resolve.  The Linker is not
    * mutated through this handle; it's used by the format-specific emit
    * passes that need to walk LinkInputs (e.g. resolving an imported
    * symbol's dso_input_id back to the providing dylib's install-name). */
   struct Linker* linker;
 
   /* Final merged RISC-V ELF flags, copied after archive selection. */
   u32 elf_e_flags;
   u8 have_elf_e_flags;
 
   LinkSyms syms;   /* LinkSymId = slot index + 1 */
   SymHash globals; /* name -> LinkSymId for global/weak */
 
   LinkSection* sections; /* id = index + 1 */
   u32 nsections;
 
   LinkSegment* segments; /* id = index + 1 */
   u32 nsegments;
   u8** segment_bytes;        /* one per segment; size = file_size */
   size_t* segment_bytes_cap; /* allocation size for free */
 
   LinkRelocs relocs;
 
   /* IFUNC trampoline table (image-relative vaddrs).  One entry per
    * defined STT_GNU_IFUNC symbol: (resolver_vaddr, slot_vaddr).  The
    * JIT path walks this after applying relocations, calls each
    * resolver in-process, and stores the result into the slot's write
    * alias.  The ELF emit path uses it to seed a startup init routine
    * (or panics when the routine is not yet wired in). */
   u64* iplt_pairs; /* 2 * niplt entries */
   u32 niplt;
 
   LinkSymId entry_sym;
 
   /* TLS image span (image-relative).  Set when any input contributes
    * an SF_TLS section.  filesz covers the .tdata bytes that initialize
    * the per-thread block; memsz adds .tbss zero-fill.  tls_align is
    * the natural alignment of the TLS image (max of contributing
    * sections), distinct from the containing PT_LOAD's page align.
    * AArch64 ELF ABI: TP-relative offset of a TLS symbol with image
    * offset `o` is `o + 16` (16-byte TCB ahead of the TLS data). */
   u64 tls_vaddr;
   u64 tls_filesz;
   u64 tls_memsz;
   u32 tls_align;
 
   InputMap* input_maps; /* one per input; indexed by input_id-1 */
   u32 ninput_maps;
 
   /* Debug-capture state for the JIT path.  Populated by
    * link_capture_debug_inputs at the tail of link_resolve so the input
    * ObjBuilders (which carry .debug_* sections + their per-section
    * relocations — neither consumed nor mutated by layout) survive the
    * Linker's teardown and become reachable from kit_jit_view.
    *
    * Parallel to input_maps: dbg_objs[i] is the ObjBuilder for input
    * (i+1), or NULL when no debug info is present / the input kind isn't
    * relevant (DSO/TBD).  dbg_objs_owned[i] is 1 when the image must
    * obj_free the builder at link_image_free (transferred from
    * LINK_INPUT_OBJ_BYTES), 0 when borrowed (LINK_INPUT_OBJ — caller
    * still owns). */
   ObjBuilder** dbg_objs;
   u8* dbg_objs_owned;
   u32 dbg_objs_n;
 
   /* File-only debug-section registry (AOT ELF path).  link_layout_debug
    * appends one file-only LinkSection per surviving .debug_* contribution
    * as a contiguous id range [dbg_first_lsid, dbg_first_lsid+dbg_count).
    * dbg_bytes[i] / dbg_size[i] hold that contribution's own byte buffer
    * (relocs applied in place at reloc-offset), indexed by lsid -
    * dbg_first_lsid.  Empty on the JIT / Mach-O / COFF lanes. */
   LinkSectionId dbg_first_lsid;
   u32 dbg_count;
   u8** dbg_bytes;
   u64* dbg_size;
 
   /* Dynamic-link state (Phase 4). NULL when emit_pie was not set on
    * the Linker — i.e., the static-exe / JIT path. Owned by the image. */
   LinkDynState* dyn;
   /* Mirror of Linker.emit_pie at link_resolve time; consulted by emit. */
   int pie;
   /* Mirror of Linker.emit_shared at link_resolve time; consulted by emit. */
   int shared;
   /* Set when layout was driven by Linker.script. The emitter then keeps
    * segment vaddrs at their script-assigned absolute values, drops the
    * self-describing headers PT_LOAD / build-id PT_NOTE, and only shifts
    * file offsets to make room for ehdr+phdrs. */
   u8 scripted;
   /* -Ttext: when text_base_set, the static-exe image base override, mirrored
    * from Linker at link_resolve time. Ignored if pie/scripted. */
   int text_base_set;
   u64 text_base;
 
   /* Final emit facts recorded by the format emitter for the link-map /
    * symbols side-files (kit_link_session_write_map / _write_symbols, which run
    * on the format-neutral image *after* emit). The emitter owns runtime-base
    * selection and headers synthesis, so the report writers read the resolved
    * values back from here instead of re-deriving format-specific policy.
    *
    * load_base is the runtime base the emitter added to image-relative vaddrs:
    * IMAGE_BASE_STATIC, or a -Ttext override, for a static ET_EXEC; 0 for
    * PIE/scripted/JIT (which keep image-relative addresses). The headers_*
    * fields describe the synthesized read-only headers load segment (ELF: the
    * ehdr+phdrs PT_LOAD mapped at load_base); headers_present is 0 when the
    * format emits no separate headers segment (scripted ELF, non-ELF). All
    * stay zero until emit runs, so a report taken without an emit reports
    * image-relative addresses, as before. */
   u64 load_base;
   u64 headers_filesz;
   u64 headers_memsz;
   u32 headers_align;
   u8 headers_present;
 };
 
 /* Whether S is the canonical LinkSymbol for its non-local name.
  *
  * Resolution deliberately keeps one LinkSymbol per input symbol: after an
  * undefined reference is resolved, its per-input slot mirrors the definition
  * so relocations can retain their stable LinkSymId.  img->globals remains the
  * authority for the single canonical global/weak slot.  Format emitters and
  * post-link reports must use this predicate rather than mistaking those
  * resolved reference slots for distinct definitions.
  *
  * Locals and nameless records are outside the global-name authority and are
  * therefore not canonical globals.  A named non-local missing from globals is
  * retained defensively; synthetic/import bookkeeping can briefly have that
  * shape while an image is being assembled. */
 static inline int link_symbol_is_canonical_global(const LinkImage* img,
                                                   const LinkSymbol* s) {
   LinkSymId canonical;
   if (!img || !s || !s->name || s->bind == SB_LOCAL) return 0;
   canonical = symhash_get(&img->globals, s->name);
   return canonical == LINK_SYM_NONE || canonical == s->id;
 }
 
 /* Page granularity used for ELF segment alignment and the file-offset /
  * vaddr congruence the runtime loader requires. 16 KiB matches AArch64
  * Apple Silicon and the common Linux/AArch64 kernel config; 4 KiB pages
  * are also valid at runtime since 16K is a multiple. */
 #define PAGE_SIZE 0x4000u
 
 /* Apply one relocation in place. P_bytes points at the first byte of the
  * relocation site within the final memory; S is the resolved final
  * address of the target symbol; A the addend; P the final address of
  * the relocation site. Panics on unsupported kinds. */
 void link_reloc_apply(Compiler*, RelocKind, u8* P_bytes, u64 S, i64 A, u64 P);
 
 /* kit emits local-exec TLS only: a thread-local's offset within THIS image's
  * TLS block is fixed at link time, so a local-exec access (or the TP-relative
  * fill of a TLS initial-exec GOT slot) is valid only against a thread-local
  * *defined in the image being linked*.  Panic with a clear diagnostic if `tgt`
  * is imported from a shared object (its TLS block belongs to another module,
  * sized and placed by the dynamic loader) or resolved to a non-thread-local
  * definition.  There is no initial-exec/global-dynamic fallback to relax to,
  * so the only alternative is a silently bogus tp-relative offset -- hence the
  * hard error.  A no-op when `tgt` is a thread-local defined here. */
 void link_require_local_tls(Compiler*, const LinkSymbol* tgt);
 
 /* Public link_emit_image_writer dispatches by Compiler.target.obj. The
  * ELF and Mach-O writers get architecture identity from LinkArchDesc;
  * reloc application remains keyed by RelocKind. COFF arrives later. */
 void link_emit_elf(LinkImage*, Writer*);
 void link_emit_macho(LinkImage*, Writer*);
 void link_emit_coff(LinkImage*, Writer*);
 
 /* Format-agnostic 16-byte image identity, derived from per-segment
  * post-shift bytes + vaddrs/sizes.  ELF wraps it in a
  * .note.gnu.build-id; Mach-O will wrap it in LC_UUID; COFF/PE in a
  * debug directory entry.  One source of truth so the bytes match
  * across formats. */
 #define LINK_IMAGE_ID_BYTES 16u
 void link_image_id_compute(const LinkImage*, u8 out[LINK_IMAGE_ID_BYTES]);
 
 #endif