kit

emu.c (10532B)

---

 #include <kit/core.h>
 #include <kit/emu.h>
 #include <kit/object.h>
 #include <stddef.h>
 #include <stdint.h>
 #include <string.h>
 
 #include "driver.h"
 
 /* `kit emu` — run a guest user-mode executable on the host via libkit's
  * per-basic-block JIT translator.
  *
  * Argv shape mirrors `kit run`: a single positional input (the guest
  * executable path) followed by `--` and the guest argv. Flags configure the
  * translator (optimize level), tracing (PC / instruction / block), and
  * the guest arch (auto-detected when -arch is absent).
  *
  * The freestanding emu core takes guest bytes; this driver handles the
  * path -> bytes step and the argv/envp marshalling. The driver returns
  * the guest's exit code on a clean exit, or 1 on internal failure. */
 
 #define EMU_TOOL "emu"
 
 typedef struct EmuOptions {
   DriverEnv* env;
   size_t argv_bound;
 
   int opt_level;
   int interp; /* -interp: run translated blocks through the IR interpreter */
   KitEmuTraceFlags trace;
   KitArchKind guest_arch;
   int guest_arch_set;
   KitTargetSpec guest_target;
   int guest_target_set;
 
   const char* guest_path; /* positional input (required) */
 
   /* Guest argv collected after `--`. argv[0] defaults to guest_path
    * when the user supplied no `--` segment. The trailing NULL is
    * added at marshalling time and is not counted in nguest_argv. */
   const char** guest_argv;
   uint32_t nguest_argv;
 } EmuOptions;
 
 static void emu_usage(void) {
   driver_errf(EMU_TOOL, "%.*s",
               KIT_SLICE_ARG(KIT_SLICE_LIT(
                   "usage: kit emu [options] guest-exe [-- guest-arg...]\n"
                   "       kit emu --help    for full option reference")));
 }
 
 void driver_help_emu(void) {
   driver_printf(
       "%.*s",
       KIT_SLICE_ARG(KIT_SLICE_LIT(
           "kit emu — run a guest user-mode executable on the host\n"
           "\n"
           "USAGE\n"
           "  kit emu [options] guest-exe [-- guest-arg...]\n"
           "\n"
           "DESCRIPTION\n"
           "  Loads a static guest user-mode executable and runs it on the host "
           "via\n"
           "  the per-basic-block JIT translator. The host code generated by "
           "the\n"
           "  translator runs natively on the host arch.\n"
           "\n"
           "  The driver returns the guest's exit code on a clean exit, or 1 "
           "on\n"
           "  internal failure. Argv shape mirrors `kit run`: anything after\n"
           "  `--` is forwarded as the guest argv. With no `--`, argv[0] "
           "defaults\n"
           "  to the guest executable path.\n"
           "\n"
           "OPTIONS\n"
           "  -O0 -O1 -O2       Translator optimization level (default -O0)\n"
           "  -interp           Run translated blocks through the IR "
           "interpreter\n"
           "                    instead of JITing them (forces -O1)\n"
           "  -arch ARCH        Force guest arch: aarch64 (alias arm64) or\n"
           "                    riscv64 (alias rv64). When omitted the arch is\n"
           "                    auto-detected from the executable.\n"
           "  -tracepc          Trace each translated PC\n"
           "  -traceinsn        Trace each guest instruction\n"
           "  -traceblock       Trace each translated basic block\n"
           "  -h, --help        Show this help and exit\n"
           "\n"
           "EXAMPLES\n"
           "  kit emu hello\n"
           "  kit emu -arch riscv64 hello -- foo bar\n"
           "  kit emu -O2 -tracepc prog\n"
           "\n"
           "EXIT CODES\n"
           "  Returns the guest's exit code on clean exit, or 1 on internal\n"
           "  failure. 2 on bad command-line usage.\n")));
 }
 
 static int emu_alloc_arrays(EmuOptions* o, int argc) {
   size_t bound = (size_t)argc;
   o->argv_bound = bound;
   /* +1 to leave room for the guest_path default at index 0. */
   o->guest_argv =
       driver_alloc_zeroed(o->env, (bound + 1) * sizeof(*o->guest_argv));
   if (!o->guest_argv) {
     driver_errf(EMU_TOOL, "out of memory");
     return 1;
   }
   return 0;
 }
 
 static int emu_record_arch(EmuOptions* o, const char* val) {
   KitArchKind arch;
   /* Recognize arch names through the shared driver_arch_from_name table, then
    * restrict to the supported guest set so an unsupported (but otherwise
    * valid) arch still reports the same "unsupported -arch value" error. */
   if (driver_arch_from_name(val, &arch, NULL) == 0 &&
       (arch == KIT_ARCH_ARM_64 || arch == KIT_ARCH_RV64)) {
     o->guest_arch = arch;
     o->guest_arch_set = 1;
     return 0;
   }
   driver_errf(EMU_TOOL, "unsupported -arch value: %.*s",
               KIT_SLICE_ARG(kit_slice_cstr(val)));
   return 1;
 }
 
 static int emu_parse(int argc, char** argv, EmuOptions* o) {
   int i;
   int after_dash_dash = 0;
   if (emu_alloc_arrays(o, argc) != 0) return 1;
 
   for (i = 1; i < argc; ++i) {
     const char* a = argv[i];
 
     if (after_dash_dash) {
       o->guest_argv[o->nguest_argv++] = argv[i];
       continue;
     }
     if (driver_streq(a, "--")) {
       after_dash_dash = 1;
       continue;
     }
 
     if (driver_streq(a, "-O0")) {
       o->opt_level = 0;
       continue;
     }
     if (driver_streq(a, "-O1")) {
       o->opt_level = 1;
       continue;
     }
     if (driver_streq(a, "-O2")) {
       o->opt_level = 2;
       continue;
     }
 
     if (driver_streq(a, "-tracepc")) {
       o->trace |= KIT_EMU_TRACE_PC;
       continue;
     }
     if (driver_streq(a, "-traceinsn")) {
       o->trace |= KIT_EMU_TRACE_INSN;
       continue;
     }
     if (driver_streq(a, "-traceblock")) {
       o->trace |= KIT_EMU_TRACE_BLOCK;
       continue;
     }
 
     if (driver_streq(a, "-interp")) {
       o->interp = 1;
       continue;
     }
 
     if (driver_streq(a, "-arch")) {
       if (++i >= argc) {
         driver_errf(EMU_TOOL, "-arch requires an argument");
         return 1;
       }
       if (emu_record_arch(o, argv[i]) != 0) return 1;
       continue;
     }
 
     if (a[0] == '-' && a[1] != '\0') {
       driver_errf(EMU_TOOL, "unknown flag: %.*s",
                   KIT_SLICE_ARG(kit_slice_cstr(a)));
       return 1;
     }
 
     if (o->guest_path) {
       driver_errf(EMU_TOOL, "multiple guest executable inputs: %.*s, %.*s",
                   KIT_SLICE_ARG(kit_slice_cstr(o->guest_path)),
                   KIT_SLICE_ARG(kit_slice_cstr(a)));
       return 1;
     }
     o->guest_path = a;
   }
 
   if (!o->guest_path) {
     driver_errf(EMU_TOOL, "missing guest executable input");
     emu_usage();
     return 1;
   }
   return 0;
 }
 
 static void emu_options_release(EmuOptions* o) {
   size_t bound = o->argv_bound;
   if (o->guest_argv) {
     driver_free(o->env, o->guest_argv, (bound + 1) * sizeof(*o->guest_argv));
   }
 }
 
 static const char* emu_arch_name(KitArchKind a) {
   switch (a) {
     case KIT_ARCH_ARM_64:
       return "aarch64";
     case KIT_ARCH_RV64:
       return "riscv64";
     case KIT_ARCH_X86_64:
       return "x86_64";
     case KIT_ARCH_X86_32:
       return "x86";
     case KIT_ARCH_ARM_32:
       return "arm";
     case KIT_ARCH_RV32:
       return "riscv32";
     case KIT_ARCH_WASM:
       return "wasm";
   }
   return "?";
 }
 
 static int emu_resolve_target(EmuOptions* o, const KitSlice* input) {
   KitTargetSpec detected;
   if (kit_detect_target(input->data, input->len, &detected) != KIT_OK) {
     driver_errf(EMU_TOOL, "could not detect target from %.*s",
                 KIT_SLICE_ARG(kit_slice_cstr(o->guest_path)));
     return 1;
   }
   if (o->guest_arch_set) detected.arch = o->guest_arch;
   o->guest_target = detected;
   o->guest_target_set = 1;
   return 0;
 }
 
 /* Build a NULL-terminated argv for the guest. argv[0] defaults to the
  * guest executable path if the user supplied no `--` segment, matching Unix
  * convention. The returned array points into the caller-owned argv; the
  * trailing NULL slot lives in the EmuOptions back-store. */
 static void emu_finalize_argv(EmuOptions* o, const char*** out_argv) {
   if (o->nguest_argv == 0) {
     o->guest_argv[0] = o->guest_path;
     o->guest_argv[1] = 0;
   } else {
     o->guest_argv[o->nguest_argv] = 0;
   }
   *out_argv = (const char**)o->guest_argv;
 }
 
 int driver_emu(int argc, char** argv) {
   DriverEnv env;
   EmuOptions eo = {0};
   KitContext ctx;
   KitTarget* target = NULL;
   KitCompiler* compiler = NULL;
   DriverLoad guest_lf = {0};
   KitSlice guest_in;
   KitEmuOptions opts;
   KitJitHost jhost;
   const char** guest_argv;
   int exit_code = 0;
   int rc = 1;
 
   if (argc < 2 || driver_argv_wants_help(argc, argv, 1)) {
     driver_help_emu();
     return 0;
   }
 
   driver_env_init(&env);
   eo.env = &env;
 
   if (emu_parse(argc, argv, &eo) != 0) {
     emu_options_release(&eo);
     driver_env_fini(&env);
     return 2;
   }
 
   ctx = driver_env_to_context(&env);
   if (!ctx.file_io || !ctx.file_io->read_all) {
     driver_errf(EMU_TOOL, "host file I/O unavailable");
     goto out;
   }
 
   if (driver_load_bytes(ctx.file_io, EMU_TOOL, eo.guest_path, &guest_lf,
                         &guest_in) != 0) {
     goto out;
   }
 
   if (emu_resolve_target(&eo, &guest_in) != 0) goto out;
 
   /* The emu's host-side compiler runs at the host's native target —
    * the JIT image holds host code, while the guest target is resolved
    * from the executable and optional driver flags. */
   {
     KitTargetOptions topts;
     memset(&topts, 0, sizeof topts);
     topts.spec = driver_host_target();
     if (kit_target_new(&ctx, &topts, &target) != KIT_OK ||
         driver_compiler_new(target, &ctx, &compiler) != KIT_OK) {
       driver_errf(EMU_TOOL, "failed to initialize compiler");
       goto out;
     }
   }
 
   emu_finalize_argv(&eo, &guest_argv);
   jhost = driver_env_to_jit_host(&env);
 
   {
     KitEmuOptions z = {0};
     opts = z;
   }
   opts.guest_name = kit_slice_cstr(eo.guest_path);
   opts.guest_bytes = guest_in;
   opts.guest_target = eo.guest_target;
   opts.has_guest_target = eo.guest_target_set != 0;
   opts.jit_host = &jhost;
   opts.optimize = eo.opt_level;
   opts.mode = eo.interp ? KIT_EMU_MODE_INTERP : KIT_EMU_MODE_JIT;
   opts.trace = eo.trace;
   opts.argv = (const char* const*)guest_argv;
   opts.envp = 0;
 
   if (kit_emu_run(compiler, &opts, &exit_code) != KIT_OK) {
     driver_errf(
         EMU_TOOL, "emulation of %.*s (%.*s) failed",
         KIT_SLICE_ARG(kit_slice_cstr(eo.guest_path)),
         KIT_SLICE_ARG(kit_slice_cstr(emu_arch_name(eo.guest_target.arch))));
     goto out;
   }
 
   rc = exit_code;
 
 out:
   if (compiler) driver_compiler_free(compiler);
   kit_target_free(target);
   if (guest_lf.loaded && ctx.file_io)
     driver_release_bytes(ctx.file_io, &guest_lf);
   emu_options_release(&eo);
   driver_env_fini(&env);
   return rc;
 }