Files
neoLegacy-mac/tests/test_reconstructed_empty_units.py

250 lines
10 KiB
Python

r"""Classification tests for the release-build-EMPTY translation units.
Nine Iggy 1.2.30 translation units compile to *nothing* in the retail build and
therefore need no C reconstruction -- but "empty" is a claim that must be proven
against the retail objects, not assumed. This module machine-checks that claim
so any future non-empty rebuild fails loudly.
The nine units fall into two groups:
Debug / instrumentation units (6), present on all four platforms. Their
bodies are guarded by release-stripped debug macros, so the compiler emits an
object with no code, data, bss, or imports:
as3vm_abc_dump, as3vm_dump_value, iggy_debug, rrMem, rrSyncCheck, swf_cache
Durango dispatch stubs (3), present only as durango objects. The durango
build reuses the win32 atomics/threads/time implementations, so these
platform-named translation units compile to empty objects while the real
symbols are exported by win32_rrAtomics / win32_rrThreads2 / win32_rrTime
(also linked into the durango DLL):
durango_rrAtomics, durango_rrThreads2, durango_rrTime
Evidence per (unit, platform), all verified with the pinned Homebrew LLVM
toolchain against work/iggy-native-decomp/<platform>-objects/<unit>.obj:
* llvm-nm (full, every symbol class) emits NO symbol of any content class
(T/t D/d B/b R/r C U ...). Durango COFF objects carry only the two MSVC
per-TU absolute pseudo-symbols @comp.id and @feat.00 (class `a`, no section,
no code); orbis/ps3/vita ELF objects carry zero symbols at all.
* llvm-objdump -h shows every allocatable content section (.text/.data/.bss/
.toc, tagged TEXT/DATA/BSS) at size 0. The only non-empty sections are
non-allocatable metadata: .drectve (linker directives), .debug$S (CodeView),
.comment, .symtab/.strtab/.shstrtab, .ARM.attributes -- all expected in a
compiled-but-empty object and none of which carry program content.
* The raw Ghidra decompile raw/<platform>/<unit>.c is the 3-line provenance
banner with no recovered code.
Supersession proof for the durango trio: the win32_* objects that ship in the
same durango DLL define the rr* atomics/threads/time functions the stubs would
otherwise own (checked here with llvm-nm --defined-only).
These are classified `empty` in iggy-decompiled/src/reconstructed/modules.tsv
(0 source functions, 0 external functions) -- distinct from `complete`
reconstructions -- and this test is the classification of record.
"""
from pathlib import Path
import re
import subprocess
import unittest
ROOT = Path(__file__).resolve().parents[1]
RECONSTRUCTED = ROOT / "iggy-decompiled/src/reconstructed"
OBJECTS = ROOT / "work/iggy-native-decomp"
RAW = ROOT / "iggy-decompiled/raw"
LLVM_NM = Path("/opt/homebrew/opt/llvm/bin/llvm-nm")
LLVM_OBJDUMP = Path("/opt/homebrew/opt/llvm/bin/llvm-objdump")
ALL_PLATFORMS = ("durango", "orbis", "ps3", "vita")
DURANGO_ONLY = ("durango",)
# unit -> platforms whose <platform>-objects/<unit>.obj must exist and be empty.
EMPTY_UNITS = {
"as3vm_abc_dump": ALL_PLATFORMS,
"as3vm_dump_value": ALL_PLATFORMS,
"iggy_debug": ALL_PLATFORMS,
"rrMem": ALL_PLATFORMS,
"rrSyncCheck": ALL_PLATFORMS,
"swf_cache": ALL_PLATFORMS,
"durango_rrAtomics": DURANGO_ONLY,
"durango_rrThreads2": DURANGO_ONLY,
"durango_rrTime": DURANGO_ONLY,
}
# MSVC emits these two absolute (class `a`) pseudo-symbols in every compiled
# translation unit. They occupy no section and carry no code, so they are the
# only symbols an empty COFF object is allowed to expose.
ALLOWED_ABSOLUTE_CLASSES = {"a", "A"}
# The durango dispatch stubs are empty because these win32 objects -- linked
# into the same durango DLL -- own the real rr* symbols. A representative,
# non-exhaustive set of exported functions is asserted per superseding object.
SUPERSESSION = {
"durango_rrAtomics": (
"win32_rrAtomics",
{"rrAtomicCAS32", "rrAtomicCAS64", "rrAtomicExchange32",
"rrAtomicMemoryBarrierFull"},
),
"durango_rrThreads2": (
"win32_rrThreads2",
{"rrThreadSetPriorityThreadID"},
),
"durango_rrTime": (
"win32_rrTime",
{"rrGetTime", "rrGetTicks", "rrGetThreadTicks"},
),
}
# objdump -h section line: " <idx> <name> <size8hex> <vma...> [Type...]".
_SECTION_LINE = re.compile(
r"^\s*\d+\s+(?P<name>\S+)\s+(?P<size>[0-9a-fA-F]{8})\s+[0-9a-fA-F]{8,16}\b"
r"(?P<type>.*)$")
def object_path(unit, platform):
return OBJECTS / f"{platform}-objects/{unit}.obj"
def nm_full(obj):
"""Every symbol llvm-nm reports for `obj` as (class_char, name) tuples."""
result = subprocess.run(
[str(LLVM_NM), str(obj)], capture_output=True, text=True)
if result.returncode != 0:
raise AssertionError(f"llvm-nm failed on {obj}: {result.stderr}")
symbols = []
for line in result.stdout.splitlines():
parts = line.split()
if len(parts) < 2:
continue
symbols.append((parts[-2], parts[-1]))
return symbols
def content_sections(obj):
"""(name, size) for every allocatable content section objdump reports.
Non-allocatable metadata (.drectve, .debug*, .comment, symbol/string
tables, .ARM.attributes) is excluded -- those are expected in a
compiled-but-empty object and carry no program content. A section counts
as content when objdump tags it TEXT/DATA/BSS and does not mark it DEBUG.
"""
result = subprocess.run(
[str(LLVM_OBJDUMP), "-h", str(obj)], capture_output=True, text=True)
if result.returncode != 0:
raise AssertionError(f"llvm-objdump failed on {obj}: {result.stderr}")
sections = []
for line in result.stdout.splitlines():
match = _SECTION_LINE.match(line)
if not match:
continue
section_type = match.group("type").upper()
if "DEBUG" in section_type:
continue
if not any(tag in section_type for tag in ("TEXT", "DATA", "BSS")):
continue
sections.append((match.group("name"), int(match.group("size"), 16)))
return sections
class EmptyUnitObjectTests(unittest.TestCase):
def test_object_matrix_matches_declared_platforms(self):
# Each unit's object exists exactly on its declared platforms; the
# durango-only trio has no orbis/ps3/vita object.
for unit, platforms in EMPTY_UNITS.items():
for platform in platforms:
obj = object_path(unit, platform)
self.assertTrue(obj.exists(), f"missing {obj}")
for platform in set(ALL_PLATFORMS) - set(platforms):
obj = object_path(unit, platform)
self.assertFalse(
obj.exists(),
f"{unit} unexpectedly present on {platform}: {obj}")
def test_objects_expose_no_content_symbols(self):
if not LLVM_NM.exists():
self.skipTest(f"llvm-nm not found at {LLVM_NM}")
for unit, platforms in EMPTY_UNITS.items():
for platform in platforms:
obj = object_path(unit, platform)
for kind, name in nm_full(obj):
self.assertIn(
kind, ALLOWED_ABSOLUTE_CLASSES,
f"{unit} on {platform} exposes content symbol "
f"'{kind} {name}' -- object is NOT empty; it needs "
f"real reconstruction.")
def test_objects_have_no_nonempty_content_section(self):
if not LLVM_OBJDUMP.exists():
self.skipTest(f"llvm-objdump not found at {LLVM_OBJDUMP}")
for unit, platforms in EMPTY_UNITS.items():
for platform in platforms:
obj = object_path(unit, platform)
for name, size in content_sections(obj):
self.assertEqual(
size, 0,
f"{unit} on {platform} has non-empty {name} "
f"({size} bytes) -- object is NOT empty; it needs "
f"real reconstruction.")
def test_raw_decompile_is_empty_banner(self):
for unit, platforms in EMPTY_UNITS.items():
for platform in platforms:
raw = RAW / platform / f"{unit}.c"
self.assertTrue(raw.exists(), f"missing {raw}")
text = raw.read_text(encoding="utf-8")
self.assertLessEqual(
len(text.splitlines()), 3,
f"{raw} has recovered code beyond the provenance banner")
self.assertIn("Recovered from", text, str(raw))
self.assertNotIn(
"{", text,
f"{raw} contains a function body -- not an empty stub")
class DurangoTrioSupersessionTests(unittest.TestCase):
def test_win32_objects_own_the_rr_symbols(self):
# The durango_rr* stubs are legitimately empty because these win32
# objects (linked into the same durango DLL) define the rr* functions.
if not LLVM_NM.exists():
self.skipTest(f"llvm-nm not found at {LLVM_NM}")
for stub, (win32_unit, expected) in SUPERSESSION.items():
obj = object_path(win32_unit, "durango")
self.assertTrue(
obj.exists(), f"missing superseding object {obj} for {stub}")
result = subprocess.run(
[str(LLVM_NM), "--defined-only", str(obj)],
capture_output=True, text=True)
self.assertEqual(result.returncode, 0, result.stderr)
defined = {
name
for kind, name in (
(parts[-2], parts[-1])
for parts in (line.split()
for line in result.stdout.splitlines())
if len(parts) >= 2)
if kind == "T"
}
missing = expected - defined
self.assertEqual(
missing, set(),
f"{win32_unit} does not export {missing}; the {stub} stub "
f"cannot be classified empty until supersession holds.")
class EmptyUnitInventoryTests(unittest.TestCase):
def test_modules_tsv_records_each_unit_empty(self):
inventory = (RECONSTRUCTED / "modules.tsv").read_text(encoding="utf-8")
for unit, platforms in EMPTY_UNITS.items():
row = f"{unit}\t0\t0\t{','.join(platforms)}\tempty"
self.assertIn(
row, inventory,
f"modules.tsv is missing the empty-classification row: {row}")
if __name__ == "__main__":
unittest.main()