summaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'README.md')
-rw-r--r--README.md37
1 files changed, 33 insertions, 4 deletions
diff --git a/README.md b/README.md
index 05a8823..8ce4372 100644
--- a/README.md
+++ b/README.md
@@ -67,7 +67,9 @@ 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`), 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.
+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; `function(m, pc)` is the function that holds a pc as the recorded walk went through it, its `start` and `len` by its call frame information (a PLT stub's 16 bytes), for every frame of every stop; `got(m, slot)` is what a GOT slot holds and whether that is still `lazy` (its name has `@plt`: the way back into the PLT, so the next call runs the loader's resolver) or bound.
+For a call followed down, each frame has its module (`mapping`), whether it has source (its instructions' `line`), its function's bounds (`function`), and, from a caller, three instructions round its call: the return address, the call `back` from it, and the row before the call `back` from that.
+Code is named at every pc, a function's first instruction too, and a PLT stub and a GOT slot for the function they lead to: `open@plt+0`, `open@got+0` (from the relocations and the dynamic symbols; an IFUNC's in libc by the function its resolver is, `libc.so.6!strlen@plt+0`); of the names libc gives one address (`open`, `open64`, `__open64`) the one the program's relocations use. A slot is named when an instruction jumps or calls through it.
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.
@@ -337,7 +339,10 @@ unstripped libc) and else in libc's writable data as the struct whose
`next` is itself, the tcache as the word below the thread pointer that
points at a chunk of the tcache's size. Known: glibc 2.44 (this machine's,
stripped: no fastbins, 76 tcache bins counted down, 16 a bin, the tcache
-made at the first free) and 2.40 (pwndbg's own, the classic layout);
+made at the first free: until then the thread's pointer is on a dummy, zeros
+in libc's read-only data, which the reader says as `tcache_dummy`; a bin's
+count is the slots it has left, and `Tcache.capacity`, an empty bin's
+count, what a bin holds when full) and 2.40 (pwndbg's own, the classic layout);
another version is refused by name. A static glibc has no version in it:
its layout is told by the size of `main_arena`. Not read: a stripped static
glibc, musl, the arenas of other threads, mmapped chunks (`--alloc` has
@@ -402,8 +407,32 @@ it followed as a pointer; `--around BYTES` of memory each side of what a
pointer leads to (0: the 32 bytes at it); `--disasm ROWS` of instructions
above and below the pc (8). On the list of `anim/tools` by instruction,
`--stack 512 --around 64 --disasm 24` is 184 bytes a moment against 159,
-and 27 000 moments a second against 45 000. In a program, it is
-`zt.Debugger`:
+and 27 000 moments a second against 45 000.
+
+By instruction, a few kinds of code are not what one steps through:
+
+- **The vDSO** (`clock_gettime`, `gettimeofday`: the kernel's code mapped
+ into the process) is run through: the instruction that calls or jumps
+ into it is a moment, the next is where it returns to, with rax the
+ result, and none is inside it. Its loops retry while the kernel's time
+ data changes under them, which a stop at each instruction made them do
+ for as long as stops were slow: three clock reads were three million
+ moments. The call is a `branch` into `[vdso]`; what it wrote is in
+ memory where the stack window or a watch has it.
+- **Lazy binding**: the first call through a PLT stub runs the loader's
+ resolver, hundreds of instructions in ld.so (named by offset: Arch's
+ ld.so has no symbols), the call chain under it intact. A target linked
+ with `-Wl,-z,now` is bound at load and goes straight to the function.
+- **A system call**: the moment whose pc is the `syscall` instruction is
+ followed by one that holds the call, `syscall_enter` (aux the number,
+ `zt.syscalls.name` its name; the six arguments; the path or bytes it
+ points at, read by its signature in `zt.syscalls`) and `syscall_exit`
+ (a0 the result), whose registers are those after it: rax the result,
+ rcx the instruction after the `syscall`, r11 the flags (the trap flag of
+ the step among them), the two the instruction clobbers. The moment after
+ that is the step to the next instruction, at the same pc.
+
+In a program, it is `zt.Debugger`:
```zig
var d = try zt.Debugger.spawn(gpa, io, path, argv, envp, recorder.sink());