Files
neoLegacy-mac/tests/test_reconstructed_as3vm_class.py
2026-07-18 06:06:39 -05:00

403 lines
18 KiB
Python

"""Runtime tests for the reconstructed as3vm_class translation unit.
RED STATE: as3vm_class.c / as3vm_class.h do not exist yet, so setUpClass raises
"missing as3vm_class runtime inputs". Every assertion below is grounded in a
specific line of iggy-decompiled/raw/durango/as3vm_class.c (cited inline) so a
faithful DURANGO reconstruction turns these green.
as3vm_class is Iggy's AS3 / AVM2 ABC class linker: it converts ABC
(ActionScript Byte Code) class definitions into runtime classes -- trait-array
construction, two-phase class linking / finish-linking, parametrized
Vector.<T> class creation, ABC constant-pool conversion, and inherited
super-name copying. It exports EXACTLY 7 entry points on all four platforms
and -- LIKE the sibling as3vm_create, UNLIKE as3vm_gc -- owns NO externally
named data global (nm shows no B/D/C symbol on any object), so there is no
owned-globals runtime test here.
CLASS / TRAIT / CONSTANT MODEL (raw/durango, cross-checked vita 32-bit; offsets
here are 64-bit DURANGO -- the runtime test builds ONLY the durango dylib, so
64-bit layout is correct; the 32-bit targets halve these, e.g. finish_linking's
arena field is vm+0x6970 on durango but vm+0x472c on vita, which is why the
runtime path is durango-only):
- class struct: +0x19 link word (link_class stamps 0x1001), +0x1a flags,
+0x1b kind, +0x28 prototype, +0x34/+0x36 interface-name
counts, +0x40 super/base ptr, +0x48 instance traits,
+0x50 static traits.
- trait table: +0 backing arraydata, +8/+0x10/+0x18/+0x20 inherited name
arrays, +0x1c trait count, +0x20 owning-class back-ptr,
+0x38 method-name count, +0x3a slot-name count.
- VM context: +0x3538 linker error-code slot (OOM stamps 0x3e9, raw:1237),
+0x6970 link-time arena handle (raw:1075).
WHAT IS PINNED (real, deterministic DURANGO behavior):
- copy_super_names' full inherited-name copy: two element-wise loops (methods
at trait+8/+0x10, slots at trait+0x18/+0x20) gated by the class's
interface flag (param_1+0x28), plus the trailing count summary writes
(raw:1983-2022).
- as3vm_linker_alloc's arena bump on success (one iggy_arena_malloc_lowlevel,
no error, no longjmp) and its OOM escape (error code 0x3e9 at vm+0x3538 +
longjmp, raw:1234-1243).
- as3vm_finish_linking's arena destroy + field zero, and its NULL no-op
(raw:1071-1078).
- as3vm_abc_convert_constant's constant-pool-absent sentinel dispatch (the
per-kind byte at entry+0x1b selecting stable module sentinels) and its
invalid-kind error path (iggy_send_error 0x196, raw:451-488).
- as3vm_make_vector_class' NULL-element-class guard (raw:1257).
DEFERRED (flagged for the impl / review phase, NOT exercised here):
- as3vm_abc_convert_constant's live per-kind conversion (the 27-entry jump
table Ghidra could not emulate at 0x340b -- int/uint/double/string/
namespace/bool boxing via as3vm_make_*_GC).
- as3vm_build_trait_array's main trait-record build (deep, VM-context heavy).
- as3vm_link_class' two-phase vtable/slot layout beyond its entry stamp
(calls build_trait_array + make_object_no_constructor_GC over full VM
state) and as3vm_make_vector_class' populated path.
Full-suite runs use python3.12 (the machine python3 is 3.14, which SEGFAULTs on
the full suite via an unrelated CPython ctypes-GC bug); single-module runs of
this file are fine on either interpreter.
"""
import ctypes
import shutil
from pathlib import Path
import subprocess
import tempfile
import unittest
ROOT = Path(__file__).resolve().parents[1]
RECONSTRUCTED = ROOT / "iggy-decompiled/src/reconstructed"
SOURCE = RECONSTRUCTED / "as3vm_class.c"
HEADER = RECONSTRUCTED / "as3vm_class.h"
SUPPORT = ROOT / "tests/support/as3vm_class_test_support.c"
# 64-bit DURANGO VM-context / struct offsets (cited per test).
OFF_LINKER_ERR = 0x3538 # linker error-code slot (raw:1237)
OFF_FINISH_ARENA = 0x6970 # link-time arena handle (raw:1075)
LINKER_ERR_OOM = 0x3E9 # OOM error code (raw:1237)
OFF_HOLDER_TRAITS = 0x28 # class/holder -> trait table (raw:1983/1990)
OFF_CLS_FLAG = 0x28 # interface-copy gate (param_1+0x28, raw:1992)
OFF_CLS_CNT_METHODS = 0x36 # method-name count summary (raw:2021)
OFF_CLS_CNT_SLOTS = 0x34 # slot-name count summary (raw:2022)
OFF_TR_SRC_A = 0x08 # method-name src/dst array (raw:1990)
OFF_TR_SRC_B = 0x10 # method 2-byte array (raw:1993)
OFF_TR_SRC_C = 0x18 # slot-name src/dst array (raw:2008)
OFF_TR_SRC_D = 0x20 # slot 2-byte array (raw:2011)
OFF_TR_CNT_METHODS = 0x38 # method count (raw:1988)
OFF_TR_CNT_SLOTS = 0x3A # slot count (raw:2006)
def _u16(base, offset):
return ctypes.c_uint16.from_address(base + offset).value
def _u32(base, offset):
return ctypes.c_uint32.from_address(base + offset).value
def _u64(base, offset):
return ctypes.c_uint64.from_address(base + offset).value
def _set16(base, offset, value):
ctypes.c_uint16.from_address(base + offset).value = value
def _set32(base, offset, value):
ctypes.c_uint32.from_address(base + offset).value = value
def _set64(base, offset, value):
ctypes.c_uint64.from_address(base + offset).value = value
class ReconstructedAs3vmClassTests(unittest.TestCase):
@classmethod
def setUpClass(cls):
missing = [str(path) for path in (SOURCE, HEADER, SUPPORT)
if not path.exists()]
if missing:
raise AssertionError(
"missing as3vm_class runtime inputs: " + ", ".join(missing))
cls.temp = tempfile.TemporaryDirectory()
cls.base = Path(cls.temp.name) / "as3vm_class.dylib"
build = subprocess.run([
"clang", "-dynamiclib", "-std=c11", "-O2", "-Wall", "-Wextra",
"-Werror", "-Wl,-undefined,dynamic_lookup",
"-DIGGY_RECONSTRUCT_AS3VM_CLASS_DURANGO=1",
"-I", str(RECONSTRUCTED),
str(SOURCE), str(SUPPORT), "-o", str(cls.base),
], capture_output=True, text=True)
if build.returncode:
raise AssertionError(build.stdout + build.stderr)
@classmethod
def tearDownClass(cls):
cls.temp.cleanup()
def setUp(self):
unique = (Path(self.temp.name) /
f"as3vm_class_{self._testMethodName}.dylib")
shutil.copyfile(self.base, unique)
self.lib = ctypes.CDLL(str(unique))
self._bind(self.lib)
self.lib.as3vm_class_test_reset()
self._keep = []
def _bind(self, lib):
void_p = ctypes.c_void_p
u32 = ctypes.c_uint32
lib.as3vm_class_test_reset.argtypes = []
lib.as3vm_class_test_reset.restype = None
for name in ("send_error", "arena_malloc", "arena_malloc_lowlevel",
"arena_alloc_destroy", "free_alloc", "copy_arraydata",
"make_arraydata", "qname_find", "longjmp"):
fn = getattr(lib, f"as3vm_class_test_{name}_count")
fn.restype = ctypes.c_size_t
fn.argtypes = []
lib.as3vm_class_test_last_destroyed_handle.restype = void_p
lib.as3vm_class_test_last_destroyed_handle.argtypes = []
lib.as3vm_class_test_last_lowlevel_size.restype = ctypes.c_long
lib.as3vm_class_test_last_lowlevel_size.argtypes = []
lib.as3vm_class_test_last_error_code.restype = ctypes.c_int32
lib.as3vm_class_test_last_error_code.argtypes = []
lib.as3vm_class_test_set_lowlevel_fail.restype = None
lib.as3vm_class_test_set_lowlevel_fail.argtypes = [ctypes.c_int]
lib.as3vm_class_test_linker_alloc_protected.restype = ctypes.c_int
lib.as3vm_class_test_linker_alloc_protected.argtypes = [
void_p, void_p, ctypes.c_int]
# Module exports under test.
lib.copy_super_names.restype = None
lib.copy_super_names.argtypes = [void_p, void_p, void_p]
lib.as3vm_linker_alloc.restype = None
lib.as3vm_linker_alloc.argtypes = [void_p, void_p, ctypes.c_int]
lib.as3vm_finish_linking.restype = None
lib.as3vm_finish_linking.argtypes = [void_p]
lib.as3vm_abc_convert_constant.restype = void_p
lib.as3vm_abc_convert_constant.argtypes = [void_p, u32, void_p, void_p]
lib.as3vm_make_vector_class.restype = void_p
lib.as3vm_make_vector_class.argtypes = [void_p, void_p]
def _count(self, name):
return getattr(self.lib, f"as3vm_class_test_{name}_count")()
def _buffer(self, size):
buf = (ctypes.c_uint8 * size)()
self._keep.append(buf)
return ctypes.addressof(buf)
# ------------------------------------------------------------------ #
# copy_super_names -- inherited-name copy + count summary
# ------------------------------------------------------------------ #
def _seed(self, base, offset, count, width, first):
for i in range(count):
byte_off = offset + i * width
if width == 8:
_set64(base, byte_off, first + i)
else:
_set16(base, byte_off, (first + i) & 0xFFFF)
def _build_super_copy(self, count1, count2, copy_2byte):
# raw:1983-2022. Three structs: cls (param_1, receives the count
# summary + owns the interface-copy gate at +0x28), tgt (param_2, whose
# +0x28 trait table receives the copied arrays) and src (param_3, whose
# +0x28 trait table supplies counts + source arrays).
cls = self._buffer(0x40)
tgt = self._buffer(0x40)
src = self._buffer(0x40)
src_tr = self._buffer(0x40)
tgt_tr = self._buffer(0x40)
_set64(src, OFF_HOLDER_TRAITS, src_tr)
_set64(tgt, OFF_HOLDER_TRAITS, tgt_tr)
_set16(src_tr, OFF_TR_CNT_METHODS, count1)
_set16(src_tr, OFF_TR_CNT_SLOTS, count2)
_set32(cls, OFF_CLS_FLAG, 0 if copy_2byte else 1)
arrays = {}
for tag, off, count, width, first in (
("sa", OFF_TR_SRC_A, count1, 8, 0x1100),
("sb", OFF_TR_SRC_B, count1, 2, 0x22),
("sc", OFF_TR_SRC_C, count2, 8, 0x3300),
("sd", OFF_TR_SRC_D, count2, 2, 0x44)):
src_arr = self._buffer(max(count * width, width))
dst_arr = self._buffer(max(count * width, width))
self._seed(src_arr, 0, count, width, first)
_set64(src_tr, off, src_arr)
_set64(tgt_tr, off, dst_arr)
arrays[tag] = (src_arr, dst_arr, count, width)
return cls, tgt, src, arrays
def _assert_copied(self, arrays, tag):
src_arr, dst_arr, count, width = arrays[tag]
for i in range(count):
off = i * width
got = _u64(dst_arr, off) if width == 8 else _u16(dst_arr, off)
want = _u64(src_arr, off) if width == 8 else _u16(src_arr, off)
self.assertEqual(got, want, (tag, i))
def _assert_untouched(self, arrays, tag):
_, dst_arr, count, width = arrays[tag]
for i in range(count):
off = i * width
got = _u64(dst_arr, off) if width == 8 else _u16(dst_arr, off)
self.assertEqual(got, 0, (tag, i))
def test_copy_super_names_copies_all_arrays_when_interface_gate_clear(self):
# raw:1988-2022 with the interface gate (cls+0x28) zero, BOTH the
# 8-byte name arrays (methods +8, slots +0x18) and the 2-byte arrays
# (methods +0x10, slots +0x20) copy count-many elements, and the class
# receives the method count at +0x36 and slot count at +0x34.
cls, tgt, src, arrays = self._build_super_copy(3, 2, copy_2byte=True)
self.lib.copy_super_names(cls, tgt, src)
self._assert_copied(arrays, "sa")
self._assert_copied(arrays, "sb")
self._assert_copied(arrays, "sc")
self._assert_copied(arrays, "sd")
self.assertEqual(_u16(cls, OFF_CLS_CNT_METHODS), 3)
self.assertEqual(_u16(cls, OFF_CLS_CNT_SLOTS), 2)
def test_copy_super_names_skips_2byte_arrays_when_interface_gate_set(self):
# raw:1992/2010 a non-zero interface gate skips the 2-byte copies; the
# 8-byte name arrays still copy and the count summary is still written.
cls, tgt, src, arrays = self._build_super_copy(3, 2, copy_2byte=False)
self.lib.copy_super_names(cls, tgt, src)
self._assert_copied(arrays, "sa")
self._assert_copied(arrays, "sc")
self._assert_untouched(arrays, "sb")
self._assert_untouched(arrays, "sd")
self.assertEqual(_u16(cls, OFF_CLS_CNT_METHODS), 3)
self.assertEqual(_u16(cls, OFF_CLS_CNT_SLOTS), 2)
def test_copy_super_names_empty_counts_only_writes_zero_summary(self):
# raw:1988/2006 zero method/slot counts short-circuit both loops; only
# the trailing summary writes run, storing 0 / 0.
cls, tgt, src, arrays = self._build_super_copy(0, 0, copy_2byte=True)
_set16(cls, OFF_CLS_CNT_METHODS, 0x7777)
_set16(cls, OFF_CLS_CNT_SLOTS, 0x8888)
self.lib.copy_super_names(cls, tgt, src)
self.assertEqual(_u16(cls, OFF_CLS_CNT_METHODS), 0)
self.assertEqual(_u16(cls, OFF_CLS_CNT_SLOTS), 0)
# ------------------------------------------------------------------ #
# as3vm_linker_alloc -- link-time arena bump + OOM longjmp
# ------------------------------------------------------------------ #
def _linker_ctx(self):
vm = self._buffer(0x4000)
ctx = (ctypes.c_uint64 * 1)()
self._keep.append(ctx)
ctx[0] = vm
return ctypes.addressof(ctx), vm
def test_linker_alloc_bumps_arena_on_success(self):
# raw:1234 the happy path is a single iggy_arena_malloc_lowlevel of the
# requested size; a non-NULL block returns with no error stamp and no
# longjmp.
ctx, vm = self._linker_ctx()
result = self.lib.as3vm_class_test_linker_alloc_protected(ctx, 0, 0xC0)
self.assertEqual(result, 0)
self.assertEqual(self._count("arena_malloc_lowlevel"), 1)
self.assertEqual(self.lib.as3vm_class_test_last_lowlevel_size(), 0xC0)
self.assertEqual(self._count("longjmp"), 0)
self.assertEqual(_u32(vm, OFF_LINKER_ERR), 0)
def test_linker_alloc_stamps_error_and_longjmps_on_oom(self):
# raw:1235-1238 a NULL arena block stamps error code 0x3e9 into
# vm+0x3538 and longjmps to the interpreter recovery buffer.
ctx, vm = self._linker_ctx()
self.lib.as3vm_class_test_set_lowlevel_fail(1)
result = self.lib.as3vm_class_test_linker_alloc_protected(ctx, 0, 0x40)
self.assertNotEqual(result, 0)
self.assertEqual(self._count("longjmp"), 1)
self.assertEqual(_u32(vm, OFF_LINKER_ERR), LINKER_ERR_OOM)
# ------------------------------------------------------------------ #
# as3vm_finish_linking -- arena teardown
# ------------------------------------------------------------------ #
def test_finish_linking_destroys_arena_and_zeroes_field(self):
# raw:1074-1077 finish_linking destroys the link-time arena handle at
# vm+0x6970 and then zeroes that field.
vm = self._buffer(0x6978 + 8)
handle = self._buffer(0x40)
_set64(vm, OFF_FINISH_ARENA, handle)
self.lib.as3vm_finish_linking(vm)
self.assertEqual(self._count("arena_alloc_destroy"), 1)
self.assertEqual(
self.lib.as3vm_class_test_last_destroyed_handle(), handle)
self.assertEqual(_u64(vm, OFF_FINISH_ARENA), 0)
def test_finish_linking_null_context_is_noop(self):
# raw:1074 a NULL context short-circuits: no arena destroy.
self.lib.as3vm_finish_linking(None)
self.assertEqual(self._count("arena_alloc_destroy"), 0)
# ------------------------------------------------------------------ #
# as3vm_abc_convert_constant -- pool-absent sentinel dispatch + error
# ------------------------------------------------------------------ #
def _entry(self, kind_byte):
entry = self._buffer(0x20)
ctypes.c_uint8.from_address(entry + 0x1B).value = kind_byte
return entry
def test_convert_constant_pool_absent_sentinel_dispatch(self):
# raw:457-471 with no constant pool (param_3 == 0), the entry kind byte
# at +0x1b selects a stable module sentinel: the entry-less case and
# kind 7 return the SAME sentinel; kind 6 returns a distinct one; a high
# kind (>= 0xb, here 0x20) returns a third; kinds 9 and 10 fall through
# to NULL. Sentinels are module-internal rodata, so relationships (not
# absolute addresses) are pinned.
p1 = self._buffer(0x10)
r_none = self.lib.as3vm_abc_convert_constant(p1, 0, None, None)
r7 = self.lib.as3vm_abc_convert_constant(p1, 0, None, self._entry(7))
r6 = self.lib.as3vm_abc_convert_constant(p1, 0, None, self._entry(6))
r_high = self.lib.as3vm_abc_convert_constant(
p1, 0, None, self._entry(0x20))
r9 = self.lib.as3vm_abc_convert_constant(p1, 0, None, self._entry(9))
r10 = self.lib.as3vm_abc_convert_constant(p1, 0, None, self._entry(10))
self.assertIsNotNone(r_none)
self.assertEqual(r7, r_none)
self.assertIsNotNone(r6)
self.assertNotEqual(r6, r_none)
self.assertIsNotNone(r_high)
self.assertNotEqual(r_high, r6)
self.assertIsNone(r9)
self.assertIsNone(r10)
self.assertEqual(self._count("send_error"), 0)
def test_convert_constant_invalid_kind_raises_verification_error(self):
# raw:484-487 a present pool (param_3 != 0) with an out-of-range kind
# (>= 0x1b) reports a verification error (iggy_send_error code 0x196)
# and returns NULL, bypassing the per-kind jump table.
vm = self._buffer(0x40)
p1 = (ctypes.c_uint64 * 1)()
self._keep.append(p1)
p1[0] = vm
pool = self._buffer(0x20)
result = self.lib.as3vm_abc_convert_constant(
ctypes.addressof(p1), 0x1B, pool, None)
self.assertIsNone(result)
self.assertEqual(self._count("send_error"), 1)
self.assertEqual(self.lib.as3vm_class_test_last_error_code(), 0x196)
# ------------------------------------------------------------------ #
# as3vm_make_vector_class -- NULL-element guard
# ------------------------------------------------------------------ #
def test_make_vector_class_null_element_returns_null(self):
# raw:1257 a NULL element class short-circuits before any allocation.
vm = self._buffer(0x40)
result = self.lib.as3vm_make_vector_class(vm, None)
self.assertIsNone(result)
self.assertEqual(self._count("arena_malloc"), 0)
if __name__ == "__main__":
unittest.main()