kit

emit.c (26378B)

---

 /* PE/COFF relocatable .obj writer. Walks a finalized ObjBuilder and
  * emits a 64-bit little-endian relocatable object via the supplied
  * Writer. Counterpart to emit_elf / emit_macho.
  *
  * Layout strategy:
  *   1. plan COFF sections (one per kept obj section), assigning
  *      Characteristics, alignment, raw size, and per-section reloc
  *      counts;
  *   2. build the symbol table (synthesized per-section static symbols
  *      with section-definition aux records, plus file symbols and
  *      every ObjSym kept after sweep);
  *   3. build per-section relocation records via the per-arch
  *      translator (arch_for_compiler(c)->coff->reloc_to);
  *   4. assign file offsets:
  *        file header | section headers | (bytes + relocs)* | symtab | strtab
  *   5. write the file in that order.
  *
  * 64-bit little-endian only — IMAGE_FILE_MACHINE_AMD64 (x86_64) and
  * IMAGE_FILE_MACHINE_ARM64 (aarch64). Big-endian / ptr_size != 8 panic
  * at entry.
  *
  * Section name mapping policy: we pass the kit Section.name through
  * verbatim to the COFF Name field. Callers / readers are expected to
  * have stored COFF-shaped names (".text", ".rdata", ".tls$", etc.) at
  * the obj layer; emit_coff does not rewrite ELF-style spellings like
  * ".rodata" -> ".rdata". Names longer than 8 bytes spill into the
  * string table with the "/<decimal-offset>" encoding.
  *
  * Addend handling: COFF stores the addend inline in the patched bytes
  * (there is no addend field in IMAGE_RELOCATION). The ObjBuilder
  * caller is responsible for having written the addend into the section
  * bytes already — matching how MSVC / mingw emit. A nonzero
  * Reloc::addend with has_explicit_addend set is rejected here as a
  * known v1 limitation. */
 
 #include <string.h>
 
 #include "core/arena.h"
 #include "core/buf.h"
 #include "core/heap.h"
 #include "core/pool.h"
 #include "core/slice.h"
 #include "core/util.h"
 #include "obj/coff/coff.h"
 #include "obj/format.h"
 
 static int coff_rel32_absorbs_minus4(KitArchKind arch, RelocKind kind,
                                      i64 addend) {
   if (arch != KIT_ARCH_X86_64 || addend != -4) return 0;
   switch (kind) {
     case R_PC32:
     case R_REL32:
     case R_PLT32:
     case R_X64_PLT32:
     case R_X64_GOTPCREL:
     case R_X64_GOTPCRELX:
     case R_X64_REX_GOTPCRELX:
       return 1;
     default:
       return 0;
   }
 }
 
 /* ---- per-COFF-section plan record ---- */
 
 typedef struct CSec {
   /* IMAGE_SECTION_HEADER fields (little-endian-encoded at write time). */
   char name8[8];        /* Name field bytes; "/N" form if long name */
   u32 virtual_size;     /* 0 for .obj (VirtualSize is image-only) */
   u32 size_of_raw_data; /* section size, incl. NOBITS (bss) size */
   u32 pointer_to_raw_data;
   u32 pointer_to_relocations;
   u16 number_of_relocations;
   u32 characteristics; /* IMAGE_SCN_* | ALIGN nibble */
 
   /* Planning state. */
   u32 align;   /* in bytes, power of two */
   u32 obj_sec; /* originating ObjSecId */
   int is_nobits;
   const Buf* obj_bytes; /* NULL when nobits */
   u8* reloc_bytes;      /* arena-allocated, nreloc * 10 bytes */
   ObjGroupId group_id;  /* OBJ_GROUP_NONE if not in a group */
 } CSec;
 
 /* ---- emit ---- */
 
 static u32 log2_align(u32 a) {
   u32 r = 0;
   while ((1u << r) < a) ++r;
   return r;
 }
 
 /* Map kit section flags/sem to IMAGE_SCN_* Characteristics, leaving
  * the alignment nibble for the caller to OR in. */
 static u32 sec_characteristics(const Section* s, int in_group) {
   u32 r = 0;
   int is_bss = (s->kind == SEC_BSS) || (s->sem == SSEM_NOBITS);
   if (s->flags & SF_EXEC) {
     r |= IMAGE_SCN_CNT_CODE | IMAGE_SCN_MEM_EXECUTE;
   } else if (is_bss) {
     r |= IMAGE_SCN_CNT_UNINITIALIZED_DATA;
   } else if (s->flags & SF_WRITE) {
     r |= IMAGE_SCN_CNT_INITIALIZED_DATA;
   } else if (s->flags & SF_ALLOC) {
     /* Read-only allocated data (.rdata). */
     r |= IMAGE_SCN_CNT_INITIALIZED_DATA;
   }
   if (s->flags & SF_ALLOC) r |= IMAGE_SCN_MEM_READ;
   if (s->flags & SF_WRITE) r |= IMAGE_SCN_MEM_WRITE;
   if (in_group) r |= IMAGE_SCN_LNK_COMDAT;
   /* When a reader stashed format-specific flag bits on a COFF-origin
    * section, OR them back in here. ext_type carries the raw
    * Characteristics value (or zero if no override); ext_flags is a
    * sibling bag for any bits the canonical mapping above would lose. */
   if (s->ext_kind == OBJ_EXT_COFF) {
     if (s->ext_type) {
       /* Preserve the raw characteristics verbatim — overrides the
        * canonical mapping. Keeps round-trip byte-stable for sections
        * carrying CNT_INFO / LNK_REMOVE / MEM_DISCARDABLE / etc. */
       r = s->ext_type & ~IMAGE_SCN_ALIGN_MASK;
     }
     r |= s->ext_flags;
   }
   return r;
 }
 
 /* The string-table dedup + build moved to the shared ObjStrtab (obj.h); the
  * former per-add buf_flatten + linear substring scan here was the same O(n^2)
  * the ELF writer had. The COFF strtab keeps its leading 4-byte size field (a
  * raw prefix the dedup never targets, see obj_strtab_put_raw). */
 
 /* Encode an 8-byte Name field. If the name fits in 8 bytes, copy
  * verbatim and zero-pad. Otherwise allocate the name in `strtab` and
  * write "/<decimal-offset>" (NUL-padded to 8 bytes). */
 static void encode_name8(char out[8], const char* name, u32 nlen,
                          ObjStrtab* strtab) {
   memset(out, 0, 8);
   if (nlen <= 8) {
     if (nlen) memcpy(out, name, nlen);
     return;
   }
   u32 off = obj_strtab_add(strtab, name, nlen);
   /* "/<decimal-offset>" — up to 7 decimal digits leaves room for the
    * leading slash within 8 bytes. COFF .obj strtabs are < 1 MiB in
    * practice, so 7 digits is plenty. */
   char tmp[16];
   int n = 0;
   tmp[n++] = '/';
   /* Decimal-format off into tmp+1. */
   char dig[12];
   int d = 0;
   u32 v = off;
   if (v == 0) {
     dig[d++] = '0';
   } else {
     while (v) {
       dig[d++] = (char)('0' + (v % 10u));
       v /= 10u;
     }
   }
   while (d > 0 && n < (int)sizeof tmp) tmp[n++] = dig[--d];
   if (n > 8) n = 8;
   memcpy(out, tmp, (size_t)n);
 }
 
 /* Write one 18-byte IMAGE_SYMBOL record into `dst`. */
 static void wr_sym(u8* dst, const char ShortName[8], u32 Zeroes, u32 Offset,
                    u32 Value, i16 SectionNumber, u16 Type, u8 StorageClass,
                    u8 NumberOfAuxSymbols) {
   if (Zeroes == 0 && Offset != 0) {
     /* LongName form: 4 zero bytes then 4-byte LE strtab offset. */
     memset(dst, 0, 4);
     wr_u32_le(dst + 4, Offset);
   } else {
     memcpy(dst, ShortName, 8);
   }
   wr_u32_le(dst + 8, Value);
   wr_u16_le(dst + 12, (u16)SectionNumber);
   wr_u16_le(dst + 14, Type);
   dst[16] = StorageClass;
   dst[17] = NumberOfAuxSymbols;
 }
 
 /* Write a section-definition aux record (18 bytes). */
 static void wr_aux_secdef(u8* dst, u32 Length, u16 NumberOfRelocations,
                           u16 NumberOfLinenumbers, u32 CheckSum, u16 Number,
                           u8 Selection) {
   wr_u32_le(dst + 0, Length);
   wr_u16_le(dst + 4, NumberOfRelocations);
   wr_u16_le(dst + 6, NumberOfLinenumbers);
   wr_u32_le(dst + 8, CheckSum);
   wr_u16_le(dst + 12, Number);
   dst[14] = Selection;
   dst[15] = 0;
   dst[16] = 0;
   dst[17] = 0;
 }
 
 /* Write a weak-externals aux record (18 bytes). */
 static void wr_aux_weak(u8* dst, u32 TagIndex, u32 Characteristics) {
   wr_u32_le(dst + 0, TagIndex);
   wr_u32_le(dst + 4, Characteristics);
   memset(dst + 8, 0, 10);
 }
 
 /* Look up the pool-interned string for a Sym. */
 static const char* sym_to_str(Compiler* c, Sym n, u32* len_out) {
   Slice sl = pool_slice(c->global, n);
   const char* s = sl.s;
   if (!s) {
     *len_out = 0;
     return "";
   }
   *len_out = (u32)sl.len;
   return s;
 }
 
 void emit_coff(Compiler* c, ObjBuilder* ob, Writer* w) {
   Heap* h = (Heap*)c->ctx->heap;
 
   /* Tombstone sweep — see obj_sweep_dead. */
   obj_sweep_dead(ob);
 
   /* ---- target validation ----------------------------------------- */
   const ObjFormatImpl* fmt = obj_format_lookup(KIT_OBJ_COFF);
   const ObjCoffArchOps* coff =
       fmt && fmt->coff_arch ? fmt->coff_arch(c->target.arch) : NULL;
   if (!coff || !coff->reloc_to) {
     compiler_panic(c, SRCLOC_NONE, "emit_coff: unsupported target arch %u",
                    (u32)c->target.arch);
   }
   u16 machine = coff->machine;
   u32 (*reloc_to)(u32) = coff->reloc_to;
   if (c->target.big_endian) {
     compiler_panic(c, SRCLOC_NONE, "emit_coff: big-endian COFF not supported");
   }
   if (c->target.ptr_size != 8) {
     compiler_panic(c, SRCLOC_NONE, "emit_coff: ptr_size %u (expected 8)",
                    (u32)c->target.ptr_size);
   }
 
   /* ---- pass 1: plan sections ------------------------------------- */
   u32 nobjsec = obj_section_count(ob);
   CSec* secs = arena_zarray(c->scratch, CSec, nobjsec ? nobjsec : 1);
   u32* obj_to_coff = arena_zarray(c->scratch, u32, nobjsec ? nobjsec : 1);
   u32 nsecs = 0;
 
   /* String table — leading 4-byte size placeholder. Real strings start
    * at offset 4. */
   ObjStrtab strtab;
   obj_strtab_init(&strtab, h, /*dedup=*/1);
   {
     u8 zero4[COFF_STRTAB_SIZE_FIELD_BYTES] = {0, 0, 0, 0};
     obj_strtab_put_raw(&strtab, zero4, COFF_STRTAB_SIZE_FIELD_BYTES);
   }
 
   for (u32 i = 1; i < nobjsec; ++i) {
     const Section* s = obj_section_get(ob, i);
     if (s->removed) continue;
     /* Skip ELF-style synthetic sections (a reader from another format
      * may have surfaced them) — COFF stores symtab/strtab/relocs
      * out-of-band, not as named sections. */
     if (s->sem == SSEM_SYMTAB || s->sem == SSEM_STRTAB || s->sem == SSEM_RELA ||
         s->sem == SSEM_REL || s->sem == SSEM_GROUP) {
       continue;
     }
 
     CSec* cs = &secs[nsecs];
     u32 nlen;
     const char* nm = sym_to_str(c, s->name, &nlen);
     encode_name8(cs->name8, nm, nlen, &strtab);
 
     cs->obj_sec = i;
     cs->group_id = s->group_id;
     cs->align = s->align ? s->align : 1;
 
     int in_group = (s->group_id != OBJ_GROUP_NONE);
     u32 ch = sec_characteristics(s, in_group);
     /* Alignment lives in bits 20..23. Cap at log2(8192)=13 -> nibble
      * value 14 (IMAGE_SCN_ALIGN_8192BYTES). */
     u32 lg = log2_align(cs->align);
     if (lg > 13) lg = 13;
     ch &= ~IMAGE_SCN_ALIGN_MASK;
     ch |= IMAGE_SCN_ALIGN_FROM_LOG2(lg);
     cs->characteristics = ch;
 
     if (s->sem == SSEM_NOBITS || s->kind == SEC_BSS) {
       cs->is_nobits = 1;
       /* COFF object files carry the section size in SizeOfRawData (with
        * PointerToRawData=0 / no file bytes for uninitialized data) and
        * keep VirtualSize=0 — VirtualSize is meaningful only for linked
        * images. lld / link.exe treat a section with SizeOfRawData==0 as
        * empty and discard it, orphaning every symbol defined there and
        * breaking relocations that target them ("relocation against
        * symbol in discarded section"). Match clang/MSVC: size in
        * SizeOfRawData, VirtualSize 0, no raw data. */
       cs->virtual_size = 0;
       cs->size_of_raw_data = s->bss_size;
       cs->obj_bytes = NULL;
     } else {
       cs->is_nobits = 0;
       cs->virtual_size = 0;
       cs->size_of_raw_data = s->bytes.total;
       cs->obj_bytes = &s->bytes;
     }
 
     obj_to_coff[i] = nsecs + 1; /* 1-based; matches SectionNumber. */
     nsecs++;
   }
 
   /* ---- pass 2: count and assign per-section reloc counts --------- */
   /* COFF stores NumberOfRelocations as u16; sections with > 65535
    * relocs use the IMAGE_SCN_LNK_NRELOC_OVFL extension which we don't
    * implement in v1. Panic if any single section exceeds the limit. */
   for (u32 ci = 0; ci < nsecs; ++ci) {
     CSec* cs = &secs[ci];
     u32 nr = obj_reloc_count(ob, cs->obj_sec);
     if (nr > 0xFFFFu) {
       compiler_panic(c, SRCLOC_NONE,
                      "emit_coff: section %u has %u relocs (max 65535)",
                      (u32)cs->obj_sec, nr);
     }
     cs->number_of_relocations = (u16)nr;
   }
 
   /* ---- pass 3: build the symbol table ---------------------------- */
   /* Count ObjSyms (incl. tombstoned — we'll skip those when emitting). */
   u32 nobjsym = 0;
   {
     ObjSymIter* it = obj_symiter_new(ob);
     ObjSymEntry e;
     while (obj_symiter_next(it, &e)) ++nobjsym;
     obj_symiter_free(it);
   }
 
   /* Upper bound on symbol-table records (including aux slots):
    *   - 2 records per section symbol (primary + 1 aux secdef)
    *   - 2 records per ObjSym (primary + up to 1 weak aux)
    *   - +2 spare for safety
    * Worst case is generous; we trim by tracking nrecords as we emit. */
   u32 max_records = 2u * nsecs + 2u * nobjsym + 4u;
   u8* symtab =
       (u8*)arena_zarray(c->scratch, u8, (size_t)COFF_SYMBOL_SIZE * max_records);
   u32 nrecords = 0;
 
   /* obj_id -> COFF symbol index (including aux slots). Index 0 is
    * reserved as "none" in our internal map (a real COFF symbol may
    * legitimately live at index 0, but no ObjSym ever maps there since
    * we never put OBJ_SYM_NONE through). */
   u32* sym_to_coff = arena_zarray(c->scratch, u32, nobjsym + 2);
 
   /* Section symbols first — one STATIC per kept obj section, each
    * followed by a SECTION DEFINITION aux. Reloc-against-section in
    * other tools' output uses these; emitting them unconditionally
    * matches what clang / mingw emit and gives readers a stable target. */
   u32* secsym_index = arena_zarray(c->scratch, u32, nsecs + 1);
   for (u32 ci = 0; ci < nsecs; ++ci) {
     CSec* cs = &secs[ci];
     char short_name[8];
     /* The section symbol's name is the section's own name (truncated
      * to 8 bytes — section symbols never use the strtab spill form in
      * MSVC/clang output). */
     memcpy(short_name, cs->name8, 8);
 
     u8* slot = symtab + (size_t)nrecords * COFF_SYMBOL_SIZE;
     wr_sym(slot, short_name, /*Zeroes*/ 1, /*Offset*/ 0,
            /*Value*/ 0,
            /*SectionNumber*/ (i16)(ci + 1),
            /*Type*/ IMAGE_SYM_TYPE_NULL,
            /*StorageClass*/ IMAGE_SYM_CLASS_STATIC,
            /*NumberOfAuxSymbols*/ 1);
     secsym_index[ci] = nrecords;
     nrecords++;
 
     /* Section-definition aux. For COMDAT members we encode the
      * Selection from the group; default to SELECT_ANY which is what
      * gcc/clang emit unless the user requests a specific selection
      * mode. The associated-section Number is left at 0 (kit does
      * not produce associative-COMDAT chains today). */
     u8 selection = 0;
     if (cs->group_id != OBJ_GROUP_NONE) {
       const ObjGroup* g = obj_group_get(ob, cs->group_id);
       if (g && !g->removed) {
         selection = g->flags ? (u8)IMAGE_COMDAT_SELECT_ANY
                              : (u8)IMAGE_COMDAT_SELECT_ANY;
       }
     }
     u8* aux = symtab + (size_t)nrecords * COFF_SYMBOL_SIZE;
     wr_aux_secdef(aux, /*Length*/ cs->size_of_raw_data,
                   /*NumberOfRelocations*/ cs->number_of_relocations,
                   /*NumberOfLinenumbers*/ 0,
                   /*CheckSum*/ 0,
                   /*Number*/ 0,
                   /*Selection*/ selection);
     nrecords++;
   }
 
   /* File / regular symbols. */
   {
     ObjSymIter* it = obj_symiter_new(ob);
     ObjSymEntry e;
     while (obj_symiter_next(it, &e)) {
       const ObjSym* s = e.sym;
       if (s->removed) continue;
       if (s->kind == SK_IFUNC) {
         compiler_panic(c, SRCLOC_NONE,
                        "emit_coff: SK_IFUNC has no PE/COFF representation");
       }
       /* Don't re-emit SK_SECTION symbols — section symbols are
        * synthesized above. Map any input-side SK_SECTION onto the
        * already-emitted one. */
       if (s->kind == SK_SECTION) {
         if (s->section_id && s->section_id < nobjsec) {
           u32 ci = obj_to_coff[s->section_id];
           if (ci) sym_to_coff[e.id] = secsym_index[ci - 1];
         }
         continue;
       }
 
       u32 nlen;
       const char* nm = sym_to_str(c, s->name, &nlen);
 
       if (s->kind == SK_FILE) {
         /* File symbol: name ".file" (short), section IMAGE_SYM_DEBUG,
          * storage class FILE, followed by aux records carrying the
          * NUL-padded file path (18 bytes per aux). */
         u32 file_len = nlen;
         u32 naux =
             file_len ? (file_len + COFF_AUX_FILE_SIZE - 1u) / COFF_AUX_FILE_SIZE
                      : 1u;
         char short_name[8] = {'.', 'f', 'i', 'l', 'e', 0, 0, 0};
         u8* slot = symtab + (size_t)nrecords * COFF_SYMBOL_SIZE;
         wr_sym(slot, short_name, 1, 0, /*Value*/ 0,
                /*SectionNumber*/ (i16)IMAGE_SYM_DEBUG,
                /*Type*/ IMAGE_SYM_TYPE_NULL,
                /*StorageClass*/ IMAGE_SYM_CLASS_FILE,
                /*NumberOfAuxSymbols*/ (u8)naux);
         sym_to_coff[e.id] = nrecords;
         nrecords++;
         for (u32 a = 0; a < naux; ++a) {
           u8* aux = symtab + (size_t)nrecords * COFF_SYMBOL_SIZE;
           memset(aux, 0, COFF_AUX_FILE_SIZE);
           u32 off = a * COFF_AUX_FILE_SIZE;
           u32 copy = file_len > off ? file_len - off : 0;
           if (copy > COFF_AUX_FILE_SIZE) copy = COFF_AUX_FILE_SIZE;
           if (copy) memcpy(aux, nm + off, copy);
           nrecords++;
         }
         continue;
       }
 
       /* Regular symbol. */
       char short_name[8];
       u32 zeroes = 1, offset = 0;
       memset(short_name, 0, 8);
       if (nlen <= 8) {
         if (nlen) memcpy(short_name, nm, nlen);
       } else {
         zeroes = 0;
         offset = obj_strtab_add(&strtab, nm, nlen);
       }
 
       i16 section_number = 0;
       u32 value = 0;
       u8 storage_class = IMAGE_SYM_CLASS_NULL;
       u16 type = IMAGE_SYM_TYPE_NULL;
       u8 naux = 0;
       int emit_weak_aux = 0;
 
       switch (s->kind) {
         case SK_ABS:
           section_number = (i16)IMAGE_SYM_ABSOLUTE;
           value = (u32)s->value;
           break;
         case SK_COMMON:
           /* COFF lacks a per-common alignment field; encode size in
            * Value with SectionNumber=UNDEFINED and rely on the linker
            * to pick a default alignment. (kit's frontend uses
            * COMMON only via __attribute__((common)) which is rare on
            * PE/COFF targets.) */
           section_number = (i16)IMAGE_SYM_UNDEFINED;
           value = (u32)s->size;
           break;
         default:
           if (s->section_id == OBJ_SEC_NONE) {
             section_number = (i16)IMAGE_SYM_UNDEFINED;
             value = 0;
           } else if (s->section_id < nobjsec && obj_to_coff[s->section_id]) {
             section_number = (i16)obj_to_coff[s->section_id];
             value = (u32)s->value;
           } else {
             section_number = (i16)IMAGE_SYM_UNDEFINED;
             value = 0;
           }
           break;
       }
 
       if (s->kind == SK_FUNC) type = (u16)COFF_SYM_TYPE_FUNCTION;
 
       switch (s->bind) {
         case SB_LOCAL:
           storage_class = IMAGE_SYM_CLASS_STATIC;
           break;
         case SB_GLOBAL:
           storage_class = IMAGE_SYM_CLASS_EXTERNAL;
           break;
         case SB_WEAK:
           /* mingw / clang spell weak as EXTERNAL with a WeakExternal
            * aux that points at the fallback symbol. kit's obj layer
            * doesn't carry a separate fallback symbol today, so we emit
            * a self-referential weak aux (TagIndex=0) which the linker
            * treats as "weak, no fallback" — equivalent to ELF STB_WEAK. */
           storage_class = IMAGE_SYM_CLASS_WEAK_EXTERNAL;
           emit_weak_aux = 1;
           naux = 1;
           break;
         default:
           storage_class = IMAGE_SYM_CLASS_STATIC;
           break;
       }
 
       u8* slot = symtab + (size_t)nrecords * COFF_SYMBOL_SIZE;
       wr_sym(slot, short_name, zeroes, offset, value, section_number, type,
              storage_class, naux);
       sym_to_coff[e.id] = nrecords;
       nrecords++;
       if (emit_weak_aux) {
         u8* aux = symtab + (size_t)nrecords * COFF_SYMBOL_SIZE;
         wr_aux_weak(aux, /*TagIndex*/ 0,
                     /*Characteristics*/ IMAGE_WEAK_EXTERN_SEARCH_LIBRARY);
         nrecords++;
       }
     }
     obj_symiter_free(it);
   }
 
   /* ---- pass 4: build per-section relocation tables --------------- */
   for (u32 ci = 0; ci < nsecs; ++ci) {
     CSec* cs = &secs[ci];
     u32 nr;
     const u32* rix = obj_reloc_section(ob, cs->obj_sec, &nr);
     if (!nr) continue;
     u8* buf = (u8*)arena_alloc(c->scratch, (size_t)COFF_RELOC_SIZE * nr,
                                _Alignof(u32));
     u32 j = 0;
     /* rix[] lists this section's live relocs in ascending global order. */
     for (u32 k = 0; k < nr; ++k) {
       const Reloc* r = obj_reloc_at(ob, rix[k]);
       if (r->sym == OBJ_SYM_NONE) {
         compiler_panic(c, SRCLOC_NONE,
                        "emit_coff: reloc without symbol not supported "
                        "(sec=%u offset=%u kind=%u)",
                        (u32)r->section_id, (u32)r->offset, (u32)r->kind);
       }
       if (r->has_explicit_addend && r->addend != 0 &&
           !coff_rel32_absorbs_minus4(c->target.arch, (RelocKind)r->kind,
                                      r->addend)) {
         /* v1 limitation: COFF carries the addend in the patched bytes,
          * and we don't currently mutate the obj's section bytes to
          * encode a separate explicit addend. kit's MCEmitter writes
          * the addend inline for COFF targets, so this branch only
          * fires for inputs synthesized by external tools. */
         compiler_panic(c, SRCLOC_NONE,
                        "emit_coff: explicit nonzero addend not supported "
                        "(sec=%u offset=%u kind=%u addend=%lld)",
                        (u32)r->section_id, (u32)r->offset, (u32)r->kind,
                        (long long)r->addend);
       }
       u32 wire = reloc_to(r->kind);
       /* Both arch translators use 0 (IMAGE_REL_*_ABSOLUTE) as the
        * unsupported-input sentinel; treat that as a panic unless the
        * input really is R_NONE. */
       if (wire == 0 && r->kind != R_NONE) {
         compiler_panic(c, SRCLOC_NONE,
                        "emit_coff: unsupported relocation kind %u for arch %u",
                        (u32)r->kind, (u32)c->target.arch);
       }
       u32 sym_idx = sym_to_coff[r->sym];
       u8* slot = buf + (size_t)j * COFF_RELOC_SIZE;
       wr_u32_le(slot + 0, r->offset);
       wr_u32_le(slot + 4, sym_idx);
       wr_u16_le(slot + 8, (u16)wire);
       ++j;
     }
     cs->reloc_bytes = buf;
     /* If a tombstoned reloc was skipped between count and emit, j may
      * be less than nr; trust the latter count for the wire field. */
     if (j != nr) cs->number_of_relocations = (u16)j;
   }
 
   /* ---- pass 5: assign file offsets ------------------------------- */
   /* Layout:
    *   [file header] [section headers] [per-section: bytes, relocs]*
    *   [symbol table] [string table] */
   u64 cur =
       (u64)COFF_FILE_HEADER_SIZE + (u64)COFF_SECTION_HEADER_SIZE * (u64)nsecs;
 
   for (u32 ci = 0; ci < nsecs; ++ci) {
     CSec* cs = &secs[ci];
     /* Raw data offset. NOBITS contributes nothing on disk. */
     if (cs->is_nobits || cs->size_of_raw_data == 0) {
       cs->pointer_to_raw_data = 0;
     } else {
       cur = ALIGN_UP(cur, (u64)cs->align);
       cs->pointer_to_raw_data = (u32)cur;
       cur += cs->size_of_raw_data;
     }
     /* Reloc table. COFF doesn't mandate alignment for the reloc array,
      * but llvm and binutils emit them naturally byte-packed; we 4-align
      * for tidiness. */
     if (cs->number_of_relocations) {
       cur = ALIGN_UP(cur, (u64)4);
       cs->pointer_to_relocations = (u32)cur;
       cur += (u64)cs->number_of_relocations * COFF_RELOC_SIZE;
     } else {
       cs->pointer_to_relocations = 0;
     }
   }
 
   cur = ALIGN_UP(cur, (u64)4);
   u64 symtab_off = cur;
   cur += (u64)nrecords * COFF_SYMBOL_SIZE;
 
   /* String table starts immediately after the symtab. Patch the 4-byte
    * size prefix (inclusive). */
   u32 strtab_size = obj_strtab_size(&strtab);
   /* The size field is part of the on-disk strtab and is the total
    * inclusive byte count. Patch it now. */
   {
     u8 sz_le[4];
     wr_u32_le(sz_le, strtab_size);
     /* Buf doesn't expose in-place patch; flatten, patch, re-emit when
      * we write. Just remember the value. */
     (void)sz_le;
   }
   u64 strtab_off = cur;
   cur += strtab_size;
 
   /* ---- pass 6: write the file ------------------------------------ */
   kit_writer_seek(w, 0);
 
   /* IMAGE_FILE_HEADER */
   coff_wr_u16(w, machine);
   coff_wr_u16(w, (u16)nsecs);
   coff_wr_u32(w, 0); /* TimeDateStamp: reproducible */
   coff_wr_u32(w, (u32)symtab_off);
   coff_wr_u32(w, nrecords);
   coff_wr_u16(w, 0); /* SizeOfOptionalHeader: 0 for .obj */
   coff_wr_u16(w, IMAGE_FILE_LARGE_ADDRESS_AWARE);
 
   /* Section headers — one 40-byte block immediately after the file
    * header. */
   for (u32 ci = 0; ci < nsecs; ++ci) {
     const CSec* cs = &secs[ci];
     kit_writer_write(w, cs->name8, 8);
     coff_wr_u32(w, cs->virtual_size);
     coff_wr_u32(w, 0); /* VirtualAddress: 0 for .obj */
     coff_wr_u32(w, cs->size_of_raw_data);
     coff_wr_u32(w, cs->pointer_to_raw_data);
     coff_wr_u32(w, cs->pointer_to_relocations);
     coff_wr_u32(w, 0); /* PointerToLinenumbers: 0 */
     coff_wr_u16(w, cs->number_of_relocations);
     coff_wr_u16(w, 0); /* NumberOfLinenumbers: 0 */
     coff_wr_u32(w, cs->characteristics);
   }
 
   /* Section bytes + relocs (interleaved). */
   for (u32 ci = 0; ci < nsecs; ++ci) {
     const CSec* cs = &secs[ci];
     if (!cs->is_nobits && cs->size_of_raw_data && cs->obj_bytes) {
       kit_writer_seek(w, cs->pointer_to_raw_data);
       u32 sz = cs->obj_bytes->total;
       u8* tmp = (u8*)h->alloc(h, sz ? sz : 1, 1);
       if (sz) buf_flatten(cs->obj_bytes, tmp);
       kit_writer_write(w, tmp, sz);
       h->free(h, tmp, sz ? sz : 1);
     }
     if (cs->number_of_relocations && cs->reloc_bytes) {
       kit_writer_seek(w, cs->pointer_to_relocations);
       kit_writer_write(w, cs->reloc_bytes,
                        (size_t)cs->number_of_relocations * COFF_RELOC_SIZE);
     }
   }
 
   /* Symbol table. */
   kit_writer_seek(w, symtab_off);
   kit_writer_write(w, symtab, (size_t)nrecords * COFF_SYMBOL_SIZE);
 
   /* String table: 4-byte total size (inclusive) followed by the body.
    * `strtab` was initialized with 4 placeholder zero bytes; rewrite
    * them with the real size before flushing. */
   {
     u8* flat = (u8*)arena_alloc(c->scratch, strtab_size ? strtab_size : 1, 1);
     if (strtab_size) memcpy(flat, obj_strtab_data(&strtab), strtab_size);
     /* Patch the 4-byte size prefix in place. */
     if (strtab_size >= COFF_STRTAB_SIZE_FIELD_BYTES) {
       wr_u32_le(flat, strtab_size);
     }
     kit_writer_seek(w, strtab_off);
     kit_writer_write(w, flat, strtab_size);
   }
   obj_strtab_fini(&strtab);
 }