diff --git a/MANUAL.md b/MANUAL.md index f57d610..8abd49d 100644 --- a/MANUAL.md +++ b/MANUAL.md @@ -63,20 +63,24 @@ cmp -l assets/disk.1 build/disk_1.bin # 0 differences | `-m analyze --trace [--budget N]` | Trace-driven analysis: run the binary from its entry point in the built-in sandboxed M68000 interpreter (`m68kemu`) + minimal Amiga chipset, then resolve indirect dispatch (trampolines, `d16(An)`/indexed computed calls), self-installed interrupt/trap handlers, and hardware-register accesses **by observation** and seed them into recursive descent. Opt-in, for **flat self-booting binaries** (games/demos); default `analyze` is unchanged. `--budget` caps the instruction count (default 20,000,000). All facts are non-byte-affecting (labels/edges/comments) — parity is preserved. | | `-m emit [--amiga] [--all] [--relocatable] [--force]` | Emit modular Amiga assembly (`--amiga`: `src//hunk*.asm` + `disasm/.asm` + shared `src/equates.i`) or single-file assembly (`disasm/.asm`). Refuses to overwrite existing files unless `--force` is passed. | | `-m callgraph` / `cg [TARGET...] [FLAGS]` | Inspect multi-hunk call graphs, bottom-up worklists, string/HW anchors, indirect dispatch sites (`--indirect`), and function disassembly | +| `-m disasm` / `d TARGET [-n INSTS] [--len BYTES] [--try-code] [-f text\|json]` | Disassemble `N` instructions or `BYTES` starting at any address or mid-function label without dumping the full function (`--try-code` previews candidate instructions on `DATA` bytes read-only) | | `-m search QUERY [-s SEG] [-n LIMIT] [--dense] [-f text\|json]` | Search instructions, operands, strings, labels, comments, bytes, hardware/math clusters (`cluster:`), or self-modifying code (`smc`) | -| `-m data` / `inspect TARGET [--len N] [--copper] [--struct NAME [--count N]] [-f text\|json]` | Inspect non-code data, pointer tables, strings, Amiga Copper lists (`--copper`), or structured record arrays (`--struct`) | +| `-m data` / `inspect TARGET [--len N] [--copper] [--struct NAME [--count N]] [--try-code] [-f text\|json]` | Inspect non-code data, pointer tables, strings, Amiga Copper lists (`--copper`), structured record arrays (`--struct`), or candidate instructions (`--code` / `--try-code`) | | `-m xref TARGET_OR_RANGE [-f text\|json]` | Query all incoming cross-references to an address/label (`xref $1178`) or external references into an address/offset range (`xref $1000..$1FFF`, `xref +3DDEE..+3EFFF`) | -| `-m hint code TARGET` | Mark target as code entry (`confidence = 100`) and run incremental analysis | +| `-m hint [--batch FILE \| -f FILE]` | Apply multiple `code`, `data`, `pointer`, or `jump-table` hints in a single transaction + one incremental analysis pass | +| `-m hint code TARGET... [--batch FILE]` | Mark one or more targets as code entries (`confidence = 100`), reclaim unreferenced interior labels, and run incremental analysis once | | `-m hint data TARGET [COUNT] [--string] [--comment TEXT]` | Mark byte/data range or null-terminated string (`--string`) at `confidence = 100` | | `-m hint pointer TARGET [COUNT] [--follow] [--comment TEXT]` | Mark 32-bit pointer(s) (`confidence = 100`), create target labels + `DATA_ADDR` xrefs, and seed code targets when `--follow` is passed | +| `-m hint jump-table TARGET [COUNT] [--base BASE] [--count N] [--entry-size 2\|4]` | Mark a relative offset jump table (`dc.w Target-Base` or `dc.l Target-Base`), create `Target-Base` expressions + `DATA_ADDR` xrefs, and seed all target handlers as `CODE` | | `-m hint base-reg REG BASE_HEX [--segment NAME] [--function LABEL]` | Declare a base-register invariant (`REG` = `a4`/`a5`/`a6`, e.g. `hint base-reg a6 0xDFF000`) so `d16(An)` accesses resolve to hardware names / global `DATA`/`BSS` xrefs. Scope is global, or limited to one `--segment` or `--function`; re-runs analysis | -| `-m rename OLD_NAME NEW_NAME` | Rename a symbol (or multiple `OLD=NEW` pairs, or `--file ` batch file) across all segments in a single transaction | -| `-m comment TARGET [TEXT] [--block] [--batch FILE]` | Set or clear inline comment or function/block header comment (`--block` / `-b`), with strict cell-boundary & function-bounds validation and batch file support (`--batch` / `--file`) | -| `-m abi [TARGET [SIGNATURE]] [--verify] [--batch FILE] [-f text\|json]` | Set, inspect, or statically verify (`--verify`) a function's register call signature (`(a0=Model*) -> d0 \| clobbers: d1/a1`) | -| `-m struct add NAME [--size BYTES] OFFSET=FIELD[.b\|.w\|.l\|.p]...` | Define or update a named struct and its field offsets (`struct list [-f text\|json]`, `struct remove NAME`); emitted as ` equ ` and `_SIZEOF equ ` | +| `-m label delete TARGET...` | Delete one or more bogus/mid-instruction labels (and associated renames) and re-format covering cells | +| `-m rename [OLD_NAME NEW_NAME \| --delete TARGET... \| --batch FILE \| -f FILE]` | Rename a symbol (or multiple `OLD=NEW` pairs, `--batch`/`-f ` batch file, or `--delete` labels) across all segments in a single transaction | +| `-m comment [TARGET [TEXT]] [--block] [--batch FILE \| -f FILE]` | Set or clear inline comment or function/block header comment (`--block` / `-b`), with strict cell-boundary & function-bounds validation and batch file support (`--batch` / `--file` / `-f`) | +| `-m abi [TARGET [SIGNATURE]] [--verify] [--batch FILE \| -f FILE] [-f text\|json]` | Set, inspect, or statically verify (`--verify`) a function's register call signature (`(a0=Model*) -> d0 \| clobbers: d1/a1`) | +| `-m struct add NAME [--size BYTES] OFFSET=FIELD[.b\|.w\|.l\|.p]...` | Define or update a named struct and its field offsets (including negative stack-frame offsets like `-220=rf_NormTablePtr.l`; `struct list [-f text\|json]`, `struct remove NAME`) | | `-m alias [REG STRUCT [--fn FUNC]]` | Bind an address register (`a0`..`a6`) globally or per-function (`--fn `) to a struct so `d16(An)` renders symbolically (`alias list [-f text\|json]`, `alias remove REG [--fn FUNC]`) | | `-m dump [-f text\|json] [--section SEC]` | Export all durable reverse-engineering state (`entry_points`, `memory_regions`, `renames`, non-auto `comments`, `structs`, `register_aliases`, `carves`) | -| `-m operand TARGET FORMAT` | Set operand numeric format (`HEX`, `DEC`, `BIN`) and reformat the instruction | +| `-m operand [TARGET FORMAT] [--batch FILE \| -f FILE]` | Set operand numeric format (`HEX`, `DEC`, `BIN`) for one target or a batch file (` `) and reformat instructions | | `-m segment add --file F --base HEX --name N` | Add a binary segment to the module | | `-m segment split PARENT --at OFF (--len N \| --to OFF) --base HEX --name N` | Slice an extent out of a segment into a new static-base part (`.bin` + shared DB), filed into the active space | | `-m segment remove NAME` | Remove a segment from the module | @@ -96,13 +100,13 @@ cmp -l assets/disk.1 build/disk_1.bin # 0 differences ## Target Address & Label Resolution Syntax -Every CLI command that takes a `TARGET` (`callgraph`, `hint`, `comment`, `operand`) as well as the TUI `Goto` (`g`) prompt accepts any of the following human- and LLM-friendly formats: +Every CLI command that takes a `TARGET` (`callgraph`, `disasm`, `data`, `xref`, `hint`, `comment`, `operand`, `label delete`) as well as the TUI `Goto` (`g`) prompt accepts any of the following human- and LLM-friendly formats: | Format | Example | Meaning | |--------|---------|---------| | `: