[PATCH v2 1/1] Define a low power mode for devices

[David Stevens <stevensd@chromium.org>]

Define a low power mode for virtio devices where the devices are
expected to maintain their state. This gives drivers an option for power
management besides simply resetting their device. In the virtualization
use case, this allows the guest to be suspended even with stateful
virtio devices like gpu and fs.

Low power mode is primarily defined at the transport layer. The only
part that depends on device-type specific details is whether a given
virtqueue is device driven or driver driven.

This change only defines the transport-specific implementation for
Virtio over PCI.
---
 content.tex       | 45 +++++++++++++++++++++++++++++++++++++++++++++
 transport-pci.tex |  7 +++++++
 2 files changed, 52 insertions(+)

diff --git a/content.tex b/content.tex
index 0a62dce5f65f..7016778c38d6 100644
--- a/content.tex
+++ b/content.tex
@@ -502,6 +502,51 @@ \section{Exporting Objects}\label{sec:Basic Facilities of a Virtio Device / Expo
 types. It is RECOMMENDED that devices generate version 4
 UUIDs as specified by \hyperref[intro:rfc4122]{[RFC4122]}.
 
+\section{Low Power Mode}\label{sec:Basic Facilities of a Virtio Device / Low Power Mode}
+
+Low power mode is a state a driver can put its device into to try to
+reduce the resource consumption of the device. While in low power
+mode, a device can generate wakeup events to inform its driver about
+device driven events. How a device is put into and taken out of low
+power mode is transport specific, as is how wakeup events are
+implemented.
+
+\devicenormative{\subsection}{Low Power Mode}{Basic Facilities of a Virtio
+Device / Low Power Mode}
+
+A device in low power mode MUST maintain its state such that all
+driver visible state after exiting low power mode exactly matches
+driver visible state before entering low power mode.
+
+A device in low power mode MUST continue to operate device driven
+queues. Device driven queues are queues where the driver provides
+buffers to the device that the device holds onto for an indeterminate
+time until some device-side event occurs (e.g. event queues, rx
+queues). When sending a used buffer notification for such a queue, the
+device MUST generate a wakeup event.
+
+A device in low power mode MUST continue to send configuration change
+notifications. When sending a configuration change notification, the
+device MUST generate a wakeup event.
+
+A device in low power mode SHOULD NOT generate wakeup events for
+driver driven queues. A device SHOULD stop sending used buffer
+notifications for such queues until after exiting the low power state.
+
+A device in low power mode SHOULD minimize its resource usage,
+although what steps to take are specific to a particular device
+implementation.
+
+\drivernormative{\subsection}{Low Power Mode}{Basic Facilities of a Virtio
+Device / Low Power Mode}
+
+A driver MUST not interact with a device in low power mode except
+to take the device out of low power mode or to handle wakeup events
+generated by the device.
+
+A driver MAY use wakeup events as a trigger to take the device out of
+low power mode, but it MAY also ignore wakeup events.
+
 \input{admin.tex}
 
 \chapter{General Initialization And Device Operation}\label{sec:General Initialization And Device Operation}
diff --git a/transport-pci.tex b/transport-pci.tex
index a5c6719ea871..6694e0f72d46 100644
--- a/transport-pci.tex
+++ b/transport-pci.tex
@@ -1212,3 +1212,10 @@ \subsubsection{Driver Handling Interrupts}\label{sec:Virtio Transport Options /
         re-examine the configuration space to see what changed.
     \end{itemize}
 \end{itemize}
+
+\subsubsection{Low Power Mode}\label{sec:Virtio Transport Options / Virtio Over PCI Bus / PCI-specific Initialization And Device Operation / Low Power Mode}
+
+Low power mode corresponds to the device power management state
+D3\textsubscript{Hot}. A device advertises support for low power mode
+by presenting the PCI Power Management Capability. Wakeup events are
+implemented as PCI Power Management Events (PMEs).
-- 
2.42.0.869.gea05f2083d-goog