From b426a8a99bcad81ecbb41d1f2a2e83738c29d8e1 Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Tue, 10 Nov 2026 11:32:21 -0300 Subject: llvm: a pass that instruments for animation, its runtime, ztrace cc llvm/pass.cpp is an LLVM pass plugin: lines, stores, loads, calls and variables, each call into the runtime carrying names and type descriptions, selected by globs (-ztrace-only, -ztrace-mem), before the optimizer by default. src/instr/rt.zig is the runtime (libztrace-rt.a), which also answers clang's own coverage and -finstrument-functions hooks; src/instr/types.zig the grammar of the type descriptions and its parser. ztrace cc adds all of it to a compiler command. test-llvm compiles fib, two sorts, a linked list and a BFS through ztrace cc and asserts on their recordings; bench-llvm measures what each selection costs. Co-Authored-By: Claude Fable 5.2 --- src/cli/cc.zig | 116 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 116 insertions(+) create mode 100644 src/cli/cc.zig (limited to 'src/cli/cc.zig') diff --git a/src/cli/cc.zig b/src/cli/cc.zig new file mode 100644 index 0000000..1d08b51 --- /dev/null +++ b/src/cli/cc.zig @@ -0,0 +1,116 @@ +//! ztrace cc: a compiler command with the instrumentation added, so a +//! program compiled from source records itself under `ztrace run`. +const std = @import("std"); +const util = @import("util.zig"); +const fail = util.fail; + +pub const usage = + \\usage: ztrace cc [--instr LIST] [--only GLOBS] [--mem GLOBS] [--late] [--plugin SO] [--rt A] -- CLANG ARGS + \\ + \\Runs CLANG (clang, clang++) with ARGS and -g, the pass plugin and its + \\options, and when the command links, the runtime: + \\ + \\ ztrace cc -- clang sort.c -o sort && ztrace run -- ./sort + \\ + \\ --instr LIST comma separated, default lines,calls,vars,stores + \\ lines `line` at each source line reached + \\ stores `mem_write`, with the bytes, after each store to a + \\ variable or through a pointer; a memset or + \\ memcpy is one, of its first 64 KiB at most + \\ loads `mem_read` after each load + \\ calls `call` at function entry, `ret` with the value at exit + \\ vars `variable` for each named local and global: + \\ address, size, name, type description + \\ from stock clang, no plugin and no names: + \\ edges `edge` (-fsanitize-coverage=trace-pc-guard) + \\ cmps `cmp`, and `edge`: clang compares only along with edges + \\ (-fsanitize-coverage=trace-pc-guard,trace-cmp) + \\ cyg `call`, `ret` (-finstrument-functions) + \\ --only GLOBS comma separated; the plugin instruments only the functions + \\ and globals whose name, source path or source file name + \\ matches one: 'sort*,*/vdbe.c' + \\ --mem GLOBS of those, the functions whose stores and loads are recorded + \\ (default: all of them). Stores are most of a recording: + \\ in a large program, name where memory matters. + \\ --late instrument after optimization: the stores and lines of the + \\ code that runs, not of the source + \\ --plugin SO the pass (default: ../lib/ztrace-pass.so from this program) + \\ --rt A the runtime (default: ../lib/libztrace-rt.a) + \\ +; + +pub fn run(init: std.process.Init, args: []const [:0]const u8) !void { + const arena = init.arena.allocator(); + var instr: []const u8 = "lines,calls,vars,stores"; + var only: ?[]const u8 = null; + var mem: ?[]const u8 = null; + var late = false; + var plugin: ?[]const u8 = null; + var rt: ?[]const u8 = null; + var i: usize = 0; + while (i < args.len) : (i += 1) { + const arg = args[i]; + if (std.mem.eql(u8, arg, "--")) { + i += 1; + break; + } else if (std.mem.eql(u8, arg, "--late")) { + late = true; + } else if (i + 1 < args.len and std.mem.eql(u8, arg, "--instr")) { + i += 1; + instr = args[i]; + } else if (i + 1 < args.len and std.mem.eql(u8, arg, "--only")) { + i += 1; + only = args[i]; + } else if (i + 1 < args.len and std.mem.eql(u8, arg, "--mem")) { + i += 1; + mem = args[i]; + } else if (i + 1 < args.len and std.mem.eql(u8, arg, "--plugin")) { + i += 1; + plugin = args[i]; + } else if (i + 1 < args.len and std.mem.eql(u8, arg, "--rt")) { + i += 1; + rt = args[i]; + } else fail(usage, .{}); + } + if (i >= args.len) fail(usage, .{}); + const lib = try std.fs.path.join(arena, &.{ try std.process.executableDirPathAlloc(init.io, arena), "..", "lib" }); + + var argv: std.ArrayList([]const u8) = .empty; + for (args[i..]) |arg| try argv.append(arena, arg); + // What a command that only links does not use is no warning. + try argv.appendSlice(arena, &.{ "--start-no-unused-arguments", "-g" }); + // The plugin's own words, which it checks; the rest are clang's flags. + var pass: std.ArrayList(u8) = .empty; + var words = std.mem.tokenizeScalar(u8, instr, ','); + while (words.next()) |word| { + if (std.mem.eql(u8, word, "edges")) { + try argv.append(arena, "-fsanitize-coverage=trace-pc-guard"); + } else if (std.mem.eql(u8, word, "cmps")) { + try argv.append(arena, "-fsanitize-coverage=trace-pc-guard,trace-cmp"); + } else if (std.mem.eql(u8, word, "cyg")) { + try argv.append(arena, "-finstrument-functions"); + } else try pass.print(arena, "{s}{s}", .{ if (pass.items.len > 0) "," else "", word }); + } + if (pass.items.len > 0) { + const so = plugin orelse try std.fs.path.join(arena, &.{ lib, "ztrace-pass.so" }); + // -load as well: the plugin's options must exist when -mllvm is read, + // which is before -fpass-plugin loads it. + try argv.appendSlice(arena, &.{ try std.fmt.allocPrint(arena, "-fpass-plugin={s}", .{so}), "-Xclang", "-load", "-Xclang", so }); + try argv.appendSlice(arena, &.{ "-mllvm", try std.fmt.allocPrint(arena, "-ztrace-instr={s}", .{pass.items}) }); + if (only) |globs| try argv.appendSlice(arena, &.{ "-mllvm", try std.fmt.allocPrint(arena, "-ztrace-only={s}", .{globs}) }); + if (mem) |globs| try argv.appendSlice(arena, &.{ "-mllvm", try std.fmt.allocPrint(arena, "-ztrace-mem={s}", .{globs}) }); + if (late) try argv.appendSlice(arena, &.{ "-mllvm", "-ztrace-late" }); + } + try argv.append(arena, "--end-no-unused-arguments"); + // The command links unless it says where to stop. The whole archive: with + // -fsanitize-coverage clang links weak callbacks of its own first, and + // only a runtime already in the link replaces them. -x none: after an + // -x c the archive would be read as source. + const links = for (args[i..]) |arg| { + if (std.mem.eql(u8, arg, "-c") or std.mem.eql(u8, arg, "-S") or std.mem.eql(u8, arg, "-E") or std.mem.eql(u8, arg, "-fsyntax-only")) break false; + } else true; + if (links) try argv.appendSlice(arena, &.{ "-x", "none", "-Wl,--whole-archive", rt orelse try std.fs.path.join(arena, &.{ lib, "libztrace-rt.a" }), "-Wl,--no-whole-archive" }); + + const err = std.process.replace(init.io, .{ .argv = argv.items }); + fail("{s}: {t}\n", .{ argv.items[0], err }); +} -- cgit v1.3