92 lines
3.9 KiB
Markdown
92 lines
3.9 KiB
Markdown
# Function Map
|
|
|
|
The function map is the canonical ledger for reverse-engineering progress. It should be updated even
|
|
when the understanding is partial, because partial structure is still useful if it is explicit about
|
|
confidence.
|
|
|
|
The handbook index in `docs/README.md` should stay high-level. Per-pass function additions and
|
|
renames belong here and in the derived export artifacts, not in the README. High-level control-loop
|
|
and subsystem flow belongs in the split atlas under `docs/control-loop-atlas/`, with
|
|
`docs/control-loop-atlas.md` serving as the compatibility index and this file staying
|
|
function-centric.
|
|
|
|
## Canonical Schema
|
|
|
|
The committed CSV header is:
|
|
|
|
```text
|
|
address,size,name,subsystem,calling_convention,prototype_status,source_tool,confidence,notes,verified_against
|
|
```
|
|
|
|
Field meanings:
|
|
|
|
- `address`: virtual address in the canonical 1.06 executable
|
|
- `size`: best current size in bytes; leave blank if unknown
|
|
- `name`: current best function name
|
|
- `subsystem`: coarse ownership bucket such as `startup`, `bootstrap`, `support`, `render`, `audio`, `ui`, `map`, `save`, `network`
|
|
- `calling_convention`: `cdecl`, `stdcall`, `thiscall`, `fastcall`, or `unknown`
|
|
- `prototype_status`: `unknown`, `inferred`, or `confirmed`
|
|
- `source_tool`: primary tool or source behind the current row
|
|
- `confidence`: integer from `1` to `5`
|
|
- `notes`: short justification, ambiguity, or follow-up
|
|
- `verified_against`: hash, runtime trace, second tool, or other corroboration
|
|
|
|
## Update Rules
|
|
|
|
- New rows must always include `address`, `name`, `subsystem`, `source_tool`, and `confidence`.
|
|
- Prefer names in the shape `owner_verb_object[_qualifier]`.
|
|
- Prefer one primary verb, one primary object, and at most one qualifier.
|
|
- If a rename is speculative, state that directly in `notes`.
|
|
- When two tools disagree on function boundaries, preserve the ambiguity in `notes` instead of hiding it.
|
|
- Prefer one row per concrete function, not per guessed feature.
|
|
- Prefer `try_` for best-effort helpers that may fall through without mutation or publication.
|
|
- Prefer `apply_` when a helper commits one selected policy or state transition.
|
|
- Reserve `evaluate_` for read-heavy helpers that classify or score state without committing the later action themselves.
|
|
- Prefer one stable family noun once a transient runtime structure is grounded.
|
|
- Use `queue_node` for transient linked-list allocations, and reserve `record` for persisted rows or document-style payloads.
|
|
- Prefer `startup_company` over `company_start` when the object is the newly started company.
|
|
- Prefer participial qualifiers such as `_ignoring_territories` over `_with_*_ignored` once the side condition is grounded.
|
|
- Drop filler tails such as `_lanes` once a broader owner is grounded well enough to carry the family directly.
|
|
- Prefer `_and_optionally_` over `_with_optional_` when a helper may take one secondary path but the main owner is still singular.
|
|
- Treat `_and_`, `_with_`, `_if_`, and `_via_` as fallback tools for still-uncertain seams, not the
|
|
default naming style.
|
|
- Raw offset tails such as `field_0xNN` are acceptable for direct accessors and low-confidence rows,
|
|
but should be replaced once a grounded semantic field name exists.
|
|
|
|
## Starter Subsystems
|
|
|
|
Use these buckets until the map needs finer structure:
|
|
|
|
- `startup`
|
|
- `bootstrap`
|
|
- `shell`
|
|
- `support`
|
|
- `ui`
|
|
- `render`
|
|
- `audio`
|
|
- `input`
|
|
- `network`
|
|
- `filesystem`
|
|
- `resource`
|
|
- `map`
|
|
- `scenario`
|
|
- `save`
|
|
- `simulation`
|
|
- `unknown`
|
|
|
|
## Verification Sources
|
|
|
|
Examples for `verified_against`:
|
|
|
|
- `sha256:01b0... + objdump`
|
|
- `ghidra + rizin`
|
|
- `ghidra + string xref`
|
|
- `runtime trace under winedbg`
|
|
|
|
## Exit Criteria For The Milestone
|
|
|
|
The first function-mapping milestone is complete when the repo has:
|
|
|
|
- a stable starter map for the canonical binary
|
|
- named anchors for startup and a few obvious subsystem gateways
|
|
- enough notes and exports that a future session can continue without rediscovery
|