paavohtl Claude Opus 4.6 (1M context) commited on
Commit
1b0dae9
·
1 Parent(s): d350890

feat: add structured address registry with runtime pointer identification

Browse files

Replace flat pub const address definitions with define_addresses! macro
that generates both compile-time constants and a global queryable registry
via the inventory crate. ~200 addresses now have structured metadata
(kind, calling convention, class name).

Key additions:
- registry.rs: AddrEntry types, sorted lookup table, query API
(lookup_va, vtable_class_name, format_va, detect_pointer)
- define_addresses! macro: class blocks group vtable+ctor+vmethods,
standalone entries for functions/globals/data
- detect_pointer() in mem.rs: identifies static addresses by name,
heap objects by vtable class name
- classify_pointer() detail strings now include registry names

Eliminates three duplicated vtable→name mappings in snapshot.rs,
debugui/app.rs, and validation/mod.rs. All 488 existing va::* call
sites compile unchanged.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Cargo.lock CHANGED
@@ -986,6 +986,15 @@ dependencies = [
986
  "hashbrown",
987
  ]
988
 
 
 
 
 
 
 
 
 
 
989
  [[package]]
990
  name = "jni"
991
  version = "0.21.1"
@@ -1466,6 +1475,7 @@ version = "0.1.0"
1466
  dependencies = [
1467
  "heapless",
1468
  "hound",
 
1469
  "openwa-debug-proto",
1470
  "windows",
1471
  "windows-sys 0.59.0",
 
986
  "hashbrown",
987
  ]
988
 
989
+ [[package]]
990
+ name = "inventory"
991
+ version = "0.3.22"
992
+ source = "registry+https://github.com/rust-lang/crates.io-index"
993
+ checksum = "009ae045c87e7082cb72dab0ccd01ae075dd00141ddc108f43a0ea150a9e7227"
994
+ dependencies = [
995
+ "rustversion",
996
+ ]
997
+
998
  [[package]]
999
  name = "jni"
1000
  version = "0.21.1"
 
1475
  dependencies = [
1476
  "heapless",
1477
  "hound",
1478
+ "inventory",
1479
  "openwa-debug-proto",
1480
  "windows",
1481
  "windows-sys 0.59.0",
crates/openwa-core/Cargo.toml CHANGED
@@ -7,6 +7,7 @@ description = "Core library for Worms Armageddon reverse engineering — types,
7
  [dependencies]
8
  heapless = "0.9"
9
  hound = "3"
 
10
  openwa-debug-proto = { path = "../openwa-debug-proto" }
11
 
12
  [target.'cfg(target_os = "windows")'.dependencies]
 
7
  [dependencies]
8
  heapless = "0.9"
9
  hound = "3"
10
+ inventory = "0.3.22"
11
  openwa-debug-proto = { path = "../openwa-debug-proto" }
12
 
13
  [target.'cfg(target_os = "windows")'.dependencies]
crates/openwa-core/src/address.rs CHANGED
The diff for this file is too large to render. See raw diff
 
crates/openwa-core/src/lib.rs CHANGED
@@ -13,6 +13,10 @@
13
  #![allow(clippy::empty_line_after_doc_comments)]
14
  #![allow(clippy::doc_lazy_continuation)]
15
 
 
 
 
 
16
  #[macro_use]
17
  pub mod macros;
18
 
@@ -26,6 +30,7 @@ pub mod render;
26
 
27
  pub mod address;
28
  pub mod fixed;
 
29
  pub mod log;
30
  pub mod mem;
31
  pub mod rebase;
 
13
  #![allow(clippy::empty_line_after_doc_comments)]
14
  #![allow(clippy::doc_lazy_continuation)]
15
 
16
+ // Re-export inventory so the define_addresses! macro can reference it
17
+ // from any crate that depends on openwa-core.
18
+ pub use inventory;
19
+
20
  #[macro_use]
21
  pub mod macros;
22
 
 
30
 
31
  pub mod address;
32
  pub mod fixed;
33
+ pub mod registry;
34
  pub mod log;
35
  pub mod mem;
36
  pub mod rebase;
crates/openwa-core/src/macros.rs CHANGED
@@ -1,3 +1,154 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
  /// Call a virtual method through a typed vtable pointer.
2
  ///
3
  /// Assumes `$obj` is a raw pointer to a struct whose first field `vtable`
 
1
+ /// Define known WA.exe addresses and register them in the global address registry.
2
+ ///
3
+ /// Supports two forms:
4
+ ///
5
+ /// **Class blocks** — group vtable, constructor, and vtable methods under a class name:
6
+ /// ```ignore
7
+ /// define_addresses! {
8
+ /// class "CTask" {
9
+ /// /// CTask vtable - 7 virtual method pointers
10
+ /// vtable CTASK_VTABLE = 0x0066_9F8C;
11
+ /// /// CTask constructor
12
+ /// ctor/Stdcall CTASK_CONSTRUCTOR = 0x0056_25A0;
13
+ /// vmethod CTASK_VT0_INIT = 0x0056_2710;
14
+ /// }
15
+ /// }
16
+ /// ```
17
+ ///
18
+ /// **Standalone entries** — functions and globals not belonging to a class:
19
+ /// ```ignore
20
+ /// define_addresses! {
21
+ /// /// Game PRNG
22
+ /// fn/Fastcall ADVANCE_GAME_RNG = 0x0053_F320;
23
+ /// global G_GAME_SESSION = 0x007A_0884;
24
+ /// }
25
+ /// ```
26
+ ///
27
+ /// Each entry generates:
28
+ /// 1. A `pub const NAME: u32 = value;` in the current scope
29
+ /// 2. An `inventory::submit!(AddrEntry { ... })` for global registry collection
30
+ ///
31
+ /// Entry kinds: `vtable`, `ctor`, `vmethod`, `fn`, `global`, `string`, `data`
32
+ ///
33
+ /// Optional calling convention suffix: `/Stdcall`, `/Thiscall`, `/Fastcall`, `/Cdecl`, `/Usercall`
34
+ #[macro_export]
35
+ macro_rules! define_addresses {
36
+ // Main entry point: parse a sequence of class blocks and standalone entries
37
+ (@items $($rest:tt)*) => {
38
+ $crate::define_addresses!(@parse $($rest)*);
39
+ };
40
+
41
+ // --- Class block ---
42
+ (@parse class $class_name:literal { $($body:tt)* } $($rest:tt)*) => {
43
+ $crate::define_addresses!(@class_items $class_name $($body)*);
44
+ $crate::define_addresses!(@parse $($rest)*);
45
+ };
46
+
47
+ // --- Standalone entries (with doc + calling conv) ---
48
+ (@parse $(#[doc = $doc:literal])* fn / $conv:ident $name:ident = $value:expr; $($rest:tt)*) => {
49
+ $(#[doc = $doc])*
50
+ pub const $name: u32 = $value;
51
+ $crate::define_addresses!(@submit $name, $value, Function, Some($crate::registry::CallingConv::$conv), None, concat!($($doc,)* ""));
52
+ $crate::define_addresses!(@parse $($rest)*);
53
+ };
54
+ // Standalone fn without calling conv
55
+ (@parse $(#[doc = $doc:literal])* fn $name:ident = $value:expr; $($rest:tt)*) => {
56
+ $(#[doc = $doc])*
57
+ pub const $name: u32 = $value;
58
+ $crate::define_addresses!(@submit $name, $value, Function, None, None, concat!($($doc,)* ""));
59
+ $crate::define_addresses!(@parse $($rest)*);
60
+ };
61
+ // Standalone global
62
+ (@parse $(#[doc = $doc:literal])* global $name:ident = $value:expr; $($rest:tt)*) => {
63
+ $(#[doc = $doc])*
64
+ pub const $name: u32 = $value;
65
+ $crate::define_addresses!(@submit $name, $value, Global, None, None, concat!($($doc,)* ""));
66
+ $crate::define_addresses!(@parse $($rest)*);
67
+ };
68
+ // Standalone string literal
69
+ (@parse $(#[doc = $doc:literal])* string $name:ident = $value:expr; $($rest:tt)*) => {
70
+ $(#[doc = $doc])*
71
+ pub const $name: u32 = $value;
72
+ $crate::define_addresses!(@submit $name, $value, StringLiteral, None, None, concat!($($doc,)* ""));
73
+ $crate::define_addresses!(@parse $($rest)*);
74
+ };
75
+ // Standalone data table
76
+ (@parse $(#[doc = $doc:literal])* data $name:ident = $value:expr; $($rest:tt)*) => {
77
+ $(#[doc = $doc])*
78
+ pub const $name: u32 = $value;
79
+ $crate::define_addresses!(@submit $name, $value, DataTable, None, None, concat!($($doc,)* ""));
80
+ $crate::define_addresses!(@parse $($rest)*);
81
+ };
82
+
83
+ // Base case: empty
84
+ (@parse) => {};
85
+
86
+ // --- Class body items ---
87
+ // vtable
88
+ (@class_items $class_name:literal $(#[doc = $doc:literal])* vtable $name:ident = $value:expr; $($rest:tt)*) => {
89
+ $(#[doc = $doc])*
90
+ pub const $name: u32 = $value;
91
+ $crate::define_addresses!(@submit $name, $value, Vtable, None, Some($class_name), concat!($($doc,)* ""));
92
+ $crate::define_addresses!(@class_items $class_name $($rest)*);
93
+ };
94
+ // ctor with calling conv
95
+ (@class_items $class_name:literal $(#[doc = $doc:literal])* ctor / $conv:ident $name:ident = $value:expr; $($rest:tt)*) => {
96
+ $(#[doc = $doc])*
97
+ pub const $name: u32 = $value;
98
+ $crate::define_addresses!(@submit $name, $value, Constructor, Some($crate::registry::CallingConv::$conv), Some($class_name), concat!($($doc,)* ""));
99
+ $crate::define_addresses!(@class_items $class_name $($rest)*);
100
+ };
101
+ // ctor without calling conv
102
+ (@class_items $class_name:literal $(#[doc = $doc:literal])* ctor $name:ident = $value:expr; $($rest:tt)*) => {
103
+ $(#[doc = $doc])*
104
+ pub const $name: u32 = $value;
105
+ $crate::define_addresses!(@submit $name, $value, Constructor, None, Some($class_name), concat!($($doc,)* ""));
106
+ $crate::define_addresses!(@class_items $class_name $($rest)*);
107
+ };
108
+ // vmethod
109
+ (@class_items $class_name:literal $(#[doc = $doc:literal])* vmethod $name:ident = $value:expr; $($rest:tt)*) => {
110
+ $(#[doc = $doc])*
111
+ pub const $name: u32 = $value;
112
+ $crate::define_addresses!(@submit $name, $value, VtableMethod, None, Some($class_name), concat!($($doc,)* ""));
113
+ $crate::define_addresses!(@class_items $class_name $($rest)*);
114
+ };
115
+ // fn inside class (with calling conv)
116
+ (@class_items $class_name:literal $(#[doc = $doc:literal])* fn / $conv:ident $name:ident = $value:expr; $($rest:tt)*) => {
117
+ $(#[doc = $doc])*
118
+ pub const $name: u32 = $value;
119
+ $crate::define_addresses!(@submit $name, $value, Function, Some($crate::registry::CallingConv::$conv), Some($class_name), concat!($($doc,)* ""));
120
+ $crate::define_addresses!(@class_items $class_name $($rest)*);
121
+ };
122
+ // fn inside class (without calling conv)
123
+ (@class_items $class_name:literal $(#[doc = $doc:literal])* fn $name:ident = $value:expr; $($rest:tt)*) => {
124
+ $(#[doc = $doc])*
125
+ pub const $name: u32 = $value;
126
+ $crate::define_addresses!(@submit $name, $value, Function, None, Some($class_name), concat!($($doc,)* ""));
127
+ $crate::define_addresses!(@class_items $class_name $($rest)*);
128
+ };
129
+ // Base case: empty class body
130
+ (@class_items $class_name:literal) => {};
131
+
132
+ // --- Submit helper ---
133
+ (@submit $name:ident, $value:expr, $kind:ident, $conv:expr, $class:expr, $doc:expr) => {
134
+ $crate::inventory::submit! {
135
+ $crate::registry::AddrEntry {
136
+ va: $value,
137
+ name: stringify!($name),
138
+ kind: $crate::registry::AddrKind::$kind,
139
+ calling_conv: $conv,
140
+ class_name: $class,
141
+ doc: $doc,
142
+ }
143
+ }
144
+ };
145
+
146
+ // Top-level entry point
147
+ ($($tokens:tt)*) => {
148
+ $crate::define_addresses!(@parse $($tokens)*);
149
+ };
150
+ }
151
+
152
  /// Call a virtual method through a typed vtable pointer.
153
  ///
154
  /// Assumes `$obj` is a raw pointer to a struct whose first field `vtable`
crates/openwa-core/src/mem.rs CHANGED
@@ -1,6 +1,7 @@
1
  //! Memory inspection utilities — pointer classification and safe read checks.
2
 
3
  use crate::address::va;
 
4
  use openwa_debug_proto::{PointerInfo, PointerKind};
5
 
6
  #[cfg(target_os = "windows")]
@@ -37,11 +38,12 @@ pub unsafe fn classify_pointer(value: u32, delta: u32) -> Option<PointerInfo> {
37
 
38
  // .rdata → Vtable (likely vtable or function pointer table)
39
  if (va::RDATA_START..va::DATA_START).contains(&ghidra_val) {
 
40
  let detail = if can_read(value, 4) {
41
  let vt0 = *(value as *const u32);
42
- Some(format!("vt[0]=ghidra:0x{:08X}", vt0.wrapping_sub(delta)))
43
  } else {
44
- Some("(unreadable)".to_string())
45
  };
46
  return Some(PointerInfo {
47
  offset: 0, // caller fills this in
@@ -54,23 +56,31 @@ pub unsafe fn classify_pointer(value: u32, delta: u32) -> Option<PointerInfo> {
54
 
55
  // .text → Code
56
  if (va::TEXT_START..=va::TEXT_END).contains(&ghidra_val) {
 
 
 
 
 
 
 
57
  return Some(PointerInfo {
58
  offset: 0,
59
  raw_value: value,
60
  ghidra_value: ghidra_val,
61
  kind: PointerKind::Code,
62
- detail: None,
63
  });
64
  }
65
 
66
  // .data/.bss → Data
67
  if (va::DATA_START..va::DATA_END).contains(&ghidra_val) {
 
68
  return Some(PointerInfo {
69
  offset: 0,
70
  raw_value: value,
71
  ghidra_value: ghidra_val,
72
  kind: PointerKind::Data,
73
- detail: None,
74
  });
75
  }
76
 
@@ -81,15 +91,18 @@ pub unsafe fn classify_pointer(value: u32, delta: u32) -> Option<PointerInfo> {
81
 
82
  // Object — heap pointer whose first DWORD is a vtable
83
  if (va::RDATA_START..va::DATA_START).contains(&ghidra_first) {
84
- let detail = if can_read(first, 4) {
85
- let vt0 = *(first as *const u32);
86
- Some(format!(
87
- "vtable=ghidra:0x{:08X} vt[0]=ghidra:0x{:08X}",
88
- ghidra_first,
89
- vt0.wrapping_sub(delta)
90
- ))
91
- } else {
92
- Some(format!("vtable=ghidra:0x{:08X} vt[0]=?", ghidra_first))
 
 
 
93
  };
94
  return Some(PointerInfo {
95
  offset: 0,
@@ -113,6 +126,92 @@ pub unsafe fn classify_pointer(value: u32, delta: u32) -> Option<PointerInfo> {
113
  None
114
  }
115
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
116
  /// Classify all DWORD-aligned values in a byte slice.
117
  ///
118
  /// Returns a vec of `PointerInfo` with offsets filled in relative to `base_offset`.
 
1
  //! Memory inspection utilities — pointer classification and safe read checks.
2
 
3
  use crate::address::va;
4
+ use crate::registry;
5
  use openwa_debug_proto::{PointerInfo, PointerKind};
6
 
7
  #[cfg(target_os = "windows")]
 
38
 
39
  // .rdata → Vtable (likely vtable or function pointer table)
40
  if (va::RDATA_START..va::DATA_START).contains(&ghidra_val) {
41
+ let name = registry::format_va(ghidra_val);
42
  let detail = if can_read(value, 4) {
43
  let vt0 = *(value as *const u32);
44
+ Some(format!("{} vt[0]=ghidra:0x{:08X}", name, vt0.wrapping_sub(delta)))
45
  } else {
46
+ Some(format!("{} (unreadable)", name))
47
  };
48
  return Some(PointerInfo {
49
  offset: 0, // caller fills this in
 
56
 
57
  // .text → Code
58
  if (va::TEXT_START..=va::TEXT_END).contains(&ghidra_val) {
59
+ let detail = registry::lookup_va(ghidra_val).map(|r| {
60
+ if r.offset == 0 {
61
+ r.entry.name.to_string()
62
+ } else {
63
+ format!("{}+0x{:X}", r.entry.name, r.offset)
64
+ }
65
+ });
66
  return Some(PointerInfo {
67
  offset: 0,
68
  raw_value: value,
69
  ghidra_value: ghidra_val,
70
  kind: PointerKind::Code,
71
+ detail,
72
  });
73
  }
74
 
75
  // .data/.bss → Data
76
  if (va::DATA_START..va::DATA_END).contains(&ghidra_val) {
77
+ let detail = registry::lookup_va_exact(ghidra_val).map(|e| e.name.to_string());
78
  return Some(PointerInfo {
79
  offset: 0,
80
  raw_value: value,
81
  ghidra_value: ghidra_val,
82
  kind: PointerKind::Data,
83
+ detail,
84
  });
85
  }
86
 
 
91
 
92
  // Object — heap pointer whose first DWORD is a vtable
93
  if (va::RDATA_START..va::DATA_START).contains(&ghidra_first) {
94
+ let class = registry::vtable_class_name(ghidra_first);
95
+ let detail = match class {
96
+ Some(name) => Some(format!("{}* (vtable=0x{:08X})", name, ghidra_first)),
97
+ None if can_read(first, 4) => {
98
+ let vt0 = *(first as *const u32);
99
+ Some(format!(
100
+ "vtable=ghidra:0x{:08X} vt[0]=ghidra:0x{:08X}",
101
+ ghidra_first,
102
+ vt0.wrapping_sub(delta)
103
+ ))
104
+ }
105
+ None => Some(format!("vtable=ghidra:0x{:08X} vt[0]=?", ghidra_first)),
106
  };
107
  return Some(PointerInfo {
108
  offset: 0,
 
126
  None
127
  }
128
 
129
+ /// Rich pointer identification result.
130
+ #[derive(Debug)]
131
+ pub struct KnownPointer {
132
+ /// Raw runtime value.
133
+ pub raw_value: u32,
134
+ /// Ghidra VA (raw_value - ASLR delta).
135
+ pub ghidra_value: u32,
136
+ /// Memory segment classification.
137
+ pub segment: PointerKind,
138
+ /// Human-readable name (e.g., "CTASK_CONSTRUCTOR" or "CTaskWorm*").
139
+ pub name: Option<String>,
140
+ /// Class name if this is a vtable or an object with a known vtable.
141
+ pub class_name: Option<&'static str>,
142
+ /// Extra context detail.
143
+ pub detail: Option<String>,
144
+ }
145
+
146
+ /// Given an arbitrary runtime pointer value, identify what it is.
147
+ ///
148
+ /// Combines the static address registry with segment-based classification
149
+ /// and vtable-based object identification for heap pointers.
150
+ ///
151
+ /// `delta` is `runtime_base - 0x400000` (the ASLR offset).
152
+ #[cfg(target_os = "windows")]
153
+ pub unsafe fn detect_pointer(value: u32, delta: u32) -> Option<KnownPointer> {
154
+ if value == 0 || value < 0x10000 {
155
+ return None;
156
+ }
157
+
158
+ let ghidra_val = value.wrapping_sub(delta);
159
+
160
+ // 1. Check static registry for a known address
161
+ if let Some(resolved) = registry::lookup_va(ghidra_val) {
162
+ if resolved.offset < 0x1000 {
163
+ let segment = match resolved.entry.kind {
164
+ registry::AddrKind::Vtable | registry::AddrKind::VtableMethod => {
165
+ PointerKind::Vtable
166
+ }
167
+ registry::AddrKind::Function | registry::AddrKind::Constructor => {
168
+ PointerKind::Code
169
+ }
170
+ _ => PointerKind::Data,
171
+ };
172
+ let name = if resolved.offset == 0 {
173
+ resolved.entry.name.to_string()
174
+ } else {
175
+ format!("{}+0x{:X}", resolved.entry.name, resolved.offset)
176
+ };
177
+ return Some(KnownPointer {
178
+ raw_value: value,
179
+ ghidra_value: ghidra_val,
180
+ segment,
181
+ name: Some(name),
182
+ class_name: resolved.entry.class_name,
183
+ detail: None,
184
+ });
185
+ }
186
+ }
187
+
188
+ // 2. If heap pointer, check if first DWORD is a known vtable
189
+ if can_read(value, 4) {
190
+ let first = *(value as *const u32);
191
+ let ghidra_first = first.wrapping_sub(delta);
192
+ if let Some(class) = registry::vtable_class_name(ghidra_first) {
193
+ return Some(KnownPointer {
194
+ raw_value: value,
195
+ ghidra_value: ghidra_val,
196
+ segment: PointerKind::Object,
197
+ name: Some(format!("{}*", class)),
198
+ class_name: Some(class),
199
+ detail: Some(format!("vtable=0x{:08X}", ghidra_first)),
200
+ });
201
+ }
202
+ }
203
+
204
+ // 3. Fall back to segment-based classification
205
+ classify_pointer(value, delta).map(|info| KnownPointer {
206
+ raw_value: info.raw_value,
207
+ ghidra_value: info.ghidra_value,
208
+ segment: info.kind,
209
+ name: None,
210
+ class_name: None,
211
+ detail: info.detail,
212
+ })
213
+ }
214
+
215
  /// Classify all DWORD-aligned values in a byte slice.
216
  ///
217
  /// Returns a vec of `PointerInfo` with offsets filled in relative to `base_offset`.
crates/openwa-core/src/registry.rs ADDED
@@ -0,0 +1,341 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ //! Structured address registry for WA.exe reverse engineering.
2
+ //!
3
+ //! Provides a queryable database of known addresses (functions, vtables,
4
+ //! globals, etc.) collected from distributed `define_addresses!` invocations
5
+ //! across the codebase. Enables runtime pointer identification for debug tools.
6
+ //!
7
+ //! # Usage
8
+ //!
9
+ //! ```ignore
10
+ //! use openwa_core::registry;
11
+ //!
12
+ //! // Look up a Ghidra VA
13
+ //! if let Some(resolved) = registry::lookup_va(0x0056_25A0) {
14
+ //! println!("{}", resolved.entry.name); // "CTASK_CONSTRUCTOR"
15
+ //! }
16
+ //!
17
+ //! // Identify a vtable
18
+ //! if let Some(class) = registry::vtable_class_name(0x0066_9F8C) {
19
+ //! println!("{}", class); // "CTask"
20
+ //! }
21
+ //!
22
+ //! // Format for debug output
23
+ //! println!("{}", registry::format_va(0x0056_25A4)); // "CTASK_CONSTRUCTOR+0x4 (0x5625A4)"
24
+ //! ```
25
+
26
+ use std::sync::OnceLock;
27
+
28
+ /// What kind of known address this is.
29
+ #[derive(Debug, Clone, Copy, PartialEq, Eq)]
30
+ pub enum AddrKind {
31
+ /// A regular function.
32
+ Function,
33
+ /// A class constructor.
34
+ Constructor,
35
+ /// A vtable pointer table in .rdata.
36
+ Vtable,
37
+ /// A specific method within a vtable.
38
+ VtableMethod,
39
+ /// A global variable in .data/.bss.
40
+ Global,
41
+ /// A string literal in .rdata.
42
+ StringLiteral,
43
+ /// A data table (lookup table, constant array, etc.).
44
+ DataTable,
45
+ }
46
+
47
+ /// Calling convention of a function or constructor.
48
+ #[derive(Debug, Clone, Copy, PartialEq, Eq)]
49
+ pub enum CallingConv {
50
+ Stdcall,
51
+ Thiscall,
52
+ Fastcall,
53
+ Cdecl,
54
+ /// Non-standard register usage (e.g., ESI/EDI params).
55
+ Usercall,
56
+ }
57
+
58
+ /// A single entry in the address registry.
59
+ ///
60
+ /// Created by `define_addresses!` and collected globally via `inventory`.
61
+ #[derive(Debug, Clone, Copy)]
62
+ pub struct AddrEntry {
63
+ /// Ghidra virtual address (image base 0x400000).
64
+ pub va: u32,
65
+ /// Constant name (e.g., "CTASK_CONSTRUCTOR").
66
+ pub name: &'static str,
67
+ /// What kind of address this is.
68
+ pub kind: AddrKind,
69
+ /// Calling convention (for functions/constructors).
70
+ pub calling_conv: Option<CallingConv>,
71
+ /// Owning class name (e.g., "CTask"), if part of a class block.
72
+ pub class_name: Option<&'static str>,
73
+ /// Brief description from doc comment.
74
+ pub doc: &'static str,
75
+ }
76
+
77
+ inventory::collect!(AddrEntry);
78
+
79
+ /// Result of looking up a pointer in the registry.
80
+ #[derive(Debug)]
81
+ pub struct ResolvedAddr {
82
+ /// The matched registry entry.
83
+ pub entry: &'static AddrEntry,
84
+ /// Offset from the entry's VA (0 = exact match).
85
+ pub offset: u32,
86
+ }
87
+
88
+ // --- Sorted table (built once at first query) ---
89
+
90
+ static SORTED: OnceLock<Vec<&'static AddrEntry>> = OnceLock::new();
91
+
92
+ fn sorted_entries() -> &'static [&'static AddrEntry] {
93
+ SORTED.get_or_init(|| {
94
+ let mut v: Vec<&'static AddrEntry> = inventory::iter::<AddrEntry>.into_iter().collect();
95
+ v.sort_by_key(|e| e.va);
96
+ v
97
+ })
98
+ }
99
+
100
+ // --- Query API ---
101
+
102
+ /// Look up a Ghidra VA. Returns the exact match or the nearest entry below.
103
+ ///
104
+ /// For near-misses, `offset` indicates how far past the entry the VA is.
105
+ /// Returns `None` if below all known entries or the offset exceeds 0x10000
106
+ /// (likely a different symbol).
107
+ pub fn lookup_va(ghidra_va: u32) -> Option<ResolvedAddr> {
108
+ let table = sorted_entries();
109
+ match table.binary_search_by_key(&ghidra_va, |e| e.va) {
110
+ Ok(i) => Some(ResolvedAddr {
111
+ entry: table[i],
112
+ offset: 0,
113
+ }),
114
+ Err(i) if i > 0 => {
115
+ let entry = table[i - 1];
116
+ let offset = ghidra_va - entry.va;
117
+ if offset < 0x10000 {
118
+ Some(ResolvedAddr { entry, offset })
119
+ } else {
120
+ None
121
+ }
122
+ }
123
+ _ => None,
124
+ }
125
+ }
126
+
127
+ /// Look up a Ghidra VA, exact match only.
128
+ pub fn lookup_va_exact(ghidra_va: u32) -> Option<&'static AddrEntry> {
129
+ let table = sorted_entries();
130
+ table
131
+ .binary_search_by_key(&ghidra_va, |e| e.va)
132
+ .ok()
133
+ .map(|i| table[i])
134
+ }
135
+
136
+ /// Given a Ghidra vtable address, return the class name.
137
+ ///
138
+ /// Replaces all duplicated `vtable_name()` functions throughout the codebase.
139
+ pub fn vtable_class_name(ghidra_vtable: u32) -> Option<&'static str> {
140
+ lookup_va_exact(ghidra_vtable)
141
+ .filter(|e| e.kind == AddrKind::Vtable)
142
+ .and_then(|e| e.class_name)
143
+ }
144
+
145
+ /// Format a Ghidra VA as a human-readable string.
146
+ ///
147
+ /// - Exact match: `"CTASK_CONSTRUCTOR (0x5625A0)"`
148
+ /// - Near match: `"CTASK_CONSTRUCTOR+0x4 (0x5625A4)"`
149
+ /// - Unknown: `"0x005625A4"`
150
+ pub fn format_va(ghidra_va: u32) -> String {
151
+ match lookup_va(ghidra_va) {
152
+ Some(r) if r.offset == 0 => {
153
+ format!("{} (0x{:X})", r.entry.name, ghidra_va)
154
+ }
155
+ Some(r) => {
156
+ format!(
157
+ "{}+0x{:X} (0x{:X})",
158
+ r.entry.name, r.offset, ghidra_va
159
+ )
160
+ }
161
+ None => format!("0x{:08X}", ghidra_va),
162
+ }
163
+ }
164
+
165
+ /// Iterate all entries of a given kind.
166
+ pub fn entries_by_kind(kind: AddrKind) -> impl Iterator<Item = &'static AddrEntry> {
167
+ sorted_entries().iter().copied().filter(move |e| e.kind == kind)
168
+ }
169
+
170
+ /// Iterate all registered entries (sorted by VA).
171
+ pub fn all_entries() -> impl Iterator<Item = &'static AddrEntry> {
172
+ sorted_entries().iter().copied()
173
+ }
174
+
175
+ /// Return the total number of registered entries.
176
+ pub fn entry_count() -> usize {
177
+ sorted_entries().len()
178
+ }
179
+
180
+ // --- Struct field registry types (for Phase 4 #[derive(FieldRegistry)]) ---
181
+
182
+ /// A known field within a struct.
183
+ #[derive(Debug, Clone, Copy)]
184
+ pub struct FieldEntry {
185
+ /// Offset from struct base.
186
+ pub offset: u32,
187
+ /// Field name (e.g., "rng_state").
188
+ pub name: &'static str,
189
+ /// Field size in bytes.
190
+ pub size: u32,
191
+ /// Brief description.
192
+ pub doc: &'static str,
193
+ }
194
+
195
+ /// Field map for a struct, enabling offset → name lookups.
196
+ #[derive(Debug)]
197
+ pub struct StructFields {
198
+ /// Struct/class name (e.g., "DDGame").
199
+ pub struct_name: &'static str,
200
+ /// Fields sorted by offset.
201
+ pub fields: &'static [FieldEntry],
202
+ }
203
+
204
+ impl StructFields {
205
+ /// Look up the field at an exact offset.
206
+ pub fn field_at(&self, offset: u32) -> Option<&FieldEntry> {
207
+ self.fields
208
+ .binary_search_by_key(&offset, |f| f.offset)
209
+ .ok()
210
+ .map(|i| &self.fields[i])
211
+ }
212
+
213
+ /// Find which field contains the given offset.
214
+ ///
215
+ /// Returns the field and the byte offset within it.
216
+ pub fn field_containing(&self, offset: u32) -> Option<(&FieldEntry, u32)> {
217
+ match self.fields.binary_search_by_key(&offset, |f| f.offset) {
218
+ Ok(i) => Some((&self.fields[i], 0)),
219
+ Err(i) if i > 0 => {
220
+ let f = &self.fields[i - 1];
221
+ if offset < f.offset + f.size {
222
+ Some((f, offset - f.offset))
223
+ } else {
224
+ None
225
+ }
226
+ }
227
+ _ => None,
228
+ }
229
+ }
230
+ }
231
+
232
+ /// Trait for structs that have an auto-generated field registry.
233
+ pub trait HasFieldRegistry {
234
+ fn field_registry() -> &'static StructFields;
235
+ }
236
+
237
+ #[cfg(test)]
238
+ mod tests {
239
+ use super::*;
240
+
241
+ // Test entries defined via the macro
242
+ define_addresses! {
243
+ class "TestClass" {
244
+ /// A test vtable
245
+ vtable TEST_VTABLE = 0x0066_0000;
246
+ ctor/Stdcall TEST_CTOR = 0x0050_0000;
247
+ vmethod TEST_VMETHOD = 0x0050_1000;
248
+ }
249
+
250
+ /// A standalone function
251
+ fn/Fastcall TEST_FUNC = 0x0053_0000;
252
+ global TEST_GLOBAL = 0x007A_0000;
253
+ }
254
+
255
+ #[test]
256
+ fn macro_generates_constants() {
257
+ assert_eq!(TEST_VTABLE, 0x0066_0000);
258
+ assert_eq!(TEST_CTOR, 0x0050_0000);
259
+ assert_eq!(TEST_FUNC, 0x0053_0000);
260
+ assert_eq!(TEST_GLOBAL, 0x007A_0000);
261
+ }
262
+
263
+ #[test]
264
+ fn registry_collects_entries() {
265
+ // The inventory should have collected our test entries
266
+ let count = entry_count();
267
+ assert!(count >= 5, "expected at least 5 entries, got {count}");
268
+ }
269
+
270
+ #[test]
271
+ fn exact_lookup() {
272
+ let entry = lookup_va_exact(0x0066_0000);
273
+ assert!(entry.is_some(), "TEST_VTABLE not found");
274
+ let entry = entry.unwrap();
275
+ assert_eq!(entry.name, "TEST_VTABLE");
276
+ assert_eq!(entry.kind, AddrKind::Vtable);
277
+ assert_eq!(entry.class_name, Some("TestClass"));
278
+ }
279
+
280
+ #[test]
281
+ fn near_lookup() {
282
+ let resolved = lookup_va(0x0066_0004);
283
+ assert!(resolved.is_some());
284
+ let resolved = resolved.unwrap();
285
+ assert_eq!(resolved.entry.name, "TEST_VTABLE");
286
+ assert_eq!(resolved.offset, 4);
287
+ }
288
+
289
+ #[test]
290
+ fn vtable_class_name_lookup() {
291
+ assert_eq!(vtable_class_name(0x0066_0000), Some("TestClass"));
292
+ // Constructor should not match vtable lookup
293
+ assert_eq!(vtable_class_name(0x0050_0000), None);
294
+ }
295
+
296
+ #[test]
297
+ fn format_va_display() {
298
+ let s = format_va(0x0066_0000);
299
+ assert!(s.contains("TEST_VTABLE"), "got: {s}");
300
+
301
+ let s = format_va(0x0066_0004);
302
+ assert!(s.contains("TEST_VTABLE+0x4"), "got: {s}");
303
+
304
+ let s = format_va(0x0000_1234);
305
+ assert_eq!(s, "0x00001234");
306
+ }
307
+
308
+ #[test]
309
+ fn entries_by_kind_filter() {
310
+ let vtables: Vec<_> = entries_by_kind(AddrKind::Vtable).collect();
311
+ assert!(
312
+ vtables.iter().any(|e| e.name == "TEST_VTABLE"),
313
+ "TEST_VTABLE not in vtable list"
314
+ );
315
+ assert!(
316
+ !vtables.iter().any(|e| e.name == "TEST_FUNC"),
317
+ "TEST_FUNC should not be in vtable list"
318
+ );
319
+ }
320
+
321
+ #[test]
322
+ fn struct_fields_lookup() {
323
+ static FIELDS: StructFields = StructFields {
324
+ struct_name: "TestStruct",
325
+ fields: &[
326
+ FieldEntry { offset: 0x00, name: "vtable", size: 4, doc: "" },
327
+ FieldEntry { offset: 0x10, name: "health", size: 4, doc: "" },
328
+ FieldEntry { offset: 0x20, name: "name", size: 16, doc: "" },
329
+ ],
330
+ };
331
+
332
+ assert_eq!(FIELDS.field_at(0x10).unwrap().name, "health");
333
+ assert!(FIELDS.field_at(0x08).is_none());
334
+
335
+ let (f, off) = FIELDS.field_containing(0x22).unwrap();
336
+ assert_eq!(f.name, "name");
337
+ assert_eq!(off, 2);
338
+
339
+ assert!(FIELDS.field_containing(0x30).is_none());
340
+ }
341
+ }
crates/openwa-debugui/src/app.rs CHANGED
@@ -12,33 +12,14 @@ use crate::log;
12
  // Known task types for census display
13
  // ---------------------------------------------------------------------------
14
 
15
- const KNOWN_VTABLES: &[(u32, &str)] = &[
16
- (va::CTASK_WORM_VTABLE, "CTaskWorm"),
17
- (va::CTASK_LAND_VTABLE, "CTaskLand"),
18
- (va::CTASK_TURN_GAME_VTABLE, "CTaskTurnGame"),
19
- (va::CTASK_TEAM_VTABLE, "CTaskTeam"),
20
- (va::CTASK_FILTER_VTABLE, "CTaskFilter"),
21
- (va::CTASK_DIRT_VTABLE, "CTaskDirt"),
22
- (va::CTASK_SPRITE_ANIM_VTABLE, "CTaskSpriteAnim"),
23
- (va::CTASK_CPU_VTABLE, "CTaskCPU"),
24
- (va::CTASK_MISSILE_VTABLE, "CTaskMissile"),
25
- (va::CTASK_MINE_VTABLE, "CTaskMine"),
26
- (va::CTASK_OILDRUM_VTABLE, "CTaskOilDrum"),
27
- (va::CTASK_CRATE_VTABLE, "CTaskCrate"),
28
- (va::CTASK_CLOUD_VTABLE, "CTaskCloud"),
29
- (va::CTASK_SEA_BUBBLE_VTABLE, "CTaskSeaBubble"),
30
- (va::CTASK_FIRE_VTABLE, "CTaskFire"),
31
- ];
32
-
33
  /// Vtables of entities that are created/destroyed every frame (particles,
34
  /// bubbles, etc.). Filtered from the census by default to reduce noise.
35
  const TRANSIENT_VTABLES: &[u32] = &[va::CTASK_SEA_BUBBLE_VTABLE];
36
 
37
  fn vtable_name(runtime_vtable: u32) -> Option<&'static str> {
38
- KNOWN_VTABLES
39
- .iter()
40
- .find(|&&(ghidra_va, _)| rb(ghidra_va) == runtime_vtable)
41
- .map(|&(_, name)| name)
42
  }
43
 
44
  /// Returns a display name for the entity at `addr`.
 
12
  // Known task types for census display
13
  // ---------------------------------------------------------------------------
14
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
15
  /// Vtables of entities that are created/destroyed every frame (particles,
16
  /// bubbles, etc.). Filtered from the census by default to reduce noise.
17
  const TRANSIENT_VTABLES: &[u32] = &[va::CTASK_SEA_BUBBLE_VTABLE];
18
 
19
  fn vtable_name(runtime_vtable: u32) -> Option<&'static str> {
20
+ let delta = rb(va::IMAGE_BASE).wrapping_sub(va::IMAGE_BASE);
21
+ let ghidra_va = runtime_vtable.wrapping_sub(delta);
22
+ openwa_core::registry::vtable_class_name(ghidra_va)
 
23
  }
24
 
25
  /// Returns a display name for the entity at `addr`.
crates/openwa-wormkit/src/snapshot.rs CHANGED
@@ -156,22 +156,5 @@ pub unsafe fn capture() -> String {
156
  }
157
 
158
  fn vtable_name(ghidra_vt: u32) -> &'static str {
159
- match ghidra_vt {
160
- x if x == va::CTASK_WORM_VTABLE => "CTaskWorm",
161
- x if x == va::CTASK_MISSILE_VTABLE => "CTaskMissile",
162
- x if x == va::CTASK_TEAM_VTABLE => "CTaskTeam",
163
- x if x == va::CTASK_LAND_VTABLE => "CTaskLand",
164
- x if x == va::CTASK_TURN_GAME_VTABLE => "CTaskTurnGame",
165
- x if x == va::CTASK_CLOUD_VTABLE => "CTaskCloud",
166
- x if x == va::CTASK_DIRT_VTABLE => "CTaskDirt",
167
- x if x == va::CTASK_FIRE_VTABLE => "CTaskFire",
168
- x if x == va::CTASK_SEA_BUBBLE_VTABLE => "CTaskSeaBubble",
169
- x if x == va::CTASK_MINE_VTABLE => "CTaskMine",
170
- x if x == va::CTASK_OILDRUM_VTABLE => "CTaskOilDrum",
171
- x if x == va::CTASK_CRATE_VTABLE => "CTaskCrate",
172
- x if x == va::CTASK_CPU_VTABLE => "CTaskCPU",
173
- x if x == va::CTASK_FILTER_VTABLE => "CTaskFilter",
174
- x if x == va::CTASK_SPRITE_ANIM_VTABLE => "CTaskSpriteAnim",
175
- _ => "Unknown",
176
- }
177
  }
 
156
  }
157
 
158
  fn vtable_name(ghidra_vt: u32) -> &'static str {
159
+ openwa_core::registry::vtable_class_name(ghidra_vt).unwrap_or("Unknown")
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
160
  }
crates/openwa-wormkit/src/validation/mod.rs CHANGED
@@ -937,20 +937,7 @@ fn dump_entity_census() {
937
 
938
  let table = SharedDataTable::from_ptr(shared_data_ptr);
939
 
940
- // Name table: Ghidra VA → display name
941
- let known: &[(u32, &str)] = &[
942
- (va::CTASK_WORM_VTABLE, "CTaskWorm"),
943
- (va::CTASK_LAND_VTABLE, "CTaskLand"),
944
- (va::CTASK_TURN_GAME_VTABLE, "CTaskTurnGame"),
945
- (va::CTASK_TEAM_VTABLE, "CTaskTeam"),
946
- (va::CTASK_FILTER_VTABLE, "CTaskFilter"),
947
- (va::CTASK_DIRT_VTABLE, "CTaskDirt"),
948
- (va::CTASK_SPRITE_ANIM_VTABLE, "CTaskSpriteAnim"),
949
- (va::CTASK_CPU_VTABLE, "CTaskCPU"),
950
- (va::CTASK_CRATE_VTABLE, "CTaskCrate"),
951
- (va::CTASK_VTABLE, "CTask"),
952
- (va::CGAMETASK_VTABLE, "CGameTask"),
953
- ];
954
 
955
  // Collect (ghidra_va, entity_ptr) for every node.
956
  let delta = rb(va::IMAGE_BASE).wrapping_sub(va::IMAGE_BASE);
@@ -985,10 +972,7 @@ fn dump_entity_census() {
985
  groups.sort_by(|a, b| b.1.len().cmp(&a.1.len()));
986
 
987
  for (vt_ghidra, ptrs) in &groups {
988
- let name = known
989
- .iter()
990
- .find(|(v, _)| *v == *vt_ghidra)
991
- .map(|(_, n)| *n)
992
  .unwrap_or("UNKNOWN");
993
  let _ = log_validation(&format!(
994
  " {:>3}x {:<20} (vtable 0x{:08X})",
 
937
 
938
  let table = SharedDataTable::from_ptr(shared_data_ptr);
939
 
940
+ // Use the global address registry for vtable → class name lookup
 
 
 
 
 
 
 
 
 
 
 
 
 
941
 
942
  // Collect (ghidra_va, entity_ptr) for every node.
943
  let delta = rb(va::IMAGE_BASE).wrapping_sub(va::IMAGE_BASE);
 
972
  groups.sort_by(|a, b| b.1.len().cmp(&a.1.len()));
973
 
974
  for (vt_ghidra, ptrs) in &groups {
975
+ let name = openwa_core::registry::vtable_class_name(*vt_ghidra)
 
 
 
976
  .unwrap_or("UNKNOWN");
977
  let _ = log_validation(&format!(
978
  " {:>3}x {:<20} (vtable 0x{:08X})",