kit

link_internal.h (28288B)

---

 #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_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;
   /* 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;
   /* 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;
   /* Caller-supplied PT_INTERP. layout_dyn falls back to a target-
    * derived default when this is 0. */
   Sym interp_path;
   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*);
 /* 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*);
 
 /* ---- 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) ----
  *
  * Owned by LinkImage when emit_pie is set. Holds the synthesized
  * .interp / .dynsym / .dynstr / .gnu.hash / .rela.dyn / .rela.plt /
  * .plt / .got.plt / .dynamic content plus the section ids the emit
  * pass needs to fill PT_DYNAMIC and the .dynamic body.
  *
  * Phase 4 builds the dynsym/dynstr/gnu.hash content and the JUMP_SLOT
  * .rela.plt records (one per imported function, against its synthetic
  * .got.plt slot). The .plt body is allocated but not emitted (Phase 5).
  * Phase 6 populates .rela.dyn with R_AARCH64_RELATIVE records for any
  * internal absolute reloc seen during reloc-apply.
  *
  * Layout invariants this struct enforces:
  *   - dynsym entry 0 is the reserved STN_UNDEF slot (zero-filled).
  *   - dynsym entries 1..nimport_func+nimport_data are imports, in the
  *     order PLT-functions first, then GOT-data.
  *   - PLT slots and JUMP_SLOT entries match the import_func order 1:1.
  *   - .got.plt has 3 reserved leading u64 slots (per AArch64 psABI:
  *     slot 0 = &.dynamic, slot 1 = link_map cookie, slot 2 =
  *     _dl_runtime_resolve), then one slot per imported function.
  */
 
 typedef struct DynSymRec {
   u32 st_name; /* offset into .dynstr */
   u8 st_info;
   u8 st_other;
   u16 st_shndx;
   u64 st_value;
   u64 st_size;
 } DynSymRec;
 
 typedef struct DynRela {
   u64 r_offset; /* image-relative vaddr of the patch site */
   u64 r_info;   /* ELF64_R_INFO(dynsym_index, elf_reloc_type) */
   i64 r_addend;
 } DynRela;
 
 typedef struct LinkDynState {
   /* PT_INTERP / .interp. interp_path is interned in compiler->global. */
   Sym interp_path;
   LinkSectionId sec_interp;
 
   /* .dynsym */
   LinkSectionId sec_dynsym;
   DynSymRec* dynsym;
   u32 ndynsym;      /* incl. slot-0 STN_UNDEF */
   u32 first_global; /* sh_info value: index of first non-local entry */
 
   /* .dynstr */
   LinkSectionId sec_dynstr;
   u8* dynstr;
   u32 dynstr_len;
 
   /* .gnu.hash */
   LinkSectionId sec_gnu_hash;
   u8* gnu_hash;
   u32 gnu_hash_len;
 
   /* GNU symbol versioning. Emitted only when at least one imported symbol
    * binds to a versioned DSO export (nverneed > 0); otherwise all three are
    * zero and no version sections / DT_VER* entries are produced (musl/static
    * links are unchanged). .gnu.version is one u16 per .dynsym entry;
    * .gnu.version_r holds Verneed/Vernaux requirements keyed by DT_NEEDED
    * soname. Both carry only .dynstr offsets + version indices (no vaddrs), so
    * the bytes are final at layout time and copied verbatim during emit. */
   LinkSectionId sec_gnu_version;
   u8* versym; /* ndynsym * 2 bytes */
   u32 versym_len;
   LinkSectionId sec_gnu_version_r;
   u8* verneed; /* nverneed Verneed records + their Vernaux */
   u32 verneed_len;
   u32 nverneed; /* DT_VERNEEDNUM */
 
   /* .rela.dyn — R_AARCH64_GLOB_DAT (imports against .got slots) and
    * R_AARCH64_RELATIVE (PIE internal abs64 fixups, populated during
    * Phase 6 emit). Pre-sized at layout time; the RELATIVE tail is
    * filled in during emit. */
   LinkSectionId sec_rela_dyn;
   DynRela* rela_dyn;
   u32 nrela_dyn;    /* number of records currently populated */
   u32 cap_rela_dyn; /* allocation capacity (records, not bytes) */
 
   /* .rela.plt — R_AARCH64_JUMP_SLOT, one per imported function. */
   LinkSectionId sec_rela_plt;
   DynRela* rela_plt;
   u32 nrela_plt;
 
   /* .plt — 32-byte PLT0 stub + 16 bytes per imported function. Body
    * is allocated (zero-initialized) but not emitted in Phase 4. */
   LinkSectionId sec_plt;
   u32 nplt;      /* number of imported functions */
   u64 plt_vaddr; /* image-relative .plt base */
   u64 plt_size;
 
   /* .got.plt — 24 reserved bytes + 8 per PLT slot. */
   LinkSectionId sec_got_plt;
   u64 got_plt_vaddr;
   u64 got_plt_size;
 
   /* .dynamic — PT_DYNAMIC body. Built at layout time; its size is
    * fixed once we know the DT_NEEDED count. */
   LinkSectionId sec_dynamic;
   u64 dynamic_vaddr;
   u64 dynamic_size;
   u32 ndyn_entries;
 
   /* DT_NEEDED list (interned soname Syms, in input order). */
   Sym* needed;
   u32 nneeded;
 
   /* Per-import dynsym index, indexed by LinkSymId. 0 means "not
    * imported / not in dynsym". Used by GLOB_DAT / JUMP_SLOT emit. */
   u32* sym_dynidx; /* size = sym_dynidx_size */
   u32 sym_dynidx_size;
 
   /* Per-import PLT entry vaddr, indexed by LinkSymId (Phase 5).  Set
    * for every imported function: vaddr of its 16-byte PLT stub inside
    * `.plt`.  0 means "no PLT stub" (symbol is data-only or not
    * imported).  apply_all_relocs reads this when redirecting a
    * CALL26/JUMP26 against an imported function — S becomes the PLT
    * entry vaddr instead of the symbol's (zero) vaddr.  The vaddrs
    * stored here track the post-shift values (shift_image_addresses
    * bumps them along with .plt's segment vaddr). */
   u64* sym_plt_vaddr; /* size = sym_dynidx_size */
 } 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;
 
   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;
   /* 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;
 };
 
 /* 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