maddo/Crusader_Decomp
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Add Ghidra MCP server update workflow instructions and various binary files; enhance segment coverage ledger and mid-project plan with detailed analysis notes

Browse source
This commit is contained in:
MaddoScientisto 2026-03-21 19:29:57 +01:00
commit 8847708d41
10 changed files with 248 additions and 18 deletions
Download patch file Download diff file Expand all files Collapse all files

102
crusader_decompilation_notes.md
View file

@ -100,6 +100,108 @@ Known call-site classifications (by argument pattern):
- `rng_next_modulo` advances the RNG state and returns the result modulo the requested bound, or `0` when the bound is zero.
- Short decompiler comments were added in Ghidra at all five seg091 entries so the current evidence stays attached to the raw database.
### Raw 0x4588 Runtime Callback Lifecycle Batch (direct MCP analysis)
- New conservative runtime-callback lifecycle renames (direct analysis):
- `000a:4913` = `runtime_callback_object_init_once`
- `000a:4a56` = `runtime_callback_object_teardown_once`
- `0009:b1c3` = `runtime_callback_object_phase_finalize`
- Boundary repair applied with MCP edit-plan API:
- Rebuilt `000a:b988` as `sprite_node_get_or_traverse` with full body `000a:b988-000a:bab5`.
- This repair absorbs both callback-state sync callsites at `000a:b9e5` and `000a:ba66` that were previously in a no-function gap.
- Verified callback-object behavior from this pass:
- `runtime_callback_object_init_once` sets one-time guard `0x4594`, snapshots state words (`0x458c`/`0x4590`) via `video_bios_state_snapshot`, installs the object FAR pointer at `0x4588`, and ensures fallback buffer allocation at `0x45a6`.
- `runtime_callback_object_teardown_once` sets one-time guard `0x4595`, clears `0x4588`, conditionally emits vtable `+0x0c` callback when current/previous state differ, then calls vtable `+0x04` release path.
- `runtime_callback_object_phase_finalize` invokes vtable `+0x08` twice and sweeps table entries via `allocator_head_finalize_sweep`.
- Large caller `FUN_000d_9afd` contains both additional vtable `+0x0c` callsites (`000d:9d5e` and `000d:a3b7`) and remains the best next target for concrete subsystem naming.
- Short decompiler comments were added at the three renamed lifecycle functions to preserve current evidence.
### Raw 0x4588 Follow-up Batch (allocator/video helper clarification)
- New conservative helper renames from direct disassembly/decompile evidence:
- `0009:a961` = `allocator_head_finalize_sweep`
- `000a:4a1f` = `video_bios_state_snapshot`
- Verified behavior anchors:
- `allocator_head_finalize_sweep` performs per-head chain compaction/finalize work over allocator table entries used by `runtime_callback_object_phase_finalize`.
- `video_bios_state_snapshot` executes BIOS video interrupts (`INT 10h` with `AX=4F03` and `AX=1130,BH=3`) and returns packed state in `DX:AX`; callers store/compare this pair around callback emissions.
- Decompiler comments were updated so downstream analysis sees the new helper names directly.
### Raw 0x4588 Follow-up Batch 2 (cleanup + mode-state wrapper)
- New conservative structural renames (direct decompile/disassembly evidence):
- `000a:4972` = `video_mode_set_and_record_state`
- `000d:9afd` = `entity_cleanup_resources_and_dispatch`
- Verified behavior anchors:
- `video_mode_set_and_record_state` stores requested mode/state to `0x4590`, handles VBE-style mode values (`0x101`/`0x103`/`0x105`) via helper checks, and falls back to `INT 10h` mode path for other values.
- `entity_cleanup_resources_and_dispatch` is a large teardown/finalize path for an entity-like object: it clears flags, frees multiple owned buffers/palette handles, performs conditional callback dispatch through `0x4588` vtable `+0x0c`, then destroys object word-list structures.
- Decompiler comments were added at both renamed addresses to preserve this provenance.
### Raw 0x4588 Follow-up Batch 3 (cleanup-callee helper classification)
- New conservative helper renames from direct MCP decompile evidence:
- `0009:7853` = `palette_buffer_alloc_and_init_256`
- `0009:1c3a` = `file_handle_alloc_init_and_open`
- `0009:1d6a` = `file_handle_open_with_mode`
- `0009:8d7b` = `surface_release_internal`
- `0009:8e0a` = `surface_release_and_maybe_free`
- `000d:9231` = `sprite_redraw_global_if_active`
- Verified behavior anchors:
- `palette_buffer_alloc_and_init_256` ensures a caller-provided far buffer exists, allocates/initializes a `0x100`-entry palette/work block, and fills it from static table data.
- `file_handle_alloc_init_and_open` allocates a handle structure on demand, seeds sentinels, then delegates to `file_handle_open_with_mode`.
- `file_handle_open_with_mode` performs path/open initialization with optional pre-delete behavior and stores DOS open result metadata into the handle structure.
- `surface_release_and_maybe_free` wraps `surface_release_internal` and conditionally frees memory when `(flags & 1) != 0`.
- `sprite_redraw_global_if_active` redraws the global sprite/object pointer at `0x4f38` only when the global gate byte `0x68e5` is enabled.
- `entity_cleanup_resources_and_dispatch` now has direct named callees for file/surface/palette cleanup paths, reducing the remaining ambiguity to callback-object role naming and the `000d:7e00` event-dispatch constructor path.
- Short decompiler comments were added at all six renamed helpers to preserve evidence provenance in-database.
### Raw 0x4588 Follow-up Batch 4 (function-object recovery around `000d:7e00`)
- Missing function objects recovered from direct disassembly boundaries:
- `000d:7e00-000d:8077` created and renamed to `entity_dispatch_entry_init_runtime_state`
- `000d:8078-000d:819f` renamed to `entity_dispatch_entry_release_runtime_state`
- `0003:a880-0003:a896` created as `FUN_0003_a880` (arithmetic helper; decompiler currently simplifies it)
- `0003:b8e2-0003:bb39` created and renamed to `far_buffer_alloc_with_mode_flags`
- Verified behavior anchors:
- `entity_dispatch_entry_init_runtime_state` is a constructor-side helper that initializes runtime fields (`+0x41/+0x42/+0x44`), clears and allocates paired work/palette buffers (`+0x46/+0x48` and `+0x4a/+0x4c`), applies event/setup calls through seg061 helpers, then finalizes activation.
- `entity_dispatch_entry_release_runtime_state` is the destructor-side pair: it frees the same paired buffers, propagates active-state changes via global `0x6828`, and destroys embedded word-list members.
- `far_buffer_alloc_with_mode_flags` is a low-level far-buffer utility that allocates/reuses a destination pointer and dispatches mode-dependent copy/fill behavior via an internal flag table.
- This resolves the previous `000d:7e00` "missing function object" blocker and improves readability for `entity_cleanup_resources_and_dispatch` callback/setup paths.
### Raw 0x4588 Follow-up Batch 5 (seg061/064/076 helper stabilization)
- New conservative helper renames:
- `0009:6ec7` = `vga_palette_read`
- `0008:d3ba` = `timer_entity_enable_wrapper`
- Additional evidence-preserving decompiler comments were added (without speculative renames) on:
- `0008:eb43`
- `0008:ebe7`
- `0008:eac8`
- `0008:ec23`
- Verified behavior anchors:
- `vga_palette_read` mirrors `vga_palette_write` and reads DAC entries through ports `0x3c7/0x3c9` into a far palette buffer.
- `timer_entity_enable_wrapper` is a thin forwarder to `timer_entity_enable` and is widely used in lifecycle/setup paths.
- The seg064 gate helpers (`0008:eb43`/`0008:ebe7`/`0008:ec23`) control one-shot global flag transitions at `0x3b72/0x3b73`, then dispatch via unresolved thunk paths; names remain intentionally conservative pending stronger subsystem identity.
- Callback callsite clarification retained:
- `entity_cleanup_resources_and_dispatch` vtable `+0x0c` call at `000d:9d5e` passes object fields `+0x12d/+0x12f`.
- Matching vtable `+0x0c` call at `000d:a3b7` passes object fields `+0x74f/+0x751`.
- These pairs appear to be state/coordinate-like payloads for the runtime callback object at `0x4588`.
### Raw 0x4588 Follow-up Batch 6 (constructor lane naming + callback globals)
- New conservative helper renames:
- `0008:d27e` = `entity_set_update_period_and_reschedule`
- `0009:7905` = `palette_buffer_alloc_copy_from_source`
- Verified behavior anchors:
- `entity_set_update_period_and_reschedule` stores timing/update-period fields (`+0x36/+0x38/+0x3a`), clears deferred fields (`+0x3c/+0x3e`), then triggers timer recompute/reschedule helpers.
- `palette_buffer_alloc_copy_from_source` allocates/replaces destination palette buffer metadata and copies RGB triplets from a source far pointer (`entry_count * 3` bytes).
- Disassembly annotations added on both callback emit callsites so payload provenance remains attached in-database:
- `000d:9d5e` -> vtable `+0x0c` payload from `+0x12d/+0x12f`
- `000d:a3b7` -> vtable `+0x0c` payload from `+0x74f/+0x751`
- Global data labels were promoted for the callback lane (where symbolization applies in decompiler views):
- `g_active_dispatch_entry_farptr` at `0x6828`
- callback-state/object globals at `0x4588/0x458c/0x4590/0x4594/0x4595/0x45a6`
- dispatch callback-table pointer at `0x39ca`
### Raw 0007 Gameplay Helper Batch (entity/tile aux state)
- New conservative gameplay-side helper renames (direct analysis from field writes and call structure):