kit

link.c (77219B)

---

 /* link_emit_elf: write a static ET_EXEC ELF64 image to the
  * caller-provided Writer.
  *
  * 64-bit little-endian only. The per-arch ELF reloc-type tables in
  * obj/elf_reloc_<arch>.c handle RelocKind <-> ELF translation; this
  * file gets e_machine from the link arch descriptor.
  *
  * File layout (in write order):
  *
  *   [headers PT_LOAD, PF_R, mapped at IMAGE_BASE]
  *     Ehdr64
  *     Phdr64[nphdr]                       -- one per loaded segment + headers +
  * PT_NOTE .note.gnu.build-id                  -- 12 + 16 = 28 bytes
  * (deterministic 16-byte id) pad to PAGE
  *
  *   [PT_LOAD per kept image segment, in img->segments order]
  *     segment bytes (padded to its file_offset)
  *
  *   [non-allocatable sections, file-only]
  *     .symtab                              -- ELF64_SYM_SIZE * nsyms
  *     .strtab                              -- NUL-led blob
  *     .shstrtab                            -- NUL-led blob
  *
  *   [section header table at e_shoff]
  *     Shdr64[nshdr]
  *
  * Section header schema (for nm / objdump -t / gdb consumption):
  *
  *     0  SHN_UNDEF (zero entry)
  *     N  one shdr per loaded sub-region: .text/.rodata/.data/.bss as
  *        the corresponding RX/R/RW segments materialize (.bss split
  *        out as the trailing memsz>filesz tail of the RW segment).
  *     1  .note.gnu.build-id (allocatable, in headers PT_LOAD)
  *     1  .symtab        (sh_link -> .strtab; sh_info = first non-local idx)
  *     1  .strtab
  *     1  .shstrtab      (Ehdr64.e_shstrndx)
  *
  * Build-id is computed deterministically over the post-relocation
  * segment bytes (FNV-1a 64 over each segment, mixed into a 128-bit
  * accumulator). The 16-byte digest is written into the note before the
  * note is emitted to the Writer.
  *
  * The image image-relative addresses on entry are bumped by
  * align_up(headers_size, PAGE) before relocs are applied, exactly as
  * before — segment bytes / symbol vaddrs land at their final IMAGE_BASE
  * absolute addresses by the time relocs run. */
 
 #include "link/link.h"
 
 #include <string.h>
 
 #include "core/heap.h"
 #include "core/pool.h"
 #include "core/slice.h"
 #include "core/util.h"
 #include "core/vec.h"
 #include "link/link_arch.h"
 #include "link/link_internal.h"
 #include "obj/bytebuf.h"
 #include "obj/elf/elf.h"
 #include "obj/elf/link_dyn.h"
 #include "obj/format.h"
 
 /* ---- ELF64 wire structs (subset) ---- */
 
 #define EI_NIDENT 16
 
 typedef struct __attribute__((packed)) Ehdr64 {
   u8 e_ident[EI_NIDENT];
   u16 e_type;
   u16 e_machine;
   u32 e_version;
   u64 e_entry;
   u64 e_phoff;
   u64 e_shoff;
   u32 e_flags;
   u16 e_ehsize;
   u16 e_phentsize;
   u16 e_phnum;
   u16 e_shentsize;
   u16 e_shnum;
   u16 e_shstrndx;
 } Ehdr64;
 
 typedef struct __attribute__((packed)) Phdr64 {
   u32 p_type;
   u32 p_flags;
   u64 p_offset;
   u64 p_vaddr;
   u64 p_paddr;
   u64 p_filesz;
   u64 p_memsz;
   u64 p_align;
 } Phdr64;
 
 typedef struct __attribute__((packed)) Shdr64 {
   u32 sh_name;
   u32 sh_type;
   u64 sh_flags;
   u64 sh_addr;
   u64 sh_offset;
   u64 sh_size;
   u32 sh_link;
   u32 sh_info;
   u64 sh_addralign;
   u64 sh_entsize;
 } Shdr64;
 
 /* ---- ELF32 wire structs (RV32 static ET_EXEC) ----
  *
  * Ehdr32/Shdr32 keep the ELF64 field ORDER, only narrowing the
  * native-width members to u32. Phdr32 REORDERS p_flags to AFTER the
  * sizes (vs Phdr64 where p_flags is field #2) — the packed struct below
  * encodes that order, so the by-name field assignments in the phdr build
  * loop stay correct under either class. */
 typedef struct __attribute__((packed)) Ehdr32 {
   u8 e_ident[EI_NIDENT];
   u16 e_type;
   u16 e_machine;
   u32 e_version;
   u32 e_entry;
   u32 e_phoff;
   u32 e_shoff;
   u32 e_flags;
   u16 e_ehsize;
   u16 e_phentsize;
   u16 e_phnum;
   u16 e_shentsize;
   u16 e_shnum;
   u16 e_shstrndx;
 } Ehdr32;
 
 typedef struct __attribute__((packed)) Phdr32 {
   u32 p_type;
   u32 p_offset;
   u32 p_vaddr;
   u32 p_paddr;
   u32 p_filesz;
   u32 p_memsz;
   u32 p_flags;
   u32 p_align;
 } Phdr32;
 
 typedef struct __attribute__((packed)) Shdr32 {
   u32 sh_name;
   u32 sh_type;
   u32 sh_flags;
   u32 sh_addr;
   u32 sh_offset;
   u32 sh_size;
   u32 sh_link;
   u32 sh_info;
   u32 sh_addralign;
   u32 sh_entsize;
 } Shdr32;
 
 #define PT_NOTE 4
 #define PT_TLS 7
 
 /* Static ET_EXEC base. ET_DYN (PIE) uses 0 — the loader picks the
  * runtime base. The active value lives in `img_base` below; the macro
  * stays for the static path's hard-coded vaddrs. */
 #define IMAGE_BASE_STATIC 0x400000ULL
 
 #define BUILD_ID_DESC_LEN 16u
 #define NOTE_NAME_GNU "GNU"
 #define NOTE_NAME_GNU_LEN 4u /* "GNU\0" */
 #define NOTE_BUILD_ID_TYPE 3u
 #define BUILD_ID_NOTE_BYTES (12u + NOTE_NAME_GNU_LEN + BUILD_ID_DESC_LEN)
 
 /* ---- byte writer helpers ---- */
 
 static void write_bytes(Writer* w, const void* data, size_t n) {
   w->write(w, data, n);
 }
 
 static void write_zeroes(Writer* w, size_t n) {
   static const u8 zeroes[256] = {0};
   while (n) {
     size_t step = n > sizeof(zeroes) ? sizeof(zeroes) : n;
     w->write(w, zeroes, step);
     n -= step;
   }
 }
 
 static u32 perms_to_pflags(u32 secflags) {
   u32 f = PF_R;
   if (secflags & SF_EXEC) f |= PF_X;
   if (secflags & SF_WRITE) f |= PF_W;
   return f;
 }
 
 static u32 dynstr_find_sym(Compiler* c, const LinkDynState* dyn, Sym name,
                            const char* tag) {
   Slice nm_s = pool_slice(c->global, name);
   const char* nm = nm_s.s;
   size_t namelen = nm_s.len;
   if (nm && namelen) {
     u32 si;
     for (si = 0; si + namelen < dyn->dynstr_len; ++si) {
       if (dyn->dynstr[si + namelen] == 0 &&
           memcmp(dyn->dynstr + si, nm, namelen) == 0)
         return si;
     }
   }
   compiler_panic(c, SRCLOC_NONE, "link_emit_elf: %s missing from .dynstr",
                  tag ? tag : "dynamic string");
   return 0;
 }
 
 /* ---- class-aware header serializers ----
  *
  * The writer builds every header in the wide Ehdr64/Phdr64/Shdr64
  * in-memory form, then serializes to the on-disk class. On ELFCLASS64
  * the bytes are the wide struct verbatim (preserving the existing
  * byte-exact RV64/x86_64/aa64 output). On ELFCLASS32 the native-width
  * fields narrow to u32 and Phdr fields reorder (p_flags after sizes).
  * The serialized record sizes are the wire constants in elf.h. */
 static size_t elf_ehdr_sz(int class32) {
   return class32 ? ELF32_EHDR_SIZE : sizeof(Ehdr64);
 }
 static size_t elf_phdr_sz(int class32) {
   return class32 ? ELF32_PHDR_SIZE : sizeof(Phdr64);
 }
 static size_t elf_shdr_sz(int class32) {
   return class32 ? ELF32_SHDR_SIZE : sizeof(Shdr64);
 }
 
 static void write_ehdr(Writer* w, const Ehdr64* e, int class32) {
   if (!class32) {
     write_bytes(w, e, sizeof(*e));
     return;
   }
   Ehdr32 e32;
   memset(&e32, 0, sizeof e32);
   memcpy(e32.e_ident, e->e_ident, EI_NIDENT);
   e32.e_type = e->e_type;
   e32.e_machine = e->e_machine;
   e32.e_version = e->e_version;
   e32.e_entry = (u32)e->e_entry;
   e32.e_phoff = (u32)e->e_phoff;
   e32.e_shoff = (u32)e->e_shoff;
   e32.e_flags = e->e_flags;
   e32.e_ehsize = e->e_ehsize;
   e32.e_phentsize = e->e_phentsize;
   e32.e_phnum = e->e_phnum;
   e32.e_shentsize = e->e_shentsize;
   e32.e_shnum = e->e_shnum;
   e32.e_shstrndx = e->e_shstrndx;
   write_bytes(w, &e32, sizeof e32);
 }
 
 static void write_phdrs(Writer* w, const Phdr64* phdrs, u32 n, int class32) {
   if (!class32) {
     write_bytes(w, phdrs, sizeof(Phdr64) * n);
     return;
   }
   for (u32 i = 0; i < n; ++i) {
     const Phdr64* p = &phdrs[i];
     Phdr32 p32;
     p32.p_type = p->p_type;
     p32.p_offset = (u32)p->p_offset;
     p32.p_vaddr = (u32)p->p_vaddr;
     p32.p_paddr = (u32)p->p_paddr;
     p32.p_filesz = (u32)p->p_filesz;
     p32.p_memsz = (u32)p->p_memsz;
     p32.p_flags = p->p_flags;
     p32.p_align = (u32)p->p_align;
     write_bytes(w, &p32, sizeof p32);
   }
 }
 
 static void write_shdr(Writer* w, const Shdr64* s, int class32) {
   if (!class32) {
     write_bytes(w, s, sizeof(*s));
     return;
   }
   Shdr32 s32;
   s32.sh_name = s->sh_name;
   s32.sh_type = s->sh_type;
   s32.sh_flags = (u32)s->sh_flags;
   s32.sh_addr = (u32)s->sh_addr;
   s32.sh_offset = (u32)s->sh_offset;
   s32.sh_size = (u32)s->sh_size;
   s32.sh_link = s->sh_link;
   s32.sh_info = s->sh_info;
   s32.sh_addralign = (u32)s->sh_addralign;
   s32.sh_entsize = (u32)s->sh_entsize;
   write_bytes(w, &s32, sizeof s32);
 }
 
 /* Scripted-layout post-pass: vaddrs are already final (the script
  * pinned them via `. = …`), so only file offsets need to bump to
  * leave room for ehdr+phdrs. Mirror of shift_image_addresses but
  * touches only the file dimension. */
 static void shift_image_file_offsets(LinkImage* img, u64 delta) {
   u32 i;
   for (i = 0; i < img->nsegments; ++i) img->segments[i].file_offset += delta;
   for (i = 0; i < img->nsections; ++i) img->sections[i].file_offset += delta;
   for (i = 0; i < LinkRelocs_count(&img->relocs); ++i)
     LinkRelocs_at(&img->relocs, i)->write_file_offset += delta;
 }
 
 static void shift_image_addresses(LinkImage* img, u64 delta) {
   u32 i;
   for (i = 0; i < img->nsegments; ++i) {
     img->segments[i].file_offset += delta;
     img->segments[i].vaddr += delta;
     img->segments[i].paddr += delta;
   }
   for (i = 0; i < img->nsections; ++i) {
     /* File-only debug sections carry DWARF-section-relative bases, not
      * load addresses — they live outside any PT_LOAD and must not shift
      * with the loaded image. Their file_offset is assigned fresh by the
      * trailing-offset pass below. */
     if (img->sections[i].file_only) continue;
     img->sections[i].file_offset += delta;
     img->sections[i].vaddr += delta;
   }
   for (i = 0; i < LinkRelocs_count(&img->relocs); ++i) {
     LinkRelocs_at(&img->relocs, i)->write_file_offset += delta;
     LinkRelocs_at(&img->relocs, i)->write_vaddr += delta;
   }
   for (i = 0; i < LinkSyms_count(&img->syms); ++i) {
     LinkSymbol* s = LinkSyms_at(&img->syms, i);
     if (s->kind == SK_ABS) continue;
     if (!s->defined) continue;
     /* A symbol resolved into a file-only debug section (e.g. the local
      * SK_SECTION symbol a DWARF R_ABS32 targets) holds a sec-relative
      * offset, not a load address — leave it unshifted so the apply pass
      * writes the right DWARF offset. */
     if (s->section_id != LINK_SEC_NONE && s->section_id <= img->nsections &&
         img->sections[s->section_id - 1].file_only)
       continue;
     s->vaddr += delta;
   }
   /* tls_vaddr lives in the same image-relative coordinate system as
    * the segments it tracks, so it bumps with them. */
   if (img->tls_memsz) img->tls_vaddr += delta;
   /* Dyn-link state mirrors a few segment / section vaddrs and pre-
    * populated DynRela.r_offset values from layout_dyn.  Bump them so
    * the post-shift .rela.plt / .dynamic emit and apply_all_relocs see
    * the right addresses (sym_plt_vaddr is read to redirect CALL26
    * against imports). */
   if (img->dyn) {
     LinkDynState* dyn = img->dyn;
     if (dyn->plt_vaddr) dyn->plt_vaddr += delta;
     if (dyn->got_plt_vaddr) dyn->got_plt_vaddr += delta;
     if (dyn->dynamic_vaddr) dyn->dynamic_vaddr += delta;
     if (dyn->sym_plt_vaddr) {
       u32 j;
       for (j = 0; j < dyn->sym_dynidx_size; ++j)
         if (dyn->sym_plt_vaddr[j]) dyn->sym_plt_vaddr[j] += delta;
     }
     if (dyn->rela_plt) {
       u32 j;
       for (j = 0; j < dyn->nrela_plt; ++j) dyn->rela_plt[j].r_offset += delta;
     }
     /* rela_dyn is populated by apply_all_relocs (which runs after this
      * shift), so its records are already in post-shift coordinates. */
   }
 }
 
 /* --section-start / -Tdata / -Tbss: force the FINAL runtime address of a named
  * output section to exactly the requested value (GNU-ld semantics). Applied
  * here, AFTER shift_image_addresses, so the requested address is compared
  * against the section's final p_vaddr (img_base + post-shift vaddr); the delta
  * absorbs both the headers load-page (headers_load) and the runtime image base
  * (img_base) with no special-casing, including below-base requests. The
  * matched section's whole segment is shifted uniformly so intra-segment offsets
  * and symbol addresses stay consistent, mirroring shift_image_addresses. Must
  * run before apply_all_relocs so reloc sites see the pinned addresses. Scripted
  * images pin addresses via the script and carry no pins here. */
 static void apply_section_starts(LinkImage* img, u64 img_base) {
   Linker* l = img->linker;
   u32 i, j;
   if (!l || img->scripted) return;
   for (i = 0; i < l->nsection_starts; ++i) {
     const KitLinkSectionStart* ss = &l->section_starts[i];
     LinkSegmentId target_seg = LINK_SEG_NONE;
     i64 delta = 0;
     if (!ss->name.s || ss->name.len == 0) continue;
     /* Find the matched output section and compute the shift that lands its
      * final address on ss->addr. (A name-less warning was already issued at
      * layout time by link_apply_section_starts.) */
     for (j = 0; j < img->nsections; ++j) {
       LinkSection* sec = &img->sections[j];
       Slice nm = sec->name ? pool_slice(img->c->global, sec->name) : SLICE_NULL;
       if (!nm.s || nm.len != ss->name.len ||
           memcmp(nm.s, ss->name.s, nm.len) != 0)
         continue;
       if (sec->file_only) continue;
       if (sec->segment_id != LINK_SEG_NONE &&
           sec->segment_id <= img->nsegments) {
         target_seg = sec->segment_id;
         delta = (i64)ss->addr - (i64)(img_base + sec->vaddr);
       } else {
         /* No containing segment (rare): pin the section's vaddr directly so
          * img_base + vaddr == ss->addr. */
         sec->vaddr = ss->addr - img_base;
       }
       break;
     }
     if (target_seg == LINK_SEG_NONE || delta == 0) continue;
     /* Shift the whole segment (segment + its sections + the symbols and reloc
      * sites resolved into them) so the pinned section lands exactly, keeping
      * every relative placement within the segment. */
     img->segments[target_seg - 1].vaddr += (u64)delta;
     img->segments[target_seg - 1].paddr += (u64)delta;
     for (j = 0; j < img->nsections; ++j)
       if (img->sections[j].segment_id == target_seg)
         img->sections[j].vaddr += (u64)delta;
     for (j = 0; j < LinkSyms_count(&img->syms); ++j) {
       LinkSymbol* s = LinkSyms_at(&img->syms, j);
       if (s->kind == SK_ABS || !s->defined) continue;
       if (s->section_id == LINK_SEC_NONE || s->section_id > img->nsections)
         continue;
       if (img->sections[s->section_id - 1].segment_id == target_seg)
         s->vaddr += (u64)delta;
     }
     for (j = 0; j < LinkRelocs_count(&img->relocs); ++j) {
       LinkRelocApply* r = LinkRelocs_at(&img->relocs, j);
       if (r->link_section_id == LINK_SEC_NONE ||
           r->link_section_id > img->nsections)
         continue;
       if (img->sections[r->link_section_id - 1].segment_id == target_seg)
         r->write_vaddr += (u64)delta;
     }
   }
 }
 
 /* AArch64 ELF ABI: the per-thread TLS block starts at TP + 16 bytes
  * (the TCB sits ahead of the TLS image). RISC-V psABI normally points
  * tp at the start of the TLS image; the kit harness's start.c
  * places a 16-byte TCB ahead of .tdata and biases tp accordingly, so
  * the TPREL offset for both arches is (target - tls_vaddr) + 16. */
 #define TLS_TCB_SIZE 16ull
 
 static int reloc_is_tlsle(RelocKind k, int tls_variant_ii) {
   if (k == R_TPOFF64 && !tls_variant_ii) return 1;
   return k == R_AARCH64_TLSLE_ADD_TPREL_HI12 ||
          k == R_AARCH64_TLSLE_ADD_TPREL_LO12_NC ||
          k == R_AARCH64_TLSDESC_ADR_PAGE21 ||
          k == R_AARCH64_TLSDESC_LD64_LO12 || k == R_AARCH64_TLSDESC_ADD_LO12 ||
          k == R_AARCH64_TLSDESC_CALL || k == R_RV_TPREL_HI20 ||
          k == R_RV_TPREL_LO12_I || k == R_RV_TPREL_LO12_S ||
          k == R_RV_TLS_GD_HI20;
 }
 
 /* Variant-I TP bias: distance from the TLS image start to where `tp` points.
  *   - AArch64 (AAPCS64): tp points at a 16-byte TCB ahead of the image -> +16
  *     for both hosted and freestanding.
  *   - RISC-V: the psABI points tp at the *start* of the image, so hosted libcs
  *     (FreeBSD/Linux _init_tls) want +0; kit's own freestanding start.c places
  *     a 16-byte TCB ahead of .tdata and biases tp to match AArch64, so
  *     freestanding rv64/rv32 keep +16. */
 static u64 tls_tcb_bias(Compiler* c) {
   /* The per-arch freestanding bias lives in the ELF arch descriptor
    * (ObjElfArchOps.tls_tp_bias): 16 for AArch64/RISC-V variant-I, 0 for
    * x86_64 variant-II.  RISC-V is the only arch whose *hosted* bias
    * differs from its freestanding bias (the psABI points tp at the image
    * start, so hosted libcs want +0); that split stays here. */
   const ObjFormatImpl* fmt = obj_format_lookup(KIT_OBJ_ELF);
   const ObjElfArchOps* arch =
       (fmt && fmt->elf_arch) ? fmt->elf_arch(c->target.arch) : NULL;
   u64 bias = arch ? (u64)arch->tls_tp_bias : TLS_TCB_SIZE;
   if ((c->target.arch == KIT_ARCH_RV64 || c->target.arch == KIT_ARCH_RV32) &&
       c->target.os != KIT_OS_FREESTANDING)
     return 0ull;
   return bias;
 }
 
 /* x86_64 SysV ABI: TLS variant II — the per-thread TLS image sits at
  * *negative* offsets from %fs (which points at the TCB).  start.c
  * lays out [tdata | tbss | TCB] and arch_prctl(ARCH_SET_FS, &TCB), so
  * a symbol at offset X within the TLS image is at fs-relative offset
  * (X - tls_memsz).  The two ELF reloc kinds R_X86_64_TPOFF32/_TPOFF64
  * encode that signed offset directly at the reloc site (no TCB bias —
  * variant II's TCB sits *after* the image, so TPOFF is negative). */
 static int reloc_is_x64_tlsle(RelocKind k, int tls_variant_ii) {
   if (!tls_variant_ii) return 0;
   return k == R_TPOFF64 || k == R_X64_TPOFF32 || k == R_X64_DTPOFF32;
 }
 
 static int is_x64_tlsld_relaxed_get_addr_call(const LinkImage* img,
                                               const LinkRelocApply* r,
                                               const LinkSymbol* tgt,
                                               const u8* P_bytes) {
   Slice nm;
   if (r->kind != R_X64_PLT32 && r->kind != R_PLT32) return 0;
   if (!tgt->name) return 0;
   if (r->offset < 8u) return 0;
   nm = pool_slice(img->c->global, tgt->name);
   if (!slice_eq_cstr(nm, "__tls_get_addr")) return 0;
   return P_bytes[-8] == 0x64u && P_bytes[-7] == 0x48u &&
          P_bytes[-6] == 0x8bu && P_bytes[-5] == 0x04u &&
          P_bytes[-4] == 0x25u && P_bytes[-3] == 0x00u &&
          P_bytes[-2] == 0x00u && P_bytes[-1] == 0x00u &&
          P_bytes[0] == 0x00u && P_bytes[1] == 0x90u &&
          P_bytes[2] == 0x90u && P_bytes[3] == 0x90u;
 }
 
 static int rv_tlsgd_hi_at(const LinkImage* img, u64 write_vaddr) {
   u32 i;
   for (i = 0; i < LinkRelocs_count(&img->relocs); ++i) {
     const LinkRelocApply* hi = LinkRelocs_at(&img->relocs, i);
     if (hi->kind == R_RV_TLS_GD_HI20 && hi->write_vaddr == write_vaddr)
       return 1;
   }
   return 0;
 }
 
 static int rv_lo12_pairs_tlsgd(const LinkImage* img, const LinkRelocApply* r,
                                const LinkSymbol* tgt) {
   if (r->kind != R_RV_PCREL_LO12_I) return 0;
   return rv_tlsgd_hi_at(img, tgt->vaddr);
 }
 
 static int is_rv_tlsgd_get_addr_call(const LinkImage* img,
                                      const LinkRelocApply* r,
                                      const LinkSymbol* tgt, const u8* P_bytes) {
   Slice nm;
   u32 i;
   (void)P_bytes;
   if (r->kind != R_PLT32 && r->kind != R_RV_CALL) return 0;
   if (!tgt->name) return 0;
   if (r->offset < 8u) return 0;
   nm = pool_slice(img->c->global, tgt->name);
   if (!slice_eq_cstr(nm, "__tls_get_addr")) return 0;
   for (i = 0; i < LinkRelocs_count(&img->relocs); ++i) {
     const LinkRelocApply* hi = LinkRelocs_at(&img->relocs, i);
     u64 span;
     if (hi->kind != R_RV_TLS_GD_HI20) continue;
     if (hi->input_id != r->input_id || hi->section_id != r->section_id)
       continue;
     if (hi->link_section_id != r->link_section_id) continue;
     if (hi->write_vaddr >= r->write_vaddr) continue;
     span = r->write_vaddr - hi->write_vaddr;
     if (span >= 8u && span <= 24u) return 1;
   }
   return 0;
 }
 
 static int reloc_is_abs(RelocKind k) { return k == R_ABS32 || k == R_ABS64; }
 
 /* Function-call relocs that may route through the PLT when the target
  * is imported.  aarch64 CALL26/JUMP26, x86_64 PLT32, and risc-v CALL_PLT
  * (which kit maps to R_PLT32) all carry the "call this address; if
  * it's not resolvable here use the PLT trampoline" contract; the apply
  * pass overwrites S with the PLT entry vaddr in that case. */
 static int reloc_is_branch26(RelocKind k) {
   return k == R_AARCH64_CALL26 || k == R_AARCH64_JUMP26 || k == R_X64_PLT32 ||
          k == R_PLT32 || k == R_RV_CALL;
 }
 
 static void emit_dyn_record(LinkImage* img, u64 site_vaddr, u32 reloc_type,
                             u32 dynidx, i64 addend) {
   LinkDynState* dyn = img->dyn;
   if (!dyn || !dyn->rela_dyn) return;
   if (dyn->nrela_dyn >= dyn->cap_rela_dyn) {
     compiler_panic(img->c, SRCLOC_NONE,
                    "link: too many .rela.dyn records (%u >= %u); raise "
                    "cap_rela_dyn in layout_dyn",
                    dyn->nrela_dyn, dyn->cap_rela_dyn);
   }
   DynRela* r = &dyn->rela_dyn[dyn->nrela_dyn++];
   r->r_offset = site_vaddr;
   r->r_info = ELF64_R_INFO((u64)dynidx, reloc_type);
   r->r_addend = addend;
 }
 
 static const ObjElfArchOps* elf_arch_or_panic(Compiler* c, const char* where) {
   const ObjFormatImpl* fmt = obj_format_lookup(KIT_OBJ_ELF);
   const ObjElfArchOps* arch =
       fmt && fmt->elf_arch ? fmt->elf_arch(c->target.arch) : NULL;
   if (!arch)
     compiler_panic(c, SRCLOC_NONE, "%.*s: no ELF arch descriptor",
                    SLICE_ARG(slice_from_cstr(where)));
   return arch;
 }
 
 static void emit_relative_record(LinkImage* img, u64 site_vaddr, u64 addend) {
   const ObjElfArchOps* arch = elf_arch_or_panic(img->c, "link");
   emit_dyn_record(img, site_vaddr, arch->r_relative, 0, (i64)addend);
 }
 
 static void emit_globdat_record(LinkImage* img, u64 site_vaddr, u32 dynidx,
                                 i64 addend) {
   const ObjElfArchOps* arch = elf_arch_or_panic(img->c, "link");
   emit_dyn_record(img, site_vaddr, arch->r_glob_dat, dynidx, addend);
 }
 
 /* RISC-V PCREL_LO12_* references the address of an AUIPC carrying the
  * paired PCREL_HI20. Given the AUIPC's site vaddr (post-shift), find
  * its PCREL_HI20 reloc and compute the displacement that AUIPC
  * encoded — the LO12 then takes the low 12 bits of the same disp.
  *
  * Linear scan over img->relocs is fine in practice: kernel images and
  * cg cases produce at most a few hundred relocs total. */
 static i64 rv_pcrel_lo12_disp(LinkImage* img, u64 auipc_vaddr, u64 img_base) {
   u32 i;
   for (i = 0; i < LinkRelocs_count(&img->relocs); ++i) {
     const LinkRelocApply* hi = LinkRelocs_at(&img->relocs, i);
     const LinkSymbol* hi_tgt;
     u64 hi_S, hi_P;
     if (hi->kind != R_RV_PCREL_HI20 && hi->kind != R_RV_GOT_HI20 &&
         hi->kind != R_RV_TLS_GOT_HI20)
       continue;
     if (hi->write_vaddr + img_base != auipc_vaddr) continue;
     hi_tgt = LinkSyms_at(&img->syms, hi->target - 1);
     hi_S = (hi_tgt->kind == SK_ABS) ? hi_tgt->vaddr : hi_tgt->vaddr + img_base;
     hi_P = hi->write_vaddr + img_base;
     return (i64)hi_S + hi->addend - (i64)hi_P;
   }
   compiler_panic(img->c, SRCLOC_NONE,
                  "link: PCREL_LO12 at 0x%llx has no paired PCREL_HI20",
                  (unsigned long long)auipc_vaddr);
   return 0;
 }
 
 static void apply_all_relocs(LinkImage* img, u64 img_base) {
   u32 i;
   int dyn_output = img->pie || img->shared;
   int tls_vi = (int)link_arch_desc_for(img->c)->tls_variant_ii;
   for (i = 0; i < LinkRelocs_count(&img->relocs); ++i) {
     LinkRelocApply* r = LinkRelocs_at(&img->relocs, i);
     const LinkSymbol* tgt = LinkSyms_at(&img->syms, r->target - 1);
     const LinkSection* sec = &img->sections[r->link_section_id - 1];
     const LinkSegment* seg;
     u64 S, P;
     u8* P_bytes;
 
     /* File-only debug section: not loaded, so no dynamic reloc and no
      * img_base. Write the final value straight into the registry buffer
      * at the reloc offset. A SK_SECTION target resolves to its DWARF
      * sec-relative base (tgt->vaddr, kept unshifted); a code/data symbol
      * resolves to its link-time vaddr (img_base + vaddr) for low_pc /
      * set_address. Mirrors the JIT debug view (link_jit.c). */
     if (sec->segment_id == LINK_SEG_NONE) {
       u8* dbg = link_fileonly_bytes(img, r->link_section_id);
       if (!dbg) continue;
       if (tgt->kind == SK_SECTION || tgt->kind == SK_ABS)
         S = tgt->vaddr;
       else
         S = img_base + tgt->vaddr;
       link_reloc_apply(img->c, r->kind, dbg + r->offset, S, r->addend, 0);
       continue;
     }
     seg = &img->segments[sec->segment_id - 1];
     /* NOLOAD / NOBITS output section: the segment carries no on-disk bytes
      * (segment_bytes left NULL), so there is no patch site to write. A kept
      * PROGBITS input routed into a NOLOAD output (link_section_kept ignores
      * NOLOAD) still collects its relocs with a real segment_id, but the value
      * can never be observed at runtime — skip the apply rather than dereference
      * a NULL segment buffer (mirrors the file-only branch above). */
     if (img->segment_bytes[seg->id - 1] == NULL) continue;
     if (reloc_is_tlsle(r->kind, tls_vi) || reloc_is_x64_tlsle(r->kind, tls_vi))
       /* Both the direct local-exec relocs and the internal R_TPOFF64 used to
        * fill a TLS-IE GOT slot resolve to a tp-relative offset within THIS
        * image's TLS block — only meaningful for a thread-local defined here.
        * Reject an imported or non-thread-local target rather than emit a
        * bogus offset (kit has no initial-exec/global-dynamic fallback). */
       link_require_local_tls(img->c, tgt);
     if (reloc_is_tlsle(r->kind, tls_vi)) {
       /* S is the target's TP-relative offset: distance from the TLS image
        * start plus the arch/OS TCB bias (see tls_tcb_bias). Both vaddrs are
        * in the same (post-shift, image-relative) coordinate system, so
        * img_base cancels out. */
       S = (tgt->vaddr - img->tls_vaddr) + tls_tcb_bias(img->c);
     } else if (reloc_is_x64_tlsle(r->kind, tls_vi)) {
       /* x86_64 variant II: TP points just past the TLS image, so a symbol at
        * offset X within the image is at TP-relative offset (X - tls_size).
        * The runtime (FreeBSD/glibc _init_tls) allocates the block rounded up
        * to the TLS alignment, so tls_size must be round_up(memsz, align) --
        * using the raw memsz is off by the rounding remainder whenever memsz
        * is not a multiple of align, handing back a garbage TLS address (e.g.
        * jemalloc's tsd, faulting non-canonical). Cast through i64/u64 so the
        * apply writes the full 32- or 64-bit signed value. */
       u64 a = img->tls_align ? img->tls_align : 1u;
       u64 tls_size = (img->tls_memsz + a - 1u) & ~(a - 1u);
       i64 off = (i64)(tgt->vaddr - img->tls_vaddr) - (i64)tls_size;
       S = (u64)off;
     } else if (r->kind == R_RV_PCREL_LO12_I || r->kind == R_RV_PCREL_LO12_S) {
       /* PCREL_LO12: rewrite S so that link_reloc_apply's existing
        * LO12_I/LO12_S encoder produces the right low 12 bits of the
        * paired AUIPC's PC-relative displacement. The reloc's own
        * addend is unused; signed lo12 = disp & 0xfff. */
       P = r->write_vaddr + img_base;
       P_bytes = img->segment_bytes[seg->id - 1] +
                 (size_t)(r->write_file_offset - seg->file_offset);
       if (rv_lo12_pairs_tlsgd(img, r, tgt)) continue;
       {
         i64 disp = rv_pcrel_lo12_disp(img, tgt->vaddr + img_base, img_base);
         RelocKind alias =
             (r->kind == R_RV_PCREL_LO12_I) ? R_RV_LO12_I : R_RV_LO12_S;
         link_reloc_apply(img->c, alias, P_bytes, (u64)disp, 0, P);
       }
       continue;
     } else {
       S = tgt->vaddr + img_base;
       if (tgt->kind == SK_ABS) S = tgt->vaddr;
     }
     P = r->write_vaddr + img_base;
     P_bytes = img->segment_bytes[seg->id - 1] +
               (size_t)(r->write_file_offset - seg->file_offset);
 
     if (is_rv_tlsgd_get_addr_call(img, r, tgt, P_bytes)) continue;
 
     /* Imported target: redirect / rewrite per reloc kind (Phase 5).
      *
      * - CALL26 / JUMP26: target the import's PLT entry.  The PLT stub
      *   reads .got.plt[3+i], which the loader pre-fills via JUMP_SLOT
      *   (.rela.plt).  S becomes the PLT-entry vaddr; the existing
      *   apply path computes the disp from there.
      * - R_ABS{32,64}: leave the patch site at zero and emit a
      *   GLOB_DAT record so the loader writes the resolved address
      *   into the site at load time.  This covers both
      *   layout_got-emitted .got slot fills (target = import) and any
      *   direct absolute reference in user data (e.g. a function
      *   pointer initializer).
      * - GOT-page / LO12-NC against an import: emit_reloc_records has
      *   already redirected the target from the import to the
      *   synthetic .got slot symbol, so the apply path here sees the
      *   slot, not the import — nothing special needed; the slot's
      *   own R_ABS64 fill against the (vaddr=0) import will trip the
      *   abs-import branch above and emit GLOB_DAT.
      *
      * Anything else against an imported symbol (e.g. PREL19 / ADR
      * etc.) is rare in real binaries and would need its own
      * dynamic-reloc kind; panic loudly so a future test that needs
      * it announces itself. */
     if (tgt->imported) {
       /* `tgt` may be a per-input shadow LinkSymbol — resolve_undefs
        * stamps `imported = 1` on every undef matched by name, but
        * collect_imports only stashes plt_vaddr / dynidx on the
        * canonical entry registered in img->globals.  Resolve to the
        * canonical id before indexing the dyn-state arrays. */
       LinkSymId canon_id = tgt->id;
       if (tgt->name != 0) {
         LinkSymId hit = symhash_get(&img->globals, tgt->name);
         if (hit != LINK_SYM_NONE) canon_id = hit;
       }
       u32 dynidx = (img->dyn && canon_id < img->dyn->sym_dynidx_size)
                        ? img->dyn->sym_dynidx[canon_id]
                        : 0u;
       if (is_x64_tlsld_relaxed_get_addr_call(img, r, tgt, P_bytes)) continue;
       if (reloc_is_branch26(r->kind)) {
         u64 plt_v = (img->dyn && canon_id < img->dyn->sym_dynidx_size)
                         ? img->dyn->sym_plt_vaddr[canon_id]
                         : 0u;
         if (plt_v == 0)
           compiler_panic(img->c, SRCLOC_NONE,
                          "link: imported sym has no PLT entry (CALL26)");
         S = plt_v + img_base;
         link_reloc_apply(img->c, r->kind, P_bytes, S, r->addend, P);
         continue;
       }
       if (reloc_is_abs(r->kind)) {
         if (dynidx == 0)
           compiler_panic(img->c, SRCLOC_NONE,
                          "link: imported sym has no .dynsym entry");
         emit_globdat_record(img, r->write_vaddr, dynidx, r->addend);
         /* Site bytes are irrelevant: the loader's GLOB_DAT writes
          * (sym_value + r_addend) into r_offset before user code runs,
          * overwriting whatever's there.  Leaving the existing zero
          * fill saves a write. */
         continue;
       }
       {
         Slice nm_s =
             tgt->name ? pool_slice(img->c->global, tgt->name) : SLICE_NULL;
         const char* nm = nm_s.s ? nm_s.s : "";
         size_t nl = nm_s.len;
         compiler_panic(
             img->c, SRCLOC_NONE,
             "link: unhandled reloc kind %u against imported symbol '%.*s'",
             (unsigned)r->kind, (int)nl, nm);
       }
     }
 
     /* PIE: an absolute reloc against a defined non-imported symbol
      * stays image-relative in the file (the loader adds load-base via
      * a synthesized R_AARCH64_RELATIVE).  img_base is 0 for PIE so
      * S above is already image-relative — the apply writes that into
      * the site, and the RELATIVE record tells the loader to add
      * load_base on top. */
     if (dyn_output && reloc_is_abs(r->kind) && tgt->defined &&
         tgt->kind != SK_ABS) {
       /* RELA RELATIVE ignores the in-place site value: the loader writes
        * (load_base + r_addend) into the slot.  So the addend must be the
        * full image-relative target — symbol vaddr plus the reloc's own
        * addend — not just the symbol vaddr.  Dropping r->addend collapses
        * every entry of an addend-bearing table (jump tables, labeladdr
        * arrays, &sym+off initializers) onto the symbol base. */
       emit_relative_record(img, r->write_vaddr, tgt->vaddr + (u64)r->addend);
     }
     link_reloc_apply(img->c, r->kind, P_bytes, S, r->addend, P);
   }
 }
 
 /* The build-id payload is a format-agnostic image identity hash —
  * see link_image_id_compute in link_image_id.c.  Mach-O wraps the
  * same bytes in LC_UUID; ELF wraps them in a .note.gnu.build-id. */
 
 /* String tables (.shstrtab / .strtab) use the shared ObjByteBuf dedup builder
  * (objbb_*, obj/bytebuf.h). Both must lead with a NUL so name offset 0 reads as
  * the empty string, so each is seeded with objbb_u8(&b, 0) right after init. */
 
 /* ---- symtab builder ---- */
 
 typedef struct SymRec {
   u32 st_name;
   u8 st_info;
   u8 st_other;
   u16 st_shndx;
   u64 st_value;
   u64 st_size;
 } SymRec;
 
 static u8 sym_kind_to_st_type(u8 kind) {
   /* Shared elf.h table maps SK_COMMON -> STT_OBJECT (the on-disk shape
    * for tentative definitions). The linker, however, writes COMMON as
    * STT_NOTYPE; override that one entry locally. */
   if (kind == SK_COMMON) return STT_NOTYPE;
   return elf_st_type(kind);
 }
 
 static u8 sym_bind_to_st_bind(u8 bind) { return elf_st_bind(bind); }
 
 /* Produces one symbol record on the wire from a SymRec. Elf32_Sym (16B)
  * REORDERS fields vs Elf64_Sym (24B): st_value/st_size come BEFORE
  * st_info/st_other/st_shndx, so select the byte layout by class32. */
 static void write_sym_rec(Writer* w, const SymRec* r, int class32) {
   if (class32) {
     u8 buf[ELF32_SYM_SIZE];
     u32 i;
     buf[0] = (u8)(r->st_name);
     buf[1] = (u8)(r->st_name >> 8);
     buf[2] = (u8)(r->st_name >> 16);
     buf[3] = (u8)(r->st_name >> 24);
     for (i = 0; i < 4; ++i) buf[4 + i] = (u8)(r->st_value >> (i * 8));
     for (i = 0; i < 4; ++i) buf[8 + i] = (u8)(r->st_size >> (i * 8));
     buf[12] = r->st_info;
     buf[13] = r->st_other;
     buf[14] = (u8)(r->st_shndx);
     buf[15] = (u8)(r->st_shndx >> 8);
     write_bytes(w, buf, sizeof buf);
     return;
   }
   u8 buf[ELF64_SYM_SIZE];
   buf[0] = (u8)(r->st_name);
   buf[1] = (u8)(r->st_name >> 8);
   buf[2] = (u8)(r->st_name >> 16);
   buf[3] = (u8)(r->st_name >> 24);
   buf[4] = r->st_info;
   buf[5] = r->st_other;
   buf[6] = (u8)(r->st_shndx);
   buf[7] = (u8)(r->st_shndx >> 8);
   {
     u32 i;
     for (i = 0; i < 8; ++i) buf[8 + i] = (u8)(r->st_value >> (i * 8));
     for (i = 0; i < 8; ++i) buf[16 + i] = (u8)(r->st_size >> (i * 8));
   }
   write_bytes(w, buf, sizeof buf);
 }
 
 static void refresh_dynsym_exports(LinkImage* img, u64 img_base) {
   LinkDynState* dyn;
   const LinkSection* sec_dynsym;
   const LinkSegment* seg;
   u8* bytes;
   u32 i;
   if (!img || !img->dyn) return;
   dyn = img->dyn;
   if (!dyn->sym_dynidx || dyn->sec_dynsym == LINK_SEC_NONE) return;
   sec_dynsym = &img->sections[dyn->sec_dynsym - 1];
   seg = &img->segments[sec_dynsym->segment_id - 1];
   bytes = img->segment_bytes[seg->id - 1] +
           (size_t)(sec_dynsym->file_offset - seg->file_offset);
 
   for (i = 0; i < LinkSyms_count(&img->syms); ++i) {
     const LinkSymbol* s = LinkSyms_at(&img->syms, i);
     u32 dynidx;
     DynSymRec* r;
     if (!s->defined || s->imported) continue;
     if (s->id >= dyn->sym_dynidx_size) continue;
     dynidx = dyn->sym_dynidx[s->id];
     if (dynidx == 0 || dynidx >= dyn->ndynsym) continue;
 
     r = &dyn->dynsym[dynidx];
     r->st_value = (s->kind == SK_ABS) ? s->vaddr : img_base + s->vaddr;
     r->st_size = s->size;
     r->st_shndx = (s->kind == SK_ABS) ? SHN_ABS : 1u;
   }
 
   for (i = 0; i < dyn->ndynsym; ++i) {
     u8* p = bytes + (u64)i * ELF64_SYM_SIZE;
     const DynSymRec* r = &dyn->dynsym[i];
     wr_u32_le(p + 0, r->st_name);
     p[4] = r->st_info;
     p[5] = r->st_other;
     wr_u16_le(p + 6, r->st_shndx);
     wr_u64_le(p + 8, r->st_value);
     wr_u64_le(p + 16, r->st_size);
   }
 }
 
 /* ---- section header layout ---- *
  *
  * Per-segment cuts: each kept image segment contributes 1 .text/.rodata
  * shdr for its file portion, plus a separate .bss shdr for the trailing
  * NOBITS portion of an RW segment (memsz > filesz). The headers PT_LOAD
  * contributes a single .note.gnu.build-id shdr. Trailing non-alloc
  * shdrs: .symtab .strtab .shstrtab (always 3). */
 
 typedef struct OutShdr {
   u32 shdr_idx; /* 1-based; assigned during planning */
   LinkSegmentId segment_id;
   Sym name;
   u16 sem;   /* SecSem from source LinkSection */
   u32 flags; /* SF_* from source LinkSection */
   u32 align;
   u64 vaddr;
   u64 file_offset;
   u64 size;
   int is_nobits;
   int is_fileonly; /* non-allocatable .debug_* section (no PT_LOAD) */
 } OutShdr;
 
 static u16 sym_shndx_for(const LinkSymbol* s, const OutShdr* outshdrs,
                          u32 noutshdr) {
   if (!s->defined) return SHN_UNDEF;
   if (s->kind == SK_ABS) return SHN_ABS;
   if (s->kind == SK_FILE) return SHN_ABS;
   if (s->kind == SK_COMMON) return SHN_COMMON;
   /* Find an output shdr whose [vaddr, vaddr+size) covers s->vaddr.
    * Boundary symbols match at the upper edge. */
   {
     u32 i;
     for (i = 0; i < noutshdr; ++i) {
       u64 lo, hi;
       /* File-only debug shdrs sit at sec-relative vaddrs (0-based) and
        * never contain a loaded symbol — skip them so a low-vaddr code
        * symbol (e.g. PIE, img_base 0) isn't mis-attributed to a
        * .debug_* section whose [0,size) range happens to overlap. */
       if (outshdrs[i].is_fileonly) continue;
       lo = outshdrs[i].vaddr;
       hi = lo + outshdrs[i].size;
       if (s->vaddr >= lo && s->vaddr <= hi) return (u16)outshdrs[i].shdr_idx;
     }
   }
   return SHN_ABS;
 }
 
 static u32 sec_sem_to_sht(u16 sem) {
   switch (sem) {
     case SSEM_PROGBITS:
       return SHT_PROGBITS;
     case SSEM_NOBITS:
       return SHT_NOBITS;
     case SSEM_NOTE:
       return SHT_NOTE;
     case SSEM_INIT_ARRAY:
       return SHT_INIT_ARRAY;
     case SSEM_FINI_ARRAY:
       return SHT_FINI_ARRAY;
     case SSEM_PREINIT_ARRAY:
       return SHT_PREINIT_ARRAY;
     default:
       return SHT_PROGBITS;
   }
 }
 
 static u64 sec_flags_to_shf(u32 flags) {
   u64 r = 0;
   if (flags & SF_ALLOC) r |= SHF_ALLOC;
   if (flags & SF_EXEC) r |= SHF_EXECINSTR;
   if (flags & SF_WRITE) r |= SHF_WRITE;
   if (flags & SF_TLS) r |= SHF_TLS;
   if (flags & SF_MERGE) r |= SHF_MERGE;
   if (flags & SF_STRINGS) r |= SHF_STRINGS;
   if (flags & SF_LINK_ORDER) r |= SHF_LINK_ORDER;
   if (flags & SF_RETAIN) r |= SHF_GNU_RETAIN;
   return r;
 }
 
 /* Output-shdr sort order: loaded sections first, by (segment_id, vaddr);
  * then file-only debug sections after all segments, grouped by name (so
  * same-name multi-input contributions are adjacent and merge into one
  * output section) and ordered by their sec-relative base. Returns 1 if
  * `a` should sort before `b`. */
 static int shdr_sort_less(const LinkSection* a, const LinkSection* b) {
   if (a->file_only != b->file_only) return b->file_only; /* loaded first */
   if (a->file_only) {
     if (a->name != b->name) return a->name < b->name;
     return a->vaddr < b->vaddr;
   }
   if (a->segment_id != b->segment_id) return a->segment_id < b->segment_id;
   return a->vaddr < b->vaddr;
 }
 
 void link_emit_elf(LinkImage* img, Writer* w) {
   Heap* heap = img->heap;
   Compiler* c = img->c;
   const ObjElfArchOps* arch = elf_arch_or_panic(c, "link_emit_elf");
   u32 e_machine = arch->e_machine;
   /* class32: ELFCLASS32 (RV32) output, derived from target ptr width.
    * ptr_size must be 4 or 8 (every supported arch sets one of these). */
   int class32 = (c->target.ptr_size == 4);
   /* RV32 is static-only in v1: dynamic linking (link_dyn.c) and the
    * PIE re-serialize block below remain ELFCLASS64. Gate here so the
    * dynamic path is never reached for a 32-bit image. */
   if (class32 && (img->pie || img->dyn))
     compiler_panic(c, SRCLOC_NONE,
                    "rv32: dynamic/PIE linking unsupported; static only");
   if (!img->shared && img->entry_sym == LINK_SYM_NONE)
     compiler_panic(c, SRCLOC_NONE, "link_emit_elf: no resolved entry symbol");
   /* IFUNC trampolines: layout_iplt builds the .iplt stubs + .igot.plt
    * slots and (when emit_static_exe was set) synthesizes a
    * .init_array entry that calls __kit_ifunc_init at startup.  The
    * rt member walks .iplt.pairs and fills each slot before user code
    * runs.  The ELF writer doesn't have to do anything special here. */
 
   /* PIE / ET_DYN: img_base is 0 (the loader picks the runtime base;
    * absolute relocs against internal symbols are emitted as
    * R_AARCH64_RELATIVE in .rela.dyn). Otherwise classic ET_EXEC at
    * IMAGE_BASE_STATIC.
    *
    * Scripted: the linker script pinned absolute vaddrs (e.g.
    * `. = 0x40080000`); img_base stays 0 and the headers PT_LOAD /
    * build-id note are dropped — the script's image is consumed by a
    * raw loader (qemu -kernel, a bootloader) that doesn't need a
    * self-describing memory image. */
   int pie = img->pie;
   int shared = img->shared;
   int scripted = img->scripted;
   /* Static ET_EXEC base: a `kit ld -Ttext ADDR` override (e.g. 0x80000000 for a
    * qemu `virt` image) wins over IMAGE_BASE_STATIC; PIE/scripted keep base 0.
    */
   u64 img_base = (pie || shared || scripted) ? 0ULL
                  : img->text_base_set ? img->text_base
                                       : IMAGE_BASE_STATIC;
 
   /* ---- plan number of program headers ----
    *
    * 1 headers PT_LOAD + nsegments PT_LOAD + 1 PT_NOTE (build-id)
    * + 1 PT_TLS when this image carries any TLS sections.
    * + dynamic phdrs when PIE/shared also has real dynamic-link state. PIE
    *   executables get PT_PHDR / PT_INTERP / PT_DYNAMIC / PT_GNU_STACK; DSOs
    *   get PT_PHDR / PT_DYNAMIC / PT_GNU_STACK.
    *
    * Scripted images skip the headers PT_LOAD and PT_NOTE: phdrs are
    * just the per-segment PT_LOADs. */
   u32 has_tls = img->tls_memsz ? 1u : 0u;
   u32 nphdr_section_notes = 0;
   {
     u32 i;
     for (i = 0; i < img->nsections; ++i) {
       const LinkSection* s = &img->sections[i];
       if (!s->file_only && s->sem == SSEM_NOTE && s->size) {
         nphdr_section_notes++;
       }
     }
   }
   u32 nphdr_extra_dyn = ((pie || shared) && img->dyn) ? (shared ? 3u : 4u) : 0u;
   u32 nphdr_headers = scripted ? 0u : 1u;
   u32 nphdr_buildid = scripted ? 0u : 1u;
   u32 nphdr_total = nphdr_headers + img->nsegments + nphdr_buildid +
                     nphdr_section_notes + has_tls + nphdr_extra_dyn;
   u64 build_id_note_bytes = scripted ? 0ULL : BUILD_ID_NOTE_BYTES;
   /* Class-selected on-disk header sizes (ELF32: 52/32/40, ELF64: 64/56/64). */
   u64 ehdr_sz = elf_ehdr_sz(class32);
   u64 phent_sz = elf_phdr_sz(class32);
   u64 headers_size =
       ehdr_sz + (u64)nphdr_total * phent_sz + build_id_note_bytes;
   u64 headers_load = ALIGN_UP(headers_size, (u64)PAGE_SIZE);
 
   /* The build-id note lives inside the headers PT_LOAD at this offset. */
   u64 build_id_off = ehdr_sz + (u64)nphdr_total * phent_sz;
   u64 build_id_addr = img_base + build_id_off;
 
   /* Record final emit facts for the link-map / symbols side-files (consumed
    * after emit, off the format-neutral image). The headers PT_LOAD below maps
    * at img_base with p_filesz == p_memsz == headers_size; scripted images
    * emit no headers segment (see the nphdr_headers gate above). */
   img->load_base = img_base;
   if (!scripted) {
     img->headers_present = 1;
     img->headers_filesz = headers_size;
     img->headers_memsz = headers_size;
     img->headers_align = PAGE_SIZE;
   }
 
   /* ---- shift image addresses, apply relocations ----
    *
    * Must happen before segshdrs/symtab construction so they observe
    * post-shift vaddrs (the values that will land in the file). */
   if (scripted)
     shift_image_file_offsets(img, headers_load);
   else
     shift_image_addresses(img, headers_load);
   /* --section-start / -Tdata / -Tbss: pin chosen sections to their exact final
    * runtime addresses now that vaddrs are post-shift (and before relocs see
    * them). No-op for scripted images. */
   apply_section_starts(img, img_base);
   apply_all_relocs(img, img_base);
 
   /* ---- write .dynamic body + re-serialize .rela.dyn (PIE only) ----
    *
    * Both depend on post-shift vaddrs. .dynamic embeds image-relative
    * pointers to .dynsym/.dynstr/.gnu.hash/.rela.dyn/.rela.plt/.got.plt
    * (the loader adds load_base at runtime). .rela.dyn picked up
    * RELATIVE records during apply_all_relocs; rewrite the section
    * bytes to include them. */
   if ((pie || shared) && img->dyn) {
     LinkDynState* dyn = img->dyn;
     const LinkSection* sec_dynamic = &img->sections[dyn->sec_dynamic - 1];
     const LinkSection* sec_dynsym = &img->sections[dyn->sec_dynsym - 1];
     const LinkSection* sec_dynstr = &img->sections[dyn->sec_dynstr - 1];
     const LinkSection* sec_gnuhash = &img->sections[dyn->sec_gnu_hash - 1];
     const LinkSection* sec_reladyn = &img->sections[dyn->sec_rela_dyn - 1];
     const LinkSection* sec_relaplt = (dyn->sec_rela_plt != LINK_SEC_NONE)
                                          ? &img->sections[dyn->sec_rela_plt - 1]
                                          : NULL;
     const LinkSection* sec_gotplt = (dyn->sec_got_plt != LINK_SEC_NONE)
                                         ? &img->sections[dyn->sec_got_plt - 1]
                                         : NULL;
     const LinkSection* sec_versym =
         (dyn->sec_gnu_version != LINK_SEC_NONE)
             ? &img->sections[dyn->sec_gnu_version - 1]
             : NULL;
     const LinkSection* sec_verneed =
         (dyn->sec_gnu_version_r != LINK_SEC_NONE)
             ? &img->sections[dyn->sec_gnu_version_r - 1]
             : NULL;
     const LinkSegment* dseg = &img->segments[sec_dynamic->segment_id - 1];
     u8* dyn_bytes_at = img->segment_bytes[dseg->id - 1] +
                        (size_t)(sec_dynamic->file_offset - dseg->file_offset);
 
     refresh_dynsym_exports(img, img_base);
 
     /* Build DT_* entries in order. Layout matches count_dynamic_entries. */
     u32 written = 0;
     u8* p = dyn_bytes_at;
 #define DT_PUT(TAG, VAL)          \
   do {                            \
     wr_u64_le(p, (u64)(TAG));     \
     wr_u64_le(p + 8, (u64)(VAL)); \
     p += 16;                      \
     written++;                    \
   } while (0)
 
     /* DT_NEEDED entries — d_un.d_val is the offset of the soname
      * within .dynstr. The dynstr was built in layout_dyn with
      * dedup; look each soname up by name to compute its offset. */
     {
       u32 ni;
       for (ni = 0; ni < dyn->nneeded; ++ni) {
         Sym soname = dyn->needed[ni];
         u32 off = dynstr_find_sym(c, dyn, soname, "DT_NEEDED soname");
         DT_PUT(DT_NEEDED, off);
       }
     }
     if (dyn->soname)
       DT_PUT(DT_SONAME, dynstr_find_sym(c, dyn, dyn->soname, "DT_SONAME"));
     for (u32 ri = 0; ri < dyn->nrpaths; ++ri)
       DT_PUT(DT_RPATH, dynstr_find_sym(c, dyn, dyn->rpaths[ri], "DT_RPATH"));
     for (u32 ri = 0; ri < dyn->nrunpaths; ++ri)
       DT_PUT(DT_RUNPATH,
              dynstr_find_sym(c, dyn, dyn->runpaths[ri], "DT_RUNPATH"));
 
     DT_PUT(DT_STRTAB, img_base + sec_dynstr->vaddr);
     DT_PUT(DT_STRSZ, sec_dynstr->size);
     DT_PUT(DT_SYMTAB, img_base + sec_dynsym->vaddr);
     DT_PUT(DT_SYMENT, 24);
     DT_PUT(DT_GNU_HASH, img_base + sec_gnuhash->vaddr);
     /* Symbol-version tables (only when an import bound a versioned export). */
     if (dyn->nverneed && sec_versym && sec_verneed) {
       DT_PUT(DT_VERSYM, img_base + sec_versym->vaddr);
       DT_PUT(DT_VERNEED, img_base + sec_verneed->vaddr);
       DT_PUT(DT_VERNEEDNUM, dyn->nverneed);
     }
     /* DT_PLT* / DT_JMPREL only make sense when there's a PLT.  Emitting
      * them with size=0 / vaddr=0 (or pointing past the end of any
      * PT_LOAD) trips llvm-readelf's "address not in any segment" check
      * and confuses some loaders' DT walk. */
     if (dyn->nrela_plt) {
       DT_PUT(DT_PLTGOT, sec_gotplt ? (img_base + sec_gotplt->vaddr) : 0);
       DT_PUT(DT_PLTRELSZ, sec_relaplt ? sec_relaplt->size : 0);
       DT_PUT(DT_PLTREL, DT_RELA);
       DT_PUT(DT_JMPREL, sec_relaplt ? (img_base + sec_relaplt->vaddr) : 0);
     }
     if (dyn->cap_rela_dyn) {
       DT_PUT(DT_RELA, img_base + sec_reladyn->vaddr);
       DT_PUT(DT_RELASZ, sec_reladyn->size);
       DT_PUT(DT_RELAENT, 24);
     }
     DT_PUT(DT_FLAGS_1, DF_1_NOW);
     DT_PUT(DT_NULL, 0);
 #undef DT_PUT
 
     /* Pad any pre-allocated tail with DT_NULL. */
     while (written < dyn->ndyn_entries) {
       wr_u64_le(p, 0);
       wr_u64_le(p + 8, 0);
       p += 16;
       written++;
     }
 
     /* Re-serialize .rela.dyn body.  GLOB_DAT records (imports against
      * .got slots) and RELATIVE records (PIE internal abs64 fixups)
      * are both populated during apply_all_relocs; layout_dyn pre-counts
      * the exact number of runtime relocation records. */
     {
       const LinkSegment* rdseg = &img->segments[sec_reladyn->segment_id - 1];
       u8* rd_bytes = img->segment_bytes[rdseg->id - 1] +
                      (size_t)(sec_reladyn->file_offset - rdseg->file_offset);
       u32 i;
       for (i = 0; i < dyn->nrela_dyn; ++i) {
         const DynRela* rr = &dyn->rela_dyn[i];
         u8* rp = rd_bytes + (u64)i * ELF64_RELA_SIZE;
         wr_u64_le(rp + 0, rr->r_offset);
         wr_u64_le(rp + 8, rr->r_info);
         wr_u64_le(rp + 16, (u64)rr->r_addend);
       }
     }
 
     /* Re-serialize .rela.plt body.  JUMP_SLOT records were written by
      * layout_dyn at pre-shift vaddrs; shift_image_addresses bumped
      * dyn->rela_plt[i].r_offset along with the rest, so the post-shift
      * values match the .got.plt slot vaddrs the loader will patch. */
     if (sec_relaplt && dyn->nrela_plt) {
       const LinkSegment* rpseg = &img->segments[sec_relaplt->segment_id - 1];
       u8* rp_bytes = img->segment_bytes[rpseg->id - 1] +
                      (size_t)(sec_relaplt->file_offset - rpseg->file_offset);
       u32 i;
       for (i = 0; i < dyn->nrela_plt; ++i) {
         const DynRela* rr = &dyn->rela_plt[i];
         u8* rp = rp_bytes + (u64)i * ELF64_RELA_SIZE;
         wr_u64_le(rp + 0, rr->r_offset);
         wr_u64_le(rp + 8, rr->r_info);
         wr_u64_le(rp + 16, (u64)rr->r_addend);
       }
     }
 
     /* Re-write .got.plt[0] = &.dynamic with the post-shift vaddr.
      * layout_dyn wrote the pre-shift value into the segment bytes;
      * shift_image_addresses bumped dyn->dynamic_vaddr so we can refill
      * the slot here.  Slots 1 and 2 (link_map cookie,
      * _dl_runtime_resolve) are loader-owned for lazy binding; under
      * DF_1_NOW they're never read so leaving them zero is fine. */
     if (sec_gotplt && dyn->dynamic_vaddr) {
       const LinkSegment* gpseg = &img->segments[sec_gotplt->segment_id - 1];
       u8* gp_bytes = img->segment_bytes[gpseg->id - 1] +
                      (size_t)(sec_gotplt->file_offset - gpseg->file_offset);
       wr_u64_le(gp_bytes, dyn->dynamic_vaddr);
     }
   }
 
   /* ---- compute build-id (post-reloc, deterministic) ----
    *
    * Format-agnostic — Mach-O LC_UUID will hash the same bytes. */
   u8 build_id[BUILD_ID_DESC_LEN];
   link_image_id_compute(img, build_id);
 
   /* ---- plan section headers covering loaded segments ----
    *
    * Worst case: 1 file shdr per segment + 1 .bss shdr if RW has a tail.
    * shdr indices: 0=NULL, 1..nsegshdr=these, then build-id/symtab/...
    */
   /* Walk img->sections sorted by (segment_id, vaddr) and merge into
    * one OutShdr per (segment_id, name) run. layout already places
    * same-name sections adjacent within a segment, so a stable
    * by-vaddr sort followed by run-length grouping captures it. */
   OutShdr* outshdrs;
   u32 noutshdr = 0;
   u32 outshdr_cap = img->nsections + 1u;
   outshdrs = (OutShdr*)heap->alloc(heap, sizeof(*outshdrs) * outshdr_cap,
                                    _Alignof(OutShdr));
   if (!outshdrs)
     compiler_panic(c, SRCLOC_NONE, "link_emit_elf: oom on outshdrs");
   memset(outshdrs, 0, sizeof(*outshdrs) * outshdr_cap);
   {
     /* Build a sort index over LinkSection ids by (segment_id, vaddr). */
     u32* order = (u32*)heap->alloc(heap, sizeof(u32) * (img->nsections + 1u),
                                    _Alignof(u32));
     if (!order && img->nsections)
       compiler_panic(c, SRCLOC_NONE, "link_emit_elf: oom on shdr sort");
     u32 i, j;
     for (i = 0; i < img->nsections; ++i) order[i] = i;
     /* Insertion sort — section count is small. */
     for (i = 1; i < img->nsections; ++i) {
       u32 cur = order[i];
       const LinkSection* a = &img->sections[cur];
       j = i;
       while (j > 0) {
         const LinkSection* b = &img->sections[order[j - 1]];
         if (!shdr_sort_less(a, b)) break; /* a not before b → stop (stable) */
         order[j] = order[j - 1];
         --j;
       }
       order[j] = cur;
     }
     for (i = 0; i < img->nsections; ++i) {
       const LinkSection* ls = &img->sections[order[i]];
       OutShdr* tail = noutshdr ? &outshdrs[noutshdr - 1] : NULL;
       int merge = tail && tail->segment_id == ls->segment_id &&
                   tail->name == ls->name &&
                   tail->is_nobits == (ls->sem == SSEM_NOBITS);
       if (merge) {
         u64 end = ls->vaddr + ls->size;
         u64 prev_end = tail->vaddr + tail->size;
         if (end > prev_end) tail->size = end - tail->vaddr;
         if (ls->align > tail->align) tail->align = ls->align;
       } else {
         OutShdr* o = &outshdrs[noutshdr];
         o->shdr_idx = 1u + noutshdr;
         o->segment_id = ls->segment_id;
         o->name = ls->name;
         o->sem = ls->sem;
         o->flags = ls->flags;
         o->align = ls->align;
         o->vaddr = ls->vaddr;
         o->file_offset = ls->file_offset;
         o->size = ls->size;
         o->is_nobits = (ls->sem == SSEM_NOBITS);
         o->is_fileonly = ls->file_only;
         noutshdr++;
       }
     }
     heap->free(heap, order, sizeof(u32) * (img->nsections + 1u));
   }
 
   /* ---- build .shstrtab ---- */
   ObjByteBuf shstrtab;
   objbb_init(&shstrtab, heap);
   objbb_reserve(&shstrtab, 128);
   objbb_u8(&shstrtab, 0); /* leading NUL: name offset 0 = empty string */
   u32 sh_name_symtab = objbb_append_cstr(&shstrtab, ".symtab");
   u32 sh_name_strtab = objbb_append_cstr(&shstrtab, ".strtab");
   u32 sh_name_shstrtab = objbb_append_cstr(&shstrtab, ".shstrtab");
   u32 sh_name_buildid =
       scripted ? 0u : objbb_append_cstr(&shstrtab, ".note.gnu.build-id");
   /* Per-output-shdr names — interned strings from input section names. */
   u32* outshdr_name_off =
       (u32*)heap->alloc(heap, sizeof(u32) * (noutshdr + 1u), _Alignof(u32));
   if (!outshdr_name_off && noutshdr)
     compiler_panic(c, SRCLOC_NONE, "link_emit_elf: oom on shdr name table");
   {
     u32 i;
     for (i = 0; i < noutshdr; ++i) {
       const OutShdr* o = &outshdrs[i];
       if (o->name) {
         Slice nm_s = pool_slice(c->global, o->name);
         const char* nm = nm_s.s;
         size_t nlen = nm_s.len;
         outshdr_name_off[i] =
             nm && nlen ? objbb_append_str(&shstrtab, nm, (u32)nlen) : 0;
       } else {
         outshdr_name_off[i] = 0;
       }
     }
   }
 
   u32 nbuildid_shdr = scripted ? 0u : 1u;
   u32 nshdr = 1u + noutshdr + nbuildid_shdr + 3u;
   u32 shndx_symtab = 1u + noutshdr + nbuildid_shdr;
   u32 shndx_strtab = shndx_symtab + 1u;
   u32 shndx_shstrtab = shndx_strtab + 1u;
 
   /* ---- build .symtab + .strtab ----
    *
    * Two passes (locals first, then globals/weaks). Slot 0 is
    * STN_UNDEF. Globals are deduped via img->globals — only the
    * canonical entry per name is emitted, since per-input undef
    * records keep their own LinkSymId after resolve_undefs's
    * "copy fields from canonical def" step. sh_info = first non-local
    * idx. */
   ObjByteBuf strtab;
   objbb_init(&strtab, heap);
   objbb_reserve(&strtab, 256);
   objbb_u8(&strtab, 0); /* leading NUL: name offset 0 = empty string */
 
   SymRec* recs = (SymRec*)heap->alloc(
       heap, sizeof(*recs) * (LinkSyms_count(&img->syms) + 1u),
       _Alignof(SymRec));
   if (!recs) compiler_panic(c, SRCLOC_NONE, "link_emit_elf: oom on symrecs");
   u32 nsyms_emit = 0;
   u32 first_global_idx;
   memset(&recs[nsyms_emit++], 0, sizeof(*recs)); /* slot 0 */
   first_global_idx = nsyms_emit;
 
   {
     u32 pass, i;
     for (pass = 0; pass < 2; ++pass) {
       int want_local = (pass == 0);
       if (!want_local) first_global_idx = nsyms_emit;
       for (i = 0; i < LinkSyms_count(&img->syms); ++i) {
         const LinkSymbol* s = LinkSyms_at(&img->syms, i);
         int is_local = (s->bind == SB_LOCAL);
         size_t namelen = 0;
         const char* nm;
         u8 st_type, st_bind;
         u16 shndx;
         u64 st_value;
         SymRec* r;
         if (want_local != is_local) continue;
         if (s->name == 0 && s->kind != SK_FILE) continue;
         /* Dedupe globals: per-input undef-of-X and the canonical
          * def-of-X are separate img->syms entries (resolve_undefs
          * mirrors fields onto the undef). Only the canonical
          * (first registered) entry is in img->globals. Skip the
          * shadow copies. */
         if (!is_local && s->name &&
             !link_symbol_is_canonical_global(img, s))
           continue;
         {
           Slice nm_s = s->name ? pool_slice(c->global, s->name) : SLICE_NULL;
           nm = nm_s.s ? nm_s.s : "";
           namelen = nm_s.len;
         }
         shndx = sym_shndx_for(s, outshdrs, noutshdr);
         /* st_value: in ET_EXEC, defined non-ABS symbols carry
          * absolute virtual addresses (IMAGE_BASE + image
          * vaddr); ABS symbols carry their own value verbatim. */
         if (s->kind == SK_FILE)
           st_value = 0;
         else if (s->kind == SK_ABS)
           st_value = s->vaddr;
         else if (s->defined)
           st_value = img_base + s->vaddr;
         else
           st_value = 0;
         st_type = sym_kind_to_st_type(s->kind);
         st_bind = sym_bind_to_st_bind(s->bind);
         r = &recs[nsyms_emit++];
         memset(r, 0, sizeof(*r));
         r->st_name =
             (nm && namelen) ? objbb_append_str(&strtab, nm, (u32)namelen) : 0;
         r->st_info = ELF64_ST_INFO(st_bind, st_type);
         r->st_other = STV_DEFAULT;
         r->st_shndx = shndx;
         r->st_value = st_value;
         r->st_size = s->size;
       }
     }
   }
 
   /* ---- compute file offsets for trailing non-alloc sections ---- */
   /* End of segment data: the highest (file_offset + file_size) across
    * loaded segments. */
   u64 end_of_segs = headers_load;
   {
     u32 i;
     for (i = 0; i < img->nsegments; ++i) {
       const LinkSegment* seg = &img->segments[i];
       u64 e = seg->file_offset + seg->file_size;
       if (e > end_of_segs) end_of_segs = e;
     }
   }
   /* File-only debug sections go in the trailing non-alloc region, after
    * the loaded segments and before .symtab. Assign each merged debug
    * OutShdr a file offset (and propagate it back to its constituent
    * LinkSections for the byte-write pass). */
   u64 dbg_cursor = end_of_segs;
   if (img->dbg_count) {
     u32 oi;
     for (oi = 0; oi < noutshdr; ++oi) {
       OutShdr* o = &outshdrs[oi];
       u32 si;
       if (!o->is_fileonly) continue;
       o->file_offset = ALIGN_UP(dbg_cursor, o->align ? o->align : 1u);
       for (si = 0; si < img->dbg_count; ++si) {
         LinkSection* ls = &img->sections[img->dbg_first_lsid - 1 + si];
         if (ls->name == o->name)
           ls->file_offset = o->file_offset + ls->vaddr; /* base within run */
       }
       dbg_cursor = o->file_offset + o->size;
     }
   }
   u64 symtab_off = ALIGN_UP(dbg_cursor, (u64)8u);
   u32 sym_size = class32 ? ELF32_SYM_SIZE : ELF64_SYM_SIZE;
   u64 symtab_size = (u64)sym_size * nsyms_emit;
   u64 strtab_off = symtab_off + symtab_size;
   u64 strtab_size = strtab.len;
   u64 shstrtab_off = strtab_off + strtab_size;
   u64 shstrtab_size = shstrtab.len;
   u64 shdr_off = ALIGN_UP(shstrtab_off + shstrtab_size, (u64)8u);
 
   /* ---- build phdrs ---- */
   Phdr64* phdrs = (Phdr64*)heap->alloc(heap, sizeof(Phdr64) * nphdr_total,
                                        _Alignof(Phdr64));
   if (!phdrs) compiler_panic(c, SRCLOC_NONE, "link_emit_elf: oom on phdrs");
   memset(phdrs, 0, sizeof(Phdr64) * nphdr_total);
   {
     u32 pi = 0;
     /* PT_PHDR points at the phdr table itself within the headers
      * PT_LOAD. Required by the runtime loader for ET_DYN to know
      * where its own program headers live. Must appear before the
      * first PT_LOAD on dynamic exes (musl checks). */
     if ((pie || shared) && img->dyn) {
       phdrs[pi].p_type = PT_PHDR;
       phdrs[pi].p_flags = PF_R;
       phdrs[pi].p_offset = sizeof(Ehdr64);
       phdrs[pi].p_vaddr = img_base + sizeof(Ehdr64);
       phdrs[pi].p_paddr = phdrs[pi].p_vaddr;
       phdrs[pi].p_filesz = (u64)nphdr_total * sizeof(Phdr64);
       phdrs[pi].p_memsz = phdrs[pi].p_filesz;
       phdrs[pi].p_align = 8;
       pi++;
     }
     /* Headers PT_LOAD (covers ehdr + phdrs + build-id note).
      * Scripted images don't emit one — see plan note above. */
     if (!scripted) {
       phdrs[pi].p_type = PT_LOAD;
       phdrs[pi].p_flags = PF_R;
       phdrs[pi].p_offset = 0;
       phdrs[pi].p_vaddr = img_base;
       phdrs[pi].p_paddr = img_base;
       phdrs[pi].p_filesz = headers_size;
       phdrs[pi].p_memsz = headers_size;
       phdrs[pi].p_align = PAGE_SIZE;
       pi++;
     }
     /* Per-segment PT_LOAD. */
     u32 i;
     for (i = 0; i < img->nsegments; ++i) {
       const LinkSegment* seg = &img->segments[i];
       Phdr64* p = &phdrs[pi++];
       p->p_type = seg->phdr_type ? seg->phdr_type : PT_LOAD;
       p->p_flags =
           seg->phdr_flags_set ? seg->phdr_flags : perms_to_pflags(seg->flags);
       p->p_offset = seg->file_offset;
       p->p_vaddr = img_base + seg->vaddr; /* post-shift */
       p->p_paddr = img_base + seg->paddr;
       p->p_filesz = seg->file_size;
       /* TLS .tbss is per-thread template space, not a loadable bss
        * region — PT_TLS already records the full memsz (incl. .tbss)
        * for the loader's per-thread allocation, so the matching
        * PT_LOAD must not extend memsz past filesz.  qemu-riscv64
        * rejects PT_LOADs with memsz>filesz on non-writable mappings
        * ("PT_LOAD with non-writable bss"), and the SEG_TLS perms are
        * SF_ALLOC|SF_TLS only. */
       p->p_memsz = (seg->flags & SF_TLS) ? seg->file_size : seg->mem_size;
       p->p_align = seg->align ? seg->align : PAGE_SIZE;
     }
     /* Allocatable SHT_NOTE sections can also be addressed by PT_NOTE. QEMU's
      * x86 PVH loader uses this for XEN_ELFNOTE_PHYS32_ENTRY while the bytes
      * still live in the normal read-only PT_LOAD. */
     for (i = 0; i < img->nsections; ++i) {
       const LinkSection* s = &img->sections[i];
       Phdr64* p;
       if (s->file_only || s->sem != SSEM_NOTE || s->size == 0) continue;
       p = &phdrs[pi++];
       p->p_type = PT_NOTE;
       p->p_flags = PF_R;
       p->p_offset = s->file_offset;
       p->p_vaddr = img_base + s->vaddr;
       p->p_paddr = p->p_vaddr;
       p->p_filesz = s->size;
       p->p_memsz = s->size;
       p->p_align = s->align ? s->align : 4;
     }
     /* PT_NOTE for build-id. Scripted images skip the build-id entirely. */
     if (!scripted) {
       phdrs[pi].p_type = PT_NOTE;
       phdrs[pi].p_flags = PF_R;
       phdrs[pi].p_offset = build_id_off;
       phdrs[pi].p_vaddr = build_id_addr;
       phdrs[pi].p_paddr = build_id_addr;
       phdrs[pi].p_filesz = BUILD_ID_NOTE_BYTES;
       phdrs[pi].p_memsz = BUILD_ID_NOTE_BYTES;
       phdrs[pi].p_align = 4;
       pi++;
     }
     /* PT_TLS describing the .tdata template + .tbss zero-fill.
      * vaddr/file_offset point at the same bytes the matching
      * PT_LOAD already covers — the loader uses PT_TLS to size
      * each thread's TLS block and to seed it from .tdata. */
     if (has_tls) {
       phdrs[pi].p_type = PT_TLS;
       phdrs[pi].p_flags = PF_R;
       phdrs[pi].p_offset = img->tls_vaddr;
       phdrs[pi].p_vaddr = img_base + img->tls_vaddr;
       phdrs[pi].p_paddr = phdrs[pi].p_vaddr;
       phdrs[pi].p_filesz = img->tls_filesz;
       phdrs[pi].p_memsz = img->tls_memsz;
       phdrs[pi].p_align = img->tls_align ? img->tls_align : 1u;
       pi++;
     }
     /* Dynamic phdrs. PT_INTERP and PT_DYNAMIC point at the matching
      * sections (which layout_dyn placed in the ro/rw_dyn segments).
      * PT_GNU_STACK marks the stack as non-executable (filesz=0). */
     if ((pie || shared) && img->dyn) {
       LinkDynState* dyn = img->dyn;
       const LinkSection* sec_dynamic = &img->sections[dyn->sec_dynamic - 1];
       if (!shared) {
         const LinkSection* sec_interp = &img->sections[dyn->sec_interp - 1];
         phdrs[pi].p_type = PT_INTERP;
         phdrs[pi].p_flags = PF_R;
         phdrs[pi].p_offset = sec_interp->file_offset;
         phdrs[pi].p_vaddr = img_base + sec_interp->vaddr;
         phdrs[pi].p_paddr = phdrs[pi].p_vaddr;
         phdrs[pi].p_filesz = sec_interp->size;
         phdrs[pi].p_memsz = sec_interp->size;
         phdrs[pi].p_align = 1;
         pi++;
       }
       phdrs[pi].p_type = PT_DYNAMIC;
       phdrs[pi].p_flags = PF_R | PF_W;
       phdrs[pi].p_offset = sec_dynamic->file_offset;
       phdrs[pi].p_vaddr = img_base + sec_dynamic->vaddr;
       phdrs[pi].p_paddr = phdrs[pi].p_vaddr;
       phdrs[pi].p_filesz = sec_dynamic->size;
       phdrs[pi].p_memsz = sec_dynamic->size;
       phdrs[pi].p_align = 8;
       pi++;
       phdrs[pi].p_type = PT_GNU_STACK;
       phdrs[pi].p_flags = PF_R | PF_W;
       phdrs[pi].p_offset = 0;
       phdrs[pi].p_vaddr = 0;
       phdrs[pi].p_paddr = 0;
       phdrs[pi].p_filesz = 0;
       phdrs[pi].p_memsz = 0;
       phdrs[pi].p_align = 16;
       pi++;
       /* PT_GNU_RELRO would mark the read-only-after-relocation span
        * here. Phase 6 leaves it out — it's an optimization the loader
        * can live without, and our ro_seg already lives in a PF_R
        * PT_LOAD that's never made writable. */
     } else if (pie || shared) {
       /* dyn was nominally requested but layout_dyn early-out — no
        * imports and no DSO inputs. INTERP/DYNAMIC loader headers are skipped.
        */
       (void)0;
     }
     (void)pi;
   }
 
   /* ---- build ehdr ---- */
   Ehdr64 ehdr;
   memset(&ehdr, 0, sizeof(ehdr));
   ehdr.e_ident[0] = ELFMAG0;
   ehdr.e_ident[1] = ELFMAG1;
   ehdr.e_ident[2] = ELFMAG2;
   ehdr.e_ident[3] = ELFMAG3;
   ehdr.e_ident[4] = class32 ? ELFCLASS32 : ELFCLASS64;
   ehdr.e_ident[5] = ELFDATA2LSB;
   ehdr.e_ident[6] = EV_CURRENT;
   ehdr.e_ident[7] = ELFOSABI_NONE;
   /* Brand FreeBSD executables with EI_OSABI=ELFOSABI_FREEBSD; the kernel
    * matches that brand directly. Without it a static binary is rejected with
    * ENOEXEC -- the FreeBSD ABI note crt1.o carries is not sufficient on its
    * own for kit's images (the kernel's note scan does not recognize the
    * layout), so we set the OSABI on every arch (FreeBSD/clang only sets it on
    * amd64/aarch64, but the riscv64 kernel accepts it too). */
   if (img->c->target.os == KIT_OS_FREEBSD) ehdr.e_ident[7] = ELFOSABI_FREEBSD;
   ehdr.e_type = (pie || shared) ? ET_DYN : ET_EXEC;
   ehdr.e_machine = (u16)e_machine;
   ehdr.e_version = EV_CURRENT;
   ehdr.e_entry = img->entry_sym == LINK_SYM_NONE
                      ? 0
                      : img_base +
                            LinkSyms_at(&img->syms, img->entry_sym - 1)->vaddr;
   ehdr.e_phoff = ehdr_sz;
   ehdr.e_shoff = shdr_off;
   /* Preserve the linker's psABI merge. RVC/TSO are presence bits and were
    * ORed across selected inputs; float-ABI/RVE/reserved bits were required to
    * agree. A synthetic/no-input image falls back to the arch descriptor. */
   ehdr.e_flags = arch->e_flags;
   if (e_machine == EM_RISCV && img->have_elf_e_flags) {
     ehdr.e_flags = img->elf_e_flags;
   } else if (e_machine == EM_RISCV) {
     u32 fa = elf_riscv_float_abi_to_e_flags(c->target.float_abi);
     ehdr.e_flags = (ehdr.e_flags & ~(u32)EF_RISCV_FLOAT_ABI_MASK) | fa;
   }
   ehdr.e_ehsize = (u16)ehdr_sz;
   ehdr.e_phentsize = (u16)phent_sz;
   ehdr.e_phnum = (u16)nphdr_total;
   ehdr.e_shentsize = (u16)elf_shdr_sz(class32);
   ehdr.e_shnum = (u16)nshdr;
   ehdr.e_shstrndx = (u16)shndx_shstrtab;
 
   /* ---- write ehdr, phdrs, build-id note, pad ---- */
   u64 cur_off;
   write_ehdr(w, &ehdr, class32);
   write_phdrs(w, phdrs, nphdr_total, class32);
   cur_off = ehdr_sz + phent_sz * nphdr_total;
 
   /* .note.gnu.build-id wire format:
    *   u32 namesz = 4 ("GNU\0")
    *   u32 descsz = 16
    *   u32 type   = NT_GNU_BUILD_ID (3)
    *   "GNU\0"
    *   <16 bytes of build-id>
    *
    * Scripted images don't carry build-id; they have no PT_NOTE phdr to
    * point at it and the file payload would just be dead bytes. */
   if (!scripted) {
     u8 nh[12];
     u32 v;
     v = NOTE_NAME_GNU_LEN;
     nh[0] = (u8)v;
     nh[1] = (u8)(v >> 8);
     nh[2] = (u8)(v >> 16);
     nh[3] = (u8)(v >> 24);
     v = BUILD_ID_DESC_LEN;
     nh[4] = (u8)v;
     nh[5] = (u8)(v >> 8);
     nh[6] = (u8)(v >> 16);
     nh[7] = (u8)(v >> 24);
     v = NOTE_BUILD_ID_TYPE;
     nh[8] = (u8)v;
     nh[9] = (u8)(v >> 8);
     nh[10] = (u8)(v >> 16);
     nh[11] = (u8)(v >> 24);
     write_bytes(w, nh, sizeof nh);
     write_bytes(w, NOTE_NAME_GNU "\0", NOTE_NAME_GNU_LEN);
     write_bytes(w, build_id, BUILD_ID_DESC_LEN);
     cur_off += BUILD_ID_NOTE_BYTES;
   }
 
   /* Pad to first segment file_offset (== headers_load). */
   {
     u32 i;
     for (i = 0; i < img->nsegments; ++i) {
       const LinkSegment* seg = &img->segments[i];
       /* Alias program headers (a section listed under several :phdrs) have no
        * byte buffer of their own — their file range already lives on disk via
        * the primary segment, so skip them here (their phdr still describes the
        * shared file range). */
       if (seg->file_size == 0 || img->segment_bytes[seg->id - 1] == NULL)
         continue;
       if (cur_off < seg->file_offset) {
         write_zeroes(w, (size_t)(seg->file_offset - cur_off));
         cur_off = seg->file_offset;
       }
       write_bytes(w, img->segment_bytes[seg->id - 1], (size_t)seg->file_size);
       cur_off += seg->file_size;
     }
   }
 
   /* ---- write file-only debug sections ---- *
    *
    * Emit each merged debug OutShdr at its assigned file offset by
    * writing its constituent contributions in base order (the registry
    * is per-name base-ascending). OutShdrs were placed at ascending file
    * offsets, so cur_off advances monotonically. */
   if (img->dbg_count) {
     u32 oi;
     for (oi = 0; oi < noutshdr; ++oi) {
       const OutShdr* o = &outshdrs[oi];
       u32 si;
       if (!o->is_fileonly) continue;
       if (cur_off < o->file_offset) {
         write_zeroes(w, (size_t)(o->file_offset - cur_off));
         cur_off = o->file_offset;
       }
       for (si = 0; si < img->dbg_count; ++si) {
         const LinkSection* ls = &img->sections[img->dbg_first_lsid - 1 + si];
         if (ls->name != o->name || img->dbg_size[si] == 0) continue;
         write_bytes(w, img->dbg_bytes[si], (size_t)img->dbg_size[si]);
         cur_off += img->dbg_size[si];
       }
     }
   }
 
   /* ---- write trailing non-alloc sections ---- */
   if (cur_off < symtab_off) {
     write_zeroes(w, (size_t)(symtab_off - cur_off));
     cur_off = symtab_off;
   }
   {
     u32 i;
     for (i = 0; i < nsyms_emit; ++i) write_sym_rec(w, &recs[i], class32);
     cur_off += symtab_size;
   }
   if (strtab.len) {
     write_bytes(w, strtab.data, strtab.len);
     cur_off += strtab.len;
   }
   if (shstrtab.len) {
     write_bytes(w, shstrtab.data, shstrtab.len);
     cur_off += shstrtab.len;
   }
 
   /* ---- write section header table ---- */
   if (cur_off < shdr_off) {
     write_zeroes(w, (size_t)(shdr_off - cur_off));
     cur_off = shdr_off;
   }
   {
     Shdr64 sh;
     u32 i;
     /* shdr 0: NULL */
     memset(&sh, 0, sizeof(sh));
     write_shdr(w, &sh, class32);
     /* Locate dyn-section names (interned earlier in layout_dyn) so
      * we can override sh_type / sh_link / sh_info / sh_entsize for
      * .dynsym / .dynstr / .gnu.hash / .rela.dyn / .rela.plt /
      * .dynamic. The sh_link cross-references (e.g., .dynsym ->
      * .dynstr) need the matching shdr indices, which we look up by
      * comparing OutShdr.name to the same Sym values. */
     Sym n_dynsym = 0, n_dynstr = 0, n_gnuhash = 0;
     Sym n_reladyn = 0, n_relaplt = 0, n_dynamic = 0;
     Sym n_gotplt = 0, n_gnuver = 0, n_gnuver_r = 0;
     if ((pie || shared) && img->dyn) {
       n_dynsym = pool_intern_slice(c->global, SLICE_LIT(".dynsym"));
       n_dynstr = pool_intern_slice(c->global, SLICE_LIT(".dynstr"));
       n_gnuhash = pool_intern_slice(c->global, SLICE_LIT(".gnu.hash"));
       n_reladyn = pool_intern_slice(c->global, SLICE_LIT(".rela.dyn"));
       n_relaplt = pool_intern_slice(c->global, SLICE_LIT(".rela.plt"));
       n_dynamic = pool_intern_slice(c->global, SLICE_LIT(".dynamic"));
       n_gotplt = pool_intern_slice(c->global, SLICE_LIT(".got.plt"));
       n_gnuver = pool_intern_slice(c->global, SLICE_LIT(".gnu.version"));
       n_gnuver_r = pool_intern_slice(c->global, SLICE_LIT(".gnu.version_r"));
     }
     /* Two-pass: first find dynsym/dynstr/gotplt indices for sh_link
      * fixups, then emit. */
     u32 idx_dynsym = 0, idx_dynstr = 0, idx_gotplt = 0;
     if ((pie || shared) && img->dyn) {
       for (i = 0; i < noutshdr; ++i) {
         Sym nm = outshdrs[i].name;
         u32 ix = outshdrs[i].shdr_idx;
         if (nm == n_dynsym)
           idx_dynsym = ix;
         else if (nm == n_dynstr)
           idx_dynstr = ix;
         else if (nm == n_gotplt)
           idx_gotplt = ix;
       }
     }
     /* per-name output shdrs */
     for (i = 0; i < noutshdr; ++i) {
       const OutShdr* o = &outshdrs[i];
       memset(&sh, 0, sizeof(sh));
       sh.sh_name = outshdr_name_off[i];
       sh.sh_type = sec_sem_to_sht(o->sem);
       sh.sh_flags = sec_flags_to_shf(o->flags);
       sh.sh_addr = img_base + o->vaddr;
       /* File-only debug sections aren't loaded: SHT_PROGBITS, no
        * SHF_ALLOC, sh_addr 0. addr2line / gdb read them by file offset. */
       if (o->is_fileonly) {
         sh.sh_type = SHT_PROGBITS;
         sh.sh_flags = 0;
         sh.sh_addr = 0;
       }
       sh.sh_offset = o->file_offset;
       sh.sh_size = o->size;
       sh.sh_link = 0;
       sh.sh_info = 0;
       sh.sh_addralign = o->align ? o->align : 1;
       sh.sh_entsize = (o->sem == SSEM_INIT_ARRAY || o->sem == SSEM_FINI_ARRAY ||
                        o->sem == SSEM_PREINIT_ARRAY)
                           ? 8
                           : 0;
       /* Dyn-section overrides: sh_type / sh_link / sh_info / entsize. */
       if ((pie || shared) && img->dyn) {
         if (o->name == n_dynsym) {
           sh.sh_type = SHT_DYNSYM;
           sh.sh_link = idx_dynstr;
           sh.sh_info = img->dyn->first_global;
           sh.sh_entsize = 24;
         } else if (o->name == n_dynstr) {
           sh.sh_type = SHT_STRTAB;
         } else if (o->name == n_gnuhash) {
           sh.sh_type = SHT_GNU_HASH;
           sh.sh_link = idx_dynsym;
         } else if (o->name == n_reladyn) {
           sh.sh_type = SHT_RELA;
           sh.sh_link = idx_dynsym;
           sh.sh_entsize = 24;
         } else if (o->name == n_relaplt) {
           sh.sh_type = SHT_RELA;
           sh.sh_link = idx_dynsym;
           sh.sh_info = idx_gotplt;
           sh.sh_entsize = 24;
           sh.sh_flags |= SHF_INFO_LINK;
         } else if (o->name == n_dynamic) {
           sh.sh_type = SHT_DYNAMIC;
           sh.sh_link = idx_dynstr;
           sh.sh_entsize = 16;
         } else if (o->name == n_gnuver) {
           sh.sh_type = SHT_GNU_VERSYM;
           sh.sh_link = idx_dynsym;
           sh.sh_entsize = 2;
         } else if (o->name == n_gnuver_r) {
           sh.sh_type = SHT_GNU_VERNEED;
           sh.sh_link = idx_dynstr;
           sh.sh_info = img->dyn->nverneed;
         } else if (o->name == n_gotplt) {
           sh.sh_entsize = 8;
         }
       }
       write_shdr(w, &sh, class32);
     }
     /* shdr: .note.gnu.build-id (allocatable; in headers PT_LOAD) */
     if (!scripted) {
       memset(&sh, 0, sizeof(sh));
       sh.sh_name = sh_name_buildid;
       sh.sh_type = SHT_NOTE;
       sh.sh_flags = SHF_ALLOC;
       sh.sh_addr = build_id_addr;
       sh.sh_offset = build_id_off;
       sh.sh_size = BUILD_ID_NOTE_BYTES;
       sh.sh_addralign = 4;
       write_shdr(w, &sh, class32);
     }
     /* shdr: .symtab */
     memset(&sh, 0, sizeof(sh));
     sh.sh_name = sh_name_symtab;
     sh.sh_type = SHT_SYMTAB;
     sh.sh_flags = 0;
     sh.sh_addr = 0;
     sh.sh_offset = symtab_off;
     sh.sh_size = symtab_size;
     sh.sh_link = shndx_strtab;
     sh.sh_info = first_global_idx;
     sh.sh_addralign = 8;
     sh.sh_entsize = sym_size;
     write_shdr(w, &sh, class32);
     /* shdr: .strtab */
     memset(&sh, 0, sizeof(sh));
     sh.sh_name = sh_name_strtab;
     sh.sh_type = SHT_STRTAB;
     sh.sh_offset = strtab_off;
     sh.sh_size = strtab_size;
     sh.sh_addralign = 1;
     write_shdr(w, &sh, class32);
     /* shdr: .shstrtab */
     memset(&sh, 0, sizeof(sh));
     sh.sh_name = sh_name_shstrtab;
     sh.sh_type = SHT_STRTAB;
     sh.sh_offset = shstrtab_off;
     sh.sh_size = shstrtab_size;
     sh.sh_addralign = 1;
     write_shdr(w, &sh, class32);
   }
 
   heap->free(heap, phdrs, sizeof(Phdr64) * nphdr_total);
   heap->free(heap, recs, sizeof(*recs) * (LinkSyms_count(&img->syms) + 1u));
   heap->free(heap, outshdrs, sizeof(*outshdrs) * outshdr_cap);
   if (outshdr_name_off)
     heap->free(heap, outshdr_name_off, sizeof(u32) * (noutshdr + 1u));
   objbb_fini(&strtab);
   objbb_fini(&shstrtab);
 }