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, 53 insertions, 0 deletions

diff --git a/kernel/gsp_phys_gpu.h b/kernel/gsp_phys_gpu.h
index 709b3a6..1d1db64 100644
--- a/kernel/gsp_phys_gpu.h
+++ b/kernel/gsp_phys_gpu.h
@@ -88,4 +88,57 @@ bool gsp_phys_ctrl_forward_enabled(void);
  */
 bool gsp_phys_work_forward_enabled(void);
 
+/*
+ * True when the gsp_phys_guest_mem module parameter is set (default 0: the
+ * debugfs rm-call ladder stays entirely on module-owned buffers, exactly as
+ * before). When set, ladder triggers 6 (W2G) and 7 (G2H) may point the real
+ * CE engine at one pinned guest RAM page identified by GPA, proving the
+ * translation path and both copy directions.
+ */
+bool gsp_phys_guest_mem_enabled(void);
+
+/*
+ * Translate a guest GPA to the pinned host PA (gsp_phys_guest_mem ladder
+ * support). The mdev is registered with vfio_register_emulated_iommu_dev():
+ * its VFIO type-1 container keeps the guest DMA mappings privately, so
+ * iommu_get_domain_for_dev() returns NULL there and the original
+ * IOMMU-domain path cannot resolve a GPA at runtime. The authoritative
+ * translation is the guest RAM backing file configured through debugfs
+ * gsp-phys-guest-ram (QEMU memory-backend-file, share=yes): the range's
+ * file page is pinned with read_cache_page() and page_to_phys() gives the
+ * host PA. Returns 0 and stores the PA on success; -ENODEV with no active
+ * mdev, -ENOENT when the file page cannot be read or the GPA is not mapped
+ * by the fallback IOMMU path, -ERANGE when the result is not a valid RAM
+ * PFN (so a caller never treats MMIO/dead space as RAM), and -EINVAL for a
+ * NULL output. The caller must hold no guest or rm lock; this helper takes
+ * nv_vgpu_driver.lock only for the mdev lookup and guest_ram_lock across
+ * the range walk/read.
+ */
+int gsp_phys_gpa_to_hpa(u64 gpa, u64 *hpa_out);
+
+/*
+ * Guest RAM backing-file configuration (debugfs gsp-phys-guest-ram). One
+ * shared file per module cycle, up to four GPA->file-offset ranges keyed by
+ * gpa_base. The first configure opens the file; the same path adds/replaces
+ * ranges, a different path is refused -EBUSY, and the ranges are dropped and
+ * the file closed by gsp_phys_guest_ram_clear() on physical-GPU release. The
+ * state accessor is lock-safe and writes "active=0" or the active path,
+ * range count and per-range gpa/off/size into the caller's buffer.
+ */
+int gsp_phys_guest_ram_configure(const char *path, u64 gpa_base,
+				 u64 file_offset, u64 size);
+void gsp_phys_guest_ram_clear(void);
+bool gsp_phys_guest_ram_active(void);
+void gsp_phys_guest_ram_state(char *buf, size_t len);
+
+/*
+ * Domain shape of the physical (claimed) device, as the P6a engine path
+ * needs it: the module programs raw host PAs into the CE page tables, so the
+ * engine may only run when the physical device's DMA addresses ARE host PAs.
+ * Returns 1 when the claimed device's IOMMU domain is
+ * IOMMU_DOMAIN_IDENTITY, 0 when another domain type, and -1 when the device
+ * is not claimed or has no domain (either way the caller must refuse).
+ */
+int gsp_phys_dma_domain_identity(void);
+
 #endif /* GSP_PHYS_GPU_H */