admin: Add theory of operation for device parts

A device can get and set the state of the device which is
organized as multiple device parts. This can be useful
in cases of VM snapshot, VM migration, debug or some other use
cases.

Add the theory of operations on how to get/set device parts
and how it affects when the device is stopped or resumed.

Fixes: oasis-tcs#176
Signed-off-by: Michael S. Tsirkin <[email protected]>
Signed-off-by: Parav Pandit <[email protected]>

admin-cmds-capabilities.tex

@@ -51,6 +51,22 @@ \subsubsection{Device and driver capabilities}\label{sec:Basic Facilities of a V
 \end{tabularx}
 \end{table}
 
+Common capabilities are listed:
+
+\begin{table}[H]
+\caption{Common capability ids}
+\label{table:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device and driver capabilities / Common capability ids}
+\begin{tabularx}{\textwidth}{ |l|l|X| }
+\hline
+Id & Name & Description  \\
+\hline \hline
+0x0000 & \hyperref[par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts / VIRTIO_DEV_PARTS_CAP]{VIRTIO_DEV_PARTS_CAP} & Device parts capability \\
+\hline
+0x0001-0x07ff & - & Generic capability for all device types \\
+\hline
+\end{tabularx}
+\end{table}
+
 Device type specific capabilities are described separately for each device
 type under \field{Device and driver capabilities}.
 

admin-cmds-device-parts.tex

@@ -0,0 +1,55 @@
+\subsubsection{Device parts}\label{sec:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts}
+
+In some systems, there is a need to capture the state of all or part of
+a device and subsequently restore either the same device or a
+different one to this captured state. A group owner device can support
+administration commands to facilitate these get and set operations for
+the group member devices.
+
+For example, a hypervisor can use the administration commands to
+capture parts of the device state and save the result as part of
+a VM snapshot. Later, the hypervisor can retrieve the snapshot and use the
+administration commands to restore parts of a device to resume
+VM operation.
+
+As another example, these commands can be used to facilitate VM migration by the
+hypervisor: one (source) hypervisor can get parts of a device and send
+the results to another (destination) hypervisor, which will in turn
+set (restore) parts of (another) device to resume the VM operation on
+the destination.
+
+The device comprises many device parts which the driver can get and set.
+Administration commands are provided to either get and set all the device
+parts at once, or to get the device parts metadata that indicates which
+device parts are present, and later to get and set specific device parts.
+To get and set the device parts or their metadata, the driver first creates a
+device parts resource object, indicating whether the object should
+handle get or set operations but not both simultaneously. The device and the
+driver indicate the device parts resource objects' limit using the capability
+VIRTIO_DEV_PARTS_CAP.
+
+The device can be stopped to prevent device parts from changing.
+When the device is stopped, it does not initiate any transport requests.
+For instance, the device refrains from sending any configuration or
+virtqueue notifications and does not access any virtqueues or the driver's
+buffer memory. While the driver may remain active and continue to send
+notifications to the device, potentially updating some device parts,
+the device itself will not initiate any transport requests.
+
+\paragraph{VIRTIO_DEV_PARTS_CAP}
+\label{par:Basic Facilities of a Virtio Device / Device groups / Group administration commands / Device parts / VIRTIO_DEV_PARTS_CAP}
+
+The capability VIRTIO_DEV_PARTS_CAP indicates the device parts resource objects limit.
+\field{cap_specific_data} is in the format \field{struct virtio_dev_parts_cap}.
+
+\begin{lstlisting}
+struct virtio_dev_parts_cap {
+        u8 get_parts_resource_objects_limit;
+        u8 set_parts_resource_objects_limit;
+};
+\end{lstlisting}
+
+\field{get_parts_resource_objects_limit} indicates the supported device parts
+resource objects for retrieving the device parts.
+\field{set_parts_resource_objects_limit} indicates the supported device parts
+resource objects for restoring the device parts.

admin.tex

@@ -328,6 +328,7 @@ \subsection{Group administration commands}\label{sec:Basic Facilities of a Virti
 \input{admin-cmds-legacy-interface.tex}
 \input{admin-cmds-capabilities.tex}
 \input{admin-cmds-resource-objects.tex}
+\input{admin-cmds-device-parts.tex}
 
 \devicenormative{\subsubsection}{Group administration commands}{Basic Facilities of a Virtio Device / Device groups / Group administration commands}