From dc09d7f2a413407ed19074c762a4879afb2ae991 Mon Sep 17 00:00:00 2001 From: Gregory Lirent Date: Mon, 15 Jun 2026 12:07:43 +0300 Subject: [PATCH] Keep the arch layer's prose consumer-agnostic; note the x86-64 binding The generic address-space layer no longer names win32 in its comments: the khalf_score and gva_translate doc-comments described themselves in terms of their current Windows consumer, a downward coupling from the stable layer to a specific, swappable one. Reworded to describe what each primitive does, not who calls it. Also drop a dangling reference to the renamed engine handle. State the contract's real scope in memmodel.h: OS-agnostic but architecture- bound. The address-space key is the x86-64 CR3 (the PML4 base), shared by any guest OS on x86-64 - CR3 is an ISA register, not a Windows concept; only its per-process storage (DirectoryTableBase) is win32-specific and stays in the win32 engine. --- include/memmodel.h | 10 +++++++--- src/engine/gva.c | 4 ++-- src/engine/include/engine-arch.h | 10 +++++----- 3 files changed, 14 insertions(+), 10 deletions(-) diff --git a/include/memmodel.h b/include/memmodel.h index 6bc6512..74db7f1 100644 --- a/include/memmodel.h +++ b/include/memmodel.h @@ -1,4 +1,4 @@ -/* memmodel.h - the OS-agnostic memory-model contract (the middle layer). +/* memmodel.h - the OS-agnostic, x86-64 memory-model contract (the middle layer). * * This is the shared vocabulary between the ENGINE (which turns guest-physical * RAM into a usable virtual memory model via x86-64 paging + Windows bring-up) @@ -6,9 +6,13 @@ * concept: a handler compiled against this header literally cannot mention an * _EPROCESS, a PEB, or an LDR entry. * + * OS-agnostic, but architecture-bound: the address-space key is the x86-64 CR3 + * (the PML4 base), shared by any guest OS on x86-64 - it is not portable to an + * ISA with a different paging root (e.g. ARM64 TTBR0/1). + * * Everything here is keyed by a `vmie_mem*` (the opaque physical/paging - * substrate) plus a `cr3` (the address space). The engine handle `vmie` is - * never handed to a handler - only `vmie_mem*` + `cr3`. + * substrate) plus a `cr3` (the address space). The engine handle is never + * handed to a handler - only `vmie_mem*` + `cr3`. * * Conventions: * - `cr3` is a raw CR3 / DirectoryTableBase value; low flag bits are masked diff --git a/src/engine/gva.c b/src/engine/gva.c index 518359f..d1241a1 100644 --- a/src/engine/gva.c +++ b/src/engine/gva.c @@ -46,8 +46,8 @@ static int gva_gpa(vmie_mem* m, uintptr_t cr3, uintptr_t va, } /* cold extern translate: GPA of `va` under `cr3`, or -1. Wraps the hot static - * gva_gpa for cold callers outside this TU (win32 bring-up) without exposing the - * inlinable hot primitive. Declared in engine-arch.h. */ + * gva_gpa for cold callers outside this TU without exposing the inlinable hot + * primitive. Declared in engine-arch.h. */ __attribute__((cold)) int gva_translate(vmie_mem* m, uintptr_t cr3, uintptr_t va, uintptr_t* gpa) { return gva_gpa(m, cr3, va, gpa, NULL); diff --git a/src/engine/include/engine-arch.h b/src/engine/include/engine-arch.h index a323e65..c317513 100644 --- a/src/engine/include/engine-arch.h +++ b/src/engine/include/engine-arch.h @@ -21,15 +21,15 @@ /* gva_read/gva_write/gva_regions/gva_sweep + gva_sweep_cb and vregion/VR_* * are the OS-agnostic contract: declared in memmodel.h, pulled in above. */ -/* paging heuristic, shared by the arch walker and the win32 bring-up. Counts - * present kernel-half PML4 entries under `pml4` (an address-space liveness - * score). OS-agnostic: const vmie_mem*, no profile/struct vmie. */ +/* paging heuristic, shared by every PT-walking TU. Counts present kernel-half + * PML4 entries under `pml4` (an address-space liveness score). OS-agnostic: + * const vmie_mem*, no profile, no engine handle. */ int khalf_score(const vmie_mem* m, uint64_t pml4) __attribute__((cold)); /* cold extern wrapper over the hot static page-table walk: translate `va` under * `cr3` to a GPA (no leaf length). Returns 0 on success, -1 if not present. For - * cold callers outside gva.c (win32 bring-up); the hot inlinable primitive stays - * private to gva.c. */ + * cold callers outside gva.c; the hot inlinable primitive stays private to + * gva.c. */ int gva_translate(vmie_mem* m, uintptr_t cr3, uintptr_t va, uintptr_t* gpa) __attribute__((cold)); #endif /* VMIE_ENGINE_ARCH_H */