kit

image.c (36500B)

---

 #include <kit/image.h>
 #include <kit/object.h>
 #include <stdarg.h>
 #include <stdint.h>
 #include <stdio.h>
 #include <string.h>
 
 #include "driver.h"
 
 #define IMAGE_TOOL "image"
 
 typedef struct ImageCliOpts {
   KitImageOptions image;
   /* Backing storage for the repeatable name lists referenced by `image`. Each
    * list owns its own array; the KitImageOptions pointers alias into them. */
   KitSlice* segments;
   uint32_t cap_segments;
   KitSlice* only_sections;
   uint32_t cap_only;
   KitSlice* remove_sections;
   uint32_t cap_remove;
   KitSlice* section_order;
   uint32_t cap_section_order;
   KitSlice* require_symbols;
   uint32_t cap_require_symbols;
   KitSlice* require_sections;
   uint32_t cap_require_sections;
   /* ELF/debug knobs (only meaningful for --format elf, which is deferred). */
   bool strip_debug;
   bool keep_symbols;
   const char* split_debug;
   const char* metadata;
   const char* input;
   const char* output;
 } ImageCliOpts;
 
 void driver_help_image(void) {
   driver_printf(
       "%.*s",
       KIT_SLICE_ARG(KIT_SLICE_LIT(
           "kit image — emit flat load images from objects and linked images\n"
           "\n"
           "USAGE\n"
           "  kit image [OPTIONS] INPUT [-o OUTPUT]\n"
           "\n"
           "FORMAT\n"
           "  --format bin             flat binary from loadable ranges "
           "(default)\n"
           "  --format rom             fixed-size flat binary (requires "
           "--pad-to)\n"
           "  --format sections        concatenate --section bytes in order\n"
           "  --format ihex            Intel HEX records from loadable ranges\n"
           "  --format srec            Motorola S-records from loadable ranges\n"
           "  --from segments          linked segments; relocatables use "
           "allocated sections (default)\n"
           "  --from sections          derive bytes from named sections\n"
           "\n"
           "SELECTION\n"
           "  --segment PT_LOAD        select a segment kind/name (may repeat)\n"
           "  --only-section NAME      restrict selection to NAME (may repeat)\n"
           "  --remove-section NAME    drop NAME from the selection (may "
           "repeat)\n"
           "  --section NAME           ordered section for --format sections "
           "(may repeat)\n"
           "\n"
           "ADDRESSING\n"
           "  --addr vaddr|paddr|lma   address field used for layout "
           "(default: vaddr)\n"
           "  --base ADDR              output offset 0 corresponds to ADDR\n"
           "  --bias N                 add signed bias to selected addresses\n"
           "\n"
           "LAYOUT\n"
           "  --fill BYTE              byte used for holes/padding (default: 0)\n"
           "  --fail-on-holes          reject gaps between selected ranges\n"
           "  --max-hole SIZE          reject any gap larger than SIZE\n"
           "  --align SIZE             pad final size up to SIZE\n"
           "  --pad-to SIZE            pad final size to SIZE\n"
           "  --max-size SIZE          reject output larger than SIZE\n"
           "\n"
           "KERNEL IMAGE HEADER (bin/rom; preserves the entry branch, fills the\n"
           "metadata tail — the first segment must reserve a 64-byte header)\n"
           "  --image-header[=arm64|riscv|auto]  synthesize a flat-kernel "
           "Image header\n"
           "  --image-text-offset N    header text_offset field (default: 0)\n"
           "  --image-endian little|big header endianness flag (default: "
           "little)\n"
           "  --image-page-size 4k|16k|64k  arm64 page-size flag (default: "
           "unspecified)\n"
           "\n"
           "VALIDATION\n"
           "  --require-entry          fail unless the image declares an "
           "entry\n"
           "  --require-symbol NAME    fail unless NAME is defined (may "
           "repeat)\n"
           "  --require-section NAME   fail unless NAME is present (may "
           "repeat)\n"
           "  --no-dynamic             reject dynamic-linking artifacts\n"
           "\n"
           "REPORTING\n"
           "  --metadata FILE          write a deterministic JSON sidecar\n"
           "\n"
           "OUTPUT\n"
           "  -o, --output FILE        write output to FILE (default: stdout)\n"
           "\n"
           "SIZE suffixes K, M, and G are accepted.\n"
           "\n"
           "TEXT-FORMAT ADDRESS LIMITS\n"
           "  IHEX/SREC records require adjusted addresses that fit their\n"
           "  32-bit range. Native linked images can start above that range.\n"
           "  --base changes flat-output placement and is rejected for IHEX/\n"
           "  SREC. Use an explicit signed --bias to adjust every record and\n"
           "  entry address; every adjusted address must fit in 32 bits.\n"
           "\n"
           "GETTING HELP\n"
           "  -h, --help              Show this help and exit\n"
           "\n"
           "EXAMPLES\n"
           "  # Build a minimal aarch64 freestanding linked image.\n"
           "  printf '.global _start\\n.text\\n_start:\\n  b _start\\n' > start.s\n"
           "  printf 'ENTRY(_start)\\nSECTIONS { . = 0x400000; .text : { "
           "*(.text*) } }\\n' > link.ld\n"
           "  kit as -target aarch64-none-elf -o start.o start.s\n"
           "  kit ld -T link.ld \\\n"
           "    -e _start -o kernel.elf start.o\n"
           "  kit image --format bin --require-entry \\\n"
           "    --require-symbol _start --require-section .text \\\n"
           "    --metadata kernel.json kernel.elf -o kernel.bin\n"
           "  kit size kernel.elf\n"
           "  # A high-address IHEX image needs an explicit representable bias.\n"
           "  printf 'ENTRY(_start)\\nSECTIONS { . = 0x100000000; .text : "
           "{ *(.text*) } }\\n' > high.ld\n"
           "  kit ld -T high.ld \\\n"
           "    -e _start -o high.elf start.o\n"
           "  kit image --format ihex --bias -4294967296 \\\n"
           "    high.elf -o high.hex\n"
           "\n"
           "EXIT CODES\n"
           "  0   success           1   image/I/O error           2   bad "
           "usage\n")));
 }
 
 static int take_value(int* i, int argc, char** argv, const char* flag,
                       const char** out) {
   const char* a = argv[*i];
   size_t flen = kit_slice_cstr(flag).len;
   if (driver_strneq(a, flag, flen) && a[flen] == '=') {
     *out = a + flen + 1;
     return 1;
   }
   if (driver_streq(a, flag)) {
     if (*i + 1 >= argc) return -1;
     *out = argv[++(*i)];
     return 1;
   }
   return 0;
 }
 
 static int digit_value(char c) {
   if (c >= '0' && c <= '9') return c - '0';
   if (c >= 'a' && c <= 'f') return 10 + c - 'a';
   if (c >= 'A' && c <= 'F') return 10 + c - 'A';
   return -1;
 }
 
 static int parse_size(const char* s, uint64_t* out) {
   size_t len;
   size_t end;
   size_t pos = 0;
   uint64_t val = 0;
   uint64_t mult = 1;
   int base = 10;
 
   if (!s || !s[0] || !out) return -1;
   len = driver_strlen(s);
   end = len;
   switch (s[end - 1]) {
     case 'k':
     case 'K':
       mult = 1024ull;
       --end;
       break;
     case 'm':
     case 'M':
       mult = 1024ull * 1024ull;
       --end;
       break;
     case 'g':
     case 'G':
       mult = 1024ull * 1024ull * 1024ull;
       --end;
       break;
     default:
       break;
   }
   if (end == 0) return -1;
   if (end >= 2 && s[0] == '0' && (s[1] == 'x' || s[1] == 'X')) {
     base = 16;
     pos = 2;
     if (pos >= end) return -1;
   }
   for (; pos < end; ++pos) {
     int d = digit_value(s[pos]);
     if (d < 0 || d >= base) return -1;
     if (val > (UINT64_MAX - (uint64_t)d) / (uint64_t)base) return -1;
     val = val * (uint64_t)base + (uint64_t)d;
   }
   if (val > UINT64_MAX / mult) return -1;
   *out = val * mult;
   return 0;
 }
 
 static int parse_i64_size(const char* s, int64_t* out) {
   int neg = 0;
   uint64_t mag;
   uint64_t min_mag = (uint64_t)INT64_MAX + 1u;
   if (!s || !s[0] || !out) return -1;
   if (s[0] == '-' || s[0] == '+') {
     neg = s[0] == '-';
     ++s;
   }
   if (!s[0] || parse_size(s, &mag) != 0) return -1;
   if (neg) {
     if (mag > min_mag) return -1;
     if (mag == min_mag) {
       *out = INT64_MIN;
     } else {
       *out = -(int64_t)mag;
     }
   } else {
     if (mag > (uint64_t)INT64_MAX) return -1;
     *out = (int64_t)mag;
   }
   return 0;
 }
 
 static int parse_format(const char* s, uint32_t* out) {
   if (driver_streq(s, "bin") || driver_streq(s, "binary")) {
     *out = KIT_IMAGE_FORMAT_BIN;
     return 0;
   }
   if (driver_streq(s, "rom")) {
     *out = KIT_IMAGE_FORMAT_ROM;
     return 0;
   }
   if (driver_streq(s, "sections")) {
     *out = KIT_IMAGE_FORMAT_SECTIONS;
     return 0;
   }
   if (driver_streq(s, "ihex") || driver_streq(s, "ihex8")) {
     *out = KIT_IMAGE_FORMAT_IHEX;
     return 0;
   }
   if (driver_streq(s, "srec") || driver_streq(s, "s19")) {
     *out = KIT_IMAGE_FORMAT_SREC;
     return 0;
   }
   if (driver_streq(s, "elf")) {
     *out = KIT_IMAGE_FORMAT_ELF;
     return 0;
   }
   return -1;
 }
 
 static int parse_from(const char* s, uint32_t* out) {
   if (driver_streq(s, "segments")) {
     *out = KIT_IMAGE_FROM_SEGMENTS;
     return 0;
   }
   if (driver_streq(s, "sections")) {
     *out = KIT_IMAGE_FROM_SECTIONS;
     return 0;
   }
   return -1;
 }
 
 static void image_unknown_value(const char* category, const char* value,
                                 const char* const* candidates,
                                 size_t candidate_count) {
   DriverSuggestion suggestions[3];
   size_t n = driver_suggest_values(value, candidates, candidate_count,
                                    suggestions, 3);
   if (n)
     driver_errf(IMAGE_TOOL, "unknown %s: %s; did you mean '%s'?", category,
                 value, suggestions[0].value);
   else
     driver_errf(IMAGE_TOOL, "unknown %s: %s", category, value);
 }
 
 static int parse_addr(const char* s, uint32_t* out) {
   if (driver_streq(s, "vaddr")) {
     *out = KIT_IMAGE_ADDR_VADDR;
     return 0;
   }
   if (driver_streq(s, "paddr")) {
     *out = KIT_IMAGE_ADDR_PADDR;
     return 0;
   }
   if (driver_streq(s, "lma")) {
     *out = KIT_IMAGE_ADDR_LMA;
     return 0;
   }
   return -1;
 }
 
 static int parse_image_header(const char* s, uint32_t* out) {
   if (driver_streq(s, "arm64") || driver_streq(s, "aarch64") ||
       driver_streq(s, "aa64")) {
     *out = KIT_IMAGE_HEADER_ARM64;
     return 0;
   }
   if (driver_streq(s, "riscv") || driver_streq(s, "riscv64") ||
       driver_streq(s, "rv64") || driver_streq(s, "riscv32") ||
       driver_streq(s, "rv32")) {
     *out = KIT_IMAGE_HEADER_RISCV;
     return 0;
   }
   if (driver_streq(s, "auto")) {
     *out = KIT_IMAGE_HEADER_AUTO;
     return 0;
   }
   return -1;
 }
 
 /* Append cstr `name` to a growable KitSlice list, re-aliasing the matching
  * KitImageOptions pointer at *aliased_ptr to the (possibly reallocated)
  * storage and bumping *count. */
 static int push_name(DriverEnv* env, KitSlice** arr, uint32_t* count,
                      uint32_t* cap, const KitSlice** aliased_ptr,
                      const char* name) {
   if (*count >= *cap) {
     uint32_t newcap = *cap ? *cap * 2u : 4u;
     KitSlice* next;
     if (newcap <= *cap) return -1;
     next = (KitSlice*)driver_alloc_zeroed(env, (size_t)newcap * sizeof(*next));
     if (!next) return -1;
     if (*arr) {
       memcpy(next, *arr, (size_t)(*count) * sizeof(*next));
       driver_free(env, *arr, (size_t)(*cap) * sizeof(**arr));
     }
     *arr = next;
     *cap = newcap;
     *aliased_ptr = next;
   }
   (*arr)[(*count)++] = kit_slice_cstr(name);
   return 0;
 }
 
 /* ---- metadata JSON sidecar ------------------------------------------------
  *
  * Deterministic: stable key order, no host paths, no timestamps. Values that
  * vary by input (target triple, entry, build id, ranges) are derived from the
  * opened object and the layout report.
  *
  * The driver has no public string-builder, so the document is assembled into a
  * small growable byte buffer with snprintf-backed appends, then written in one
  * shot. */
 
 typedef struct MetaBuf {
   DriverEnv* env;
   char* data;
   size_t len;
   size_t cap;
   int oom;
 } MetaBuf;
 
 static void meta_reserve(MetaBuf* mb, size_t extra) {
   size_t need = mb->len + extra + 1u; /* + NUL room for snprintf */
   if (mb->oom || need <= mb->cap) return;
   {
     size_t newcap = mb->cap ? mb->cap : 256u;
     char* next;
     while (newcap < need) {
       size_t doubled = newcap * 2u;
       if (doubled <= newcap) {
         mb->oom = 1;
         return;
       }
       newcap = doubled;
     }
     next = (char*)driver_alloc_zeroed(mb->env, newcap);
     if (!next) {
       mb->oom = 1;
       return;
     }
     if (mb->data) {
       memcpy(next, mb->data, mb->len);
       driver_free(mb->env, mb->data, mb->cap);
     }
     mb->data = next;
     mb->cap = newcap;
   }
 }
 
 static void meta_putc(MetaBuf* mb, char c) {
   meta_reserve(mb, 1);
   if (mb->oom) return;
   mb->data[mb->len++] = c;
 }
 
 static void meta_putf(MetaBuf* mb, const char* fmt, ...) {
   va_list ap, ap2;
   int n;
   va_start(ap, fmt);
   va_copy(ap2, ap);
   n = vsnprintf(NULL, 0, fmt, ap);
   va_end(ap);
   if (n < 0) {
     mb->oom = 1;
     va_end(ap2);
     return;
   }
   meta_reserve(mb, (size_t)n);
   if (mb->oom) {
     va_end(ap2);
     return;
   }
   vsnprintf(mb->data + mb->len, (size_t)n + 1u, fmt, ap2);
   va_end(ap2);
   mb->len += (size_t)n;
 }
 
 /* JSON-escape a section/segment name (quotes + minimal escaping). */
 static void meta_put_json_string(MetaBuf* mb, KitSlice s) {
   size_t i;
   meta_putc(mb, '"');
   for (i = 0; i < s.len; ++i) {
     char c = s.s[i];
     if (c == '"' || c == '\\') {
       meta_putc(mb, '\\');
       meta_putc(mb, c);
     } else if ((unsigned char)c < 0x20) {
       meta_putf(mb, "\\u%04x", (unsigned)(unsigned char)c);
     } else {
       meta_putc(mb, c);
     }
   }
   meta_putc(mb, '"');
 }
 
 /* Locate and parse a `.note.gnu.build-id` ELF note's descriptor bytes. Returns
  * the descriptor slice (borrowed from the object) or an empty slice. */
 static KitSlice read_build_id(KitObjFile* of) {
   KitObjSection sid = KIT_SECTION_NONE;
   const uint8_t* data = NULL;
   size_t len = 0;
   uint32_t namesz, descsz;
   size_t off;
   KitSlice empty = KIT_SLICE_NULL;
 
   if (kit_obj_section_by_name(of, kit_slice_cstr(".note.gnu.build-id"), &sid) !=
           KIT_OK ||
       sid == KIT_SECTION_NONE)
     return empty;
   if (kit_obj_section_data(of, sid, &data, &len) != KIT_OK || !data || len < 12)
     return empty;
   /* ELF note: u32 namesz, u32 descsz, u32 type, name[namesz], desc[descsz].
    * Little-endian (the only endianness kit links). */
   namesz = (uint32_t)data[0] | ((uint32_t)data[1] << 8) |
            ((uint32_t)data[2] << 16) | ((uint32_t)data[3] << 24);
   descsz = (uint32_t)data[4] | ((uint32_t)data[5] << 8) |
            ((uint32_t)data[6] << 16) | ((uint32_t)data[7] << 24);
   off = 12u + ((namesz + 3u) & ~3u);
   if (off > len || descsz > len - off) return empty;
   {
     KitSlice s;
     s.s = (const char*)data + off;
     s.len = descsz;
     return s;
   }
 }
 
 /* Emit the JSON list of selected segments/sections that contributed bytes.
  * For the section path this is the declared --section order; for the segment
  * path it is the loadable segments the layout selected — mirroring the
  * emitter's default-ELF-PT_LOAD / explicit-list policy plus only/remove
  * filters, so the sidecar reflects exactly what the image contains. */
 static int image_name_in_list(KitSlice name, const KitSlice* list, uint32_t n) {
   uint32_t i;
   for (i = 0; i < n; ++i) {
     if (name.len == list[i].len &&
         (name.len == 0 || memcmp(name.s, list[i].s, name.len) == 0))
       return 1;
   }
   return 0;
 }
 
 static int meta_section_selected(const KitObjSecInfo* sec,
                                  const KitImageOptions* opts) {
   if (!(sec->flags & KIT_SF_ALLOC) || sec->kind == KIT_SEC_BSS ||
       sec->size == 0)
     return 0;
   if (opts->nonly_sections &&
       !image_name_in_list(sec->name, opts->only_sections,
                           opts->nonly_sections))
     return 0;
   if (opts->nremove_sections &&
       image_name_in_list(sec->name, opts->remove_sections,
                          opts->nremove_sections))
     return 0;
   return 1;
 }
 
 static void meta_put_selection(MetaBuf* mb, KitObjFile* of,
                                const ImageCliOpts* o,
                                const KitImageReport* report) {
   uint32_t i;
   int first = 1;
   if (report->sections_concat) {
     for (i = 0; i < o->image.nsection_order; ++i) {
       if (!first) meta_putc(mb, ',');
       first = 0;
       meta_put_json_string(mb, o->image.section_order[i]);
     }
     return;
   }
   if (report->section_ranges) {
     uint32_t nsections = kit_obj_nsections(of);
     for (i = 0; i < nsections; ++i) {
       KitObjSecInfo sec;
       if (kit_obj_section(of, i, &sec) != KIT_OK ||
           !meta_section_selected(&sec, &o->image))
         continue;
       if (!first) meta_putc(mb, ',');
       first = 0;
       meta_put_json_string(mb, sec.name);
     }
     return;
   }
   {
     KitObjSegIter* it = NULL;
     KitObjSegInfo seg;
     KitObjFmt fmt = kit_obj_fmt(of);
     if (kit_obj_segiter_new(of, &it) != KIT_OK) return;
     while (kit_obj_segiter_next(it, &seg) == KIT_ITER_ITEM) {
       /* Defer to the emitter's own selection predicate so the sidecar lists
        * exactly the segments that contributed bytes — matching its PT_/case
        * folding and only/remove/default-PT_LOAD policy rather than a divergent
        * exact-byte reimplementation. */
       if (!kit_image_segment_selected(fmt, &seg, &o->image)) continue;
       if (!first) meta_putc(mb, ',');
       first = 0;
       if (seg.name.len)
         meta_put_json_string(mb, seg.name);
       else
         meta_put_json_string(mb, kit_slice_cstr("PT_LOAD"));
     }
     kit_obj_segiter_free(it);
   }
 }
 
 static const char* image_format_name(uint32_t format) {
   switch ((KitImageFormat)format) {
     case KIT_IMAGE_FORMAT_ROM:
       return "rom";
     case KIT_IMAGE_FORMAT_SECTIONS:
       return "sections";
     case KIT_IMAGE_FORMAT_ELF:
       return "elf";
     case KIT_IMAGE_FORMAT_IHEX:
       return "ihex";
     case KIT_IMAGE_FORMAT_SREC:
       return "srec";
     case KIT_IMAGE_FORMAT_BIN:
     default:
       return "bin";
   }
 }
 
 static int write_metadata(DriverEnv* env, const KitContext* ctx, KitObjFile* of,
                           const ImageCliOpts* o, const KitImageReport* report,
                           const char* path) {
   MetaBuf mb;
   KitTargetSpec spec;
   char triple[128];
   KitSlice build_id;
   int from_sections;
   KitWriter* w = NULL;
   int rc = 0;
 
   memset(&mb, 0, sizeof mb);
   mb.env = env;
 
   spec = kit_obj_target(of);
   if (driver_target_to_triple(spec, triple, sizeof triple) != 0)
     triple[0] = '\0';
   build_id = read_build_id(of);
   from_sections = report->sections_concat || report->section_ranges;
 
   /* Keys are emitted in a fixed order so the sidecar is byte-stable. */
   meta_putf(&mb, "{\n");
   meta_putf(&mb, "  \"format\": \"%s\",\n",
             image_format_name(o->image.format));
   meta_putf(&mb, "  \"source\": \"%s\",\n",
             from_sections ? "sections" : "segments");
   meta_putf(&mb, "  \"target\": \"%s\",\n", triple);
   meta_putf(&mb, "  \"object_format\": \"%s\",\n",
             kit_obj_fmt_name(kit_obj_fmt(of)));
   if (report->has_entry)
     meta_putf(&mb, "  \"entry\": \"0x%llx\",\n",
               (unsigned long long)report->emitted_entry);
   else
     meta_putf(&mb, "  \"entry\": null,\n");
   if (build_id.len) {
     size_t k;
     meta_putf(&mb, "  \"build_id\": \"");
     for (k = 0; k < build_id.len; ++k)
       meta_putf(&mb, "%02x", (unsigned)(unsigned char)build_id.s[k]);
     meta_putf(&mb, "\",\n");
   } else {
     meta_putf(&mb, "  \"build_id\": null,\n");
   }
 
   meta_putf(&mb, "  \"selection\": [");
   meta_put_selection(&mb, of, o, report);
   meta_putf(&mb, "],\n");
 
   meta_putf(&mb, "  \"addr_kind\": \"%s\",\n",
             o->image.addr == KIT_IMAGE_ADDR_PADDR ? "paddr"
             : o->image.addr == KIT_IMAGE_ADDR_LMA ? "lma"
                                                   : "vaddr");
   meta_putf(&mb, "  \"base\": \"0x%llx\",\n",
             (unsigned long long)report->base);
   meta_putf(&mb, "  \"original_base\": \"0x%llx\",\n",
             (unsigned long long)report->original_base);
   meta_putf(&mb, "  \"emitted_base\": \"0x%llx\",\n",
             (unsigned long long)report->emitted_base);
   if (report->has_entry) {
     meta_putf(&mb, "  \"original_entry\": \"0x%llx\",\n",
               (unsigned long long)report->original_entry);
     meta_putf(&mb, "  \"emitted_entry\": \"0x%llx\",\n",
               (unsigned long long)report->emitted_entry);
   } else {
     meta_putf(&mb, "  \"original_entry\": null,\n");
     meta_putf(&mb, "  \"emitted_entry\": null,\n");
   }
   meta_putf(&mb, "  \"base_is_load_address\": %s,\n",
             report->base_is_load_address ? "true" : "false");
   meta_putf(&mb, "  \"bias\": %lld,\n", (long long)o->image.bias);
   meta_putf(&mb, "  \"fill\": \"0x%02x\",\n", (unsigned)o->image.fill);
   meta_putf(&mb, "  \"payload_size\": %llu,\n",
             (unsigned long long)report->payload_size);
   meta_putf(&mb, "  \"output_size\": %llu,\n",
             (unsigned long long)report->size);
   if (report->image_header != KIT_IMAGE_HEADER_NONE) {
     meta_putf(&mb, "  \"image_header\": \"%s\",\n",
               report->image_header == KIT_IMAGE_HEADER_RISCV ? "riscv"
                                                              : "arm64");
     meta_putf(&mb, "  \"image_size\": %llu,\n",
               (unsigned long long)report->mem_size);
   }
   meta_putf(&mb, "  \"ranges\": %u,\n", (unsigned)report->nranges);
   meta_putf(&mb, "  \"max_hole\": %llu,\n",
             (unsigned long long)report->max_hole);
   meta_putf(&mb, "  \"warnings\": [");
   if (report->had_holes) meta_putf(&mb, "\"holes_present\"");
   meta_putf(&mb, "]\n");
   meta_putf(&mb, "}\n");
 
   if (mb.oom) {
     driver_errf(IMAGE_TOOL, "out of memory building metadata");
     rc = 1;
     goto done;
   }
   if (ctx->file_io->open_writer(ctx->file_io->user, path, &w) != KIT_OK) {
     driver_errf(IMAGE_TOOL, "failed to open metadata file: %s", path);
     rc = 1;
     goto done;
   }
   if (kit_writer_write(w, mb.data, mb.len) != KIT_OK ||
       kit_writer_status(w) != KIT_OK) {
     driver_writer_abort(w);
     driver_errf(IMAGE_TOOL, "failed to write metadata file: %s", path);
     rc = 1;
   }
 
 done:
   if (w) kit_writer_close(w);
   if (mb.data) driver_free(env, mb.data, mb.cap);
   return rc;
 }
 
 int driver_image(int argc, char** argv) {
   DriverEnv env;
   KitContext ctx;
   ImageCliOpts o;
   DriverLoad load = {0};
   KitSlice input = KIT_SLICE_NULL;
   KitObjFile* of = NULL;
   KitWriter* out = NULL;
   KitImageReport report;
   int own_writer = 0;
   int rc = 2;
   int i;
   int options = 1;
 
   if (argc < 2 || driver_argv_wants_help(argc, argv, 1)) {
     driver_help_image();
     return 0;
   }
 
   memset(&o, 0, sizeof o);
   memset(&report, 0, sizeof report);
   o.image.format = KIT_IMAGE_FORMAT_BIN;
   o.image.from = KIT_IMAGE_FROM_SEGMENTS;
   o.image.addr = KIT_IMAGE_ADDR_VADDR;
   o.image.fill = 0;
   driver_env_init(&env);
   ctx = driver_env_to_context(&env);
 
   for (i = 1; i < argc; ++i) {
     const char* a = argv[i];
     const char* val = NULL;
     int matched;
     if (options && driver_streq(a, "--")) {
       options = 0;
       continue;
     }
     if (!options) {
       if (o.input) {
         driver_errf(IMAGE_TOOL, "only one input may be given");
         goto done;
       }
       o.input = a;
       continue;
     }
     if (driver_streq(a, "-o")) {
       if (i + 1 >= argc) {
         driver_errf(IMAGE_TOOL, "%s requires a path", a);
         goto done;
       }
       o.output = argv[++i];
       continue;
     }
     matched = take_value(&i, argc, argv, "--output", &val);
     if (matched < 0) goto missing_value;
     if (matched) {
       o.output = val;
       continue;
     }
     matched = take_value(&i, argc, argv, "--format", &val);
     if (matched < 0) goto missing_value;
     if (matched) {
       if (parse_format(val, &o.image.format) != 0) {
         const char* const formats[] = {"bin",  "binary", "rom", "sections",
                                        "ihex", "ihex8",  "srec", "s19",
                                        "elf"};
         image_unknown_value("format", val, formats,
                             sizeof formats / sizeof formats[0]);
         goto done;
       }
       continue;
     }
     matched = take_value(&i, argc, argv, "--from", &val);
     if (matched < 0) goto missing_value;
     if (matched) {
       if (parse_from(val, &o.image.from) != 0) {
         const char* const sources[] = {"segments", "sections"};
         image_unknown_value("source", val, sources,
                             sizeof sources / sizeof sources[0]);
         goto done;
       }
       continue;
     }
     matched = take_value(&i, argc, argv, "--segment", &val);
     if (matched < 0) goto missing_value;
     if (matched) {
       if (push_name(&env, &o.segments, &o.image.nsegments, &o.cap_segments,
                     &o.image.segments, val) != 0)
         goto oom;
       continue;
     }
     matched = take_value(&i, argc, argv, "--only-section", &val);
     if (matched < 0) goto missing_value;
     if (matched) {
       if (push_name(&env, &o.only_sections, &o.image.nonly_sections,
                     &o.cap_only, &o.image.only_sections, val) != 0)
         goto oom;
       continue;
     }
     matched = take_value(&i, argc, argv, "--remove-section", &val);
     if (matched < 0) goto missing_value;
     if (matched) {
       if (push_name(&env, &o.remove_sections, &o.image.nremove_sections,
                     &o.cap_remove, &o.image.remove_sections, val) != 0)
         goto oom;
       continue;
     }
     matched = take_value(&i, argc, argv, "--section", &val);
     if (matched < 0) goto missing_value;
     if (matched) {
       if (push_name(&env, &o.section_order, &o.image.nsection_order,
                     &o.cap_section_order, &o.image.section_order, val) != 0)
         goto oom;
       continue;
     }
     matched = take_value(&i, argc, argv, "--require-symbol", &val);
     if (matched < 0) goto missing_value;
     if (matched) {
       if (push_name(&env, &o.require_symbols, &o.image.nrequire_symbols,
                     &o.cap_require_symbols, &o.image.require_symbols, val) != 0)
         goto oom;
       continue;
     }
     matched = take_value(&i, argc, argv, "--require-section", &val);
     if (matched < 0) goto missing_value;
     if (matched) {
       if (push_name(&env, &o.require_sections, &o.image.nrequire_sections,
                     &o.cap_require_sections, &o.image.require_sections, val) !=
           0)
         goto oom;
       continue;
     }
     if (driver_streq(a, "--require-entry")) {
       o.image.require_entry = true;
       continue;
     }
     if (driver_streq(a, "--no-dynamic")) {
       o.image.no_dynamic = true;
       continue;
     }
     if (driver_streq(a, "--strip-debug")) {
       o.strip_debug = true;
       continue;
     }
     if (driver_streq(a, "--keep-symbols")) {
       o.keep_symbols = true;
       continue;
     }
     matched = take_value(&i, argc, argv, "--split-debug", &val);
     if (matched < 0) goto missing_value;
     if (matched) {
       o.split_debug = val;
       continue;
     }
     matched = take_value(&i, argc, argv, "--metadata", &val);
     if (matched < 0) goto missing_value;
     if (matched) {
       o.metadata = val;
       continue;
     }
     matched = take_value(&i, argc, argv, "--addr", &val);
     if (matched < 0) goto missing_value;
     if (matched) {
       if (parse_addr(val, &o.image.addr) != 0) {
         driver_errf(IMAGE_TOOL, "unknown address kind: %s", val);
         goto done;
       }
       continue;
     }
     matched = take_value(&i, argc, argv, "--base", &val);
     if (matched < 0) goto missing_value;
     if (matched) {
       if (parse_size(val, &o.image.base) != 0) {
         driver_errf(IMAGE_TOOL, "invalid --base value: %s", val);
         goto done;
       }
       o.image.have_base = true;
       continue;
     }
     matched = take_value(&i, argc, argv, "--bias", &val);
     if (matched < 0) goto missing_value;
     if (matched) {
       if (parse_i64_size(val, &o.image.bias) != 0) {
         driver_errf(IMAGE_TOOL, "invalid --bias value: %s", val);
         goto done;
       }
       continue;
     }
     matched = take_value(&i, argc, argv, "--fill", &val);
     if (matched < 0) goto missing_value;
     if (matched) {
       uint64_t fill;
       if (parse_size(val, &fill) != 0 || fill > 255u) {
         driver_errf(IMAGE_TOOL, "invalid --fill byte: %s", val);
         goto done;
       }
       o.image.fill = (uint8_t)fill;
       continue;
     }
     if (driver_streq(a, "--fail-on-holes")) {
       o.image.fail_on_holes = true;
       continue;
     }
     matched = take_value(&i, argc, argv, "--max-hole", &val);
     if (matched < 0) goto missing_value;
     if (matched) {
       if (parse_size(val, &o.image.max_hole) != 0) {
         driver_errf(IMAGE_TOOL, "invalid --max-hole value: %s", val);
         goto done;
       }
       o.image.have_max_hole = true;
       continue;
     }
     matched = take_value(&i, argc, argv, "--align", &val);
     if (matched < 0) goto missing_value;
     if (matched) {
       if (parse_size(val, &o.image.align) != 0 || o.image.align == 0) {
         driver_errf(IMAGE_TOOL, "invalid --align value: %s", val);
         goto done;
       }
       o.image.have_align = true;
       continue;
     }
     matched = take_value(&i, argc, argv, "--pad-to", &val);
     if (matched < 0) goto missing_value;
     if (matched) {
       if (parse_size(val, &o.image.pad_to) != 0) {
         driver_errf(IMAGE_TOOL, "invalid --pad-to value: %s", val);
         goto done;
       }
       o.image.have_pad_to = true;
       continue;
     }
     matched = take_value(&i, argc, argv, "--max-size", &val);
     if (matched < 0) goto missing_value;
     if (matched) {
       if (parse_size(val, &o.image.max_size) != 0) {
         driver_errf(IMAGE_TOOL, "invalid --max-size value: %s", val);
         goto done;
       }
       o.image.have_max_size = true;
       continue;
     }
     /* Bare --image-header infers the arch from the object; --image-header=VALUE
      * names it. The space form is intentionally not accepted so a following
      * input path is never mistaken for the value. */
     if (driver_streq(a, "--image-header")) {
       o.image.image_header = KIT_IMAGE_HEADER_AUTO;
       continue;
     }
     if (driver_strneq(a, "--image-header=", 15)) {
       if (parse_image_header(a + 15, &o.image.image_header) != 0) {
         driver_errf(IMAGE_TOOL, "unknown image header: %s", a + 15);
         goto done;
       }
       continue;
     }
     matched = take_value(&i, argc, argv, "--image-text-offset", &val);
     if (matched < 0) goto missing_value;
     if (matched) {
       if (parse_size(val, &o.image.image_text_offset) != 0) {
         driver_errf(IMAGE_TOOL, "invalid --image-text-offset value: %s", val);
         goto done;
       }
       o.image.have_image_text_offset = true;
       continue;
     }
     matched = take_value(&i, argc, argv, "--image-endian", &val);
     if (matched < 0) goto missing_value;
     if (matched) {
       if (driver_streq(val, "little") || driver_streq(val, "le")) {
         o.image.image_big_endian = false;
       } else if (driver_streq(val, "big") || driver_streq(val, "be")) {
         o.image.image_big_endian = true;
       } else {
         driver_errf(IMAGE_TOOL, "invalid --image-endian value: %s", val);
         goto done;
       }
       continue;
     }
     matched = take_value(&i, argc, argv, "--image-page-size", &val);
     if (matched < 0) goto missing_value;
     if (matched) {
       uint64_t bytes;
       if (parse_size(val, &bytes) != 0) {
         driver_errf(IMAGE_TOOL, "invalid --image-page-size value: %s", val);
         goto done;
       }
       if (bytes == 4096u)
         o.image.image_page_size_kib = 4;
       else if (bytes == 16384u)
         o.image.image_page_size_kib = 16;
       else if (bytes == 65536u)
         o.image.image_page_size_kib = 64;
       else {
         driver_errf(IMAGE_TOOL, "--image-page-size must be 4k, 16k, or 64k");
         goto done;
       }
       continue;
     }
     if (a[0] == '-' && a[1] != '\0') {
       const char* const options[] = {
           "-o",                "--output",          "--format",
           "--from",            "--segment",         "--only-section",
           "--section",         "--remove-section",  "--addr",
           "--base",            "--bias",            "--fill",
           "--pad-to",          "--max-size",        "--metadata",
           "--require-entry",   "--require-symbol",  "--require-section",
           "--no-dynamic",      "--image-header",    "--image-load-offset",
           "--image-page-size", "--split-debug",     "--keep-symbols",
           "--strip-debug",     "-h",                "--help",
           "--version",
       };
       DriverSuggestion suggestions[3];
       size_t n = driver_suggest_values(a, options,
                                        sizeof options / sizeof options[0],
                                        suggestions, 3);
       if (n)
         driver_errf(IMAGE_TOOL, "unknown option: %s; did you mean '%s'?", a,
                     suggestions[0].value);
       else
         driver_errf(IMAGE_TOOL, "unknown option: %s", a);
       goto done;
     }
     if (o.input) {
       driver_errf(IMAGE_TOOL, "only one input may be given");
       goto done;
     }
     o.input = a;
   }
 
   if (!o.input) {
     driver_errf(IMAGE_TOOL, "missing input file");
     goto done;
   }
   if (o.split_debug || o.keep_symbols || o.strip_debug) {
     if (o.image.format != KIT_IMAGE_FORMAT_ELF) {
       driver_errf(IMAGE_TOOL,
                   "--strip-debug/--split-debug/--keep-symbols are only "
                   "meaningful with --format elf");
       goto done;
     }
   }
   if (o.image.image_header == KIT_IMAGE_HEADER_NONE &&
       (o.image.have_image_text_offset || o.image.image_big_endian ||
        o.image.image_page_size_kib)) {
     driver_errf(IMAGE_TOOL,
                 "--image-text-offset/--image-endian/--image-page-size require "
                 "--image-header");
     goto done;
   }
   if (o.image.have_base &&
       (o.image.format == KIT_IMAGE_FORMAT_IHEX ||
        o.image.format == KIT_IMAGE_FORMAT_SREC)) {
     driver_errf(IMAGE_TOOL,
                 "--base is only valid for flat output; use --bias to rebase "
                 "IHEX/SREC addresses");
     goto done;
   }
 
   if (driver_load_bytes(&env.file_io, IMAGE_TOOL, o.input, &load, &input) != 0) {
     rc = 1;
     goto done;
   }
 
   if (kit_obj_open(&ctx, kit_slice_cstr(o.input), &input, &of) != KIT_OK) {
     driver_errf(IMAGE_TOOL, "%s is not a recognized object or linked image",
                 o.input);
     rc = 1;
     goto done;
   }
 
   if (o.output) {
     if (ctx.file_io->open_writer(ctx.file_io->user, o.output, &out) != KIT_OK) {
       driver_errf(IMAGE_TOOL, "failed to open output: %s", o.output);
       rc = 1;
       goto done;
     }
   } else {
     out = driver_stdout_writer(&env);
     if (!out) goto oom;
   }
   own_writer = 1;
 
   if (kit_image_emit(&ctx, of, &input, &o.image, out, &report) != KIT_OK) {
     driver_writer_abort(out);
     rc = 1;
     goto done;
   }
   /* Close the image writer before writing the sidecar so the image bytes are
    * flushed and the metadata reflects a complete output. */
   if (own_writer && out) {
     kit_writer_close(out);
     out = NULL;
     own_writer = 0;
   }
   rc = 0;
 
   if (o.metadata) {
     if (write_metadata(&env, &ctx, of, &o, &report, o.metadata) != 0) {
       rc = 1;
       goto done;
     }
   }
 
 done:
   if (own_writer && out) kit_writer_close(out);
   if (of) kit_obj_free(of);
   driver_release_bytes(&env.file_io, &load);
   if (o.segments)
     driver_free(&env, o.segments, (size_t)o.cap_segments * sizeof(*o.segments));
   if (o.only_sections)
     driver_free(&env, o.only_sections,
                 (size_t)o.cap_only * sizeof(*o.only_sections));
   if (o.remove_sections)
     driver_free(&env, o.remove_sections,
                 (size_t)o.cap_remove * sizeof(*o.remove_sections));
   if (o.section_order)
     driver_free(&env, o.section_order,
                 (size_t)o.cap_section_order * sizeof(*o.section_order));
   if (o.require_symbols)
     driver_free(&env, o.require_symbols,
                 (size_t)o.cap_require_symbols * sizeof(*o.require_symbols));
   if (o.require_sections)
     driver_free(&env, o.require_sections,
                 (size_t)o.cap_require_sections * sizeof(*o.require_sections));
   driver_env_fini(&env);
   return rc;
 
 missing_value:
   driver_errf(IMAGE_TOOL, "%s requires a value", argv[i]);
   goto done;
 oom:
   driver_errf(IMAGE_TOOL, "out of memory");
   rc = 1;
   goto done;
 }