kit

link.c (31151B)

---

 /* Linker: lifecycle, input registration, and LinkImage accessors.
  *
  * Resolution and layout live in link_layout.c; relocation application
  * in link_reloc.c; format-specific emit in link_elf.c; JIT mapping in
  * link_jit.c.
  *
  * Discipline (see link.h:136): inputs are never destroyed by
  * link_resolve, LinkInputId / ObjBuilder* mappings are stable for the
  * Linker's lifetime, and resolution produces a fresh LinkImage rather
  * than mutating the Linker. The single-shot implementation must keep
  * those invariants so a future incremental re-resolve can plug in. */
 
 #include "link/link.h"
 
 #include <kit/archive.h>
 #include <kit/core.h>
 #include <kit/object.h>
 #include <kit/target.h>
 #include <string.h>
 
 #include "core/heap.h"
 #include "core/pool.h"
 #include "core/slice.h"
 #include "core/vec.h"
 #include "link/link_internal.h"
 #include "obj/elf/elf.h"
 #include "obj/format.h"
 
 static const char* link_float_abi_name(KitFloatAbi abi) {
   switch (abi) {
     case KIT_FLOAT_ABI_DEFAULT:
       return "default";
     case KIT_FLOAT_ABI_SOFT:
       return "soft";
     case KIT_FLOAT_ABI_SINGLE:
       return "single";
     case KIT_FLOAT_ABI_DOUBLE:
       return "double";
   }
   return "unknown";
 }
 
 /* OS compatibility is deliberately directional: an ELF object carrying the
  * generic/Linux OSABI may be consumed by Linux, Android, or a freestanding
  * image, because that header value is what assemblers use for otherwise
  * platform-neutral relocatables. A FreeBSD object or a Mach-O platform stamp
  * is never borrowed across operating systems. */
 static int link_target_os_compatible(KitTargetSpec expected,
                                      KitTargetSpec actual) {
   if (expected.os == actual.os) return 1;
   if (expected.obj != KIT_OBJ_ELF || actual.os != KIT_OS_LINUX) return 0;
   return expected.os == KIT_OS_ANDROID ||
          expected.os == KIT_OS_FREESTANDING;
 }
 
 static const char* link_target_mismatch(KitTargetSpec expected,
                                         KitTargetSpec actual) {
   if (expected.arch != actual.arch) return "architecture";
   if (expected.obj != actual.obj) return "object format";
   if (expected.ptr_size != actual.ptr_size) return "pointer size";
   if (expected.big_endian != actual.big_endian) return "endianness";
   if (!link_target_os_compatible(expected, actual)) return "operating system";
   if ((expected.arch == KIT_ARCH_RV32 || expected.arch == KIT_ARCH_RV64) &&
       expected.float_abi != KIT_FLOAT_ABI_DEFAULT &&
       actual.float_abi != KIT_FLOAT_ABI_DEFAULT &&
       expected.float_abi != actual.float_abi)
     return "float ABI";
   return NULL;
 }
 
 static void link_target_panic(Linker* l, Slice name, Slice container,
                               KitTargetSpec actual, const char* reason) {
   KitTargetSpec expected = l->c->target;
   if (container.s) {
     compiler_panic(
         l->c, SRCLOC_NONE,
         "link: incompatible input '%.*s(%.*s)': %s mismatch; expected "
         "arch=%s os=%s format=%s ptr=%u endian=%s float=%s, got "
         "arch=%s os=%s format=%s ptr=%u endian=%s float=%s",
         SLICE_ARG(container), SLICE_ARG(name), reason,
         kit_target_arch_name(expected.arch), kit_target_os_name(expected.os),
         kit_target_obj_name(expected.obj), (u32)expected.ptr_size,
         expected.big_endian ? "big" : "little",
         link_float_abi_name((KitFloatAbi)expected.float_abi),
         kit_target_arch_name(actual.arch), kit_target_os_name(actual.os),
         kit_target_obj_name(actual.obj), (u32)actual.ptr_size,
         actual.big_endian ? "big" : "little",
         link_float_abi_name((KitFloatAbi)actual.float_abi));
   }
   compiler_panic(
       l->c, SRCLOC_NONE,
       "link: incompatible input '%.*s': %s mismatch; expected "
       "arch=%s os=%s format=%s ptr=%u endian=%s float=%s, got "
       "arch=%s os=%s format=%s ptr=%u endian=%s float=%s",
       SLICE_ARG(name), reason, kit_target_arch_name(expected.arch),
       kit_target_os_name(expected.os), kit_target_obj_name(expected.obj),
       (u32)expected.ptr_size, expected.big_endian ? "big" : "little",
       link_float_abi_name((KitFloatAbi)expected.float_abi),
       kit_target_arch_name(actual.arch), kit_target_os_name(actual.os),
       kit_target_obj_name(actual.obj), (u32)actual.ptr_size,
       actual.big_endian ? "big" : "little",
       link_float_abi_name((KitFloatAbi)actual.float_abi));
 }
 
 static void link_validate_target(Linker* l, Slice name, Slice container,
                                  KitTargetSpec actual) {
   const char* reason = link_target_mismatch(l->c->target, actual);
   if (reason) link_target_panic(l, name, container, actual, reason);
 }
 
 static void link_validate_obj_target(Linker* l, Slice name, ObjBuilder* ob) {
   Compiler* source = obj_compiler(ob);
   if (!source)
     compiler_panic(l->c, SRCLOC_NONE,
                    "link: input '%.*s' has no target-owning compiler",
                    SLICE_ARG(name));
   link_validate_target(l, name, SLICE_NULL, source->target);
 }
 
 static void link_validate_bytes_target(Linker* l, Slice name, Slice container,
                                        const u8* data, size_t len,
                                        int allow_text_dso) {
   KitTargetSpec actual;
   KitStatus st = kit_detect_target(data, len, &actual);
   if (st == KIT_OK) {
     link_validate_target(l, name, container, actual);
     return;
   }
   if (allow_text_dso && kit_detect_fmt(data, len) == KIT_BIN_UNKNOWN) return;
   if (container.s)
     compiler_panic(l->c, SRCLOC_NONE,
                    "link: cannot determine target of input '%.*s(%.*s)'",
                    SLICE_ARG(container), SLICE_ARG(name));
   compiler_panic(l->c, SRCLOC_NONE,
                  "link: cannot determine target of input '%.*s'",
                  SLICE_ARG(name));
 }
 
 void link_merge_elf_e_flags(Linker* l, ObjBuilder* ob, KitSlice label) {
   u32 incoming;
   u32 known = EF_RISCV_RVC | EF_RISCV_FLOAT_ABI_MASK | EF_RISCV_RVE |
               EF_RISCV_TSO;
   u32 must_match = EF_RISCV_FLOAT_ABI_MASK | EF_RISCV_RVE | ~known;
   u32 merge_bits = EF_RISCV_RVC | EF_RISCV_TSO;
   KitFloatAbi incoming_abi;
   KitFloatAbi target_abi;
   Slice first;
   if (!l || !ob || l->c->target.obj != KIT_OBJ_ELF ||
       (l->c->target.arch != KIT_ARCH_RV32 &&
        l->c->target.arch != KIT_ARCH_RV64) ||
       !obj_get_elf_e_flags(ob, &incoming))
     return;
   incoming_abi = elf_riscv_float_abi_from_e_flags(incoming);
   target_abi = (KitFloatAbi)l->c->target.float_abi;
   if (target_abi != KIT_FLOAT_ABI_DEFAULT && incoming_abi != target_abi) {
     compiler_panic(l->c, SRCLOC_NONE,
                    "link: incompatible input '%.*s': RISC-V float ABI is %s, "
                    "link target requires %s (e_flags=0x%x)",
                    SLICE_ARG(label), link_float_abi_name(incoming_abi),
                    link_float_abi_name(target_abi), incoming);
   }
   if (!l->have_elf_e_flags) {
     l->elf_e_flags = incoming;
     l->elf_e_flags_source = pool_intern_slice(l->c->global, label);
     l->have_elf_e_flags = 1;
     return;
   }
   if ((l->elf_e_flags & must_match) != (incoming & must_match)) {
     first = l->elf_e_flags_source
                 ? pool_slice(l->c->global, l->elf_e_flags_source)
                 : SLICE_LIT("<first input>");
     compiler_panic(l->c, SRCLOC_NONE,
                    "link: incompatible RISC-V ELF e_flags: input '%.*s' has "
                    "0x%x, input '%.*s' has 0x%x (float ABI, RVE, and reserved "
                    "bits must agree)",
                    SLICE_ARG(label), incoming, SLICE_ARG(first),
                    l->elf_e_flags);
   }
   l->elf_e_flags |= incoming & merge_bits;
 }
 
 /* ---- SrcLoc helper ---- */
 
 /* SymHash is a HASHMAP_DEFINE instance — see link_internal.h. The thin
  * symhash_* wrappers there preserve the historic insert-if-absent / by-
  * value get API. */
 
 /* ---- Linker lifecycle ---- */
 
 static void linker_release(Linker* l) {
   u32 i, j;
   if (!l) return;
   /* Free the ObjBuilders we own (the ones we read from bytes inputs).
    * link_add_obj inputs are caller-owned and stay alive. */
   for (i = 0; i < LinkInputs_count(&l->inputs); ++i) {
     LinkInput* in = LinkInputs_at(&l->inputs, i);
     if ((in->kind == LINK_INPUT_OBJ_BYTES ||
          in->kind == LINK_INPUT_DSO_BYTES) &&
         in->obj)
       obj_free(in->obj);
   }
   /* Free archive member ObjBuilders that were never pulled into inputs.
    * Pulled members had their `obj` pointer transferred and nulled, so
    * obj_free(NULL) is safe regardless. */
   for (i = 0; i < LinkArchives_count(&l->archives); ++i) {
     LinkArchive* ar = LinkArchives_at(&l->archives, i);
     for (j = 0; j < ar->nmembers; ++j) {
       if (ar->members[j].obj) obj_free(ar->members[j].obj);
     }
     if (ar->members)
       l->heap->free(l->heap, ar->members, sizeof(*ar->members) * ar->nmembers);
   }
   LinkArchives_fini(&l->archives);
   LinkInputs_fini(&l->inputs);
   l->heap->free(l->heap, l, sizeof(*l));
 }
 
 static void linker_cleanup(void* arg) { linker_release((Linker*)arg); }
 
 Linker* link_new(Compiler* c) {
   Heap* h = (Heap*)c->ctx->heap;
   Linker* l = (Linker*)h->alloc(h, sizeof(*l), _Alignof(Linker));
   if (!l) return NULL;
   memset(l, 0, sizeof(*l));
   l->c = c;
   l->heap = h;
   LinkInputs_init(&l->inputs, h);
   LinkArchives_init(&l->archives, h);
   /* Default entry: ELF/static convention uses `_start`.  Mach-O's
    * LC_MAIN names main directly (dyld owns the C runtime startup),
    * so the on-disk symbol is `_main` (the mangled form of `main`).
    * Format choice lives in obj_format_default_entry_name. */
   l->entry_name = pool_intern_slice(
       c->global, slice_from_cstr(obj_format_default_entry_name(c)));
   /* Match the rest of libkit's lifetime story: the new'd Linker is
    * registered for cleanup in case a panic fires before link_free. */
   l->deferred = compiler_defer(c, linker_cleanup, l);
   return l;
 }
 
 void link_free(Linker* l) {
   Compiler* c;
   CompilerCleanup* d;
   if (!l) return;
   c = l->c;
   d = l->deferred;
   linker_release(l);
   if (d) compiler_undefer(c, d);
 }
 
 /* ---- input registration ---- */
 
 static LinkInput* inputs_push(Linker* l, LinkInputId* id_out) {
   u32 idx;
   LinkInput* in = LinkInputs_push(&l->inputs, &idx);
   if (!in)
     compiler_panic(l->c, SRCLOC_NONE, "link: out of memory growing inputs");
   *id_out = (LinkInputId)(idx + 1u);
   in->id = *id_out;
   return in;
 }
 
 LinkInputId link_add_obj(Linker* l, ObjBuilder* ob) {
   LinkInputId id;
   LinkInput* in;
   if (!l || !ob) return LINK_INPUT_NONE;
   link_validate_obj_target(l, SLICE_LIT("<in-memory object>"), ob);
   link_merge_elf_e_flags(l, ob, SLICE_LIT("<in-memory object>"));
   in = inputs_push(l, &id);
   in->kind = LINK_INPUT_OBJ;
   in->order = l->next_input_order++;
   in->obj = ob;
   return id;
 }
 
 LinkInputId link_add_obj_bytes(Linker* l, const char* name, const u8* data,
                                size_t len) {
   ObjBuilder* ob;
   LinkInput* in;
   LinkInputId id;
   KitBinFmt fmt;
   const ObjFormatImpl* impl;
   const char* reader_name;
   Slice label;
   if (!l || !data || !len) return LINK_INPUT_NONE;
   label = name ? slice_from_cstr(name) : SLICE_LIT("(unnamed)");
   link_validate_bytes_target(l, label, SLICE_NULL, data, len, 0);
   fmt = kit_detect_fmt(data, len);
   impl = obj_format_lookup_bin(fmt);
   if (!impl || !impl->read)
     compiler_panic(
         l->c, SRCLOC_NONE,
         "link_add_obj_bytes: unsupported object format "
         "(fmt=%u) for '%.*s'",
         (u32)fmt,
         SLICE_ARG(name ? slice_from_cstr(name) : SLICE_LIT("(unnamed)")));
   reader_name = impl->read_name;
   ob = impl->read(l->c, name, data, len);
   if (!ob)
     compiler_panic(
         l->c, SRCLOC_NONE, "link_add_obj_bytes: %.*s returned NULL for '%.*s'",
         SLICE_ARG(slice_from_cstr(reader_name)),
         SLICE_ARG(name ? slice_from_cstr(name) : SLICE_LIT("(unnamed)")));
   link_merge_elf_e_flags(l, ob, label);
   in = inputs_push(l, &id);
   in->order = l->next_input_order++;
   in->obj = ob; /* re-uses the ObjBuilder slot for ownership */
   in->name = name ? pool_intern_cstr(l->c->global, name) : 0;
   {
     Sym soname = 0;
     if (impl->classify_obj_input &&
         impl->classify_obj_input(l->c, ob, &soname)) {
       in->kind = LINK_INPUT_DSO_BYTES;
       in->soname = soname;
     } else {
       in->kind = LINK_INPUT_OBJ_BYTES;
     }
   }
   return id;
 }
 
 LinkInputId link_add_dso_bytes(Linker* l, const char* name, const u8* data,
                                size_t len) {
   ObjBuilder* ob = NULL;
   LinkInput* in;
   LinkInputId id;
   Sym soname = 0;
   KitBinFmt fmt;
   ObjFormatDsoReader reader;
   const ObjFormatImpl* target_impl;
   const char* reader_name;
   Slice label;
   if (!l || !data || !len) return LINK_INPUT_NONE;
   label = name ? slice_from_cstr(name) : SLICE_LIT("(unnamed)");
   link_validate_bytes_target(l, label, SLICE_NULL, data, len, 1);
   if (!obj_format_dso_reader_for_bytes(data, len, &fmt, &reader))
     compiler_panic(
         l->c, SRCLOC_NONE,
         "link_add_dso_bytes: unsupported DSO format "
         "(fmt=%u) for '%.*s'",
         (u32)fmt,
         SLICE_ARG(name ? slice_from_cstr(name) : SLICE_LIT("(unnamed)")));
   target_impl = obj_format_lookup(l->c->target.obj);
   if (!target_impl || reader.format != target_impl)
     compiler_panic(
         l->c, SRCLOC_NONE,
         "link: incompatible input '%.*s': object format mismatch; expected "
         "format=%s, got format=%s",
         SLICE_ARG(label), kit_target_obj_name(l->c->target.obj),
         reader.format && reader.format->name ? reader.format->name : "unknown");
   reader_name = reader.name;
   ob = reader.read(l->c, name, data, len, &soname);
   if (!ob)
     compiler_panic(
         l->c, SRCLOC_NONE, "link_add_dso_bytes: %.*s returned NULL for '%.*s'",
         SLICE_ARG(slice_from_cstr(reader_name)),
         SLICE_ARG(name ? slice_from_cstr(name) : SLICE_LIT("(unnamed)")));
   link_merge_elf_e_flags(l, ob, label);
   in = inputs_push(l, &id);
   in->kind = LINK_INPUT_DSO_BYTES;
   in->order = l->next_input_order++;
   in->obj = ob;
   in->name = name ? pool_intern_cstr(l->c->global, name) : 0;
   /* DT_SONAME wins; fall back to the file's basename if the DSO has
    * no SONAME (matches GNU ld's behaviour for hand-rolled libraries
    * that forgot to set DT_SONAME). */
   if (soname != 0) {
     in->soname = soname;
   } else if (name) {
     const char* base = name;
     const char* p;
     for (p = name; *p; ++p)
       if (*p == '/') base = p + 1;
     in->soname = pool_intern_cstr(l->c->global, base);
   } else {
     in->soname = 0;
   }
   return id;
 }
 
 LinkInputId link_add_archive_bytes(Linker* l, const char* name, const u8* data,
                                    size_t len, u8 whole_archive, u8 link_mode,
                                    u8 group_id) {
   KitSlice in_arc;
   KitArIter* it = NULL;
   KitArMember mem;
   LinkArchive* ar;
   u32 n;
   Sym archive_hint = 0;
   const ObjFormatImpl* target_impl;
 
   if (!l || !data || !len) return LINK_INPUT_NONE;
   target_impl = obj_format_lookup(l->c->target.obj);
   if (target_impl && target_impl->archive_hint)
     archive_hint = target_impl->archive_hint(l->c, name);
 
   in_arc.data = data;
   in_arc.len = len;
   if (kit_ar_iter_new(kit_compiler_context(l->c), &in_arc, &it) != KIT_OK ||
       !it)
     compiler_panic(
         l->c, SRCLOC_NONE,
         "link_add_archive_bytes: '%.*s' is not a valid ar archive",
         SLICE_ARG(name ? slice_from_cstr(name) : SLICE_LIT("(unnamed)")));
 
   /* Two-pass: count members so we allocate the member array exactly
    * once. The linker_release path frees by nmembers, so we need
    * allocation size to match. */
   n = 0;
   while (kit_ar_iter_next(it, &mem) == KIT_ITER_ITEM) ++n;
   kit_ar_iter_free(it);
   it = NULL;
 
   ar = LinkArchives_push(&l->archives, NULL);
   if (!ar)
     compiler_panic(l->c, SRCLOC_NONE, "link: out of memory growing archives");
   ar->name = name ? pool_intern_cstr(l->c->global, name) : 0;
   ar->order = l->next_input_order++;
   ar->whole_archive = whole_archive;
   ar->link_mode = link_mode;
   ar->group_id = group_id;
   ar->nmembers = n;
   ar->members =
       n ? (LinkArchiveMember*)l->heap->alloc(l->heap, sizeof(*ar->members) * n,
                                              _Alignof(LinkArchiveMember))
         : NULL;
   if (n && !ar->members)
     compiler_panic(l->c, SRCLOC_NONE, "link: oom on archive members");
   if (n) memset(ar->members, 0, sizeof(*ar->members) * n);
 
   /* Pass 2: parse each member as object. ar.c's iterator skips the
    * symbol-index ('/' and '__.SYMDEF') and long-name ('//') members
    * for us, so every member returned here is a real object file.
    * Format is detected per-member so a single archive could in
    * principle hold mixed formats (in practice it never does). */
   if (kit_ar_iter_new(kit_compiler_context(l->c), &in_arc, &it) != KIT_OK ||
       !it)
     compiler_panic(
         l->c, SRCLOC_NONE,
         "link_add_archive_bytes: ar_iter_init failed on '%.*s' "
         "second pass",
         SLICE_ARG(name ? slice_from_cstr(name) : SLICE_LIT("(unnamed)")));
   n = 0;
   while (kit_ar_iter_next(it, &mem) == KIT_ITER_ITEM && n < ar->nmembers) {
     ObjBuilder* ob = NULL;
     KitBinFmt mfmt = kit_detect_fmt(mem.data, mem.size);
     const ObjFormatImpl* member_impl = obj_format_lookup_bin(mfmt);
     link_validate_bytes_target(
         l, mem.name.len ? mem.name : SLICE_LIT("(unnamed)"),
         name ? slice_from_cstr(name) : SLICE_LIT("(unnamed)"), mem.data,
         mem.size, 0);
     if (target_impl && target_impl->archive_member) {
       ObjFormatArchiveMember desc;
       ObjFormatArchiveAction action;
       memset(&desc, 0, sizeof(desc));
       desc.archive_name = name;
       desc.member_name = mem.name.s;
       desc.data = mem.data;
       desc.len = mem.size;
       desc.bin_fmt = mfmt;
       desc.archive_hint = archive_hint;
       action = target_impl->archive_member(l->c, &desc, &ob);
       if (action != OBJ_FORMAT_ARCHIVE_KEEP) {
         ar->members[n].name =
             mem.name.len ? pool_intern_slice(l->c->global, mem.name) : 0;
         ar->members[n].obj = ob;
         ++n;
         continue;
       }
     }
     if (!member_impl || !member_impl->read)
       compiler_panic(
           l->c, SRCLOC_NONE,
           "link_add_archive_bytes: unsupported member "
           "format (fmt=%u) for '%.*s' in archive '%.*s'",
           (u32)mfmt,
           SLICE_ARG(mem.name.len ? mem.name : SLICE_LIT("(unnamed)")),
           SLICE_ARG(name ? slice_from_cstr(name) : SLICE_LIT("(unnamed)")));
     ob = member_impl->read(l->c, mem.name.s, mem.data, mem.size);
     if (!ob)
       compiler_panic(
           l->c, SRCLOC_NONE,
           "link_add_archive_bytes: object read failed for "
           "member '%.*s' of archive '%.*s'",
           SLICE_ARG(mem.name.len ? mem.name : SLICE_LIT("(unnamed)")),
           SLICE_ARG(name ? slice_from_cstr(name) : SLICE_LIT("(unnamed)")));
     ar->members[n].name =
         mem.name.len ? pool_intern_slice(l->c->global, mem.name) : 0;
     ar->members[n].obj = ob;
     ++n;
   }
   kit_ar_iter_free(it);
   return (LinkInputId)LinkArchives_count(
       &l->archives); /* opaque non-zero handle */
 }
 
 /* Intern a C-source-level symbol name in the format the input objects
  * use on the wire.  Format-specific mangling (Mach-O `_` prefix,
  * verbatim everywhere else) lives in obj_format_c_mangle. */
 Sym link_intern_c_name(Linker* l, const char* name) {
   if (!l || !name) return 0;
   return obj_format_c_mangle(l->c, name);
 }
 
 void link_set_entry(Linker* l, KitSlice name) {
   if (!l || !name.s || name.len == 0) return;
   /* entry names from the API/script are interned arena/pool slices and
    * thus NUL-terminated; the mangler scans a C string. */
   l->entry_name = link_intern_c_name(l, name.s);
 }
 
 void link_clear_entry(Linker* l) {
   if (!l) return;
   l->entry_name = 0;
 }
 
 void link_set_script(Linker* l, const KitLinkScript* script) {
   if (!l || !script) return;
   l->script = script;
   if (script->entry.s && script->entry.len)
     l->entry_name = link_intern_c_name(l, script->entry.s);
 }
 
 void link_set_extern_resolver(Linker* l, LinkExternResolver fn, void* user) {
   if (!l) return;
   l->resolver = fn;
   l->resolver_user = user;
 }
 
 void link_set_gc_sections(Linker* l, int enable) {
   if (!l) return;
   l->gc_sections = enable;
   /* Accepted but ignored this cut. Quiet by design — driver/ld.c may
    * pass 0 unconditionally and we don't want to noise that. */
 }
 
 void link_set_strip_debug(Linker* l, int enable) {
   if (!l) return;
   l->strip_debug = enable;
   /* Executable layouts already omit non-alloc debug sections. Keep the flag
    * recorded so driver -S/--strip-debug flows through the linker surface. */
 }
 
 void link_set_allow_undefined(Linker* l, int enable) {
   if (!l) return;
   l->allow_undefined = enable ? 1 : 0;
 }
 
 void link_set_shared(Linker* l, int enable) {
   if (!l) return;
   l->emit_shared = enable ? 1 : 0;
 }
 
 void link_set_emit_static_exe(Linker* l, int enable) {
   if (!l) return;
   l->emit_static_exe = enable ? 1 : 0;
 }
 
 void link_set_jit_mode(Linker* l, int enable) {
   if (!l) return;
   l->jit_mode = enable ? 1 : 0;
 }
 
 void link_set_pie(Linker* l, int enable) {
   if (!l) return;
   l->emit_pie = enable ? 1 : 0;
 }
 
 void link_set_text_base(Linker* l, u64 base) {
   if (!l) return;
   l->text_base_set = 1;
   l->text_base = base;
 }
 
 void link_set_pe_subsystem(Linker* l, u16 subsystem) {
   if (!l) return;
   l->pe_subsystem = subsystem;
 }
 
 void link_set_jit_host(Linker* l, const KitJitHost* host) {
   if (!l) return;
   l->jit_host = host;
 }
 
 void link_set_interp_path(Linker* l, KitSlice path) {
   if (!l) return;
   l->interp_path =
       (path.s && path.len) ? pool_intern_slice(l->c->global, path) : 0;
 }
 
 /* ---- debug-input capture ----
  *
  * Called once at the tail of link_resolve.  For each LinkInput, record
  * its ObjBuilder on the LinkImage so the JIT debug view (kit_jit_view)
  * can read .debug_* sections after the Linker is freed.  Two ownership
  * regimes:
  *
  *   LINK_INPUT_OBJ_BYTES: linker owns; transfer to the image and null
  *     the LinkInput's obj so linker_release doesn't double-free.
  *   LINK_INPUT_OBJ:       caller owns; borrow the pointer (do not free
  *     at image teardown).  Caller is responsible for keeping the
  *     builder alive at least as long as the JIT.
  *
  * DSO / archive-only inputs carry no source-level debug info worth
  * surfacing through kit_jit_view, so their slot stays NULL. */
 void link_capture_debug_inputs(Linker* l, LinkImage* img) {
   u32 n;
   u32 i;
   Heap* h;
   if (!l || !img) return;
   n = LinkInputs_count(&l->inputs);
   img->dbg_objs_n = n;
   if (n == 0) {
     img->dbg_objs = NULL;
     img->dbg_objs_owned = NULL;
     return;
   }
   h = img->heap;
   img->dbg_objs = (ObjBuilder**)h->alloc(h, sizeof(*img->dbg_objs) * n,
                                          _Alignof(ObjBuilder*));
   img->dbg_objs_owned = (u8*)h->alloc(h, sizeof(*img->dbg_objs_owned) * n, 1u);
   if (!img->dbg_objs || !img->dbg_objs_owned)
     compiler_panic(img->c, SRCLOC_NONE,
                    "link_capture_debug_inputs: oom on dbg arrays");
   memset(img->dbg_objs, 0, sizeof(*img->dbg_objs) * n);
   memset(img->dbg_objs_owned, 0, sizeof(*img->dbg_objs_owned) * n);
   for (i = 0; i < n; ++i) {
     LinkInput* in = LinkInputs_at(&l->inputs, i);
     if (!in || !in->obj) continue;
     switch (in->kind) {
       case LINK_INPUT_OBJ_BYTES:
         img->dbg_objs[i] = in->obj;
         img->dbg_objs_owned[i] = 1u;
         in->obj = NULL; /* transfer: linker_release must not free it */
         break;
       case LINK_INPUT_OBJ:
         img->dbg_objs[i] = in->obj;
         img->dbg_objs_owned[i] = 0u; /* borrowed; caller still owns */
         break;
       default:
         /* DSO / TBD: skip — no user-level debug sections we expose. */
         break;
     }
   }
 }
 
 /* ---- LinkImage accessors ---- */
 
 const LinkSymbol* link_symbol(LinkImage* img, LinkSymId id) {
   if (!img || id == LINK_SYM_NONE || id > LinkSyms_count(&img->syms))
     return NULL;
   return LinkSyms_at(&img->syms, id - 1);
 }
 
 LinkSymId link_symbol_lookup(LinkImage* img, Sym name) {
   if (!img) return LINK_SYM_NONE;
   return symhash_get(&img->globals, name);
 }
 
 u32 link_segment_count(LinkImage* img) { return img ? img->nsegments : 0; }
 
 const LinkSegment* link_segment_get(LinkImage* img, u32 id) {
   if (!img || id == LINK_SEG_NONE || id > img->nsegments) return NULL;
   return &img->segments[id - 1];
 }
 
 const u8* link_segment_bytes(LinkImage* img, LinkSegmentId id,
                              size_t* size_out) {
   if (size_out) *size_out = 0;
   if (!img || id == LINK_SEG_NONE || id > img->nsegments) return NULL;
   if (size_out) *size_out = (size_t)img->segments[id - 1].file_size;
   return img->segment_bytes[id - 1];
 }
 
 u32 link_section_count(LinkImage* img) { return img ? img->nsections : 0; }
 
 const LinkSection* link_section_get(LinkImage* img, LinkSectionId id) {
   if (!img || id == LINK_SEC_NONE || id > img->nsections) return NULL;
   return &img->sections[id - 1];
 }
 
 u32 link_reloc_apply_count(LinkImage* img) {
   return img ? LinkRelocs_count(&img->relocs) : 0;
 }
 
 const LinkRelocApply* link_reloc_apply_get(LinkImage* img, u32 id) {
   if (!img || id >= LinkRelocs_count(&img->relocs)) return NULL;
   return LinkRelocs_at(&img->relocs, id);
 }
 
 /* ---- LinkImage free / cleanup ---- */
 
 static void link_image_release(LinkImage* img) {
   u32 i;
   if (!img) return;
   if (img->segment_bytes) {
     for (i = 0; i < img->nsegments; ++i) {
       if (img->segment_bytes[i])
         img->heap->free(img->heap, img->segment_bytes[i],
                         img->segment_bytes_cap[i]);
     }
     img->heap->free(img->heap, img->segment_bytes,
                     sizeof(*img->segment_bytes) * img->nsegments);
     img->heap->free(img->heap, img->segment_bytes_cap,
                     sizeof(*img->segment_bytes_cap) * img->nsegments);
   }
   if (img->segments)
     img->heap->free(img->heap, img->segments,
                     sizeof(*img->segments) * img->nsegments);
   if (img->sections)
     img->heap->free(img->heap, img->sections,
                     sizeof(*img->sections) * img->nsections);
   LinkSyms_fini(&img->syms);
   LinkRelocs_fini(&img->relocs);
   if (img->iplt_pairs)
     img->heap->free(img->heap, img->iplt_pairs,
                     sizeof(*img->iplt_pairs) * img->niplt * 2u);
   if (img->input_maps) {
     for (i = 0; i < img->ninput_maps; ++i) {
       InputMap* m = &img->input_maps[i];
       if (m->sym) img->heap->free(img->heap, m->sym, sizeof(*m->sym) * m->nsym);
       if (m->section)
         img->heap->free(img->heap, m->section,
                         sizeof(*m->section) * m->nsection);
       if (m->atom)
         img->heap->free(img->heap, m->atom,
                         sizeof(*m->atom) * (m->natom ? m->natom : 1u));
       if (m->sym_atom)
         img->heap->free(img->heap, m->sym_atom,
                         sizeof(*m->sym_atom) * (m->nsym ? m->nsym : 1u));
       if (m->reloc_atom)
         img->heap->free(img->heap, m->reloc_atom,
                         sizeof(*m->reloc_atom) * (m->nreloc ? m->nreloc : 1u));
       if (m->section_has_atoms)
         img->heap->free(img->heap, m->section_has_atoms,
                         m->nsection ? m->nsection : 1u);
       if (m->section_atom_first)
         img->heap->free(
             img->heap, m->section_atom_first,
             sizeof(*m->section_atom_first) * (m->nsection ? m->nsection : 1u));
       if (m->section_atom_count)
         img->heap->free(
             img->heap, m->section_atom_count,
             sizeof(*m->section_atom_count) * (m->nsection ? m->nsection : 1u));
       if (m->section_atom_ids)
         img->heap->free(img->heap, m->section_atom_ids,
                         sizeof(*m->section_atom_ids) * m->nsection_atom_ids);
       if (m->comdat_discarded)
         img->heap->free(img->heap, m->comdat_discarded,
                         m->nsection ? m->nsection : 1u);
     }
     img->heap->free(img->heap, img->input_maps,
                     sizeof(*img->input_maps) * img->ninput_maps);
   }
   if (img->dbg_objs) {
     for (i = 0; i < img->dbg_objs_n; ++i) {
       if (img->dbg_objs[i] && img->dbg_objs_owned && img->dbg_objs_owned[i])
         obj_free(img->dbg_objs[i]);
     }
     img->heap->free(img->heap, img->dbg_objs,
                     sizeof(*img->dbg_objs) * img->dbg_objs_n);
     if (img->dbg_objs_owned)
       img->heap->free(img->heap, img->dbg_objs_owned,
                       sizeof(*img->dbg_objs_owned) * img->dbg_objs_n);
   }
   if (img->dbg_bytes) {
     for (i = 0; i < img->dbg_count; ++i)
       if (img->dbg_bytes[i])
         img->heap->free(img->heap, img->dbg_bytes[i], (size_t)img->dbg_size[i]);
     img->heap->free(img->heap, img->dbg_bytes,
                     sizeof(*img->dbg_bytes) * img->dbg_count);
   }
   if (img->dbg_size)
     img->heap->free(img->heap, img->dbg_size,
                     sizeof(*img->dbg_size) * img->dbg_count);
   symhash_fini(&img->globals);
   if (img->dyn) {
     const ObjFormatImpl* fmt = obj_format_lookup(img->c->target.obj);
     if (fmt && fmt->free_dyn) fmt->free_dyn(img);
   }
   img->heap->free(img->heap, img, sizeof(*img));
 }
 
 static void link_image_cleanup(void* arg) {
   link_image_release((LinkImage*)arg);
 }
 
 LinkImage* link_image_alloc(Compiler* c) {
   Heap* h = (Heap*)c->ctx->heap;
   LinkImage* img = (LinkImage*)h->alloc(h, sizeof(*img), _Alignof(LinkImage));
   if (!img)
     compiler_panic(c, SRCLOC_NONE, "link: out of memory allocating image");
   memset(img, 0, sizeof(*img));
   img->c = c;
   img->heap = h;
   LinkSyms_init(&img->syms, h);
   LinkRelocs_init(&img->relocs, h);
   symhash_init(&img->globals, h);
   img->deferred = compiler_defer(c, link_image_cleanup, img);
   return img;
 }
 
 void link_image_free(LinkImage* img) {
   if (!img) return;
   if (img->deferred) compiler_undefer(img->c, img->deferred);
   link_image_release(img);
 }
 
 /* ---- Incremental resolution (stubs) ----
  * Per-block JIT translation in src/emu/ wants to grow a single
  * LinkImage as cold blocks land (doc/EMU.md §6). The single-shot
  * link_resolve discipline (link.h header comment) is set up to
  * support this — inputs are non-destructively consumed, ObjBuilder*
  * mappings are stable, resolution is functional. The two entries
  * below are the surface; the implementation lands alongside the
  * emu lifter cut. */
 
 LinkImage* link_resolve_at(Linker* l, uintptr_t base_va) {
   (void)base_va;
   if (!l) return NULL;
   compiler_panic(l->c, SRCLOC_NONE,
                  "link_resolve_at: incremental resolution not yet "
                  "implemented");
   return NULL;
 }
 
 void link_resolve_extend(Linker* l, LinkImage* img) {
   (void)img;
   if (!l) return;
   compiler_panic(l->c, SRCLOC_NONE,
                  "link_resolve_extend: incremental resolution not "
                  "yet implemented");
 }
 
 /* ---- public emit dispatcher ---- */
 
 void link_emit_image_writer(LinkImage* img, Writer* w) {
   const ObjFormatImpl* fmt;
   if (!img || !w) return;
   fmt = obj_format_lookup(img->c->target.obj);
   if (fmt && fmt->link_emit) {
     fmt->link_emit(img, w);
     return;
   }
   compiler_panic(img->c, SRCLOC_NONE,
                  "link_emit_image_writer: unsupported obj format %u",
                  (u32)img->c->target.obj);
 }