1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
|
//! The one record every backend produces (ptrace, the in-process agent,
//! LLVM instrumentation, kernel tracing) and every consumer reads (the
//! recorder, the animations). 64 bytes, plus an optional payload carried
//! beside it. `extern` because it crosses processes (the ring) and is
//! written to disk (the recorder).
const std = @import("std");
pub const Kind = enum(u16) {
// Execution stops. Payload: `Regs`, when the backend has them.
/// a0=pc
step = 1,
/// a0=pc a1=breakpoint id
breakpoint = 2,
/// aux=nr a0..a5=args. Payload: optional decoded bytes (a path).
syscall_enter = 3,
/// aux=nr a0=return value
syscall_exit = 4,
/// aux=signo a0=fault address a1=pc
signal = 5,
/// a0=exit code, or 128+signo when killed
exit = 6,
/// a0=new tid
thread_start = 7,
thread_exit = 8,
// Memory.
/// a0=addr a1=len. Payload: the bytes now at addr (len of them, or the
/// first of them: a backend may record a large write in part).
mem_write = 16,
/// a0=addr a1=len a2=pc (0: not given)
mem_read = 17,
/// a0=ptr a1=size a2=caller pc. aux: `Alloc`. A realloc that moves is a
/// `free` of the old pointer, then this.
alloc = 18,
/// a0=ptr a1=caller pc
free = 19,
/// a0=addr a1=len a2=prot a3=file offset. Payload: path, if file-backed.
map = 20,
/// a0=addr a1=len
unmap = 21,
/// The instruction at the pc is about to touch memory: a0=addr a1=len
/// a2=pc. aux: 1 it reads there, 2 it writes there, 3 both. From a
/// debugger, which sees the instruction before it runs; what is there is
/// recorded beside it, and what a write left there after the step.
touch = 22,
/// The instruction at the pc is a call, a jump or a return: a0=where it
/// goes a1=1 when it will go there (0: a conditional jump that falls
/// through) a2=pc. aux: 1 call, 2 jump, 3 return. From a debugger,
/// before the instruction runs; the target is named like any code address.
branch = 23,
// Instrumentation (compiler passes, hooks).
/// a0=callee (the string id of its name, or its address when the
/// backend has no names) a1=call site a2=sp a3=string id of the
/// function's type description, if any
call = 32,
/// a0=callee a1=return value. aux: how many bytes of a1 are the value
/// (0: none, or not known)
ret = 33,
/// a0=file string id a1=line a2=column a3=pc (0: not given)
line = 34,
/// a0=pc (a coverage edge)
edge = 35,
/// aux=operand bytes a0=pc a1=lhs a2=rhs
cmp = 36,
/// A named variable comes alive: a0=addr a1=size a2=name string id
/// a3=type string id (a description: src/instr/types.zig). aux: N for a
/// function's Nth parameter.
variable = 37,
// Kernel.
/// a0=prev tid a1=next tid a2=cpu
sched = 48,
/// a0=fault address a1=pc. aux: fault flags.
fault = 49,
/// a0=pc a1=counter id a2=value
sample = 50,
/// A kprobe, uprobe, tracepoint or USDT probe: a0=probe string id a1..a5=arguments
probe = 51,
// Annotations.
/// a0=user value. Payload: text.
mark = 60,
/// Defines a string id for later events: a0=id. Payload: the text.
string = 61,
_,
/// The bit of a kind in a 64-bit set (kinds are all below 64).
pub fn bit(k: Kind) u64 {
return @as(u64, 1) << @intCast(@intFromEnum(k));
}
};
pub const Alloc = enum(u16) { malloc, calloc, realloc, memalign, mmap };
pub const Event = extern struct {
/// CLOCK_MONOTONIC nanoseconds.
ts: u64 = 0,
/// 0 for an event no thread made (a string defined at startup).
tid: u32 = 0,
kind: Kind,
/// Small kind-specific value (syscall number, signal, operand size).
aux: u16 = 0,
a: [6]u64 = @splat(0),
comptime {
std.debug.assert(@sizeOf(Event) == 64);
}
};
/// Where events go. A recorder, a ring, a printer.
pub const Sink = struct {
ctx: *anyopaque,
emitFn: *const fn (ctx: *anyopaque, ev: *const Event, payload: []const u8) anyerror!void,
pub fn emit(s: Sink, ev: Event, payload: []const u8) !void {
return s.emitFn(s.ctx, &ev, payload);
}
};
/// x86-64 general registers, in the kernel's `user_regs_struct` order, so
/// PTRACE_GETREGS fills it directly.
pub const Regs = extern struct {
r15: u64 = 0,
r14: u64 = 0,
r13: u64 = 0,
r12: u64 = 0,
rbp: u64 = 0,
rbx: u64 = 0,
r11: u64 = 0,
r10: u64 = 0,
r9: u64 = 0,
r8: u64 = 0,
rax: u64 = 0,
rcx: u64 = 0,
rdx: u64 = 0,
rsi: u64 = 0,
rdi: u64 = 0,
orig_rax: u64 = 0,
rip: u64 = 0,
cs: u64 = 0,
eflags: u64 = 0,
rsp: u64 = 0,
ss: u64 = 0,
fs_base: u64 = 0,
gs_base: u64 = 0,
ds: u64 = 0,
es: u64 = 0,
fs: u64 = 0,
gs: u64 = 0,
comptime {
std.debug.assert(@sizeOf(Regs) == 27 * 8);
}
/// The registers a viewer shows, in display order.
pub const names = [_][]const u8{ "rax", "rbx", "rcx", "rdx", "rsi", "rdi", "rbp", "rsp", "r8", "r9", "r10", "r11", "r12", "r13", "r14", "r15", "rip", "eflags" };
pub fn get(r: *const Regs, comptime name: []const u8) u64 {
return @field(r, name);
}
/// By name at runtime: null for a name that is no register.
pub fn named(r: *const Regs, name: []const u8) ?u64 {
inline for (@typeInfo(Regs).@"struct".field_names) |f| {
if (std.mem.eql(u8, f, name)) return @field(r, f);
}
return null;
}
};
/// The id of a string, for a producer that keeps no table: its text's
/// hash, with the top bit set. The instrumentation counts its strings from
/// 1, and a symbol's name is the string whose id is its address; a hash up
/// here meets neither, so the producers of one recording (a debugger, an
/// agent and instrumentation at once) never define an id twice.
pub fn stringId(text: []const u8) u64 {
return std.hash.Wyhash.hash(0, text) | 1 << 63;
}
/// The id of the string that describes the instruction at `addr`: a byte
/// for its length, a byte for the length of the instruction before it (0
/// when that is not known), then its text ("mov rbp, rsp"). The string whose id is
/// `addr` itself is the address's name ("main+4"). Addresses stay below
/// bit 47 and hashed ids have bit 63: bit 62 keeps the two apart.
pub fn codeId(addr: u64) u64 {
return addr | 1 << 62;
}
/// The id of the string that describes the frame of the function that
/// begins at `addr`: how to walk through it to its caller (its call frame
/// information) and where its locals are (`Debugger.emitFunction`). A
/// reader finds the one that holds a pc as the greatest id at or below the
/// pc's (`Trace.stringBelow`). `frameId(0)`, where no function begins, is
/// the process's first stack (`Debugger.Start`). Bit 61 keeps these apart
/// from names, instructions and hashed ids.
pub fn frameId(addr: u64) u64 {
return addr | 1 << 61;
}
pub fn now() u64 {
var ts: std.os.linux.timespec = undefined;
_ = std.os.linux.clock_gettime(.MONOTONIC, &ts);
return @as(u64, @intCast(ts.sec)) * std.time.ns_per_s + @as(u64, @intCast(ts.nsec));
}
test "kind bits fit a u64 set" {
inline for (@typeInfo(Kind).@"enum".field_values) |v| try std.testing.expect(v < 64);
try std.testing.expectEqual(@as(?u64, 7), (Regs{ .rip = 7 }).named("rip"));
}
|