[PATCH RFC] virtio-mem: add shared/private memory property details

From: Marc-André Lureau <[email protected]>

Add specification text for platforms where system RAM has a
shared/private property (e.g., confidential computing environments such
as AMD SEV-SNP or Intel TDX). Define the device and driver requirements
for memory state transitions during plug/unplug operations, and
guidance for VIRTIO_MEM_F_UNPLUGGED_INACCESSIBLE case.

Signed-off-by: Marc-André Lureau <[email protected]>
---
 device-types/mem/description.tex | 37 ++++++++++++++++++++++++++++++--
 1 file changed, 35 insertions(+), 2 deletions(-)

diff --git a/device-types/mem/description.tex b/device-types/mem/description.tex
index 9acf63f..1eefea0 100644
--- a/device-types/mem/description.tex
+++ b/device-types/mem/description.tex
@@ -42,6 +42,18 @@ \section{Memory Device}\label{sec:Device Types / Memory Device}
 provides the exact same properties with the exact same semantics for
 plugged device memory as available for comparable RAM in the same configuration.
 
+In some configurations, system RAM might additionally have a shared/private
+property, indicating whether memory is accessible to both the guest and the
+host (shared) or only to the guest (private). \footnote{For example, in
+confidential computing environments such as AMD SEV-SNP or Intel TDX.
+The mechanism for converting between shared and private states is
+platform-specific; for example, it might involve dedicated CPU instructions
+or hypercalls.} The device provides unplugged memory in the shared state.
+When memory blocks are plugged, the driver is expected to convert them to
+the private state before use. Unless VIRTIO_MEM_F_UNPLUGGED_INACCESSIBLE
+has been negotiated, the driver is expected to convert them back to the
+shared state before unplugging.
+
 \subsection{Device ID}\label{sec:Device Types / Memory Device / Device ID}
 24
 
@@ -58,8 +70,9 @@ \subsection{Feature bits}\label{sec:Device Types / Memory Device / Feature bits}
 configuration is valid and corresponds to an ACPI PXM.
 \item[VIRTIO_MEM_F_UNPLUGGED_INACCESSIBLE (1)] The driver is not allowed to
 access unplugged memory. \footnote{On platforms with memory properties that
-might get modified implicitly on memory access, this feature is expected to
-be offered by the device.}
+might get modified implicitly on memory access, or on platforms with a
+shared/private memory property, this feature is expected to be offered by
+the device.}
 \item[VIRTIO_MEM_F_PERSISTENT_SUSPEND (2)] The driver can allow the guest
 to enter suspended state (deep sleep, suspend-to-RAM).
 \end{description}
@@ -176,9 +189,15 @@ \subsection{Device Initialization}\label{Device Types / Memory Device / Device I
 The device MUST NOT modify memory or memory properties of plugged memory
 blocks during device reset.
 
+On platforms with a shared/private memory property, the device MUST NOT
+change the shared/private state of memory blocks during device reset.
+
 The device SHOULD offer VIRTIO_MEM_F_PERSISTENT_SUSPEND if the platform
 supports suspending (deep sleep, suspend-to-RAM) with plugged memory blocks.
 
+The device SHOULD offer VIRTIO_MEM_F_UNPLUGGED_INACCESSIBLE if the platform
+has a shared/private memory property.
+
 \subsection{Device Operation}\label{sec:Device Types / Memory Device / Device Operation}
 
 The device notifies the driver about the amount of memory the device wants
@@ -256,6 +275,15 @@ \subsection{Device Operation}\label{sec:Device Types / Memory Device / Device Op
 If VIRTIO_MEM_F_UNPLUGGED_INACCESSIBLE has been negotiated, the driver
 MUST NOT read memory or query memory properties of unplugged memory blocks.
 
+On platforms with a shared/private memory property, the driver MUST convert
+plugged memory blocks to the private state before initializing or otherwise
+using them.
+
+On platforms with a shared/private memory property, the driver MUST convert
+memory blocks to the shared state before requesting to unplug them (for
+VIRTIO_MEM_REQ_UNPLUG_ALL, this applies to all plugged memory blocks), unless
+VIRTIO_MEM_F_UNPLUGGED_INACCESSIBLE has been negotiated.
+
 The driver MUST NOT request unplug of memory blocks while corresponding memory
 or memory properties are still in use.
 
@@ -285,6 +313,11 @@ \subsection{Device Operation}\label{sec:Device Types / Memory Device / Device Op
 The device MAY modify memory of unplugged memory blocks or reset memory
 properties of such memory blocks to platform defaults at any time.
 
+On platforms with a shared/private memory property, the device MUST provide
+unplugged memory blocks in the shared state.  If
+VIRTIO_MEM_F_UNPLUGGED_INACCESSIBLE has been negotiated, the device MUST
+convert memory blocks to the shared state after unplugging them.
+
 The device MUST NOT modify memory or memory properties of plugged memory
 blocks.
 
-- 
2.53.0