From 21dfefcfb24254dad6358285ae7e65421e6488d4 Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Thu, 19 Nov 2026 20:13:26 -0500 Subject: [PATCH] refactor(il2cpp): share stored native image scalar reads (#12638) refactor(il2cpp): share native registration scalar reads --- scripts/verify/baselines/raw-buffer-read.json | 2 - src/il2cpp/Il2cppBinaryImage.ts | 10 +++-- src/il2cpp/Il2cppBinaryRegistration.ts | 37 +++++++------------ src/native/metadata/Il2cppContainer.test.ts | 2 +- .../boundary/il2cpp/il2cppBinaryFile.test.ts | 28 ++++++++++++++ .../il2cpp/il2cppMappingOwnership.test.ts | 6 ++- 6 files changed, 52 insertions(+), 33 deletions(-) diff --git a/scripts/verify/baselines/raw-buffer-read.json b/scripts/verify/baselines/raw-buffer-read.json index 1a8e6b97f8..a240de1c55 100644 --- a/scripts/verify/baselines/raw-buffer-read.json +++ b/scripts/verify/baselines/raw-buffer-read.json @@ -8,8 +8,6 @@ "src/domain/native/nativeAotPe.ts": 10, "src/domain/native/readBinaryContainer.ts": 1, "src/ghidra/extensions/GhidraExtensions.ts": 1, - "src/il2cpp/Il2cppBinaryImage.ts": 2, - "src/il2cpp/Il2cppBinaryRegistration.ts": 8, "src/native/AppleDispatchMetadata.ts": 4, "src/native/AppleObjcDispatchFacets.ts": 1, "src/native/AppleSwiftDispatchFacets.ts": 1, diff --git a/src/il2cpp/Il2cppBinaryImage.ts b/src/il2cpp/Il2cppBinaryImage.ts index 13b621bf50..62eb8290fb 100644 --- a/src/il2cpp/Il2cppBinaryImage.ts +++ b/src/il2cpp/Il2cppBinaryImage.ts @@ -7,6 +7,7 @@ import { import { BinaryFormatFailure, BinaryMappingFailure, + BinaryReader, BinaryResourceFailure, createFileMappingIndex, mappedFileOffset, @@ -73,7 +74,8 @@ export const requireIl2cppBinaryImage = ( ); export interface NativeImage { - readonly bytes: Buffer; + /** Stored file coordinates only; virtual translation and fixups stay separate. */ + readonly stored: BinaryReader; readonly container: BinaryContainer; /** One image's immutable load mappings, shared by stored and loader-aware reads. */ readonly fileMappings: FileMappingIndex; @@ -226,7 +228,7 @@ export function* openImageSteps( ) ?? 0n; return { - bytes: image, + stored: new BinaryReader(image, true, container.format), container, fileMappings: createFileMappingIndex( container.mappings, @@ -242,7 +244,7 @@ export function* openImageSteps( const readStoredWord = (image: NativeImage, address: bigint): bigint | null => { try { const offset = image.fileMappings.offset(address, 8); - return image.bytes.readBigUInt64LE(offset); + return image.stored.word(offset, 64); } catch (cause) { if (cause instanceof BinaryFormatFailure) return null; throw cause; @@ -261,7 +263,7 @@ export const readUInt32 = ( const value = image.elfPointerOverlay.unsignedAt(address, 4); return value === undefined ? "unknown" : Number(value); } - return image.bytes.readUInt32LE(image.fileMappings.offset(address, 4)); + return image.stored.u32(image.fileMappings.offset(address, 4)); } catch (cause) { if (cause instanceof BinaryFormatFailure) return null; throw cause; diff --git a/src/il2cpp/Il2cppBinaryRegistration.ts b/src/il2cpp/Il2cppBinaryRegistration.ts index 0ecb015425..4f5b269f36 100644 --- a/src/il2cpp/Il2cppBinaryRegistration.ts +++ b/src/il2cpp/Il2cppBinaryRegistration.ts @@ -1,7 +1,4 @@ -import { - BinaryFormatFailure, - mappedFileOffset, -} from "../domain/binaryContainer.js"; +import { BinaryFormatFailure } from "../domain/binaryContainer.js"; import { Il2cppBinaryFormatFailure } from "./Il2cppBinaryFormat.js"; import { isMapped, @@ -138,9 +135,10 @@ function* nameAddresses( } const found = new Map(); for (const mapping of image.container.mappings) { - const region = image.bytes.subarray( + const region = image.stored.range( mapping.offset, - mapping.offset + mapping.size, + mapping.size, + "module-name load range", ); for (let chunk = 0; chunk < region.length; chunk += SCAN_BYTES) { yield; @@ -222,7 +220,7 @@ export function* findModules( if ((at & 0xffff) < 8) yield; const offset = mapping.offset + at; const address = mapping.address + BigInt(at); - const raw = image.bytes.readBigUInt64LE(offset); + const raw = image.stored.word(offset, 64); const elfSlot = image.elfPointerOverlay === undefined ? undefined @@ -276,12 +274,7 @@ export function* findModules( if (indices === undefined) continue; let recordOffset: number; try { - recordOffset = mappedFileOffset( - image.container.mappings, - address, - 24, - image.container.zero_fills, - ); + recordOffset = image.fileMappings.offset(address, 24); } catch (cause) { if (cause instanceof BinaryFormatFailure) throw new Il2cppBinaryFormatFailure( @@ -458,7 +451,7 @@ function* findModuleArrayByCode( let duplicateValues = 0; for (let at = start; at + 8 <= mapping.size; at += 8) { if ((at & 0xffff) < 8) yield; - const raw = image.bytes.readBigUInt64LE(mapping.offset + at); + const raw = image.stored.word(mapping.offset + at, 64); const address = mapping.address + BigInt(at); const elfSlot = image.elfPointerOverlay === undefined @@ -514,7 +507,7 @@ function* findModuleArrayByCode( image.elfPointerOverlay !== undefined || unresolvedPointerMatcher(image, [expectedXor ^ possibleXor])( mapping.address + BigInt(unknownAt), - image.bytes.readBigUInt64LE(mapping.offset + unknownAt), + image.stored.word(mapping.offset + unknownAt, 64), ) !== undefined ) return null; @@ -557,7 +550,6 @@ function* ripRelativeReferences( ): Generator> { const referenced = new Set(); for (const mapping of image.container.executable_mappings ?? []) { - const bytes = image.bytes; const loaded = image.elfPointerOverlay?.hasWrites(mapping.address, mapping.size) === true; @@ -565,9 +557,7 @@ function* ripRelativeReferences( for (let at = mapping.offset; at <= end; at++) { if ((at & 0xffff) < 8) yield; const address = mapping.address + BigInt(at - mapping.offset); - const prefix = loaded - ? readUInt32(image, address) - : bytes.readUInt32LE(at); + const prefix = loaded ? readUInt32(image, address) : image.stored.u32(at); if (typeof prefix !== "number") continue; const rex = prefix & 0xff; if ((rex & 0xfb) !== 0x48) continue; // REX.W, optionally REX.R @@ -577,7 +567,7 @@ function* ripRelativeReferences( const next = mapping.address + BigInt(at - mapping.offset + 7); const displacement = loaded ? readUInt32(image, address + 3n) - : bytes.readUInt32LE(at + 3); + : image.stored.u32(at + 3); if (typeof displacement !== "number") continue; const target = next + BigInt(displacement | 0); if (arrays.has(target)) referenced.add(target); @@ -598,7 +588,6 @@ function* arm64PageReferences( arrays: ReadonlySet, ): Generator> { const referenced = new Set(); - const bytes = image.bytes; for (const mapping of image.container.executable_mappings ?? []) { const loaded = image.elfPointerOverlay?.hasWrites(mapping.address, mapping.size) === @@ -609,12 +598,12 @@ function* arm64PageReferences( const address = mapping.address + BigInt(at); const adrp = loaded ? readUInt32(image, address) - : bytes.readUInt32LE(mapping.offset + at); + : image.stored.u32(mapping.offset + at); if (typeof adrp !== "number") continue; if ((adrp & 0x9f000000) >>> 0 !== 0x90000000) continue; const add = loaded ? readUInt32(image, address + 4n) - : bytes.readUInt32LE(mapping.offset + at + 4); + : image.stored.u32(mapping.offset + at + 4); if (typeof add !== "number") continue; if ((add & 0xffc00000) >>> 0 !== 0x91000000) continue; const register = adrp & 0x1f; @@ -850,7 +839,7 @@ function* findTypeTableByCode( const address = mapping.address + BigInt(at); let endUnknown = at + 8 > mapping.size; if (!endUnknown) { - const raw = image.bytes.readBigUInt64LE(mapping.offset + at); + const raw = image.stored.word(mapping.offset + at, 64); let state: "type" | "other" | "unknown"; if (image.elfPointerOverlay === undefined) { if ( diff --git a/src/native/metadata/Il2cppContainer.test.ts b/src/native/metadata/Il2cppContainer.test.ts index dc5f1eb835..4da2729f7c 100644 --- a/src/native/metadata/Il2cppContainer.test.ts +++ b/src/native/metadata/Il2cppContainer.test.ts @@ -23,7 +23,7 @@ it.each(["unmapped", "zero-fill", "duplicate", "out-of-file"] as const)( expect(image.done).toBe(true); if (!image.done) throw new Error("container admission unexpectedly yielded"); - expect(image.value.bytes).toBe(goNamed); + expect(image.value.stored.bytes).toBe(goNamed); expect(image.value.container).toMatchObject({ format: "macho", macho_chained_fixups: false, diff --git a/tests/boundary/il2cpp/il2cppBinaryFile.test.ts b/tests/boundary/il2cpp/il2cppBinaryFile.test.ts index fae8059031..3624b70752 100644 --- a/tests/boundary/il2cpp/il2cppBinaryFile.test.ts +++ b/tests/boundary/il2cpp/il2cppBinaryFile.test.ts @@ -586,6 +586,34 @@ it.each([ ).toBe("code-registration-not-found"); }); +it.each([ + ["x86-64", 7], + ["arm64", 8], +] as const)( + "keeps the entire %s registration reference inside the executable extent", + (arch, width) => { + const instruction = 0xc00; + const makeImage = (inside: number) => { + const bytes = createIl2cppBinaryFixture({ + codeRegistration: false, + codeReference: arch === "x86-64", + adrpAdd: arch === "arm64" ? [[instruction, 0x500]] : [], + splitSegmentAt: instruction + inside, + }); + if (arch === "x86-64") bytes.writeUInt32LE(0x01000007, 4); + bytes.writeUInt32LE(1, 32 + 72 + 60); // The second segment is read-only. + return bytes; + }; + expect(link(makeImage(width)).code_gen_modules_array).toBe( + FIXTURE_BINARY_BASE + 0x500n, + ); + expect(failure(makeImage(width - 1))).toMatchObject({ + reason: "code-registration-not-found", + kind: "malformed", + }); + }, +); + it("finds an arm64 module array through the ADRP+ADD pair that loads it", () => { const linked = link( createIl2cppBinaryFixture({ diff --git a/tests/boundary/il2cpp/il2cppMappingOwnership.test.ts b/tests/boundary/il2cpp/il2cppMappingOwnership.test.ts index cf1e0c867c..5fdb0e1c9e 100644 --- a/tests/boundary/il2cpp/il2cppMappingOwnership.test.ts +++ b/tests/boundary/il2cpp/il2cppMappingOwnership.test.ts @@ -299,12 +299,13 @@ it("reads both halves of a relocated word without changing a physical alias's UI { offset: 0, size: original.length }, { offset: 0x304, size: 16, address: FIXTURE_BINARY_BASE + 0x2000n }, ]); + const snapshot = Buffer.from(bytes); const image = open(bytes); expect(readUInt32(image, FIXTURE_BINARY_BASE + 0x308n)).toBe(0x200); expect(readUInt32(image, FIXTURE_BINARY_BASE + 0x30cn)).toBe(1); expect(readUInt32(image, FIXTURE_BINARY_BASE + 0x2004n)).toBe(0); expect(readUInt32(image, FIXTURE_BINARY_BASE + 0x2008n)).toBe(0); - expect(image.bytes.equals(bytes)).toBe(true); + expect(bytes.equals(snapshot)).toBe(true); }); it.each([183, 62])( @@ -327,6 +328,7 @@ it.each([183, 62])( { offset: 0, size: original.length }, { offset: 0x308, size: 8, address: FIXTURE_BINARY_BASE + 0x2000n }, ]); + const snapshot = Buffer.from(bytes); const image = open(bytes); expect(readSlot(image, FIXTURE_BINARY_BASE + 0x308n)).toBe( FIXTURE_BINARY_BASE + 0x200n, @@ -334,7 +336,7 @@ it.each([183, 62])( expect(readSlot(image, FIXTURE_BINARY_BASE + 0x2000n)).toBe( FIXTURE_BINARY_BASE + 0x333n, ); - expect(image.bytes.equals(bytes)).toBe(true); + expect(bytes.equals(snapshot)).toBe(true); }, );