summaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'README.md')
-rw-r--r--README.md43
1 files changed, 37 insertions, 6 deletions
diff --git a/README.md b/README.md
index 4d7a0ae..b960593 100644
--- a/README.md
+++ b/README.md
@@ -67,7 +67,7 @@ is any of them, in any order: time travel is an index.
| `string(id)` | `string` |
| `events()` | everything, as it came |
-From a debugger's recording, `zt.telescope`: `instruction(m, addr, buf)` is an instruction's text, its source `line`, and for a direct call its callee's `params` (DWARF's); `frames(m, regs, out)` is the call chain with each frame's extent on the stack, `low` to `high` (a `stack()` frame's is up to `sp + 8`).
+From a debugger's recording, `zt.telescope`: `instruction(m, addr, buf)` is an instruction's text, its source `line`, and for a direct call its callee's `params` (DWARF's); `frames(m, regs, out)` is the call chain with each frame's extent on the stack, `low` to `high` (a `stack()` frame's is up to `sp + 8`), walked by the call frame information the recording holds (below), else by frame pointer; `slots(m, regs, low, out)` is what each stack word from `low` is (`out[i]` the word at `low + 8 i`), a `Slot`: its `frame`, an index into `frames` (null in none), and its `role`: `.saved` (the register a function saved for its caller there: `"rbx"`, `"rbp"`, `"r12"` to `"r15"`), `.return_address`, `.local` (a variable or parameter: `name`, `size`, and `offset`, where the word is in it), or the process's first stack, `.argc`, `.argv` i, `.envp` i (i = argc, envc: the zero that ends them) and `.auxv` i (the auxiliary vector's i-th word, two an entry); `.none` where the recording does not say.
With `--alloc`, every live allocation and the 16 bytes of allocator header before it are in `read` at each stop (its first 4 KiB; what changed, a stop at a time; 256 KiB of them at most, lowest addresses first: `Debugger.allocation_watch`).
Recorded `--by insn`, the instructions that ran between two moments are the `rip` of each moment between them; `--by line` does not keep them.
A byte in `read` is as it was when the debugger last sent it: the stack window, the watched regions and the live allocations at every stop, a `read`'s or `write`'s buffer at that syscall (`-s` bytes of it). Memory it looked at once and not since is known and may be stale.
@@ -276,12 +276,43 @@ address, the size, read or write) with what is there, and after the step
what a write left there. So an instruction-level recording has every
memory write the stepped thread makes, with nothing watched and nothing
compiled in. A call, a jump or a return at the pc is a `branch` event:
-where it goes, and for a conditional jump whether it will. And each frame of the call chain is recorded, its return
-address named: `zt.telescope.backtrace` walks it again from the recording.
+where it goes, and for a conditional jump whether it will.
+
+**The call chain** is walked at every stop by the unwind tables
+(`.eh_frame`, `.debug_frame`, through `std.debug.Dwarf.Unwind`), as gdb
+walks it: right inside a function that keeps no frame (a libc wrapper at
+a syscall, malloc's fast path), in a prologue, in a PLT entry; by frame
+pointer where there are none (JIT code, a PLT Zig's linker made). What the walk reads of
+the stack is recorded, its return addresses named, and each function it
+goes through once, as a string (`event.frameId` of where it begins): its
+rows of call frame information (where its caller's stack pointer is, the
+CFA, and where it saved each register, a row for each stretch of its
+code) and, from DWARF, its frame base and the locals the debug info
+places by it (`DW_OP_fbreg`), each with its size and its block's range of
+code. `zt.telescope.frames` walks the same chain again from the recording,
+which needs no ELF file, and `slots` names the words: the saved registers
+and return addresses of every frame; the locals of -O0 and -Og code where
+the frame's pc is in their block (a leaf's in the red zone too); and argc,
+argv, envp and the auxiliary vector, from where the stack began (the
+string `event.frameId(0)`, `Debugger.Start`, read from `/proc/pid/stat`).
+What it does not say: a local in a register or a list of places (-O1 and
+up), or in a block whose code is in pieces (`DW_AT_ranges`); a local's
+name in a prologue or an epilogue where the frame base is rbp and rbp is
+not yet or no longer the frame's; one of two small locals sharing a word
+(the first keeps it); a frame whose CFA is an expression (a signal frame)
+or that has no unwind tables, which falls back on the frame pointer;
+inlined calls, which have no frame (gdb lists them).
What it costs, on `fib(12)` by instruction (142 000 moments): 154 000
moments a second and 64 bytes a moment with the disassembly and the
-touches, 57 000 and 77 bytes with the telescope and the call chain. Capstone is built from source for x86
+touches, 57 000 and 77 bytes with the telescope and the call chain. The
+call chain by unwind tables costs nothing a second over the frame
+pointer's (the walk reads the stack once and remembers each pc's row) and
+1 to 4 bytes a moment: on the list of `anim/tools` by instruction
+(`--from main --stack 1024 --around 80 --disasm 48`, -O0) 229 bytes a
+moment against 225, 16 000 moments a second either way; SQLite by
+breakpoint on `sqlite3BtreeInsert`, 310 bytes and 33 000 a second, as
+before. Capstone is built from source for x86
(`build/capstone.zig`), into the command only: the library takes a
disassembler as a function (`Debugger.disasm`) and links none.
@@ -362,8 +393,8 @@ Memory is read with `process_vm_readv`: 64 bytes in 0.3 µs where
written the same way, and through `/proc/pid/mem` where the page is
read-only (a breakpoint in code: 0.5 µs).
-Limits: `bt` walks frame pointers, so a function without a frame hides its
-caller. Threads are followed, each stop is one thread's and the others run
+Limits: `bt` walks the unwind tables, and where there are none (JIT code)
+frame pointers, where a function without a frame hides its caller. Threads are followed, each stop is one thread's and the others run
on; stepping by line in a threaded program reports the other threads'
instructions too. A target that execs is not followed into the new program.