kit

link.h (13213B)

---

 #ifndef KIT_INTERNAL_LINK_H
 #define KIT_INTERNAL_LINK_H
 
 #include <kit/core.h>
 #include <kit/jit.h>
 #include <kit/link.h>
 
 #include "obj/obj.h"
 
 typedef struct Linker Linker;
 typedef struct LinkImage LinkImage;
 
 struct KitLinkSession {
   Compiler* c;
   Linker* linker;
   KitLinkSessionOptions opts;
   LinkImage* image;
   KitObjBuilder** publish_objs;
   u32 npublish_objs;
   u32 publish_objs_cap;
   u32 non_obj_inputs;
   u8 resolved;
   u8 linker_transferred;
   u8 pad[2];
 };
 
 typedef enum LinkInputKind {
   LINK_INPUT_OBJ,
   LINK_INPUT_OBJ_BYTES,
   LINK_INPUT_ARCHIVE_BYTES,
   /* Shared-object input (ET_DYN). Parsed via read_elf_dso into an
    * ObjBuilder containing only the DSO's exported (dynsym) symbols.
    * Contributes nothing to layout — its symbols are searched by
    * resolve_undefs to satisfy imported references. */
   LINK_INPUT_DSO_BYTES,
 } LinkInputKind;
 
 typedef u32 LinkInputId;
 #define LINK_INPUT_NONE 0u
 
 typedef u32 LinkSymId;
 #define LINK_SYM_NONE 0u
 
 typedef u32 LinkSegmentId;
 #define LINK_SEG_NONE 0u
 
 typedef u32 LinkSectionId;
 #define LINK_SEC_NONE 0u
 
 typedef struct LinkInput {
   LinkInputId id;
   u8 kind; /* LinkInputKind */
   u8 pad[3];
   u32 order;
   ObjBuilder* obj; /* for LINK_INPUT_OBJ, otherwise NULL until read */
   Sym name;        /* diagnostic name for bytes inputs */
   /* DSO-only: SONAME extracted from PT_DYNAMIC.DT_SONAME. 0 if absent.
    * Used as the DT_NEEDED entry for the consuming exe / shared lib —
    * the runtime loader looks up the dependency by SONAME, not by the
    * filesystem path passed at link time. */
   Sym soname;
   /* COFF short-import only: the name the loader must resolve in the DLL when
    * it differs from the symbol's link name (Microsoft short-import NameType
    * NOPREFIX/UNDECORATE/EXPORTAS — e.g. local __msvcrt_assert -> export
    * _assert). 0 when the import name equals the symbol name. Consumed by the
    * COFF import-table synthesis for the PE hint/name-table entry. */
   Sym coff_import_name;
 } LinkInput;
 
 typedef struct LinkSymbol {
   LinkSymId id;
   Sym name;
   LinkInputId input_id;
   ObjSymId obj_sym;
   ObjSecId section_id;
   ObjAtomId atom_id;
   u64 value;
   u64 vaddr; /* final linked address, 0 for unresolved undef */
   u64 size;
   u32 common_align; /* alignment for SK_COMMON symbols */
   u8 bind;          /* SymBind */
   u8 kind;          /* SymKind */
   u8 defined;
   /* Dynamic-link bookkeeping. `imported` is set when an undef was
    * matched against a DSO input's exports — the symbol stays
    * structurally undefined (the static linker has no value for it)
    * but resolve_undefs no longer panics on it. `dso_input_id` is the
    * id of the providing DSO LinkInput; the DSO's SONAME ends up in
    * the produced image's DT_NEEDED list. The needs_* flags are set
    * during reloc-rewrite (Phase 5) — declared here so the model is
    * stable across the dyn-link work. */
   u8 imported;
   LinkInputId dso_input_id;
   /* ELF-only: explicit version required by a name@VERSION undefined reference.
    * Dynamic symbol emission still writes the base name; this field drives the
    * matching .gnu.version_r entry. 0 means use the providing DSO's default
    * version, if any. */
   Sym elf_version;
   u8 needs_plt;
   u8 needs_got;
   u8 needs_copy;
   u8 vis;
   u8 pad[4];
 } LinkSymbol;
 
 typedef struct LinkSegment {
   LinkSegmentId id;
   u32 flags; /* SecFlag-like permissions after layout */
   u64 file_offset;
   u64 vaddr;
   u64 paddr;
   u64 mem_size;
   u64 file_size;
   u32 align;
   u32 phdr_type;
   u32 phdr_flags;
   u32 nsections;
   u8 phdr_flags_set;
   u8 phdr_filehdr;
   u8 phdr_phdrs;
   u8 pad[5];
 } LinkSegment;
 
 typedef struct LinkSection {
   LinkSectionId id;
   LinkInputId input_id;
   ObjSecId obj_section_id;
   ObjAtomId obj_atom_id;
   LinkSegmentId segment_id;
   u64 obj_offset;
   u64 input_offset;
   u64 file_offset;
   u64 vaddr;
   u64 size;
   u32 flags;
   u32 align;
   Sym name; /* section name (interned); 0 if anon */
   u16 sem;  /* SecSem of the source obj section */
   /* Non-segment, file-resident section (a .debug_* contribution). It
    * lives in img->sections so its SK_SECTION symbol resolves and the
    * reloc engine applies, but it has segment_id == LINK_SEG_NONE and
    * carries its bytes in the LinkImage debug registry, not a segment
    * buffer. See link_layout_debug / link_fileonly_bytes. */
   u8 file_only;
   u8 pad;
 } LinkSection;
 
 typedef struct LinkRelocApply {
   LinkInputId input_id;
   ObjSecId section_id;
   LinkSectionId link_section_id;
   u32 offset;
   u32 width;
   u64 write_vaddr;
   u64 write_file_offset;
   RelocKind kind;
   LinkSymId target;
   i64 addend;
 } LinkRelocApply;
 
 /* Internal resolver type matches the public KitExternResolver: name is a
  * C string at the linker boundary. The Linker interns it on entry. */
 typedef KitExternResolver LinkExternResolver;
 
 Linker* link_new(Compiler*);
 void link_free(Linker*);
 
 /* Inputs are byte-buffer-shaped. Path-based adapters live in the driver
  * (see driver/driver.h) and use Compiler.env->file_io to read bytes before
  * calling these. All bytes inputs must remain alive until link_resolve
  * returns; ObjBuilder inputs must remain alive until link_image_free.
  *
  * `name` is an unowned diagnostic string; the linker interns it on entry
  * (callers do not need to pre-intern). */
 LinkInputId link_add_obj(Linker*, ObjBuilder*);
 LinkInputId link_add_obj_bytes(Linker*, const char* name, const u8* data,
                                size_t len);
 /* Shared-object input. The bytes are parsed as ET_DYN ELF; only the
  * DSO's dynsym (exported symbols) is materialized. The DSO contributes
  * no sections to the output image — its presence influences resolution
  * (an undef matched by name against this DSO's exports becomes an
  * imported symbol) and DT_NEEDED bookkeeping (the DSO's SONAME, or its
  * filename if no SONAME, is recorded as a runtime dependency). */
 LinkInputId link_add_dso_bytes(Linker*, const char* name, const u8* data,
                                size_t len);
 /* `whole_archive` (nonzero == --whole-archive) and `link_mode`
  * (KitLinkMode: -Bstatic / -Bdynamic / --as-needed positional state) are
  * orthogonal per-archive flags. `group_id == 0` means linear single-pass;
  * archives sharing a nonzero `group_id` are scanned cyclically (equivalent
  * to GNU ld --start-group ... --end-group). */
 LinkInputId link_add_archive_bytes(Linker*, const char* name, const u8* data,
                                    size_t len, u8 whole_archive, u8 link_mode,
                                    u8 group_id);
 
 void link_set_entry(Linker*, KitSlice name);
 void link_clear_entry(Linker*);
 /* Borrowed reference; the script and every sub-object must outlive
  * link_resolve. The linker accepts only the structured form — there is no
  * text-shaped setter. Hosts that have GNU-ld text use
  * kit_link_script_parse first. */
 void link_set_script(Linker*, const KitLinkScript*);
 void link_set_extern_resolver(Linker*, LinkExternResolver, void* user);
 /* Enable --gc-sections on this link. Roots are: entry symbol, exported
  * symbols (shared link), and any section flagged KEEP by the linker
  * script. Unreferenced sections are dropped from the output. */
 void link_set_gc_sections(Linker*, int enable);
 void link_set_strip_debug(Linker*, int enable);
 void link_set_allow_undefined(Linker*, int enable);
 void link_set_shared(Linker*, int enable);
 
 /* Mark this link as targeting a static ET_EXEC ELF binary (vs. the
  * in-process JIT).  Setter is called by kit_link_exe; the JIT path
  * leaves it disabled.  Currently controls the IFUNC startup-init
  * synthesis in layout_iplt: with this flag set, layout appends a
  * .init_array entry that calls __kit_ifunc_init at exe startup so
  * .igot.plt slots get filled before user code runs.  The JIT pre-
  * resolves slots in-process and doesn't need the ctor. */
 void link_set_emit_static_exe(Linker*, int enable);
 /* Mark this link as the in-process JIT lane (set by kit_link_jit).
  * Lets link_resolve tolerate platform undefs the JIT image patches
  * post-link (currently: Mach-O `__tlv_bootstrap`).  Leaves AOT lanes
  * untouched. */
 void link_set_jit_mode(Linker*, int enable);
 
 /* Mark this link as producing a position-independent ET_DYN exe (-pie).
  * Triggers Phase 4 layout_dyn pass (synthetic .interp/.dynsym/.dynstr/
  * .gnu.hash/.plt/.got.plt/.rela.dyn/.rela.plt/.dynamic) and Phase 6 ELF
  * emit (e_type=ET_DYN, IMAGE_BASE=0, PT_PHDR/PT_INTERP/PT_DYNAMIC,
  * R_AARCH64_RELATIVE on internal absolute relocs). Orthogonal to
  * emit_static_exe; both may be set in the same link (the IFUNC ctor
  * still wants to run on the exe path regardless of PIE). */
 void link_set_pie(Linker*, int enable);
 /* Override the static ET_EXEC image (text) base, from `kit ld -Ttext ADDR`. No
  * effect on PIE/shared (base 0) or scripted layout (script pins vaddrs). */
 void link_set_text_base(Linker*, u64 base);
 void link_set_pe_subsystem(Linker*, u16 subsystem);
 
 /* Runtime loader path written into PT_INTERP / .interp. NULL leaves the
  * default ("/lib/ld-musl-aarch64.so.1" for aarch64-linux). Only
  * consulted when -pie is enabled (or any DSO input is present). */
 void link_set_interp_path(Linker*, KitSlice path);
 
 /* Borrowed JIT host. The layout passes read execmem->page_size; the JIT
  * mapper reads the full host (execmem reserve/protect, tls). NULL on
  * AOT exe/shared lanes. The host and its sub-tables must outlive the
  * link / the produced KitJit. */
 void link_set_jit_host(Linker*, const KitJitHost*);
 
 /* Symbol resolution and layout are explicit so file linking and JIT share the
  * same resolved image. Fatal diagnostics use Compiler.panic.
  *
  * link_resolve registers the returned LinkImage with compiler_defer so a
  * panic between resolve and consumer (emit_writer / jit_from_image) reaps
  * it. Successful consumers either call link_image_free (which undefers and
  * frees) or transfer ownership via kit_jit_from_image (which undefers and
  * keeps the image alive for the JIT's lifetime).
  *
  * ---- Incremental-linking invariant (forward compat) ----
  * The single-shot link_resolve implementation must not destroy or consume
  * input-side state that a future incremental re-resolve would need.
  * Specifically:
  *   - LinkRelocApply records stay as data: do not burn them into segment
  *     bytes destructively without preserving the originals.
  *   - LinkInputId -> ObjBuilder* mappings stay stable for the lifetime of
  *     the Linker — adding an input never invalidates an existing handle.
  *   - Resolution is structured as a function from inputs to a fresh
  *     LinkImage, not as in-place mutation of the Linker.
  * Incremental linking is the single most likely future addition; this
  * comment locks in the implementation discipline that keeps the existing
  * surface amenable, with no speculative API. */
 LinkImage* link_resolve(Linker*);
 
 /* Incremental resolution (per doc/EMU.md §6). link_resolve_at reserves
  * the image's layout starting at the caller-specified base VA — used
  * by the emu so the JIT image's host addresses are stable for the
  * session (chaining patches live host code with section addresses).
  * link_resolve_extend appends new inputs to an existing image: places
  * new sections at the next free offset within the reserved region,
  * resolves new symbols against the existing image's globals plus the
  * registered LinkExternResolver, and applies new relocations. It
  * MUST NOT change host addresses of previously placed sections —
  * chaining and the code cache depend on it. The image must have been
  * produced by a prior link_resolve_at call on the same Linker. */
 LinkImage* link_resolve_at(Linker*, uintptr_t base_va);
 void link_resolve_extend(Linker*, LinkImage*);
 
 void link_image_free(LinkImage*);
 const LinkSymbol* link_symbol(LinkImage*, LinkSymId);
 LinkSymId link_symbol_lookup(LinkImage*, Sym name);
 u32 link_segment_count(LinkImage*);
 const LinkSegment* link_segment_get(LinkImage*, u32 id);
 const u8* link_segment_bytes(LinkImage*, LinkSegmentId, size_t* size_out);
 u32 link_section_count(LinkImage*);
 const LinkSection* link_section_get(LinkImage*, LinkSectionId id);
 u32 link_reloc_apply_count(LinkImage*);
 const LinkRelocApply* link_reloc_apply_get(LinkImage*, u32 id);
 
 /* Writes an executable in the format implied by Compiler.target into the
  * caller-provided Writer. Path-based emit lives in the driver. */
 void link_emit_image_writer(LinkImage*, Writer*);
 
 /* Writes an ET_REL / MH_OBJECT relocatable partial-link output. This consumes
  * the Linker's object/archive inputs and emits a fresh ObjBuilder through the
  * active object-format writer; it does not perform executable layout, section
  * GC, entry resolution, GOT/IPLT synthesis, or DSO binding. */
 void link_emit_relocatable_writer(Linker*, Writer*);
 
 /* JIT: maps the image into executable memory and returns an owning handle.
  * The returned KitJit takes ownership of the LinkImage (undefers it from
  * the cleanup stack registered by link_resolve); on kit_jit_free both the
  * JIT mapping and the LinkImage are released. Lookup is by name; the public
  * `kit_jit_lookup` and `kit_jit_free` declarations live in
  * <kit/jit.h>. */
 KitJit* kit_jit_from_image(LinkImage*);
 
 #endif