use super::adapters::{read_m68k_memory, M68K_SPACE};
use super::error::DebugResult;
use super::model::DebugAddress;
use crate::runner::FixtureRunner;
use serde::{Deserialize, Serialize};
const TERMINATORS: [u16; 4] = [0x4E75, 0x4ED0, 0x4E5E, 0x4E74];
const ROUTINE_ENDS: [u16; 3] = [0x4E75, 0x4ED0, 0x4E74];
const MIN_NAME_LEN: usize = 3;
const MAX_NAME_LEN: usize = 31;
pub const DEFAULT_RESOLVE_WINDOW: u64 = 64 * 1024;
#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
pub struct SymbolEntry {
pub address: DebugAddress,
pub name: String,
}
fn entry_bytes(entry: &SymbolEntry) -> u64 {
(std::mem::size_of::<SymbolEntry>() + entry.name.len()) as u64
}
fn is_name_byte(byte: u8, first: bool) -> bool {
let character = byte as char;
if first {
character.is_ascii_alphabetic() || character == '_'
} else {
character.is_ascii_alphanumeric() || character == '_' || character == '.'
}
}
fn symbol_at(data: &[u8], offset: usize) -> Option<String> {
if offset < 2 || offset >= data.len() {
return None;
}
let previous = u16::from_be_bytes([data[offset - 2], data[offset - 1]]);
if !TERMINATORS.contains(&previous) {
return None;
}
let length = usize::from(data[offset] & 0x1f);
if data[offset] & 0x80 == 0 || !(MIN_NAME_LEN..=MAX_NAME_LEN).contains(&length) {
return None;
}
let name = data.get(offset + 1..offset + 1 + length)?;
if !name
.iter()
.enumerate()
.all(|(index, byte)| is_name_byte(*byte, index == 0))
{
return None;
}
Some(String::from_utf8(name.to_vec()).ok()?)
}
pub fn scan(
runner: &FixtureRunner,
start: u64,
length: u64,
entry_limit: usize,
byte_budget: u64,
) -> DebugResult<(Vec<SymbolEntry>, bool)> {
let memory = read_m68k_memory(runner, start, length)?;
let data = &memory.bytes;
let mut symbols = Vec::new();
let mut used = 0u64;
let mut truncated = false;
for offset in 0..data.len() {
let Some(name) = symbol_at(data, offset) else {
continue;
};
let entry = SymbolEntry {
address: DebugAddress::new(M68K_SPACE, start + offset as u64),
name,
};
let cost = entry_bytes(&entry);
if symbols.len() >= entry_limit || used + cost > byte_budget {
truncated = true;
break;
}
used += cost;
symbols.push(entry);
}
Ok((symbols, truncated || memory.truncated))
}
#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
#[serde(tag = "outcome", rename_all = "snake_case")]
pub enum SymbolResolution {
Contained { symbol: SymbolEntry, distance: u64 },
Unsymbolised { next: Option<SymbolEntry> },
NotFound,
}
pub fn resolve_containing(
runner: &FixtureRunner,
address: u64,
window: u64,
) -> DebugResult<SymbolResolution> {
let memory = read_m68k_memory(runner, address, window)?;
let data = &memory.bytes;
let mut ended_unnamed = false;
for offset in 0..data.len() {
if let Some(name) = symbol_at(data, offset) {
let symbol = SymbolEntry {
address: DebugAddress::new(M68K_SPACE, address + offset as u64),
name,
};
return Ok(if ended_unnamed {
SymbolResolution::Unsymbolised {
next: Some(symbol),
}
} else {
SymbolResolution::Contained {
symbol,
distance: offset as u64,
}
});
}
if (address + offset as u64) % 2 == 0 && offset + 2 <= data.len() {
let word = u16::from_be_bytes([data[offset], data[offset + 1]]);
if ROUTINE_ENDS.contains(&word) && symbol_at(data, offset + 2).is_none() {
ended_unnamed = true;
}
}
}
Ok(if ended_unnamed {
SymbolResolution::Unsymbolised { next: None }
} else {
SymbolResolution::NotFound
})
}
pub fn lookup(
runner: &FixtureRunner,
start: u64,
length: u64,
name: &str,
) -> DebugResult<Vec<SymbolEntry>> {
let memory = read_m68k_memory(runner, start, length)?;
let data = &memory.bytes;
let mut found = Vec::new();
for offset in 0..data.len() {
if symbol_at(data, offset).as_deref() == Some(name) {
found.push(SymbolEntry {
address: DebugAddress::new(M68K_SPACE, start + offset as u64),
name: name.to_string(),
});
}
}
Ok(found)
}
#[cfg(test)]
mod tests {
use super::*;
use crate::memory::bus::MemoryBus;
use crate::runner::FixtureRunnerConfig;
fn encoded(terminator: u16, name: &str) -> Vec<u8> {
let mut bytes = terminator.to_be_bytes().to_vec();
bytes.push(0x80 | name.len() as u8);
bytes.extend_from_slice(name.as_bytes());
bytes
}
#[test]
fn decodes_a_symbol_after_each_terminator() {
for terminator in TERMINATORS {
let data = encoded(terminator, "GetAnEvent");
assert_eq!(symbol_at(&data, 2).as_deref(), Some("GetAnEvent"));
}
}
#[test]
fn requires_a_terminator_before_the_name() {
let data = encoded(0x4E71, "GetAnEvent");
assert_eq!(symbol_at(&data, 2), None);
}
#[test]
fn rejects_names_that_are_not_identifiers() {
for name in ["9bad", " lead", "has-dash"] {
let data = encoded(0x4E75, name);
assert_eq!(symbol_at(&data, 2), None, "should reject {name:?}");
}
}
#[test]
fn rejects_lengths_outside_the_accepted_range() {
let short = encoded(0x4E75, "ab");
assert_eq!(symbol_at(&short, 2), None);
let mut plain = encoded(0x4E75, "Routine");
plain[2] &= 0x7f;
assert_eq!(symbol_at(&plain, 2), None);
}
fn guest_runner() -> FixtureRunner {
FixtureRunner::new(0x100000, FixtureRunnerConfig::default())
}
fn routine(name: &str) -> Vec<u8> {
let mut bytes = encoded(0x4E75, name);
bytes.extend_from_slice(&[0x4E, 0x71]); bytes
}
#[test]
fn scan_reports_truncation_when_the_entry_limit_is_reached() {
let mut runner = guest_runner();
let mut data = Vec::new();
data.extend_from_slice(&routine("Alpha"));
data.extend_from_slice(&routine("Beta"));
data.extend_from_slice(&routine("Gamma"));
runner.bus_mut().write_bytes(0, &data);
let (symbols, truncated) =
scan(&runner, 0, data.len() as u64, 2, u64::MAX).unwrap();
assert_eq!(symbols.len(), 2);
assert_eq!(symbols[0].name, "Alpha");
assert_eq!(symbols[1].name, "Beta");
assert!(truncated);
}
#[test]
fn scan_reports_truncation_when_the_byte_budget_is_reached() {
let mut runner = guest_runner();
let data = routine("Alpha");
runner.bus_mut().write_bytes(0, &data);
let (symbols, truncated) = scan(&runner, 0, data.len() as u64, 8, 4).unwrap();
assert!(symbols.is_empty());
assert!(truncated);
}
#[test]
fn scan_is_not_truncated_when_limits_are_not_reached() {
let mut runner = guest_runner();
let data = routine("Alpha");
runner.bus_mut().write_bytes(0, &data);
let (symbols, truncated) = scan(&runner, 0, data.len() as u64, 8, u64::MAX).unwrap();
assert_eq!(symbols.len(), 1);
assert!(!truncated);
}
#[test]
fn resolve_containing_attributes_the_address_to_the_following_symbol() {
let mut runner = guest_runner();
let data = routine("GetAnEvent");
runner.bus_mut().write_bytes(0, &data);
match resolve_containing(&runner, 0, 4096).unwrap() {
SymbolResolution::Contained { symbol, distance } => {
assert_eq!(symbol.name, "GetAnEvent");
assert_eq!(symbol.address.offset, 2); assert_eq!(distance, 2);
}
other => panic!("expected Contained, got {other:?}"),
}
}
#[test]
fn resolve_containing_reports_an_unsymbolised_routine_rather_than_inheriting_a_name() {
let mut runner = guest_runner();
let mut data = Vec::new();
data.extend_from_slice(&[0x4E, 0x75]); data.extend_from_slice(&[0x4E, 0x71]); data.extend_from_slice(&encoded(0x4E75, "Named"));
runner.bus_mut().write_bytes(0, &data);
match resolve_containing(&runner, 0, 4096).unwrap() {
SymbolResolution::Unsymbolised { next } => {
assert_eq!(next.expect("a later symbol was present").name, "Named");
}
other => panic!("expected Unsymbolised, got {other:?}"),
}
}
#[test]
fn resolve_containing_reports_not_found_when_the_window_has_no_symbols() {
let mut runner = guest_runner();
let data = [0x4Eu8, 0x71, 0x4E, 0x71];
runner.bus_mut().write_bytes(0, &data);
assert_eq!(resolve_containing(&runner, 0, 4096).unwrap(),
SymbolResolution::NotFound);
}
#[test]
fn lookup_returns_every_copy_of_a_name_in_ascending_order() {
let mut runner = guest_runner();
let mut data = Vec::new();
data.extend_from_slice(&routine("GetAnEvent"));
data.extend_from_slice(&routine("Other"));
data.extend_from_slice(&routine("GetAnEvent"));
runner.bus_mut().write_bytes(0, &data);
let found = lookup(&runner, 0, data.len() as u64, "GetAnEvent").unwrap();
assert_eq!(found.len(), 2);
assert!(found[0].address.offset < found[1].address.offset);
assert!(lookup(&runner, 0, data.len() as u64, "Missing").unwrap().is_empty());
}
#[test]
fn an_ordinary_epilogue_is_not_treated_as_an_unnamed_routine_end() {
assert!(!ROUTINE_ENDS.contains(&0x4E5E));
assert!(TERMINATORS.contains(&0x4E5E));
}
#[test]
fn truncated_name_at_the_end_of_the_buffer_is_not_a_symbol() {
let mut data = encoded(0x4E75, "GetAnEvent");
data.truncate(data.len() - 4);
assert_eq!(symbol_at(&data, 2), None);
}
#[test]
fn probing_one_past_the_end_of_the_buffer_is_not_a_symbol() {
let data = 0x4E75u16.to_be_bytes();
assert_eq!(symbol_at(&data, data.len()), None);
assert_eq!(symbol_at(&data, data.len() + 1), None);
}
#[test]
fn resolve_containing_handles_a_window_ending_at_a_return_instruction() {
let mut runner = guest_runner();
runner
.bus_mut()
.write_bytes(0x20000, &0x4E75u16.to_be_bytes());
match resolve_containing(&runner, 0x20000, 2).unwrap() {
SymbolResolution::Unsymbolised { next: None } => {}
other => panic!("expected Unsymbolised without a next symbol, got {other:?}"),
}
}
#[test]
fn resolve_containing_handles_a_read_truncated_at_the_end_of_mapped_ram() {
let mut runner = guest_runner();
let ram_size = u64::from(runner.bus().ram_size());
runner
.bus_mut()
.write_bytes(ram_size as u32 - 2, &0x4E75u16.to_be_bytes());
match resolve_containing(&runner, ram_size - 4, 8).unwrap() {
SymbolResolution::Unsymbolised { next: None } => {}
other => panic!("expected Unsymbolised without a next symbol, got {other:?}"),
}
}
}