[PATCH v3 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       | 61 +++++++++++++++++++++++++++++++++++++++++++++++
 transport-pci.tex |  9 +++++++
 2 files changed, 70 insertions(+)

diff --git a/content.tex b/content.tex
index 0a62dce5f65f..c1ff542bbe2c 100644
--- a/content.tex
+++ b/content.tex
@@ -502,6 +502,67 @@ \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}
+
+Devices and drivers can implement a low power mode: in this mode,
+device state is maintained but the driver does not access the device,
+allowing the device to reduce its power consumption. While in low
+power mode, after a device sends a notification, it generates a wakeup
+signal to inform the driver of the pending notification. While the
+device is in low power mode, the driver only needs to check for
+notifications after receiving a wakeup signal. How a device is put
+into and taken out of low power mode is transport specific, as is how
+wakeup signals are implemented.
+
+To give the driver a chance to respond to external input, the device
+is expected to send a wakeup signal after sending a notification
+resulting from such input. To achieve this, the device is expected to
+send wakeup signals after sending configuration change notifications.
+For used buffer notifications, device queues can be split into two
+categories: device led queues and driver led queues. Device led queues
+are queues where the device holds onto buffers that have been made
+available by the driver for an indeterminate period of time, until
+some device-side event occurs (e.g. event queues, rx queues). Driver
+led queues are queues where the device processes available buffers and
+adds them to used queue within a bounded time (e.g. command queues, tx
+queues). The device is expected to send wakeup signals after sending
+used buffer notifications for device led queues, but not for driver
+led queues.
+
+\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 led queues.
+After sending a used buffer notification for such a queue, the device
+MUST generate a wakeup signal.
+
+A device in low power mode MUST continue to send configuration change
+notifications. After sending a configuration change notification, the
+device MUST generate a wakeup signal.
+
+A device in low power mode SHOULD NOT generate wakeup signal 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 recieve and
+acknowledge a wakeup signal generated by the device, all of which are
+done in a transport-specific way.
+
+A driver MAY use wakeup signals as a trigger to take the device out of
+low power mode, but it MAY also ignore wakeup signals.
+
 \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..932f3299dbab 100644
--- a/transport-pci.tex
+++ b/transport-pci.tex
@@ -1212,3 +1212,12 @@ \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}
+
+Devices can implement support for low power mode (see \ref{sec:Basic
+Facilities of a Virtio Device / 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.43.0.rc2.451.g8631bc7472-goog