Skip to main content

game_cheetah/
address.rs

1//! Persistent address definitions. Resolved addresses are session-local only.
2use std::{collections::BTreeMap, ops::Range};
3
4use i18n_embed_fl::fl;
5use process_memory::{CopyAddress, TryIntoProcessHandle};
6use serde::{Deserialize, Serialize};
7
8use crate::{SearchResult, SearchType};
9
10/// Absolute strings retain compatibility with v1 tables. Module offsets are
11/// relative to the image's first mapping, NOT its writable/executable segment.
12#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
13#[serde(untagged, deny_unknown_fields)]
14pub enum AddressSpec {
15    Absolute(String),
16    Module {
17        module: String,
18        offset: String,
19    },
20    Pointer {
21        module: String,
22        offset: String,
23        offsets: Vec<String>,
24        pointer_width: PointerWidth,
25    },
26}
27
28/// Explicit target pointer size, independent of the scanner's architecture and
29/// the final value type. Supported desktop targets use little-endian pointers.
30#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize, Default)]
31pub enum PointerWidth {
32    #[serde(rename = "32")]
33    Bits32,
34    #[default]
35    #[serde(rename = "64")]
36    Bits64,
37}
38
39impl PointerWidth {
40    pub fn bytes(self) -> usize {
41        match self {
42            Self::Bits32 => 4,
43            Self::Bits64 => 8,
44        }
45    }
46}
47
48pub const MAX_POINTER_DEPTH: usize = 16;
49
50#[derive(Debug, Clone)]
51pub struct PointerStep {
52    pub location: usize,
53    pub pointer: usize,
54    pub offset: String,
55    pub target: usize,
56}
57
58#[derive(Debug, Clone)]
59pub struct ResolvedAddress {
60    pub address: usize,
61    pub steps: Vec<PointerStep>,
62}
63
64impl AddressSpec {
65    pub fn absolute(address: usize) -> Self {
66        Self::Absolute(format!("0x{address:X}"))
67    }
68
69    pub fn validate(&self) -> Result<(), String> {
70        match self {
71            Self::Absolute(address) => parse_hex(address).map(|_| ()),
72            Self::Module { module, offset } | Self::Pointer { module, offset, .. } => {
73                if module.trim().is_empty() {
74                    return Err(fl!(crate::LANGUAGE_LOADER, "address-module-missing"));
75                }
76                parse_hex(offset)?;
77                if let Self::Pointer { offsets, .. } = self {
78                    if offsets.is_empty() || offsets.len() > MAX_POINTER_DEPTH {
79                        return Err(fl!(crate::LANGUAGE_LOADER, "pointer-depth"));
80                    }
81                    for offset in offsets {
82                        parse_pointer_offset(offset)?;
83                    }
84                }
85                Ok(())
86            }
87        }
88    }
89
90    pub fn label(&self) -> String {
91        match self {
92            Self::Absolute(address) => address.clone(),
93            Self::Module { module, offset } => format!("{} + {offset}", module.rsplit(['/', '\\']).next().unwrap_or(module)),
94            Self::Pointer { module, offset, offsets, .. } => {
95                format!("{} + {offset} -> [{}]", module.rsplit(['/', '\\']).next().unwrap_or(module), offsets.join(", "))
96            }
97        }
98    }
99
100    pub fn is_relative(&self) -> bool {
101        !matches!(self, Self::Absolute(_))
102    }
103
104    pub fn is_pointer(&self) -> bool {
105        matches!(self, Self::Pointer { .. })
106    }
107}
108
109fn parse_pointer_offset(text: &str) -> Result<(bool, usize), String> {
110    let text = text.trim();
111    let (negative, magnitude) = if let Some(rest) = text.strip_prefix('-') {
112        (true, rest)
113    } else {
114        (false, text.strip_prefix('+').unwrap_or(text))
115    };
116    Ok((negative, parse_hex(magnitude)?))
117}
118
119pub fn parse_hex(text: &str) -> Result<usize, String> {
120    let text = text.trim();
121    let digits = text.strip_prefix("0x").or_else(|| text.strip_prefix("0X")).unwrap_or(text);
122    if digits.is_empty() || !digits.bytes().all(|byte| byte.is_ascii_hexdigit()) {
123        return Err(fl!(crate::LANGUAGE_LOADER, "address-invalid-hex", value = text));
124    }
125    usize::from_str_radix(digits, 16).map_err(|_| fl!(crate::LANGUAGE_LOADER, "address-invalid-hex", value = text))
126}
127
128#[derive(Debug, Clone)]
129pub struct PendingAddress {
130    pub address: AddressSpec,
131    pub search_type: SearchType,
132    pub reason: String,
133}
134
135#[derive(Debug, Clone)]
136pub struct LoadedModule {
137    pub path: String,
138    pub base: usize,
139    pub ranges: Vec<Range<usize>>,
140    pub ambiguous: bool,
141}
142
143#[derive(Debug, Clone, Default)]
144pub struct ModuleCatalog {
145    pub modules: Vec<LoadedModule>,
146}
147
148impl ModuleCatalog {
149    pub fn for_process(pid: process_memory::Pid) -> Result<Self, String> {
150        if pid == 0 {
151            return Ok(Self::default());
152        }
153        let maps = proc_maps::get_process_maps(pid).map_err(|err| fl!(crate::LANGUAGE_LOADER, "address-map-error", error = err.to_string()))?;
154        let mut groups: BTreeMap<String, Vec<&proc_maps::MapRange>> = BTreeMap::new();
155        for map in &maps {
156            if let Some(path) = map.filename().and_then(|path| path.to_str())
157                && !path.starts_with('[')
158                && !path.ends_with(" (deleted)")
159            {
160                groups.entry(path.to_owned()).or_default().push(map);
161            }
162        }
163        let mut modules = Vec::new();
164        for (path, maps) in groups {
165            // Do not promote ordinary mapped save files/assets to modules.
166            if !maps.iter().any(|map| map.is_exec()) {
167                continue;
168            }
169            #[cfg(target_os = "linux")]
170            let bases: Vec<usize> = maps.iter().filter(|map| map.offset == 0).map(|map| map.start()).collect();
171            #[cfg(not(target_os = "linux"))]
172            let bases: Vec<usize> = maps.iter().map(|map| map.start()).min().into_iter().collect();
173            let Some(base) = bases.iter().copied().min() else {
174                continue;
175            };
176            modules.push(LoadedModule {
177                path,
178                base,
179                ambiguous: bases.len() != 1,
180                // Deliberately exclude anonymous BSS/heap mappings rather than
181                // guessing ownership from proximity to an image.
182                ranges: maps
183                    .iter()
184                    .filter(|map| map.is_read())
185                    .map(|map| map.start()..map.start().saturating_add(map.size()))
186                    .collect(),
187            });
188        }
189        Ok(Self { modules })
190    }
191
192    pub fn resolve(&self, spec: &AddressSpec, width: usize) -> Result<usize, String> {
193        spec.validate()?;
194        if spec.is_pointer() {
195            return Err(fl!(crate::LANGUAGE_LOADER, "pointer-needs-process"));
196        }
197        let AddressSpec::Module { module, offset } = spec else {
198            if let AddressSpec::Absolute(address) = spec {
199                return parse_hex(address);
200            }
201            unreachable!();
202        };
203        let matches: Vec<_> = self
204            .modules
205            .iter()
206            .filter(|loaded| loaded.path == *module || (!module.contains(['/', '\\']) && loaded.path.rsplit(['/', '\\']).next() == Some(module.as_str())))
207            .collect();
208        if matches.is_empty() {
209            return Err(fl!(crate::LANGUAGE_LOADER, "address-module-not-found", module = module.as_str()));
210        }
211        if matches.len() != 1 || matches[0].ambiguous {
212            return Err(fl!(crate::LANGUAGE_LOADER, "address-module-ambiguous", module = module.as_str()));
213        }
214        let loaded = matches[0];
215        let address = loaded
216            .base
217            .checked_add(parse_hex(offset)?)
218            .ok_or_else(|| fl!(crate::LANGUAGE_LOADER, "address-outside-module"))?;
219        let end = address
220            .checked_add(width.max(1))
221            .ok_or_else(|| fl!(crate::LANGUAGE_LOADER, "address-outside-module"))?;
222        if !loaded.ranges.iter().any(|range| range.start <= address && end <= range.end) {
223            return Err(fl!(crate::LANGUAGE_LOADER, "address-outside-module"));
224        }
225        Ok(address)
226    }
227
228    pub fn resolve_for_process(&self, spec: &AddressSpec, width: usize, pid: process_memory::Pid) -> Result<usize, String> {
229        self.trace_for_process(spec, width, pid).map(|resolved| resolved.address)
230    }
231
232    pub fn trace_for_process(&self, spec: &AddressSpec, width: usize, pid: process_memory::Pid) -> Result<ResolvedAddress, String> {
233        if !spec.is_pointer() {
234            return self.resolve(spec, width).map(|address| ResolvedAddress { address, steps: Vec::new() });
235        }
236        if pid == 0 {
237            return Err(fl!(crate::LANGUAGE_LOADER, "address-no-process"));
238        }
239        let handle = pid.try_into_process_handle().map_err(|err| err.to_string())?;
240        self.resolve_with_reader(spec, width, &crate::state::memory_reader::ExactProcessReader(&handle))
241    }
242
243    /// Read a pointer at the module root, add offsets[0], then repeat at
244    /// the resulting address. The final target contains the VALUE, not a pointer.
245    /// The reader must reject short reads; production uses ExactProcessReader.
246    pub fn resolve_with_reader<T: CopyAddress>(&self, spec: &AddressSpec, width: usize, reader: &T) -> Result<ResolvedAddress, String> {
247        spec.validate()?;
248        let AddressSpec::Pointer {
249            module,
250            offset,
251            offsets,
252            pointer_width,
253        } = spec
254        else {
255            return self.resolve(spec, width).map(|address| ResolvedAddress { address, steps: Vec::new() });
256        };
257        let root = AddressSpec::Module {
258            module: module.clone(),
259            offset: offset.clone(),
260        };
261        let mut address = self.resolve(&root, pointer_width.bytes())?;
262        let mut steps = Vec::with_capacity(offsets.len());
263        for (index, offset) in offsets.iter().enumerate() {
264            let stage = (index + 1).to_string();
265            let mut bytes = [0; 8];
266            checked_pointer_range(address, pointer_width.bytes(), *pointer_width)?;
267            reader.copy_address(address, &mut bytes[..pointer_width.bytes()]).map_err(|err| {
268                fl!(
269                    crate::LANGUAGE_LOADER,
270                    "pointer-read-error",
271                    step = stage.as_str(),
272                    address = format!("0x{address:X}"),
273                    error = err.to_string()
274                )
275            })?;
276            let raw = match pointer_width {
277                PointerWidth::Bits32 => u64::from(u32::from_le_bytes(bytes[..4].try_into().unwrap())),
278                PointerWidth::Bits64 => u64::from_le_bytes(bytes),
279            };
280            if raw == 0 {
281                return Err(fl!(crate::LANGUAGE_LOADER, "pointer-null", step = stage));
282            }
283            let pointer = usize::try_from(raw).map_err(|_| fl!(crate::LANGUAGE_LOADER, "pointer-overflow"))?;
284            let (negative, delta) = parse_pointer_offset(offset)?;
285            let target = if negative { pointer.checked_sub(delta) } else { pointer.checked_add(delta) }
286                .filter(|target| *target != 0)
287                .ok_or_else(|| fl!(crate::LANGUAGE_LOADER, "pointer-overflow"))?;
288            checked_pointer_range(target, 1, *pointer_width)?;
289            steps.push(PointerStep {
290                location: address,
291                pointer,
292                offset: offset.clone(),
293                target,
294            });
295            address = target;
296        }
297        // Bounded validation of the entire final value. No stale or partially
298        // readable target may be reported as a successfully resolved entry.
299        checked_pointer_range(address, width.max(1), *pointer_width)?;
300        if width > 1024 * 1024 {
301            return Err(fl!(crate::LANGUAGE_LOADER, "pointer-overflow"));
302        }
303        reader.copy_address(address, &mut vec![0; width.max(1)]).map_err(|err| {
304            fl!(
305                crate::LANGUAGE_LOADER,
306                "pointer-target-error",
307                address = format!("0x{address:X}"),
308                error = err.to_string()
309            )
310        })?;
311        Ok(ResolvedAddress { address, steps })
312    }
313
314    pub fn suggest(&self, result: &SearchResult) -> AddressSpec {
315        let width = result.search_type.fixed_byte_length().unwrap_or(1);
316        for module in &self.modules {
317            if !module.ambiguous
318                && module.ranges.iter().any(|range| range.contains(&result.addr))
319                && let Some(offset) = result.addr.checked_sub(module.base)
320            {
321                let spec = AddressSpec::Module {
322                    module: module.path.clone(),
323                    offset: format!("0x{offset:X}"),
324                };
325                if self.resolve(&spec, width).ok() == Some(result.addr) {
326                    return spec;
327                }
328            }
329        }
330        AddressSpec::absolute(result.addr)
331    }
332}
333
334fn checked_pointer_range(address: usize, width: usize, pointer_width: PointerWidth) -> Result<(), String> {
335    let last = address
336        .checked_add(width.saturating_sub(1))
337        .ok_or_else(|| fl!(crate::LANGUAGE_LOADER, "pointer-overflow"))?;
338    if pointer_width == PointerWidth::Bits32 && u32::try_from(last).is_err() {
339        return Err(fl!(crate::LANGUAGE_LOADER, "pointer-overflow"));
340    }
341    Ok(())
342}