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

Enhance segment coverage ledger and mid-project plan with detailed updates

Browse source 
- Added new binary files for segment coverage in `Crusader.rep/idata/00/~00000006.db/`
- Updated `crusader_segment_coverage_ledger.csv` to reflect new findings and classifications, including:
  - Renamed segments for clarity on allocator mechanics and dispatch entry roles.
  - Adjusted coverage status for segments related to startup/display orchestration and allocator phase finalization.
- Revised `plan-mid.md` to include recent progress on segment recovery and classification, emphasizing the ongoing work on the `0x4588` callback object and related functions.
This commit is contained in:
MaddoScientisto 2026-03-21 20:32:21 +01:00
commit d1222a2a4f
7 changed files with 123 additions and 34 deletions
Download patch file Download diff file Expand all files Collapse all files

36
plan-mid.md
View file

@ -20,30 +20,36 @@ The estimates below are intentionally conservative. They measure verified behavi
- Priority 0 has started: `crusader_segment_coverage_ledger.csv` exists and contains a first-pass 145-row ledger.
- The currently seeded ledger rows are conservative and strongest around seg001, seg004, seg021, seg043, seg080, seg082/083/085, seg091, seg094, and seg095.
- Priority 1 has started on the cache/backend cluster: the seg082 allocator mechanics are now materially recovered (`allocator_head_try_alloc_block`, `allocator_head_free_block`, `allocator_free_block_by_ptr`), and the `0x4588` path now has named lifecycle helpers (`runtime_callback_object_init_once`, `runtime_callback_object_teardown_once`, `runtime_callback_object_phase_finalize`).
- Priority 1 has started on the cache/backend cluster: the seg082 allocator mechanics are now materially recovered (`allocator_head_try_alloc_block`, `allocator_head_free_block`, `allocator_free_block_by_ptr`, `allocator_try_alloc_from_head_table`, `allocator_phase_finalize_pass`), and the `0x4588` path now has named lifecycle helpers (`runtime_callback_object_init_once`, `runtime_callback_object_teardown_once`).
- The `0x4588` blocker is tighter than before: `000a:b988` boundary repair now includes both callback sync callsites (`000a:b9e5` / `000a:ba66`) inside one real function body, `000d:9d5e` / `000d:a3b7` are confirmed inside `entity_cleanup_resources_and_dispatch`, and adjacent helpers are now clarified as `allocator_head_finalize_sweep` (`0009:a961`), `video_bios_state_snapshot` (`000a:4a1f`), and `video_mode_set_and_record_state` (`000a:4972`). Concrete subsystem identity is still unresolved.
- A larger MCP rename batch completed for cleanup callees: `palette_buffer_alloc_and_init_256` (`0009:7853`), `file_handle_alloc_init_and_open` (`0009:1c3a`), `file_handle_open_with_mode` (`0009:1d6a`), `surface_release_internal` (`0009:8d7b`), `surface_release_and_maybe_free` (`0009:8e0a`), and `sprite_redraw_global_if_active` (`000d:9231`). This reduces `entity_cleanup_resources_and_dispatch` ambiguity on file/surface/palette teardown paths.
- The previously missing `000d:7e00` function object is now recovered and named `entity_dispatch_entry_init_runtime_state`, with paired destructor `entity_dispatch_entry_release_runtime_state` at `000d:8078`. Adjacent missing helpers `0003:a880` and `0003:b8e2` were also recovered, with `0003:b8e2` promoted to `far_buffer_alloc_with_mode_flags`.
- Additional helper stabilization now covers seg061/064/076: `vga_palette_read` (`0009:6ec7`) is confirmed alongside existing palette write/free paths, `timer_entity_enable_wrapper` (`0008:d3ba`) is named, and seg064 one-shot gate helpers around `0x3b72/0x3b73` are documented with conservative comments while keeping speculative naming deferred.
- Constructor-lane semantics tightened further: `entity_set_update_period_and_reschedule` (`0008:d27e`) and `palette_buffer_alloc_copy_from_source` (`0009:7905`) are now named, and both `0x4588` callback emit callsites (`000d:9d5e`, `000d:a3b7`) now have explicit payload-pair annotations in disassembly.
- The seg082 allocator table structure is now pinned down as the allocator head table at `0x8724` and active head count at `0x879c`, and the old structural helpers at `0009:b06b` / `0009:b1c3` are now promoted to `allocator_try_alloc_from_head_table` and `allocator_phase_finalize_pass`.
- New caller-side seg138 evidence now exists at `FUN_000d_938c` (`000d:938c-000d:9583`): it builds one scratch-palette dispatch entry (`kind 0x3c`) and one current-palette dispatch entry (`kind 0x14`) through `entity_dispatch_entry_init_runtime_state`, waits for each entry's active flag to clear, then redraws the global sprite path and dispatches through the input object's vtable slot `+0x08`. This narrows the open lane to presentation/dispatch semantics without yet justifying a concrete subsystem rename.
- seg137 is now promoted from `Foothold` to `Partial`: direct MCP recovery stabilized a coherent palette/dispatch-entry helper family with safe renames for all-black, all-white, arbitrary-RGB, grayscale, black-state, and solid-color state builders around the same `entity_dispatch_entry_init_runtime_state` lane. The remaining gap is the higher-level event/script meaning of those helpers, not the local mechanics.
- seg005 and seg136 now have new high-value footholds: `FUN_0004_60c0` is recovered as a startup/display orchestration handoff that drives the seg137 palette helper family, validates an object through vtable `+0x0c`, creates the default active dispatch entry, programs mouse state, and then hands off into `0004:1e00`; nearby seg136 helpers are now stabilized as `active_dispatch_entry_mark_enabled`, `active_dispatch_entry_mark_disabled`, and `active_dispatch_entry_create_default`.
- The downstream seg005 handoff body is now also classified further: `FUN_0004_1e00` (`0004:1e00-0004:2420`) is a non-return startup/display transition driver with confirmed use of `vga_palette_set_all_black`, `animation_ctor_variant_b`, `sprite_node_get_or_traverse`, seg064 gate helpers, the `0x2bd8` vtable lane, and the `0x4aa/0x7e22` resource/object lane. The remaining work is naming the exact state label, not repairing the structure.
- seg126 now has a deeper foothold instead of only wrapper coverage: `FUN_000c_7412`, `FUN_000c_c9f4`, and the newly recovered `FUN_000c_c890` now show a coherent pre-entry preparation lane that releases tracked objects, resets palette/render state, conditionally constructs animation state at `DS:0x6341`, and then feeds the same `FUN_0004_1e00` startup/display transition from the seg076 side.
### Current Focus
1. Finish Priority 0 refinement by promoting more exact segment rows where notes already support a verified foothold.
2. Continue the Priority 1 pass by tracing remaining caller-side `0x4588` / `0009:b1c3` object-role evidence now that the `000d:7e00` constructor/destructor path is readable.
2. Continue the Priority 1 pass by tracing the higher-level startup/display callers, branch outcomes, and pre-entry object lanes that stitch the seg137 palette helper family into the wider `0x4588` / dispatch-entry object-role lane.
### Next Resume Point
1. Update the ledger for any additional exact segment anchors found in the reset/cache or render-path notes.
2. Continue caller-role classification inside `entity_cleanup_resources_and_dispatch` (contains both `000d:9d5e` and `000d:a3b7`) and map how it relates to `runtime_callback_object_phase_finalize` + `allocator_head_finalize_sweep`.
3. Promote additional field-level names inside `entity_cleanup_resources_and_dispatch` and `entity_dispatch_entry_init_runtime_state` now that update-period/palette-copy helpers are named.
4. Classify remaining callback-role semantics for the `0x4588` object (especially vtable `+0x08` vs `+0x0c` intent and phase/event meaning) using the confirmed payload pairs `+0x12d/+0x12f` and `+0x74f/+0x751`.
5. Continue `ASYLUM.24` only after the `0x4588` path has no further cheap wins.
1. Classify the remaining seg126 pre-entry object lanes around `FUN_000c_c890`, especially tracked pairs `0x8c5c`, `0x8c60`, local state gates `0x62fe` / `0x31a2`, and animation buffer/object `DS:0x6341`.
2. Continue caller-role classification inside `entity_cleanup_resources_and_dispatch` (contains both `000d:9d5e` and `000d:a3b7`) and map how it relates to `FUN_000d_938c`, `FUN_0004_60c0`, `FUN_000c_7412`, `FUN_000c_c890`, and the seg136/seg137 active-dispatch helper family.
3. Clarify the object validated through `FUN_0004_60c0` vtable slot `+0x0c` and how it relates to the sprite/object lane at `0x4f38`, the `0x2bd8` vtable callbacks used inside `FUN_0004_1e00`, and the tracked object pairs released by `FUN_000c_c890`.
4. Revisit `allocator_phase_finalize_pass` only where it intersects the same callback object semantics, rather than broad allocator mechanics that are already sufficiently constrained.
5. Continue `ASYLUM.24` only after the `0x4588` / dispatch-entry lane and `0004:1e00` transition path have no further cheap wins.
### Headline Estimate
- Overall useful decompilation progress: about 25%
- Reasonable uncertainty band: about 20% to 30%
- Overall useful decompilation progress: about 30%
- Reasonable uncertainty band: about 25% to 35%
This is the best single-number estimate for the full game right now.
@ -52,8 +58,8 @@ This is the best single-number estimate for the full game right now.
| Metric | Estimate | Meaning |
|---|---:|---|
| Top 100 far-call target coverage | about 80% | Roughly 80 of the top 100 most-called far-call targets have been named or materially classified |
| Whole-program behavioral coverage | about 25% | Verified subsystem and function understanding across the executable |
| Segment spread with meaningful analysis | about 10% to 15% | Segments with more than a trivial foothold or isolated note |
| Whole-program behavioral coverage | about 30% | Verified subsystem and function understanding across the executable |
| Segment spread with meaningful analysis | about 14% to 20% | Segments with more than a trivial foothold or isolated note |
| Tooling maturity for continued work | about 75% | Core repair, lookup, and fallback automation needed for continued progress |
### Why These Numbers Differ
@ -127,7 +133,7 @@ This is the best single-number estimate for the full game right now.
### High-Value Classification Gaps
- The object rooted at `0x4588` is still not classified well enough to safely rename `0009:b1c3`.
- The object rooted at `0x4588` is still not classified well enough to safely rename the callback object itself beyond the current allocator-side glue names.
- `ASYLUM.24` is only known as an import site, not yet a confidently identified routine.
- Some structural names in the cache/backend/finalize cluster are waiting on object-role confirmation.
@ -194,7 +200,7 @@ Work the newest verified reset-path cluster to closure:
1. Trace more callers of `0009:b06b`.
2. Trace more callers of `FUN_0009_a961`.
3. Classify the object rooted at `0x4588`.
4. Revisit `0009:b1c3` once the object role is clearer.
4. Revisit `allocator_phase_finalize_pass` once the object role is clearer.
This is currently the best next analysis target because it closes a live cluster that already has fresh verified work around it.
@ -265,7 +271,7 @@ Use these status values for subsystem maturity:
### Queue A: Highest Leverage
1. Expand the first-pass segment coverage ledger beyond the currently seeded segments.
2. Trace `0009:b06b`, `FUN_0009_a961`, and `0009:b1c3`.
2. Trace `allocator_try_alloc_from_head_table`, `allocator_head_finalize_sweep`, and `allocator_phase_finalize_pass`.
3. Identify `ASYLUM.24`.
### Queue B: Repair And Stabilize
@ -309,5 +315,5 @@ Update this file when one of the following happens:
- the overall estimate changes materially,
- a new subsystem reaches behavioral or stable status,
- a major blocker such as `0x4588`, `0009:b1c3`, or `ASYLUM.24` is resolved,
- a major blocker such as `0x4588`, `allocator_phase_finalize_pass`, or `ASYLUM.24` is resolved,
- or the segment coverage ledger is created and becomes the new primary progress source.