From db923fa823354270217362db06356f2b1a41315e Mon Sep 17 00:00:00 2001 From: Gabriel Schneider Date: Tue, 10 Nov 2026 11:39:20 -0300 Subject: ztrace perf: the kernel's view of a program, unprivileged perf_event_open on a held child: counters, a sampling profile, every page fault with its registers, maps, threads, context switches, every syscall (the per-syscall tracepoints, the only ones open to a user), and the debug registers as watchpoints and breakpoints that do not stop the target. One time-ordered stream of Events into a Sink; --threads follows with a ring per CPU. usdt.zig: the notes of and their arguments from a Regs and a memory reader, independent of BPF. test-kernel runs all of it on targets/kernel_*. Co-Authored-By: Claude Fable 5.2 --- src/trace/kernel_test.zig | 346 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 346 insertions(+) create mode 100644 src/trace/kernel_test.zig (limited to 'src/trace/kernel_test.zig') diff --git a/src/trace/kernel_test.zig b/src/trace/kernel_test.zig new file mode 100644 index 0000000..6098c58 --- /dev/null +++ b/src/trace/kernel_test.zig @@ -0,0 +1,346 @@ +//! The kernel area against real programs: perf events on the targets of +//! `targets/kernel_*`, the USDT notes of one checked against readelf and +//! stopped at under ptrace. Built by `build/kernel.zig`, which hands over +//! the targets' paths. +const std = @import("std"); +const linux = std.os.linux; +const zt = @import("ztrace"); +const targets = @import("targets"); +const perf = zt.perf; +const gpa = std.testing.allocator; +const expect = std.testing.expect; +const expectEqual = std.testing.expectEqual; + +/// A sink that keeps everything. +const Log = struct { + items: std.ArrayList(Item) = .empty, + counts: [8]u64 = @splat(0), + + const Item = struct { ev: zt.Event, payload: []u8 }; + + fn sink(l: *Log) zt.Sink { + return .{ .ctx = l, .emitFn = emit }; + } + + fn emit(ctx: *anyopaque, ev: *const zt.Event, payload: []const u8) anyerror!void { + const l: *Log = @ptrCast(@alignCast(ctx)); + try l.items.append(gpa, .{ .ev = ev.*, .payload = try gpa.dupe(u8, payload) }); + } + + fn deinit(l: *Log) void { + for (l.items.items) |item| gpa.free(item.payload); + l.items.deinit(gpa); + } + + fn count(l: *const Log, kind: zt.Kind) usize { + var n: usize = 0; + for (l.items.items) |item| n += @intFromBool(item.ev.kind == kind); + return n; + } + + /// The string a `string` event gave `id`. + fn string(l: *const Log, id: u64) ?[]const u8 { + for (l.items.items) |item| if (item.ev.kind == .string and item.ev.a[0] == id) return item.payload; + return null; + } +}; + +const Armed = struct { symbol: []const u8, mode: perf.Watch.Mode }; + +/// Runs a target to its end with a session on it. `log.counts` gets the +/// counters. Skips the test where the kernel or CPU refuses the events +/// (perf_event_paranoid above 2, a VM without a PMU). +fn record(log: *Log, path: []const u8, args: []const []const u8, options: perf.Options, armed: []const Armed) !void { + var arena_state: std.heap.ArenaAllocator = .init(gpa); + defer arena_state.deinit(); + const arena = arena_state.allocator(); + const argv = try arena.allocSentinel(?[*:0]const u8, args.len + 1, null); + argv[0] = try arena.dupeSentinel(u8, path, 0); + for (argv[1..], args) |*dst, arg| dst.* = try arena.dupeSentinel(u8, arg, 0); + const envp = [_:null]?[*:0]const u8{}; + + var proc = try zt.ptrace.Process.spawn(argv[0].?, argv, &envp); + errdefer proc.kill(); + var session = perf.Session.open(gpa, proc.pid, options, log.sink()) catch |err| switch (err) { + error.PerfAccess, error.PerfNoSuchEvent => { + proc.kill(); + return error.SkipZigTest; + }, + else => |e| return e, + }; + defer session.close(); + for (armed) |a| { + const sym = (try perf.lookup(gpa, proc.pid, a.symbol)).?; + try session.watch(.{ .addr = sym.addr, .len = @intCast(@min(sym.size, 8)), .mode = a.mode, .name = a.symbol }); + } + perf.release(proc); + while (try session.poll(100)) {} + try session.readCounters(); + @memcpy(log.counts[0..session.counts.len], session.counts); + try expectEqual(@as(u64, 0), session.lost); + var status: u32 = 0; + _ = linux.waitpid(proc.pid, @ptrCast(&status), 0); + try expect(linux.W.IFEXITED(status) and linux.W.EXITSTATUS(status) == 0); +} + +test "counters: the instructions of a loop of known length" { + var log: Log = .{}; + defer log.deinit(); + try record(&log, targets.spin, &.{"5000000"}, .{ .counters = &.{ .instructions, .branches, .@"task-clock" } }, &.{}); + // Four instructions and one branch an iteration, plus the loader and libc starting up. + try expect(log.counts[0] >= 20_000_000 and log.counts[0] < 20_600_000); + try expect(log.counts[1] >= 5_000_000 and log.counts[1] < 5_150_000); + try expect(log.counts[2] > 100_000); + // ... and the same as events, named. + const last = log.items.items[log.items.items.len - 3]; + try expectEqual(zt.Kind.sample, last.ev.kind); + try expectEqual(perf.reading, last.ev.aux); + try expectEqual(log.counts[0], last.ev.a[2]); + try std.testing.expectEqualStrings("instructions", log.string(last.ev.a[1]).?); +} + +test "faults: every fresh page touched, with the registers; maps: the program itself and what it maps" { + var log: Log = .{}; + defer log.deinit(); + const pages = 64; + try record(&log, targets.touch, &.{std.fmt.comptimePrint("{d}", .{pages})}, .{ .faults = true }, &.{}); + + // Text of the program itself (mapped before we came: from /proc), of + // libc (mapped after: from the kernel's records), and anonymous memory. + var text: [2]u64 = .{ 0, 0 }; + var libc = false; + var anonymous: std.ArrayList([2]u64) = .empty; + defer anonymous.deinit(gpa); + var touched: usize = 0; + for (log.items.items) |item| switch (item.ev.kind) { + .map => { + const range: [2]u64 = .{ item.ev.a[0], item.ev.a[0] + item.ev.a[1] }; + const executable = item.ev.a[2] & 4 != 0; + if (std.mem.endsWith(u8, item.payload, "/kernel_touch") and executable) text = range; + if (std.mem.indexOf(u8, item.payload, "libc.so") != null and executable) libc = true; + // The target's own mmap is in one of these: the kernel reports + // it merged with its neighbour, not by itself. + if (item.payload.len == 0 and item.ev.a[1] >= pages * 4096) try anonymous.append(gpa, range); + }, + .fault => { + const regs = std.mem.bytesToValue(zt.Regs, item.payload); + try expectEqual(item.ev.a[1], regs.rip); + try expect(regs.rsp != 0); + // Its loop: from its own code, the first byte of a page of anonymous memory. + if (regs.rip < text[0] or regs.rip >= text[1] or item.ev.a[0] % 4096 != 0) continue; + for (anonymous.items) |range| { + if (item.ev.a[0] >= range[0] and item.ev.a[0] < range[1]) break; + } else continue; + touched += 1; + }, + else => {}, + }; + try expect(text[0] != 0 and libc); + try expect(touched >= pages); + try expect(touched <= pages + 2); +} + +test "debug registers: a watchpoint sees every write of a global, a breakpoint every call and its arguments" { + var log: Log = .{}; + defer log.deinit(); + const steps = 100; + try record(&log, targets.touch, &.{ "1", std.fmt.comptimePrint("{d}", .{steps}) }, .{}, &.{ + .{ .symbol = "counter", .mode = .write }, + .{ .symbol = "step", .mode = .exec }, + }); + var writes: u64 = 0; + var calls: u64 = 0; + var sum: u64 = 0; + var step_pc: u64 = 0; + for (log.items.items) |item| switch (item.ev.kind) { + .probe => { + try std.testing.expectEqualStrings("step", log.string(item.ev.a[0]).?); + // step(i, the sum so far) + try expectEqual(calls, item.ev.a[1]); + try expectEqual(sum, item.ev.a[2]); + step_pc = std.mem.bytesToValue(zt.Regs, item.payload).rip; + sum += calls; + calls += 1; + }, + .mem_write => { + try expectEqual(@as(u64, 8), item.ev.a[1]); + // The pc is the instruction after the store, a few bytes into step. + try expect(item.ev.a[2] > step_pc and item.ev.a[2] < step_pc + 32); + // The value is read when the record is: what was written, or something later. + if (item.payload.len == 8) try expect(std.mem.readInt(u64, item.payload[0..8], .little) >= sum); + writes += 1; + }, + else => {}, + }; + // The thread's three calls are not this task's: nobody asked to follow. + try expectEqual(@as(u64, steps), calls); + try expectEqual(@as(u64, steps), writes); +} + +test "syscalls with their paths, context switches, threads followed" { + var log: Log = .{}; + defer log.deinit(); + try record(&log, targets.touch, &.{ "1", "2" }, .{ .syscalls = true, .switches = true, .follow = true }, &.{.{ .symbol = "step", .mode = .exec }}); + + var fd: ?u64 = null; + var opened = false; + var wrote = false; + var slept = false; + var thread: u32 = 0; + var thread_calls: usize = 0; + var last_ts: u64 = 0; + for (log.items.items, 0..) |item, i| { + const ev = item.ev; + // One stream in time order, whichever CPU's ring a record came from. + if (ev.kind != .string and ev.kind != .map) { + try expect(ev.ts >= last_ts); + last_ts = ev.ts; + } + switch (ev.kind) { + .syscall_enter => switch (@as(linux.SYS, @fromBackingInt(@intCast(ev.aux)))) { + // Linux 6.19 and later copy the path and the bytes written into the record. + .openat => if (ev.a[1] != 0 and (item.payload.len == 0 or std.mem.eql(u8, item.payload, "/dev/null")) and ev.a[2] & 3 == 1) { + opened = true; + // Its exit is the same thread's next event. + for (log.items.items[i + 1 ..]) |next| if (next.ev.tid == ev.tid) { + try expectEqual(zt.Kind.syscall_exit, next.ev.kind); + try expectEqual(ev.aux, next.ev.aux); + fd = next.ev.a[0]; + break; + }; + }, + .write => if (fd != null and ev.a[0] == fd.? and ev.a[2] == 5) { + try expect(item.payload.len == 0 or std.mem.eql(u8, item.payload, "hello")); + wrote = true; + }, + .nanosleep, .clock_nanosleep => slept = true, + else => {}, + }, + // It left the CPU to sleep. + .sched => if (slept and ev.a[0] == ev.tid) { + slept = false; + thread_calls += 1000; + }, + .thread_start => thread = @intCast(ev.a[0]), + .probe => if (ev.tid == thread and thread != 0) { + try expect(ev.a[1] >= 1000); + thread_calls += 1; + }, + else => {}, + } + } + try expect(opened and wrote and thread != 0); + try expectEqual(@as(usize, 1003), thread_calls); + try expect(log.count(.syscall_enter) == log.count(.syscall_exit) + 1 or log.count(.syscall_enter) == log.count(.syscall_exit) + 2); + try expectEqual(@as(usize, 2), log.count(.thread_exit)); +} + +test "a profile: samples in the program's code, their callchains starting there" { + var log: Log = .{}; + defer log.deinit(); + try record(&log, targets.spin, &.{"100000000"}, .{ .sample_hz = 5000, .callchain = true }, &.{}); + var text: [2]u64 = .{ 0, 0 }; + var in_text: usize = 0; + for (log.items.items) |item| switch (item.ev.kind) { + .map => if (std.mem.endsWith(u8, item.payload, "/kernel_spin") and item.ev.a[2] & 4 != 0) { + text = .{ item.ev.a[0], item.ev.a[0] + item.ev.a[1] }; + }, + .sample => { + try std.testing.expectEqualStrings("cycles", log.string(item.ev.a[1]).?); + try expect(item.payload.len >= 8 and item.payload.len % 8 == 0); + try expectEqual(item.ev.a[0], std.mem.readInt(u64, item.payload[0..8], .little)); + in_text += @intFromBool(item.ev.a[0] >= text[0] and item.ev.a[0] < text[1]); + }, + else => {}, + }; + // All but the few taken while the loader ran. + try expect(in_text >= 20 and in_text + 10 >= log.count(.sample)); +} + +test "usdt: the notes say what readelf says; arguments are fetched at a probe" { + const io = std.testing.io; + const path = try gpa.dupeSentinel(u8, targets.usdt, 0); + defer gpa.free(path); + const elf = try zt.usdt.Elf.open(path); + defer elf.close(); + const found = try zt.usdt.probes(gpa, elf, 0); + defer gpa.free(found); + try expectEqual(@as(usize, 3), found.len); + + const result = std.process.run(gpa, io, .{ .argv = &.{ "readelf", "-n", targets.usdt } }) catch return error.SkipZigTest; + defer gpa.free(result.stdout); + defer gpa.free(result.stderr); + var lines = std.mem.tokenizeScalar(u8, result.stdout, '\n'); + var seen: usize = 0; + while (lines.next()) |line| { + const provider = after(line, "Provider: ") orelse continue; + const probe = found[seen]; + seen += 1; + try std.testing.expectEqualStrings(provider, probe.provider); + try std.testing.expectEqualStrings(after(lines.next().?, "Name: ").?, probe.name); + // Location: 0x..., Base: 0x..., Semaphore: 0x... + var numbers = std.mem.tokenizeAny(u8, lines.next().?, " ,"); + var values: [3]u64 = undefined; + for (&values) |*v| { + _ = numbers.next(); + v.* = try std.fmt.parseInt(u64, numbers.next().?, 0); + } + try expectEqual(values[0], probe.pc); + try expectEqual(values[2], probe.semaphore); + try std.testing.expectEqualStrings(after(lines.next().?, "Arguments: ").?, probe.args); + } + try expectEqual(found.len, seen); + + // What the debugger will do: an int3 on each nop, the semaphore raised, + // and at every stop the arguments read from the registers and memory. + const argv = [_:null]?[*:0]const u8{ path, "4", null }; + const envp = [_:null]?[*:0]const u8{}; + var proc = try zt.ptrace.Process.spawn(path, &argv, &envp); + errdefer proc.kill(); + const maps = try perf.readMaps(gpa, proc.pid); + defer gpa.free(maps); + // The program itself is the first thing mapped. + const live = try zt.usdt.probes(gpa, elf, elf.bias(perf.parseMap(maps[0..std.mem.indexOfScalar(u8, maps, '\n').?]).?.start)); + defer gpa.free(live); + for (live) |probe| { + var nop: [1]u8 = undefined; + try expectEqual(@as(usize, 1), proc.read(probe.pc, &nop)); + try expectEqual(@as(u8, 0x90), nop[0]); + try proc.write(probe.pc, &.{0xcc}); + if (probe.semaphore != 0) try proc.write(probe.semaphore, &.{ 1, 0 }); + } + // start(n), then tick(i, the sum of squares so far) n times, then done(n, sum). + const expected = [_]struct { []const u8, []const u64 }{ + .{ "start", &.{4} }, .{ "tick", &.{ 0, 0 } }, .{ "tick", &.{ 1, 1 } }, + .{ "tick", &.{ 2, 5 } }, .{ "tick", &.{ 3, 14 } }, .{ "done", &.{ 4, 14 } }, + }; + var stops: usize = 0; + while (true) switch (try proc.cont()) { + .trap => { + // The int3 was the whole instruction: the thread is already past the probe. + const regs = try proc.regs(); + const probe = for (live) |probe| { + if (probe.pc == regs.rip - 1) break probe; + } else return error.StoppedElsewhere; + try std.testing.expectEqualStrings(expected[stops][0], probe.name); + var specs = std.mem.tokenizeScalar(u8, probe.args, ' '); + for (expected[stops][1]) |value| { + const arg = try zt.usdt.Arg.parse(specs.next().?); + try expectEqual(@as(?u64, value), arg.fetch(®s, proc)); + } + try expect(specs.next() == null); + stops += 1; + }, + .exited => |code| { + try expectEqual(@as(u8, 0), code); + break; + }, + else => {}, + }; + try expectEqual(expected.len, stops); +} + +fn after(line: []const u8, label: []const u8) ?[]const u8 { + const at = std.mem.indexOf(u8, line, label) orelse return null; + return line[at + label.len ..]; +} -- cgit v1.3