xenia-rs/audit-runs/audit-068-host-mem-watch/instrumentation-design.md

# AUDIT-068 Session 1 — host-side memory-write watch (canary instrumentation)

Date: 2026-05-19

## Goal

Capture which host C++ functions perform the writes to guest memory that ours never reproduces:
1. Vtable install at `0xBCE25340 = 0x8200A208` (and clone `0x8200A928`) — gates `sub_825070F0`.
2. Voice-struct field clear `[VOICE+0x164]` (value `0x00000000`, on guest-VA likely in heap `0x425xxxxx`).
3. Anything else surfaced.

## Write-path surface inventory (canary)

### A. `xe::store_and_swap<T>` template family (`xenia-canary/src/xenia/base/memory.h:410-475`)

- Sized specializations for T = int8/uint8/int16/uint16/int32/uint32/int64/uint64/float/double.
- String specializations recurse to `store_and_swap<uint8_t>` / `<uint16_t>`.
- Receives `void* mem` = HOST pointer; does `*p = byte_swap(value)`.
- **This is the canonical path** for host-side typed writes to guest memory used by kernel-import handlers in `xboxkrnl_*.cc`. Confirmed wide use (16 kernel sub-modules call `store_and_swap<uint32_t>` alone).
- Vtable install (PPC `stw vptr,0(obj)` equivalent on host side) almost certainly uses `store_and_swap<uint32_t>(host_ptr, vptr)`.

### B. `Memory::Zero/Fill/Copy` (`xenia/memory.cc:542-554`)

- Use `std::memset`/`std::memcpy` directly via host pointer (after `TranslateVirtual`).
- Wrappers for `RtlZeroMemory`, `RtlFillMemory`, `RtlMoveMemory`, `RtlCopyMemory`.
- Bypass `store_and_swap` — must instrument separately if we want full coverage.
- Voice-struct clears via `0x00000000` could plausibly come through here (RtlZeroMemory) or directly via `store_and_swap<uint32_t>` (typed write).

### C. Direct guest writes via `*TranslateVirtual<T*>() = …`

- Some sites cast and write through the host pointer directly without going through `store_and_swap`.
- Lower coverage priority — start with A+B; add C only if first 2 don't catch our targets.

## Cvar design (mimics audit_67 pattern)

Two new cvars in `xenia/cpu/cpu_flags.{h,cc}`:

```cpp
DECLARE_string(audit_68_host_mem_watch_values);   // CSV of u32 values (max 8)
DECLARE_string(audit_68_host_mem_watch_addrs);    // CSV of guest VAs or VA ranges (max 8)
```

Format examples:
- Values: `--audit_68_host_mem_watch_values=0x8200A208,0x8200A928`
- Addrs single: `--audit_68_host_mem_watch_addrs=0xBCE25340`
- Addrs range: `--audit_68_host_mem_watch_addrs=0x42500000-0x42600000,0xBCE25340`

Default empty → zero overhead.

Sample log line (XELOGI):
```
AUDIT-068-HOST-WRITE guest_va=0xBCE25340 val=0x8200A208 sz=4 fn=<host_function> host_ns=10123456789 tid=N
```

`fn=<host_function>` is filled by the caller (each `store_and_swap<T>` specialization passes `__FUNCTION__` or a tag). We can't get a real backtrace cheaply across MSVC; we instead instrument the high-fanout entry points (kernel-import handlers, `Memory::Zero/Fill/Copy`) with a string tag. For Session 1, capture is sufficient with just template name + caller tag.

## Implementation strategy

1. New file `xenia/audit_68_host_mem_watch.h` (top-level): forward decls of helper functions in `namespace xe::audit_68`:
   ```cpp
   extern std::atomic<uint8_t> g_active;  // 0=off, 1=values, 2=addrs, 3=both
   void check_host_write(const void* host_ptr, uint64_t value, uint8_t size,
                         const char* tag);
   void check_guest_write(uint32_t guest_va, uint64_t value, uint8_t size,
                          const char* tag);
   ```
2. New file `xenia/audit_68_host_mem_watch.cc`: lazy-parse the cvars on first call, atomic-bool sets active. Performs `Memory::active()->HostToGuestVirtual(host_ptr)` translation, then matches against value-list and addr-range list, emits XELOGI.
3. `xenia/memory.h`: add public static `Memory::active()` (returns `active_memory_`).
4. `xenia/base/memory.h`: extend `store_and_swap<T>` specializations (uint8/uint16/uint32/uint64 only — the integer typed paths most likely to write vptrs / clear flags) to check `g_active` and call the helper. Hot path: 1 atomic load + branch when off. The added cost when on is one cmp+jne per byte/word/dword/qword store; acceptable for capture runs.
5. `xenia/memory.cc`: instrument `Memory::Zero/Fill/Copy` with calls to `check_guest_write` (each ranges through the affected guest VAs; for capture purposes we only log the first matching byte+size+tag — we don't expand to per-byte events).

Total estimated LOC: ~120-160 LOC across 5 files.

## Capture protocol

- Build canary with the new code.
- Smoke test: `--audit_68_host_mem_watch_values=0x12345678` (no expected hits) → confirm no spurious lines, build/init OK.
- Sanity test: `--audit_68_host_mem_watch_values=0x82000000` (very common vtable-base) → confirm many lines, then revert.
- Run 1 (vtable install): `--audit_68_host_mem_watch_values=0x8200A208,0x8200A928 --mute=true`. Kill after ~90s.
- Run 2 (voice-struct clear): `--audit_68_host_mem_watch_addrs=0x42500000-0x42600000 --mute=true`. Kill after ~30s (this is heap-region wide; likely lots of hits, capture early window only). May need narrower range once we see the first writes.
- Cold-protocol: backup canary's cache (`xenia-canary/build-cross/bin/Windows/Debug/cache/`) to `/tmp/canary-cache-bak-audit-068`, wipe before run, restore after.