gsp-phys: P6a - real copy engine reads/writes guest RAM pages

- file-backed guest RAM (launcher memory-backend-file share=on) and
  in-kernel GPA->HPA translation through the shared file page cache
  (read_cache_page + page_to_phys + pfn_valid), opened O_LARGEFILE;
  new default-off gsp_phys_guest_mem parameter
- debugfs gsp-phys-guest-ram (path + gpa/off/size ranges) and
  gsp-phys-guest-gpa (one pinned GPA per boot); rm-call triggers 6/7 run
  host->guest and guest->host 4 KiB CE copies; trigger 8 is a PTE
  self-test through a fresh slot
- guest page-table slots are pre-built during ladder stage 3: runtime
  PTE writes into an already-walked page-table line are not observed
  without a TLB invalidate
- guest RAM layout (q35 4.2, 4 GiB): below-4G GPA == file offset,
  above-4G offset = GPA - 0x80000000 (2 GiB PCI hole)
- tests: tools/test/gpage_test.c guest probe; docs + STATE-CURRENT
  record the live green (G2H/W2G with semaphore release, guest observed
  the write, smoke ALL OK 64/64, clean latched release)

1 files changed, 16 insertions, 1 deletions

diff --git a/kernel/gsp_phys_booter.h b/kernel/gsp_phys_booter.h
index 2c24524..b44d079 100644
--- a/kernel/gsp_phys_booter.h
+++ b/kernel/gsp_phys_booter.h
@@ -283,7 +283,22 @@ int gsp_phys_boot_rm_unload(void __iomem *bar0);
  *     gsp_phys_rm_lock, per-RPC bounded (2000 ms), aborts at the first
  *     failure with no object teardown (UNLOAD + rmmod is the fail-safe),
  *     never touches WPR2, and is inert until the file is written. Ladder
- *     buffers are freed by gsp_phys_boot_staging_free() on release.
+ *     buffers are freed by gsp_phys_boot_staging_free() on release. With
+ *     gsp_phys_guest_mem=1 and a GPA pinned through gsp-phys-guest-gpa,
+ *     writing 7 (G2H, guest read) and then 6 (W2G, guest write) additionally
+ *     run one 4 KB CE copy each against that guest RAM page: the GPA is
+ *     translated through the active mdev's VFIO type-1 domain, the physical
+ *     device's domain must be identity, the corresponding channel PDB slot
+ *     (0x106 read / 0x105 write) is programmed with the translated HPA, and
+ *     the result is verified with a direct-map memcmp. Both directions are
+ *     gated on a live READY claim, ladder stage >= 3 and the pinned GPA;
+ *     every refusal is a logged no-op and no guest byte is touched unless
+ *     G2H already proved the translation.
+ *   - "gsp-phys-guest-gpa" (write-only, mode 0200): pin the one guest RAM
+ *     GPA ("0x<hex>", 4 KB page-aligned) that the rm-call guest directions
+ *     may touch. One GPA per boot (a second different GPA is refused:
+ *     stale-GMMU-TLB safety); the pin is cleared with the ladder state on
+ *     release/re-prime.
  *   - "gsp-phys-log-dump" (read-only, mode 0444): dumps the LOGINIT and
  *     LOGRM libos task-log host buffers allocated at stage-3d prime. Per
  *     buffer: a one-line header (name, allocated size, kernel VA, DMA