diff options
Diffstat (limited to 'introspect/README.md')
| -rw-r--r-- | introspect/README.md | 130 |
1 files changed, 0 insertions, 130 deletions
diff --git a/introspect/README.md b/introspect/README.md deleted file mode 100644 index ba7120b..0000000 --- a/introspect/README.md +++ /dev/null @@ -1,130 +0,0 @@ -# introspect - -A 9P2000 debug/introspection server as a Zig 0.16 library, built on -[cloud9](../): a debugger-shaped interface where the protocol is just files. -Anything that can read a filesystem (a shell, an agent, an editor, `9p`, -[9player](../9player)) can inspect a running program: build facts, comptime -type layouts, live values, threads and their stacks, memory, breakpoints, -panics. - -The core (`core`, `vars`) is freestanding: no allocator, no OS, no threads, -caller-owned static `Storage`, fixed-capacity tables sized at comptime. It -compiles for `riscv32-freestanding-none`. `scratch` (an in-memory read/write -tree) takes an allocator; `linux` is the platform layer (listeners, a poll -loop on one background thread, threads/stacks/registers, memory, breakpoints -and panics via `std.debug`). [docs/LIBRARY.md](docs/LIBRARY.md) has the full -contract. - -``` -introspect/ - build.zig fragment imported by cloud9's root build.zig (steps below) - src/root.zig pub const core, vars, scratch, linux; Config, Server(cfg), Provider - src/core.zig Tree/Server engine on cloud9.Server: fids, walks, dir reads, providers - src/vars.zig comptime value renderers (@typeInfo) for /vars - src/scratch.zig in-memory read/write tree provider (takes an Allocator) - src/freestanding_check.zig root for the riscv32-freestanding-none compile check - src/linux/probe.zig background thread + poll loop + unix/tcp/fd listeners - src/linux/debug.zig threads, stacks, registers, addr→source, memory, breakpoints, panic - src/linux/provider.zig the debug provider (/threads, /addr, /mem, /hex, /breakpoints, /panic) - src/linux/runtime.zig /runtime generators (pid, uptime, argv, cwd, env, clients) - demo/main.zig the `introspect` binary (below) - test/ debug.sh, adv_introspect_hostile, adv_core_hostile, adv_linux_probe, adversarial.sh - docs/LIBRARY.md design rules and the module contracts -``` - -## Using the library - -cloud9's `build.zig` exports two modules: `cloud9` (the protocol) and -`introspect` (this library, which imports `cloud9` itself). A package that -depends on cloud9 takes both from the one dependency: - -```zig -const cloud9_dep = b.dependency("cloud9", .{ .target = target, .optimize = optimize }); -exe.root_module.addImport("cloud9", cloud9_dep.module("cloud9")); -exe.root_module.addImport("introspect", cloud9_dep.module("introspect")); -``` - -Embedding the core is three static objects and a push/step/output loop, the -same shape as cloud9's `Server`: - -```zig -const introspect = @import("introspect"); - -const State = struct { ticks: u32, phase: enum { idle, busy } }; -const cfg: introspect.Config = .{ .name = "fw", .types = &.{State}, .msize = 2048, .max_fids = 16 }; -const S = introspect.Server(cfg); - -var state: State = .{ .ticks = 0, .phase = .idle }; -var storage: S.Storage = undefined; // per connection: in/out frames + snapshot slots -var shared: S.Shared = undefined; // once: providers and exposed variables - -pub fn main() void { - shared = .init(&state); - shared.expose("state", &state) catch unreachable; // /vars/state/{value,type,size,addr,raw,f/...} - var conn: S.Conn = .init(&shared, &storage, cfg.msize); - // transport loop: conn.push(bytes) ... while (try conn.step()) {} ... send conn.output(), conn.wrote(n) -} -``` - -On Linux, `introspect.linux.Probe` runs that loop for you on one background -thread over a Unix, TCP or inherited listener, and adds the debug provider; -`pub const panic = std.debug.FullPanic(introspect.linux.debug.panicHook);` -in the root module publishes panics under `/panic`. `demo/main.zig` shows -every piece together. - -## The demo (`zig build introspect`, binary `introspect`) - -A single-binary 9P2000 server whose file tree is the binary itself: build-time -facts, `comptime` reflection, live runtime state, a worker thread whose state -is exposed under `/vars`, and the Linux debug layer. - -``` -/README -/build/{zig_version,target,optimize,time,change} captured by introspect/build.zig (jj change id, UTC time) -/comptime/types/<T>/{name,size,align,fields} @sizeOf/@alignOf/@typeInfo, generated at comptime -/comptime/decls pub declarations of the server module -/runtime/{pid,ppid,uptime,argv,cwd,env,clients} -/runtime/fn/<name> reading calls a Zig function (hostname, now, random, uname, fib30) -/runtime/ctl write "fib N" | "add A B" | "echo TEXT" | "sleep-ms N" | "trap" | "panic" -/scratch/ in-memory read/write tree -/vars/state/... the worker's State (readable and writable leaves) -/threads/<tid>/{name,stat,stack,regs} /addr/<hex> /mem/{maps,<hex>} /hex/<hex> -/breakpoints/<tid>/{stack,regs,ctl} /panic/{message,stack,ctl} -``` - -`/runtime/env` exposes the server's whole environment, so serve it on a Unix -socket or loopback only. - -```sh -zig-out/bin/introspect --unix /tmp/intro.sock & # or --tcp IP:PORT, --stdio, --no-hold -zig-out/bin/9player --unix /tmp/intro.sock -- sh -c ' - cat $NINEPLAYER_MOUNT/build/zig_version; echo - cat $NINEPLAYER_MOUNT/comptime/types/Qid/fields - echo "fib 20" > $NINEPLAYER_MOUNT/runtime/ctl; cat $NINEPLAYER_MOUNT/runtime/ctl - cat $NINEPLAYER_MOUNT/threads/*/stack' -``` - -## Building and testing - -introspect lives in the cloud9 repository as `cloud9/introspect/` and is -wired into cloud9's `build.zig` through the fragment `introspect/build.zig`. -Everything is run from the cloud9 root: - -```sh -zig build # installs zig-out/bin/introspect with the other binaries -zig build introspect # build and install only the demo -zig build introspect-test # library unit tests (core, vars, scratch, linux) and the demo's -zig build introspect-check-freestanding # compile the core for riscv32-freestanding-none -zig build introspect-debug-test # src/linux/debug.zig unit tests -zig build introspect-debug-itest # test/debug.sh: threads, stacks, breakpoints, panic through 9player -zig build introspect-adv # hostile raw-9P clients against the demo and the core, - # the Linux layer through a 9player mount (several minutes) -zig build -Dintrospect=false # leave introspect out -zig build introspect-check-freestanding -Dtarget=riscv32-freestanding-none -Dintrospect=true -``` - -`-Dintrospect` (default: on for Linux targets) enables the module and the -freestanding check on any target; the demo and the Linux suites are added -only when the target OS is Linux. The end-to-end suites also need 9player -(`-D9player=true`, the Linux default), unprivileged user namespaces, -`/dev/fuse` and Python 3, and skip themselves otherwise. |