kit

symbolize.c (7144B)

---

 #include <kit/core.h>
 #include <stddef.h>
 #include <stdint.h>
 #include <string.h>
 
 #include "driver.h"
 #include "dwarfsym.h"
 
 /* kit symbolize — annotate a __kit_print_backtrace stream in place.
  *
  * Where `addr2line` is a faithful clone of the GNU/LLVM "addresses in,
  * file:line out" contract, `symbolize` matches kit's actual backtrace
  * artifact: it reads the raw "#N 0x<hex>" lines that __kit_print_backtrace
  * writes (rt/lib/stack/print_backtrace.c), finds the address on each line,
  * resolves it through the same DWARF reader (kit_dwarf_func_at +
  * kit_dwarf_addr_to_line, via driver/lib/dwarfsym), and rewrites the line as
  *
  *     #0 0x401136 bt_leaf at addr2line_prog.c:51:3
  *
  * preserving the original "#N" framing that addr2line structurally can't keep.
  * Lines with no recognizable 0x<hex> token pass through verbatim, so a mixed
  * log (banner + frames) survives unharmed. See doc/plan/BACKTRACE.md (WS5). */
 
 #define SYM_TOOL "symbolize"
 
 typedef struct SymOpts {
   const char* exe_path;
   int basenames; /* --basenames */
 } SymOpts;
 
 /* Find the first "0x"/"0X"-prefixed hex run in [s, s+len) and decode it.
  * Returns 1 and stores the value in *out when a token with at least one hex
  * digit is found, else 0. Works on a non-NUL-terminated span (the line is a
  * slice of the stdin buffer), so it never reads past `len`. */
 static int sym_line_addr(const char* s, size_t len, uint64_t* out) {
   size_t i;
   for (i = 0; i + 1 < len; ++i) {
     if (s[i] == '0' && (s[i + 1] == 'x' || s[i + 1] == 'X')) {
       uint64_t v = 0;
       size_t j = i + 2;
       int any = 0;
       for (; j < len; ++j) {
         char c = s[j];
         int d;
         if (c >= '0' && c <= '9')
           d = c - '0';
         else if (c >= 'a' && c <= 'f')
           d = c - 'a' + 10;
         else if (c >= 'A' && c <= 'F')
           d = c - 'A' + 10;
         else
           break;
         v = (v << 4) | (uint64_t)d;
         any = 1;
       }
       if (any) {
         *out = v;
         return 1;
       }
     }
   }
   return 0;
 }
 
 /* Print " <func> at <file>:<line>[:<col>]" for a resolved address, using the
  * "??" / "??:0" placeholders addr2line's pretty mode uses for the missing
  * halves. Mirrors a2l_translate's pretty path so the two tools render an
  * unresolved frame identically. */
 static void sym_emit_annotation(const KitDwarfResolve* loc,
                                 const SymOpts* opts) {
   driver_printf(" ");
   if (loc->have_func)
     driver_printf("%.*s at ", (int)loc->func.len, loc->func.s);
   else
     driver_printf("?? at ");
 
   if (loc->have_line) {
     const char* f = loc->file.s;
     if (opts->basenames) f = driver_basename(f);
     driver_printf("%s:%u", f, loc->line);
     if (loc->col) driver_printf(":%u", loc->col);
   } else {
     driver_printf("??:0");
   }
 }
 
 void driver_help_symbolize(void) {
   driver_printf(
       "%.*s",
       KIT_SLICE_ARG(KIT_SLICE_LIT(
           "kit symbolize — annotate a kit backtrace stream with func at "
           "file:line\n"
           "\n"
           "USAGE\n"
           "  <prog that prints a backtrace> | kit symbolize -e FILE\n"
           "  kit symbolize -e FILE < backtrace.txt\n"
           "\n"
           "DESCRIPTION\n"
           "  Reads raw `#N 0x<hex>` backtrace lines as text on stdin, resolves\n"
           "  each address via FILE's debug info, and writes annotated text to\n"
           "  stdout in the form\n"
           "  #0 0x401136 bt_leaf at file.c:51:3\n"
           "  keeping the original \"#N\" framing. Lines with no 0x<hex> "
           "address "
           "pass\n"
           "  through unchanged. FILE is required for normal operation; with "
           "no\n"
           "-e this release prints help and returns 0.\n"
           "\n"
           "OPTIONS\n"
           "  -e FILE              object file with debug info (required)\n"
           "  --basenames          strip directory from file paths\n"
           "  -h, --help           show this help\n"
           "\n"
           "ADDRESS RESTRICTION\n"
           "  Input addresses must be link-time addresses. Static/non-PIE\n"
           "  runtime addresses already match. For PIE/ASLR, subtract the load\n"
           "  bias before producing the input; no load-bias option is exposed.\n"
           "\n"
           "EXAMPLES\n"
           "  # debug-app was linked with -g -no-pie.\n"
           "  kit nm -n debug-app\n"
           "  ADDR=$(kit nm -n debug-app | awk '$3 == \"main\" || "
           "$3 == \"_main\" { print $1; exit }')\n"
           "  printf '#0 0x%s\\nplain line\\n' \"$ADDR\" | \\\n"
           "    kit symbolize --basenames -e debug-app\n"
           "\n"
           "EXIT CODES\n"
           "  0   success (also no -e help exception)\n"
           "  1   debug/object or I/O error           2   bad usage\n")));
 }
 
 int driver_symbolize(int argc, char** argv) {
   DriverEnv env;
   SymOpts opts;
   DriverDwarfSym sym;
   uint8_t* data = NULL;
   size_t size = 0;
   int i, rc = 1, opened = 0;
   size_t pos;
 
   if (argc < 2 || driver_argv_wants_help(argc, argv, 1)) {
     driver_help_symbolize();
     return 0;
   }
 
   memset(&opts, 0, sizeof opts);
   driver_env_init(&env);
 
   for (i = 1; i < argc; ++i) {
     const char* a = argv[i];
     if (driver_streq(a, "-e")) {
       if (i + 1 >= argc) {
         driver_errf(SYM_TOOL, "-e requires a path");
         rc = 2;
         goto done;
       }
       opts.exe_path = argv[++i];
       continue;
     }
     if (driver_streq(a, "--basenames")) {
       opts.basenames = 1;
       continue;
     }
     if (a[0] == '-' && a[1] != '\0') {
       driver_errf(SYM_TOOL, "unknown option: %s", a);
       rc = 2;
       goto done;
     }
     driver_errf(SYM_TOOL, "unexpected argument: %s", a);
     rc = 2;
     goto done;
   }
 
   if (!opts.exe_path) {
     driver_errf(SYM_TOOL, "no object file specified (-e FILE)");
     rc = 2;
     goto done;
   }
 
   /* open() memsets `sym` before any fallible step, so once we are past this
    * point driver_dwarfsym_close is always safe — even on a partial failure. */
   opened = 1;
   if (driver_dwarfsym_open(&sym, &env, SYM_TOOL, opts.exe_path) != 0) goto done;
 
   if (!driver_read_stdin(&env, &data, &size)) {
     driver_errf(SYM_TOOL, "failed to read backtrace stream from stdin");
     goto done;
   }
 
   /* Emit each line verbatim, appending an annotation when it carries an
    * address. Split on '\n'; a final line without a trailing newline is still
    * processed (and printed without one). */
   pos = 0;
   while (pos < size) {
     size_t start = pos;
     size_t end = start;
     uint64_t addr = 0;
     while (end < size && data[end] != '\n') ++end;
 
     driver_printf("%.*s", (int)(end - start), (const char*)(data + start));
     if (sym_line_addr((const char*)(data + start), end - start, &addr)) {
       KitDwarfResolve loc;
       kit_dwarf_resolve(sym.dwarf, addr, 1, &loc);
       sym_emit_annotation(&loc, &opts);
     }
     if (end < size) {
       driver_printf("\n");
       pos = end + 1;
     } else {
       pos = end; /* last line had no terminator */
     }
   }
 
   rc = 0;
 
 done:
   if (data) driver_free(&env, data, size);
   if (opened) driver_dwarfsym_close(&sym);
   driver_env_fini(&env);
   return rc;
 }