[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: [PATCH v1 06/20] virtio-mem-balloon: Maintain mem balloon device spec in separate directory
Move virtio memory balloon device specification to its own file
similar to recent virtio devices.
While at it, place device specification, its driver and device
conformance into its own directory to have self contained device
specification.
Fixes: https://github.com/oasis-tcs/virtio-spec/issues/153
Signed-off-by: Parav Pandit <parav@nvidia.com>
---
changelog:
v0->v1:
- moved to device specific directory
---
conformance.tex | 28 +-
content.tex | 636 +-----------------
.../virtio-mem-balloon/device-conformance.tex | 12 +
device-types/virtio-mem-balloon/device.tex | 634 +++++++++++++++++
.../virtio-mem-balloon/driver-conformance.tex | 12 +
5 files changed, 661 insertions(+), 661 deletions(-)
create mode 100644 device-types/virtio-mem-balloon/device-conformance.tex
create mode 100644 device-types/virtio-mem-balloon/device.tex
create mode 100644 device-types/virtio-mem-balloon/driver-conformance.tex
diff --git a/conformance.tex b/conformance.tex
index e5bb9d9..a92ed5f 100644
--- a/conformance.tex
+++ b/conformance.tex
@@ -138,19 +138,7 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets}
\import{device-types/virtio-block/}{driver-conformance}
\import{device-types/virtio-console/}{driver-conformance}
\import{device-types/virtio-entropy/}{driver-conformance}
-
-\conformance{\subsection}{Traditional Memory Balloon Driver Conformance}\label{sec:Conformance / Driver Conformance / Traditional Memory Balloon Driver Conformance}
-
-A traditional memory balloon driver MUST conform to the following normative statements:
-
-\begin{itemize}
-\item \ref{drivernormative:Device Types / Memory Balloon Device / Feature bits}
-\item \ref{drivernormative:Device Types / Memory Balloon Device / Device Operation}
-\item \ref{drivernormative:Device Types / Memory Balloon Device / Device Operation / Memory Statistics}
-\item \ref{drivernormative:Device Types / Memory Balloon Device / Device Operation / Free Page Hinting}
-\item \ref{drivernormative:Device Types / Memory Balloon Device / Device Operation / Page Poison}
-\item \ref{drivernormative:Device Types / Memory Balloon Device / Device Operation / Free Page Reporting}
-\end{itemize}
+\import{device-types/virtio-mem-balloon/}{driver-conformance}
\conformance{\subsection}{SCSI Host Driver Conformance}\label{sec:Conformance / Driver Conformance / SCSI Host Driver Conformance}
@@ -366,19 +354,7 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets}
\import{device-types/virtio-block/}{device-conformance}
\import{device-types/virtio-console/}{device-conformance}
\import{device-types/virtio-entropy/}{device-conformance}
-
-\conformance{\subsection}{Traditional Memory Balloon Device Conformance}\label{sec:Conformance / Device Conformance / Traditional Memory Balloon Device Conformance}
-
-A traditional memory balloon device MUST conform to the following normative statements:
-
-\begin{itemize}
-\item \ref{devicenormative:Device Types / Memory Balloon Device / Feature bits}
-\item \ref{devicenormative:Device Types / Memory Balloon Device / Device Operation}
-\item \ref{devicenormative:Device Types / Memory Balloon Device / Device Operation / Memory Statistics}
-\item \ref{devicenormative:Device Types / Memory Balloon Device / Device Operation / Free Page Hinting}
-\item \ref{devicenormative:Device Types / Memory Balloon Device / Device Operation / Page Poison}
-\item \ref{devicenormative:Device Types / Memory Balloon Device / Device Operation / Free Page Reporting}
-\end{itemize}
+\import{device-types/virtio-mem-balloon/}{device-conformance}
\conformance{\subsection}{SCSI Host Device Conformance}\label{sec:Conformance / Device Conformance / SCSI Host Device Conformance}
diff --git a/content.tex b/content.tex
index 953488e..d374ae2 100644
--- a/content.tex
+++ b/content.tex
@@ -3007,641 +3007,7 @@ \chapter{Device Types}\label{sec:Device Types}
\import{device-types/virtio-block/}{device}
\import{device-types/virtio-console/}{device}
\import{device-types/virtio-entropy/}{device}
-
-\section{Traditional Memory Balloon Device}\label{sec:Device Types / Memory Balloon Device}
-
-This is the traditional balloon device. The device number 13 is
-reserved for a new memory balloon interface, with different
-semantics, which is expected in a future version of the standard.
-
-The traditional virtio memory balloon device is a primitive device for
-managing guest memory: the device asks for a certain amount of
-memory, and the driver supplies it (or withdraws it, if the device
-has more than it asks for). This allows the guest to adapt to
-changes in allowance of underlying physical memory. If the
-feature is negotiated, the device can also be used to communicate
-guest memory statistics to the host.
-
-\subsection{Device ID}\label{sec:Device Types / Memory Balloon Device / Device ID}
- 5
-
-\subsection{Virtqueues}\label{sec:Device Types / Memory Balloon Device / Virtqueues}
-\begin{description}
-\item[0] inflateq
-\item[1] deflateq
-\item[2] statsq
-\item[3] free_page_vq
-\item[4] reporting_vq
-\end{description}
-
- statsq only exists if VIRTIO_BALLOON_F_STATS_VQ is set.
-
- free_page_vq only exists if VIRTIO_BALLOON_F_FREE_PAGE_HINT is set.
-
- reporting_vq only exists if VIRTIO_BALLOON_F_PAGE_REPORTING is set.
-
-\subsection{Feature bits}\label{sec:Device Types / Memory Balloon Device / Feature bits}
-\begin{description}
-\item[VIRTIO_BALLOON_F_MUST_TELL_HOST (0)] Host has to be told before
- pages from the balloon are used.
-
-\item[VIRTIO_BALLOON_F_STATS_VQ (1)] A virtqueue for reporting guest
- memory statistics is present.
-\item[VIRTIO_BALLOON_F_DEFLATE_ON_OOM (2) ] Deflate balloon on
- guest out of memory condition.
-\item[ VIRTIO_BALLOON_F_FREE_PAGE_HINT(3) ] The device has support for free
- page hinting. A virtqueue for providing hints as to what memory is
- currently free is present. Configuration field \field{free_page_hint_cmd_id}
- is valid.
-\item[ VIRTIO_BALLOON_F_PAGE_POISON(4) ] A hint to the device, that the driver
- will immediately write \field{poison_val} to pages after deflating them.
- Configuration field \field{poison_val} is valid.
-\item[ VIRTIO_BALLOON_F_PAGE_REPORTING(5) ] The device has support for free
- page reporting. A virtqueue for reporting free guest memory is present.
-
-\end{description}
-
-\drivernormative{\subsubsection}{Feature bits}{Device Types / Memory Balloon Device / Feature bits}
-The driver SHOULD accept the VIRTIO_BALLOON_F_MUST_TELL_HOST
-feature if offered by the device.
-
-The driver SHOULD clear the VIRTIO_BALLOON_F_PAGE_POISON flag if it will
-not immediately write \field{poison_val} to deflated pages (e.g., to
-initialize them, or fill them with a poison value).
-
-If the driver is expecting the pages to retain some initialized value,
-it MUST NOT accept VIRTIO_BALLOON_F_PAGE_REPORTING unless it also
-negotiates VIRTIO_BALLOON_F_PAGE_POISON.
-
-\devicenormative{\subsubsection}{Feature bits}{Device Types / Memory Balloon Device / Feature bits}
-If the device offers the VIRTIO_BALLOON_F_MUST_TELL_HOST feature
-bit, and if the driver did not accept this feature bit, the
-device MAY signal failure by failing to set FEATURES_OK
-\field{device status} bit when the driver writes it.
-\subparagraph{Legacy Interface: Feature bits}\label{sec:Device
-Types / Memory Balloon Device / Feature bits / Legacy Interface:
-Feature bits}
-As the legacy interface does not have a way to gracefully report feature
-negotiation failure, when using the legacy interface,
-transitional devices MUST support guests which do not negotiate
-VIRTIO_BALLOON_F_MUST_TELL_HOST feature, and SHOULD
-allow guest to use memory before notifying host if
-VIRTIO_BALLOON_F_MUST_TELL_HOST is not negotiated.
-
-\subsection{Device configuration layout}\label{sec:Device Types / Memory Balloon Device / Device configuration layout}
- \field{num_pages} and \field{actual} are always available.
-
- \field{free_page_hint_cmd_id} is available if
- VIRTIO_BALLOON_F_FREE_PAGE_HINT has been negotiated. The field is
- read-only by the driver.
- \field{poison_val} is available if VIRTIO_BALLOON_F_PAGE_POISON has been
- negotiated.
-
-\begin{lstlisting}
-struct virtio_balloon_config {
- le32 num_pages;
- le32 actual;
- le32 free_page_hint_cmd_id;
- le32 poison_val;
-};
-\end{lstlisting}
-
-\subparagraph{Legacy Interface: Device configuration layout}\label{sec:Device Types / Memory Balloon Device / Device
-configuration layout / Legacy Interface: Device configuration layout}
-When using the legacy interface, transitional devices and drivers
-MUST format the fields in struct virtio_balloon_config
-according to the little-endian format.
-\begin{note}
-This is unlike the usual convention that legacy device fields are guest endian.
-\end{note}
-
-\subsection{Device Initialization}\label{sec:Device Types / Memory Balloon Device / Device Initialization}
-
-The device initialization process is outlined below:
-
-\begin{enumerate}
-\item The inflate and deflate virtqueues are identified.
-
-\item If the VIRTIO_BALLOON_F_STATS_VQ feature bit is negotiated:
- \begin{enumerate}
- \item Identify the stats virtqueue.
- \item Add one empty buffer to the stats virtqueue.
- \end{enumerate}
-
-\item If the VIRTIO_BALLOON_F_FREE_PAGE_HINT feature bit is negotiated,
- identify the free_page_vq.
-\item If the VIRTIO_BALLOON_F_PAGE_POISON feature bit is negotiated, update
- the \field{poison_val} configuration field.
-\item If the VIRTIO_BALLOON_F_PAGE_REPORTING feature bit is negotiated,
- identify the reporting_vq.
-
-\item DRIVER_OK is set: device operation begins.
-
-\item If the VIRTIO_BALLOON_F_STATS_VQ feature bit is negotiated, then
- notify the device about the stats virtqueue buffer.
-\item If the VIRTIO_BALLOON_F_PAGE_REPORTING feature bit is negotiated, then
- begin reporting free pages to the device.
-\end{enumerate}
-
-\subsection{Device Operation}\label{sec:Device Types / Memory Balloon Device / Device Operation}
-
-The device is driven either by the receipt of a configuration
-change notification, or by changing guest memory needs, such as
-performing memory compaction or responding to out of memory
-conditions.
-
-\begin{enumerate}
-\item \field{num_pages} configuration field is examined. If this is
- greater than the \field{actual} number of pages, the balloon wants
- more memory from the guest. If it is less than \field{actual},
- the balloon doesn't need it all.
-
-\item To supply memory to the balloon (aka. inflate):
- \begin{enumerate}
- \item The driver constructs an array of addresses of unused memory
- pages. These addresses are divided by 4096\footnote{This is historical, and independent of the guest page size.
-} and the descriptor
- describing the resulting 32-bit array is added to the inflateq.
- \end{enumerate}
-
-\item To remove memory from the balloon (aka. deflate):
- \begin{enumerate}
- \item The driver constructs an array of addresses of memory pages
- it has previously given to the balloon, as described above.
- This descriptor is added to the deflateq.
-
- \item If the VIRTIO_BALLOON_F_MUST_TELL_HOST feature is negotiated, the
- guest informs the device of pages before it uses them.
-
- \item Otherwise, the guest is allowed to re-use pages previously
- given to the balloon before the device has acknowledged their
- withdrawal\footnote{In this case, deflation advice is merely a courtesy.
-}.
- \end{enumerate}
-
-\item In either case, the device acknowledges inflate and deflate
-requests by using the descriptor.
-\item Once the device has acknowledged the inflation or
- deflation, the driver updates \field{actual} to reflect the new number of pages in the balloon.
-\end{enumerate}
-
-\drivernormative{\subsubsection}{Device Operation}{Device Types / Memory Balloon Device / Device Operation}
-The driver SHOULD supply pages to the balloon when \field{num_pages} is
-greater than the actual number of pages in the balloon.
-
-The driver MAY use pages from the balloon when \field{num_pages} is
-less than the actual number of pages in the balloon.
-
-The driver MAY supply pages to the balloon when \field{num_pages} is
-greater than or equal to the actual number of pages in the balloon.
-
-If VIRTIO_BALLOON_F_DEFLATE_ON_OOM has not been negotiated, the
-driver MUST NOT use pages from the balloon when \field{num_pages}
-is less than or equal to the actual number of pages in the
-balloon.
-
-If VIRTIO_BALLOON_F_DEFLATE_ON_OOM has been negotiated, the
-driver MAY use pages from the balloon when \field{num_pages}
-is less than or equal to the actual number of pages in the
-balloon if this is required for system stability
-(e.g. if memory is required by applications running within
- the guest).
-
-The driver MUST use the deflateq to inform the device of pages that it
-wants to use from the balloon.
-
-If the VIRTIO_BALLOON_F_MUST_TELL_HOST feature is negotiated, the
-driver MUST NOT use pages from the balloon until
-the device has acknowledged the deflate request.
-
-Otherwise, if the VIRTIO_BALLOON_F_MUST_TELL_HOST feature is not
-negotiated, the driver MAY begin to re-use pages previously
-given to the balloon before the device has acknowledged the
-deflate request.
-
-In any case, the driver MUST NOT use pages from the balloon
-after adding the pages to the balloon, but before the device has
-acknowledged the inflate request.
-
-The driver MUST NOT request deflation of pages in
-the balloon before the device has acknowledged the inflate
-request.
-
-The driver MUST update \field{actual} after changing the number
-of pages in the balloon.
-
-The driver MAY update \field{actual} once after multiple
-inflate and deflate operations.
-
-\devicenormative{\subsubsection}{Device Operation}{Device Types / Memory Balloon Device / Device Operation}
-
-The device MAY modify the contents of a page in the balloon
-after detecting its physical number in an inflate request
-and before acknowledging the inflate request by using the inflateq
-descriptor.
-
-If the VIRTIO_BALLOON_F_MUST_TELL_HOST feature is negotiated, the
-device MAY modify the contents of a page in the balloon
-after detecting its physical number in an inflate request
-and before detecting its physical number in a deflate request
-and acknowledging the deflate request.
-
-\paragraph{Legacy Interface: Device Operation}\label{sec:Device
-Types / Memory Balloon Device / Device Operation / Legacy
-Interface: Device Operation}
-When using the legacy interface, the driver SHOULD ignore the
-used length values.
-\begin{note}
-Historically, some devices put the total descriptor length there,
-even though no data was actually written.
-\end{note}
-When using the legacy interface, the driver MUST write out all
-4 bytes each time it updates the \field{actual} value in the
-configuration space, using a single atomic operation.
-
-When using the legacy interface, the device SHOULD NOT use the
-\field{actual} value written by the driver in the configuration
-space, until the last, most-significant byte of the value has been
-written.
-\begin{note}
-Historically, devices used the \field{actual} value, even though
-when using Virtio Over PCI Bus the device-specific configuration
-space was not guaranteed to be atomic. Using intermediate
-values during update by driver is best avoided, except for
-debugging.
-
-Historically, drivers using Virtio Over PCI Bus wrote the
-\field{actual} value by using multiple single-byte writes in
-order, from the least-significant to the most-significant value.
-\end{note}
-\subsubsection{Memory Statistics}\label{sec:Device Types / Memory Balloon Device / Device Operation / Memory Statistics}
-
-The stats virtqueue is atypical because communication is driven
-by the device (not the driver). The channel becomes active at
-driver initialization time when the driver adds an empty buffer
-and notifies the device. A request for memory statistics proceeds
-as follows:
-
-\begin{enumerate}
-\item The device uses the buffer and sends a used buffer notification.
-
-\item The driver pops the used buffer and discards it.
-
-\item The driver collects memory statistics and writes them into a
- new buffer.
-
-\item The driver adds the buffer to the virtqueue and notifies the
- device.
-
-\item The device pops the buffer (retaining it to initiate a
- subsequent request) and consumes the statistics.
-\end{enumerate}
-
- Within the buffer, statistics are an array of 10-byte entries.
- Each statistic consists of a 16 bit
- tag and a 64 bit value. All statistics are optional and the
- driver chooses which ones to supply. To guarantee backwards
- compatibility, devices omit unsupported statistics.
-
-\begin{lstlisting}
-struct virtio_balloon_stat {
-#define VIRTIO_BALLOON_S_SWAP_IN 0
-#define VIRTIO_BALLOON_S_SWAP_OUT 1
-#define VIRTIO_BALLOON_S_MAJFLT 2
-#define VIRTIO_BALLOON_S_MINFLT 3
-#define VIRTIO_BALLOON_S_MEMFREE 4
-#define VIRTIO_BALLOON_S_MEMTOT 5
-#define VIRTIO_BALLOON_S_AVAIL 6
-#define VIRTIO_BALLOON_S_CACHES 7
-#define VIRTIO_BALLOON_S_HTLB_PGALLOC 8
-#define VIRTIO_BALLOON_S_HTLB_PGFAIL 9
- le16 tag;
- le64 val;
-} __attribute__((packed));
-\end{lstlisting}
-
-\drivernormative{\paragraph}{Memory Statistics}{Device Types / Memory Balloon Device / Device Operation / Memory Statistics}
-Normative statements in this section apply if and only if the
-VIRTIO_BALLOON_F_STATS_VQ feature has been negotiated.
-
-The driver MUST make at most one buffer available to the device
-in the statsq, at all times.
-
-After initializing the device, the driver MUST make an output
-buffer available in the statsq.
-
-Upon detecting that device has used a buffer in the statsq, the
-driver MUST make an output buffer available in the statsq.
-
-Before making an output buffer available in the statsq, the
-driver MUST initialize it, including one struct
-virtio_balloon_stat entry for each statistic that it supports.
-
-Driver MUST use an output buffer size which is a multiple of 6
-bytes for all buffers submitted to the statsq.
-
-Driver MAY supply struct virtio_balloon_stat entries in the
-output buffer submitted to the statsq in any order, without
-regard to \field{tag} values.
-
-Driver MAY supply a subset of all statistics in the output buffer
-submitted to the statsq.
-
-Driver MUST supply the same subset of statistics in all buffers
-submitted to the statsq.
-
-\devicenormative{\paragraph}{Memory Statistics}{Device Types / Memory Balloon Device / Device Operation / Memory Statistics}
-Normative statements in this section apply if and only if the
-VIRTIO_BALLOON_F_STATS_VQ feature has been negotiated.
-
-Within an output buffer submitted to the statsq,
-the device MUST ignore entries with \field{tag} values that it does not recognize.
-
-Within an output buffer submitted to the statsq,
-the device MUST accept struct virtio_balloon_stat entries in any
-order without regard to \field{tag} values.
-
-\paragraph{Legacy Interface: Memory Statistics}\label{sec:Device Types / Memory Balloon Device / Device Operation / Memory Statistics / Legacy Interface: Memory Statistics}
-
-When using the legacy interface, transitional devices and drivers
-MUST format the fields in struct virtio_balloon_stat
-according to the native endian of the guest rather than
-(necessarily when not using the legacy interface) little-endian.
-
-When using the legacy interface,
-the device SHOULD ignore all values in the first buffer in the
-statsq supplied by the driver after device initialization.
-\begin{note}
-Historically, drivers supplied an uninitialized buffer in the
-first buffer.
-\end{note}
-
-\subsubsection{Memory Statistics Tags}\label{sec:Device Types / Memory Balloon Device / Device Operation / Memory Statistics Tags}
-
-\begin{description}
-\item[VIRTIO_BALLOON_S_SWAP_IN (0)] The amount of memory that has been
- swapped in (in bytes).
-
-\item[VIRTIO_BALLOON_S_SWAP_OUT (1)] The amount of memory that has been
- swapped out to disk (in bytes).
-
-\item[VIRTIO_BALLOON_S_MAJFLT (2)] The number of major page faults that
- have occurred.
-
-\item[VIRTIO_BALLOON_S_MINFLT (3)] The number of minor page faults that
- have occurred.
-
-\item[VIRTIO_BALLOON_S_MEMFREE (4)] The amount of memory not being used
- for any purpose (in bytes).
-
-\item[VIRTIO_BALLOON_S_MEMTOT (5)] The total amount of memory available
- (in bytes).
-
-\item[VIRTIO_BALLOON_S_AVAIL (6)] An estimate of how much memory is available
- (in bytes) for starting new applications, without pushing the system to swap.
-
-\item[VIRTIO_BALLOON_S_CACHES (7)] The amount of memory, in bytes, that can be
- quickly reclaimed without additional I/O. Typically these pages are used for
- caching files from disk.
-
-\item[VIRTIO_BALLOON_S_HTLB_PGALLOC (8)] The number of successful hugetlb page
- allocations in the guest.
-
-\item[VIRTIO_BALLOON_S_HTLB_PGFAIL (9)] The number of failed hugetlb page
- allocations in the guest.
-\end{description}
-
-\subsubsection{Free Page Hinting}\label{sec:Device Types / Memory Balloon Device / Device Operation / Free Page Hinting}
-
-Free page hinting is designed to be used during migration to determine what
-pages within the guest are currently unused so that they can be skipped over
-while migrating the guest. The device will indicate that it is ready to start
-performing hinting by setting the \field{free_page_hint_cmd_id} to one of the
-non-reserved values that can be used as a command ID. The following values
-are reserved:
-
-\begin{description}
-\item[VIRTIO_BALLOON_CMD_ID_STOP (0)] Any command ID previously supplied by
- the device is invalid. The driver should stop hinting free pages until a
- new command ID is supplied, but should not release any hinted pages for
- use by the guest.
-
-\item[VIRTIO_BALLOON_CMD_ID_DONE (1)] Any command ID previously supplied by
- the device is invalid. The driver should stop hinting free pages, and
- should release all hinted pages for use by the guest.
-\end{description}
-
-When a hint is provided by the driver it indicates that the data contained
-in the given page is no longer needed and can be discarded. If the driver
-writes to the page this overrides the hint and the data will be retained.
-The contents of any stale pages that have not been written to since the
-page was hinted may be lost, and if read the contents of such pages will
-be uninitialized memory.
-
-A request for free page hinting proceeds as follows:
-
-\begin{enumerate}
-
-\item The driver examines the \field{free_page_hint_cmd_id} configuration field.
- If it contains a non-reserved value then free page hinting will begin.
-
-\item To supply free page hints:
- \begin{enumerate}
- \item The driver constructs an output buffer containing the new value from
- the \field{free_page_hint_cmd_id} configuration field and adds it to the
- free_page_vq.
- \item The driver maps a series of pages and adds them to the
- free_page_vq as individual scatter-gather input buffer entries.
- \item When the driver is no longer able to fetch additional pages to add
- to the free_page_vq, it will construct an output buffer containing the
- command ID VIRTIO_BALLOON_CMD_ID_STOP.
- \end{enumerate}
-
-\item A round of hinting ends either when the driver is no longer able to
- supply more pages for hinting as described above, or when the device
- updates \field{free_page_hint_cmd_id} configuration field to contain either
- VIRTIO_BALLOON_CMD_ID_STOP or VIRTIO_BALLOON_CMD_ID_DONE.
-
-\item The device may follow VIRTIO_BALLOON_CMD_ID_STOP with a new
- non-reserved value for the \field{free_page_hint_cmd_id} configuration
- field in which case it will resume supplying free page hints.
-
-\item Otherwise, if the device provides VIRTIO_BALLOON_CMD_ID_DONE then
- hinting is complete and the driver may release all previously hinted
- pages for use by the guest.
-
-\end{enumerate}
-
-\drivernormative{\paragraph}{Free Page Hinting}{Device Types / Memory Balloon Device / Device Operation / Free Page Hinting}
-
-Normative statements in this section apply if the
-VIRTIO_BALLOON_F_FREE_PAGE_HINT feature has been negotiated.
-
-The driver MUST use an output buffer size of 4 bytes for all output
-buffers submitted to the free_page_vq.
-
-The driver MUST start hinting by providing an output buffer containing
-the current command ID for the given block of pages.
-
-The driver MUST NOT provide more than one output buffer containing the
-current command ID.
-
-The driver SHOULD supply pages to the free_page_vq as input buffers when
-\field{free_page_hint_cmd_id} specifies a value of 2 or greater.
-
-The driver SHOULD stop supplying pages for hinting when
-\field{free_page_hint_cmd_id} specifies a value of VIRTIO_BALLOON_CMD_ID_STOP
-or VIRTIO_BALLOON_CMD_ID_DONE.
-
-If the driver is unable to supply pages, it MUST complete hinting by adding
-an output buffer containing the command ID VIRTIO_BALLOON_CMD_ID_STOP.
-
-The driver MAY release hinted pages for use by the guest including when the
-device has not yet used the descriptor containing the hinting request.
-
-The driver MUST treat the content of all hinted pages as uninitialized
-memory.
-
-The driver MUST initialize the contents of any previously hinted page
-released before \field{free_page_hint_cmd_id} specifies a value of
-VIRTIO_BALLOON_CMD_ID_DONE.
-
-The driver SHOULD release all previously hinted pages once
-\field{free_page_hint_cmd_id} specifies a value of
-VIRTIO_BALLOON_CMD_ID_DONE.
-
-\devicenormative{\paragraph}{Free Page Hinting}{Device Types / Memory Balloon Device / Device Operation / Free Page Hinting}
-
-Normative statements in this section apply if the
-VIRTIO_BALLOON_F_FREE_PAGE_HINT feature has been negotiated.
-
-The device SHOULD set \field{free_page_hint_cmd_id} to
-VIRTIO_BALLOON_CMD_ID_STOP any time that it will not be able to make use
-of the hints provided by the driver.
-
-The device MUST NOT reuse a command ID until it has received an output
-buffer containing VIRTIO_BALLOON_CMD_ID_STOP from the driver.
-
-The device MUST ignore pages that are provided with a command ID that does
-not match the current value in \field{free_page_hint_cmd_id}.
-
-If the content of a previously hinted page has not been modified by the
-guest since the device issued the \field{free_page_hint_cmd_id} associated
-with the hint, the device MAY modify the contents of the page.
-
-The device MUST NOT modify the content of a previously hinted page after
-\field{free_page_hint_cmd_id} is set to VIRTIO_BALLOON_CMD_ID_DONE.
-
-The device MUST report a value of VIRTIO_BALLOON_CMD_ID_DONE in
-\field{free_page_hint_cmd_id} when it no longer has need for the
-previously hinted pages.
-
-\paragraph{Legacy Interface: Free Page Hinting}\label{sec:Device Types / Memory Balloon Device / Device Operation / Free Page Hinting / Legacy Interface: Free Page Hinting}
-
-When using the legacy interface, transitional devices and drivers MUST
-format the command ID field in output buffers according to the native
-endian of the guest rather than (necessarily when not using the legacy
-interface) little-endian.
-
-\subsubsection{Page Poison}\label{sec:Device Types / Memory Balloon Device / Device Operation / Page Poison}
-
-Page Poison provides a way to notify the host that the guest is initializing
-free pages with \field{poison_val}. When the feature is enabled, pages will
-be immediately written to by the driver after deflating, and pages reported
-by free page reporting will retain the value indicated by \field{poison_val}.
-
-If the guest is not initializing freed pages, the driver should reject the
-VIRTIO_BALLOON_F_PAGE_POISON feature.
-
-If VIRTIO_BALLOON_F_PAGE_POISON feature has been negotiated, the driver
-will place the initialization value into the \field{poison_val}
-configuration field data.
-
-\drivernormative{\paragraph}{Page Poison}{Device Types / Memory Balloon Device / Device Operation / Page Poison}
-
-Normative statements in this section apply if the
-VIRTIO_BALLOON_F_PAGE_POISON feature has been negotiated.
-
-The driver MUST initialize the deflated pages with \field{poison_val} when
-they are reused by the driver.
-
-The driver MUST populate the \field{poison_val} configuration data before
-setting the DRIVER_OK bit.
-
-The driver MUST NOT modify \field{poison_val} while the DRIVER_OK bit is set.
-
-\devicenormative{\paragraph}{Page Poison}{Device Types / Memory Balloon Device / Device Operation / Page Poison}
-
-Normative statements in this section apply if the
-VIRTIO_BALLOON_F_PAGE_POISON feature has been negotiated.
-
-The device MAY use the content of \field{poison_val} as a hint to guest
-behavior.
-
-\subsubsection{Free Page Reporting}\label{sec:Device Types / Memory Balloon Device / Device Operation / Free Page Reporting}
-
-Free Page Reporting provides a mechanism similar to balloon inflation,
-however it does not provide a deflation queue. Reported free pages can
-be reused by the driver after the reporting request has been acknowledged
-without notifying the device.
-
-The driver will begin reporting free pages. When exactly and which free
-pages are reported is up to the driver.
-
-\begin{enumerate}
-
-\item The driver determines it has enough pages available to begin
- reporting free pages.
-
-\item The driver gathers free pages into a scatter-gather list and adds
- them to the reporting_vq.
-
-\item The device acknowledges the reporting request by using the
- reporting_vq descriptor.
-
-\item Once the device has acknowledged the report, the driver can reuse the
- reported free pages when needed (e.g., by putting them back to free page
- lists in the guest operating system).
-
-\item The driver can then continue to gather and report free pages until it
- has determined it has reported a sufficient quantity of pages.
-
-\end{enumerate}
-
-\drivernormative{\paragraph}{Free Page Reporting}{Device Types / Memory Balloon Device / Device Operation / Free Page Reporting}
-
-Normative statements in this section apply if the
-VIRTIO_BALLOON_F_PAGE_REPORTING feature has been negotiated.
-
-If the VIRTIO_BALLOON_F_PAGE_POISON feature has not been negotiated, then
-the driver MUST treat all reported pages as uninitialized memory.
-
-If the VIRTIO_BALLOON_F_PAGE_POISON feature has been negotiated, the
-driver MUST initialize all free pages with \field{poison_val} before
-reporting them.
-
-The driver MUST NOT use the reported pages until the device has
-acknowledged the reporting request.
-
-The driver MAY report free pages any time after DRIVER_OK is set.
-
-The driver SHOULD attempt to report large pages rather than smaller ones.
-
-The driver SHOULD avoid reading/writing reported pages if
-not strictly necessary.
-
-\devicenormative{\paragraph}{Free Page Reporting}{Device Types / Memory Balloon Device / Device Operation / Free Page Reporting}
-
-Normative statements in this section apply if the
-VIRTIO_BALLOON_F_PAGE_REPORTING feature has been negotiated.
-
-If the VIRTIO_BALLOON_F_PAGE_POISON feature has not been negotiated, the
-device MAY modify the contents of any page supplied in a report request
-before acknowledging that request by using the reporting_vq descriptor.
-
-If the VIRTIO_BALLOON_F_PAGE_POISON feature has been negotiated, the device
-MUST NOT modify the the content of a reported page to a value other than
-\field{poison_val}.
+\import{device-types/virtio-mem-balloon/}{device}
\section{SCSI Host Device}\label{sec:Device Types / SCSI Host Device}
diff --git a/device-types/virtio-mem-balloon/device-conformance.tex b/device-types/virtio-mem-balloon/device-conformance.tex
new file mode 100644
index 0000000..ff9ac4f
--- /dev/null
+++ b/device-types/virtio-mem-balloon/device-conformance.tex
@@ -0,0 +1,12 @@
+\conformance{\subsection}{Traditional Memory Balloon Device Conformance}\label{sec:Conformance / Device Conformance / Traditional Memory Balloon Device Conformance}
+
+A traditional memory balloon device MUST conform to the following normative statements:
+
+\begin{itemize}
+\item \ref{devicenormative:Device Types / Memory Balloon Device / Feature bits}
+\item \ref{devicenormative:Device Types / Memory Balloon Device / Device Operation}
+\item \ref{devicenormative:Device Types / Memory Balloon Device / Device Operation / Memory Statistics}
+\item \ref{devicenormative:Device Types / Memory Balloon Device / Device Operation / Free Page Hinting}
+\item \ref{devicenormative:Device Types / Memory Balloon Device / Device Operation / Page Poison}
+\item \ref{devicenormative:Device Types / Memory Balloon Device / Device Operation / Free Page Reporting}
+\end{itemize}
diff --git a/device-types/virtio-mem-balloon/device.tex b/device-types/virtio-mem-balloon/device.tex
new file mode 100644
index 0000000..a1d9603
--- /dev/null
+++ b/device-types/virtio-mem-balloon/device.tex
@@ -0,0 +1,634 @@
+\section{Traditional Memory Balloon Device}\label{sec:Device Types / Memory Balloon Device}
+
+This is the traditional balloon device. The device number 13 is
+reserved for a new memory balloon interface, with different
+semantics, which is expected in a future version of the standard.
+
+The traditional virtio memory balloon device is a primitive device for
+managing guest memory: the device asks for a certain amount of
+memory, and the driver supplies it (or withdraws it, if the device
+has more than it asks for). This allows the guest to adapt to
+changes in allowance of underlying physical memory. If the
+feature is negotiated, the device can also be used to communicate
+guest memory statistics to the host.
+
+\subsection{Device ID}\label{sec:Device Types / Memory Balloon Device / Device ID}
+ 5
+
+\subsection{Virtqueues}\label{sec:Device Types / Memory Balloon Device / Virtqueues}
+\begin{description}
+\item[0] inflateq
+\item[1] deflateq
+\item[2] statsq
+\item[3] free_page_vq
+\item[4] reporting_vq
+\end{description}
+
+ statsq only exists if VIRTIO_BALLOON_F_STATS_VQ is set.
+
+ free_page_vq only exists if VIRTIO_BALLOON_F_FREE_PAGE_HINT is set.
+
+ reporting_vq only exists if VIRTIO_BALLOON_F_PAGE_REPORTING is set.
+
+\subsection{Feature bits}\label{sec:Device Types / Memory Balloon Device / Feature bits}
+\begin{description}
+\item[VIRTIO_BALLOON_F_MUST_TELL_HOST (0)] Host has to be told before
+ pages from the balloon are used.
+
+\item[VIRTIO_BALLOON_F_STATS_VQ (1)] A virtqueue for reporting guest
+ memory statistics is present.
+\item[VIRTIO_BALLOON_F_DEFLATE_ON_OOM (2) ] Deflate balloon on
+ guest out of memory condition.
+\item[ VIRTIO_BALLOON_F_FREE_PAGE_HINT(3) ] The device has support for free
+ page hinting. A virtqueue for providing hints as to what memory is
+ currently free is present. Configuration field \field{free_page_hint_cmd_id}
+ is valid.
+\item[ VIRTIO_BALLOON_F_PAGE_POISON(4) ] A hint to the device, that the driver
+ will immediately write \field{poison_val} to pages after deflating them.
+ Configuration field \field{poison_val} is valid.
+\item[ VIRTIO_BALLOON_F_PAGE_REPORTING(5) ] The device has support for free
+ page reporting. A virtqueue for reporting free guest memory is present.
+
+\end{description}
+
+\drivernormative{\subsubsection}{Feature bits}{Device Types / Memory Balloon Device / Feature bits}
+The driver SHOULD accept the VIRTIO_BALLOON_F_MUST_TELL_HOST
+feature if offered by the device.
+
+The driver SHOULD clear the VIRTIO_BALLOON_F_PAGE_POISON flag if it will
+not immediately write \field{poison_val} to deflated pages (e.g., to
+initialize them, or fill them with a poison value).
+
+If the driver is expecting the pages to retain some initialized value,
+it MUST NOT accept VIRTIO_BALLOON_F_PAGE_REPORTING unless it also
+negotiates VIRTIO_BALLOON_F_PAGE_POISON.
+
+\devicenormative{\subsubsection}{Feature bits}{Device Types / Memory Balloon Device / Feature bits}
+If the device offers the VIRTIO_BALLOON_F_MUST_TELL_HOST feature
+bit, and if the driver did not accept this feature bit, the
+device MAY signal failure by failing to set FEATURES_OK
+\field{device status} bit when the driver writes it.
+\subparagraph{Legacy Interface: Feature bits}\label{sec:Device
+Types / Memory Balloon Device / Feature bits / Legacy Interface:
+Feature bits}
+As the legacy interface does not have a way to gracefully report feature
+negotiation failure, when using the legacy interface,
+transitional devices MUST support guests which do not negotiate
+VIRTIO_BALLOON_F_MUST_TELL_HOST feature, and SHOULD
+allow guest to use memory before notifying host if
+VIRTIO_BALLOON_F_MUST_TELL_HOST is not negotiated.
+
+\subsection{Device configuration layout}\label{sec:Device Types / Memory Balloon Device / Device configuration layout}
+ \field{num_pages} and \field{actual} are always available.
+
+ \field{free_page_hint_cmd_id} is available if
+ VIRTIO_BALLOON_F_FREE_PAGE_HINT has been negotiated. The field is
+ read-only by the driver.
+ \field{poison_val} is available if VIRTIO_BALLOON_F_PAGE_POISON has been
+ negotiated.
+
+\begin{lstlisting}
+struct virtio_balloon_config {
+ le32 num_pages;
+ le32 actual;
+ le32 free_page_hint_cmd_id;
+ le32 poison_val;
+};
+\end{lstlisting}
+
+\subparagraph{Legacy Interface: Device configuration layout}\label{sec:Device Types / Memory Balloon Device / Device
+configuration layout / Legacy Interface: Device configuration layout}
+When using the legacy interface, transitional devices and drivers
+MUST format the fields in struct virtio_balloon_config
+according to the little-endian format.
+\begin{note}
+This is unlike the usual convention that legacy device fields are guest endian.
+\end{note}
+
+\subsection{Device Initialization}\label{sec:Device Types / Memory Balloon Device / Device Initialization}
+
+The device initialization process is outlined below:
+
+\begin{enumerate}
+\item The inflate and deflate virtqueues are identified.
+
+\item If the VIRTIO_BALLOON_F_STATS_VQ feature bit is negotiated:
+ \begin{enumerate}
+ \item Identify the stats virtqueue.
+ \item Add one empty buffer to the stats virtqueue.
+ \end{enumerate}
+
+\item If the VIRTIO_BALLOON_F_FREE_PAGE_HINT feature bit is negotiated,
+ identify the free_page_vq.
+\item If the VIRTIO_BALLOON_F_PAGE_POISON feature bit is negotiated, update
+ the \field{poison_val} configuration field.
+\item If the VIRTIO_BALLOON_F_PAGE_REPORTING feature bit is negotiated,
+ identify the reporting_vq.
+
+\item DRIVER_OK is set: device operation begins.
+
+\item If the VIRTIO_BALLOON_F_STATS_VQ feature bit is negotiated, then
+ notify the device about the stats virtqueue buffer.
+\item If the VIRTIO_BALLOON_F_PAGE_REPORTING feature bit is negotiated, then
+ begin reporting free pages to the device.
+\end{enumerate}
+
+\subsection{Device Operation}\label{sec:Device Types / Memory Balloon Device / Device Operation}
+
+The device is driven either by the receipt of a configuration
+change notification, or by changing guest memory needs, such as
+performing memory compaction or responding to out of memory
+conditions.
+
+\begin{enumerate}
+\item \field{num_pages} configuration field is examined. If this is
+ greater than the \field{actual} number of pages, the balloon wants
+ more memory from the guest. If it is less than \field{actual},
+ the balloon doesn't need it all.
+
+\item To supply memory to the balloon (aka. inflate):
+ \begin{enumerate}
+ \item The driver constructs an array of addresses of unused memory
+ pages. These addresses are divided by 4096\footnote{This is historical, and independent of the guest page size.
+} and the descriptor
+ describing the resulting 32-bit array is added to the inflateq.
+ \end{enumerate}
+
+\item To remove memory from the balloon (aka. deflate):
+ \begin{enumerate}
+ \item The driver constructs an array of addresses of memory pages
+ it has previously given to the balloon, as described above.
+ This descriptor is added to the deflateq.
+
+ \item If the VIRTIO_BALLOON_F_MUST_TELL_HOST feature is negotiated, the
+ guest informs the device of pages before it uses them.
+
+ \item Otherwise, the guest is allowed to re-use pages previously
+ given to the balloon before the device has acknowledged their
+ withdrawal\footnote{In this case, deflation advice is merely a courtesy.
+}.
+ \end{enumerate}
+
+\item In either case, the device acknowledges inflate and deflate
+requests by using the descriptor.
+\item Once the device has acknowledged the inflation or
+ deflation, the driver updates \field{actual} to reflect the new number of pages in the balloon.
+\end{enumerate}
+
+\drivernormative{\subsubsection}{Device Operation}{Device Types / Memory Balloon Device / Device Operation}
+The driver SHOULD supply pages to the balloon when \field{num_pages} is
+greater than the actual number of pages in the balloon.
+
+The driver MAY use pages from the balloon when \field{num_pages} is
+less than the actual number of pages in the balloon.
+
+The driver MAY supply pages to the balloon when \field{num_pages} is
+greater than or equal to the actual number of pages in the balloon.
+
+If VIRTIO_BALLOON_F_DEFLATE_ON_OOM has not been negotiated, the
+driver MUST NOT use pages from the balloon when \field{num_pages}
+is less than or equal to the actual number of pages in the
+balloon.
+
+If VIRTIO_BALLOON_F_DEFLATE_ON_OOM has been negotiated, the
+driver MAY use pages from the balloon when \field{num_pages}
+is less than or equal to the actual number of pages in the
+balloon if this is required for system stability
+(e.g. if memory is required by applications running within
+ the guest).
+
+The driver MUST use the deflateq to inform the device of pages that it
+wants to use from the balloon.
+
+If the VIRTIO_BALLOON_F_MUST_TELL_HOST feature is negotiated, the
+driver MUST NOT use pages from the balloon until
+the device has acknowledged the deflate request.
+
+Otherwise, if the VIRTIO_BALLOON_F_MUST_TELL_HOST feature is not
+negotiated, the driver MAY begin to re-use pages previously
+given to the balloon before the device has acknowledged the
+deflate request.
+
+In any case, the driver MUST NOT use pages from the balloon
+after adding the pages to the balloon, but before the device has
+acknowledged the inflate request.
+
+The driver MUST NOT request deflation of pages in
+the balloon before the device has acknowledged the inflate
+request.
+
+The driver MUST update \field{actual} after changing the number
+of pages in the balloon.
+
+The driver MAY update \field{actual} once after multiple
+inflate and deflate operations.
+
+\devicenormative{\subsubsection}{Device Operation}{Device Types / Memory Balloon Device / Device Operation}
+
+The device MAY modify the contents of a page in the balloon
+after detecting its physical number in an inflate request
+and before acknowledging the inflate request by using the inflateq
+descriptor.
+
+If the VIRTIO_BALLOON_F_MUST_TELL_HOST feature is negotiated, the
+device MAY modify the contents of a page in the balloon
+after detecting its physical number in an inflate request
+and before detecting its physical number in a deflate request
+and acknowledging the deflate request.
+
+\paragraph{Legacy Interface: Device Operation}\label{sec:Device
+Types / Memory Balloon Device / Device Operation / Legacy
+Interface: Device Operation}
+When using the legacy interface, the driver SHOULD ignore the
+used length values.
+\begin{note}
+Historically, some devices put the total descriptor length there,
+even though no data was actually written.
+\end{note}
+When using the legacy interface, the driver MUST write out all
+4 bytes each time it updates the \field{actual} value in the
+configuration space, using a single atomic operation.
+
+When using the legacy interface, the device SHOULD NOT use the
+\field{actual} value written by the driver in the configuration
+space, until the last, most-significant byte of the value has been
+written.
+\begin{note}
+Historically, devices used the \field{actual} value, even though
+when using Virtio Over PCI Bus the device-specific configuration
+space was not guaranteed to be atomic. Using intermediate
+values during update by driver is best avoided, except for
+debugging.
+
+Historically, drivers using Virtio Over PCI Bus wrote the
+\field{actual} value by using multiple single-byte writes in
+order, from the least-significant to the most-significant value.
+\end{note}
+\subsubsection{Memory Statistics}\label{sec:Device Types / Memory Balloon Device / Device Operation / Memory Statistics}
+
+The stats virtqueue is atypical because communication is driven
+by the device (not the driver). The channel becomes active at
+driver initialization time when the driver adds an empty buffer
+and notifies the device. A request for memory statistics proceeds
+as follows:
+
+\begin{enumerate}
+\item The device uses the buffer and sends a used buffer notification.
+
+\item The driver pops the used buffer and discards it.
+
+\item The driver collects memory statistics and writes them into a
+ new buffer.
+
+\item The driver adds the buffer to the virtqueue and notifies the
+ device.
+
+\item The device pops the buffer (retaining it to initiate a
+ subsequent request) and consumes the statistics.
+\end{enumerate}
+
+ Within the buffer, statistics are an array of 10-byte entries.
+ Each statistic consists of a 16 bit
+ tag and a 64 bit value. All statistics are optional and the
+ driver chooses which ones to supply. To guarantee backwards
+ compatibility, devices omit unsupported statistics.
+
+\begin{lstlisting}
+struct virtio_balloon_stat {
+#define VIRTIO_BALLOON_S_SWAP_IN 0
+#define VIRTIO_BALLOON_S_SWAP_OUT 1
+#define VIRTIO_BALLOON_S_MAJFLT 2
+#define VIRTIO_BALLOON_S_MINFLT 3
+#define VIRTIO_BALLOON_S_MEMFREE 4
+#define VIRTIO_BALLOON_S_MEMTOT 5
+#define VIRTIO_BALLOON_S_AVAIL 6
+#define VIRTIO_BALLOON_S_CACHES 7
+#define VIRTIO_BALLOON_S_HTLB_PGALLOC 8
+#define VIRTIO_BALLOON_S_HTLB_PGFAIL 9
+ le16 tag;
+ le64 val;
+} __attribute__((packed));
+\end{lstlisting}
+
+\drivernormative{\paragraph}{Memory Statistics}{Device Types / Memory Balloon Device / Device Operation / Memory Statistics}
+Normative statements in this section apply if and only if the
+VIRTIO_BALLOON_F_STATS_VQ feature has been negotiated.
+
+The driver MUST make at most one buffer available to the device
+in the statsq, at all times.
+
+After initializing the device, the driver MUST make an output
+buffer available in the statsq.
+
+Upon detecting that device has used a buffer in the statsq, the
+driver MUST make an output buffer available in the statsq.
+
+Before making an output buffer available in the statsq, the
+driver MUST initialize it, including one struct
+virtio_balloon_stat entry for each statistic that it supports.
+
+Driver MUST use an output buffer size which is a multiple of 6
+bytes for all buffers submitted to the statsq.
+
+Driver MAY supply struct virtio_balloon_stat entries in the
+output buffer submitted to the statsq in any order, without
+regard to \field{tag} values.
+
+Driver MAY supply a subset of all statistics in the output buffer
+submitted to the statsq.
+
+Driver MUST supply the same subset of statistics in all buffers
+submitted to the statsq.
+
+\devicenormative{\paragraph}{Memory Statistics}{Device Types / Memory Balloon Device / Device Operation / Memory Statistics}
+Normative statements in this section apply if and only if the
+VIRTIO_BALLOON_F_STATS_VQ feature has been negotiated.
+
+Within an output buffer submitted to the statsq,
+the device MUST ignore entries with \field{tag} values that it does not recognize.
+
+Within an output buffer submitted to the statsq,
+the device MUST accept struct virtio_balloon_stat entries in any
+order without regard to \field{tag} values.
+
+\paragraph{Legacy Interface: Memory Statistics}\label{sec:Device Types / Memory Balloon Device / Device Operation / Memory Statistics / Legacy Interface: Memory Statistics}
+
+When using the legacy interface, transitional devices and drivers
+MUST format the fields in struct virtio_balloon_stat
+according to the native endian of the guest rather than
+(necessarily when not using the legacy interface) little-endian.
+
+When using the legacy interface,
+the device SHOULD ignore all values in the first buffer in the
+statsq supplied by the driver after device initialization.
+\begin{note}
+Historically, drivers supplied an uninitialized buffer in the
+first buffer.
+\end{note}
+
+\subsubsection{Memory Statistics Tags}\label{sec:Device Types / Memory Balloon Device / Device Operation / Memory Statistics Tags}
+
+\begin{description}
+\item[VIRTIO_BALLOON_S_SWAP_IN (0)] The amount of memory that has been
+ swapped in (in bytes).
+
+\item[VIRTIO_BALLOON_S_SWAP_OUT (1)] The amount of memory that has been
+ swapped out to disk (in bytes).
+
+\item[VIRTIO_BALLOON_S_MAJFLT (2)] The number of major page faults that
+ have occurred.
+
+\item[VIRTIO_BALLOON_S_MINFLT (3)] The number of minor page faults that
+ have occurred.
+
+\item[VIRTIO_BALLOON_S_MEMFREE (4)] The amount of memory not being used
+ for any purpose (in bytes).
+
+\item[VIRTIO_BALLOON_S_MEMTOT (5)] The total amount of memory available
+ (in bytes).
+
+\item[VIRTIO_BALLOON_S_AVAIL (6)] An estimate of how much memory is available
+ (in bytes) for starting new applications, without pushing the system to swap.
+
+\item[VIRTIO_BALLOON_S_CACHES (7)] The amount of memory, in bytes, that can be
+ quickly reclaimed without additional I/O. Typically these pages are used for
+ caching files from disk.
+
+\item[VIRTIO_BALLOON_S_HTLB_PGALLOC (8)] The number of successful hugetlb page
+ allocations in the guest.
+
+\item[VIRTIO_BALLOON_S_HTLB_PGFAIL (9)] The number of failed hugetlb page
+ allocations in the guest.
+\end{description}
+
+\subsubsection{Free Page Hinting}\label{sec:Device Types / Memory Balloon Device / Device Operation / Free Page Hinting}
+
+Free page hinting is designed to be used during migration to determine what
+pages within the guest are currently unused so that they can be skipped over
+while migrating the guest. The device will indicate that it is ready to start
+performing hinting by setting the \field{free_page_hint_cmd_id} to one of the
+non-reserved values that can be used as a command ID. The following values
+are reserved:
+
+\begin{description}
+\item[VIRTIO_BALLOON_CMD_ID_STOP (0)] Any command ID previously supplied by
+ the device is invalid. The driver should stop hinting free pages until a
+ new command ID is supplied, but should not release any hinted pages for
+ use by the guest.
+
+\item[VIRTIO_BALLOON_CMD_ID_DONE (1)] Any command ID previously supplied by
+ the device is invalid. The driver should stop hinting free pages, and
+ should release all hinted pages for use by the guest.
+\end{description}
+
+When a hint is provided by the driver it indicates that the data contained
+in the given page is no longer needed and can be discarded. If the driver
+writes to the page this overrides the hint and the data will be retained.
+The contents of any stale pages that have not been written to since the
+page was hinted may be lost, and if read the contents of such pages will
+be uninitialized memory.
+
+A request for free page hinting proceeds as follows:
+
+\begin{enumerate}
+
+\item The driver examines the \field{free_page_hint_cmd_id} configuration field.
+ If it contains a non-reserved value then free page hinting will begin.
+
+\item To supply free page hints:
+ \begin{enumerate}
+ \item The driver constructs an output buffer containing the new value from
+ the \field{free_page_hint_cmd_id} configuration field and adds it to the
+ free_page_vq.
+ \item The driver maps a series of pages and adds them to the
+ free_page_vq as individual scatter-gather input buffer entries.
+ \item When the driver is no longer able to fetch additional pages to add
+ to the free_page_vq, it will construct an output buffer containing the
+ command ID VIRTIO_BALLOON_CMD_ID_STOP.
+ \end{enumerate}
+
+\item A round of hinting ends either when the driver is no longer able to
+ supply more pages for hinting as described above, or when the device
+ updates \field{free_page_hint_cmd_id} configuration field to contain either
+ VIRTIO_BALLOON_CMD_ID_STOP or VIRTIO_BALLOON_CMD_ID_DONE.
+
+\item The device may follow VIRTIO_BALLOON_CMD_ID_STOP with a new
+ non-reserved value for the \field{free_page_hint_cmd_id} configuration
+ field in which case it will resume supplying free page hints.
+
+\item Otherwise, if the device provides VIRTIO_BALLOON_CMD_ID_DONE then
+ hinting is complete and the driver may release all previously hinted
+ pages for use by the guest.
+
+\end{enumerate}
+
+\drivernormative{\paragraph}{Free Page Hinting}{Device Types / Memory Balloon Device / Device Operation / Free Page Hinting}
+
+Normative statements in this section apply if the
+VIRTIO_BALLOON_F_FREE_PAGE_HINT feature has been negotiated.
+
+The driver MUST use an output buffer size of 4 bytes for all output
+buffers submitted to the free_page_vq.
+
+The driver MUST start hinting by providing an output buffer containing
+the current command ID for the given block of pages.
+
+The driver MUST NOT provide more than one output buffer containing the
+current command ID.
+
+The driver SHOULD supply pages to the free_page_vq as input buffers when
+\field{free_page_hint_cmd_id} specifies a value of 2 or greater.
+
+The driver SHOULD stop supplying pages for hinting when
+\field{free_page_hint_cmd_id} specifies a value of VIRTIO_BALLOON_CMD_ID_STOP
+or VIRTIO_BALLOON_CMD_ID_DONE.
+
+If the driver is unable to supply pages, it MUST complete hinting by adding
+an output buffer containing the command ID VIRTIO_BALLOON_CMD_ID_STOP.
+
+The driver MAY release hinted pages for use by the guest including when the
+device has not yet used the descriptor containing the hinting request.
+
+The driver MUST treat the content of all hinted pages as uninitialized
+memory.
+
+The driver MUST initialize the contents of any previously hinted page
+released before \field{free_page_hint_cmd_id} specifies a value of
+VIRTIO_BALLOON_CMD_ID_DONE.
+
+The driver SHOULD release all previously hinted pages once
+\field{free_page_hint_cmd_id} specifies a value of
+VIRTIO_BALLOON_CMD_ID_DONE.
+
+\devicenormative{\paragraph}{Free Page Hinting}{Device Types / Memory Balloon Device / Device Operation / Free Page Hinting}
+
+Normative statements in this section apply if the
+VIRTIO_BALLOON_F_FREE_PAGE_HINT feature has been negotiated.
+
+The device SHOULD set \field{free_page_hint_cmd_id} to
+VIRTIO_BALLOON_CMD_ID_STOP any time that it will not be able to make use
+of the hints provided by the driver.
+
+The device MUST NOT reuse a command ID until it has received an output
+buffer containing VIRTIO_BALLOON_CMD_ID_STOP from the driver.
+
+The device MUST ignore pages that are provided with a command ID that does
+not match the current value in \field{free_page_hint_cmd_id}.
+
+If the content of a previously hinted page has not been modified by the
+guest since the device issued the \field{free_page_hint_cmd_id} associated
+with the hint, the device MAY modify the contents of the page.
+
+The device MUST NOT modify the content of a previously hinted page after
+\field{free_page_hint_cmd_id} is set to VIRTIO_BALLOON_CMD_ID_DONE.
+
+The device MUST report a value of VIRTIO_BALLOON_CMD_ID_DONE in
+\field{free_page_hint_cmd_id} when it no longer has need for the
+previously hinted pages.
+
+\paragraph{Legacy Interface: Free Page Hinting}\label{sec:Device Types / Memory Balloon Device / Device Operation / Free Page Hinting / Legacy Interface: Free Page Hinting}
+
+When using the legacy interface, transitional devices and drivers MUST
+format the command ID field in output buffers according to the native
+endian of the guest rather than (necessarily when not using the legacy
+interface) little-endian.
+
+\subsubsection{Page Poison}\label{sec:Device Types / Memory Balloon Device / Device Operation / Page Poison}
+
+Page Poison provides a way to notify the host that the guest is initializing
+free pages with \field{poison_val}. When the feature is enabled, pages will
+be immediately written to by the driver after deflating, and pages reported
+by free page reporting will retain the value indicated by \field{poison_val}.
+
+If the guest is not initializing freed pages, the driver should reject the
+VIRTIO_BALLOON_F_PAGE_POISON feature.
+
+If VIRTIO_BALLOON_F_PAGE_POISON feature has been negotiated, the driver
+will place the initialization value into the \field{poison_val}
+configuration field data.
+
+\drivernormative{\paragraph}{Page Poison}{Device Types / Memory Balloon Device / Device Operation / Page Poison}
+
+Normative statements in this section apply if the
+VIRTIO_BALLOON_F_PAGE_POISON feature has been negotiated.
+
+The driver MUST initialize the deflated pages with \field{poison_val} when
+they are reused by the driver.
+
+The driver MUST populate the \field{poison_val} configuration data before
+setting the DRIVER_OK bit.
+
+The driver MUST NOT modify \field{poison_val} while the DRIVER_OK bit is set.
+
+\devicenormative{\paragraph}{Page Poison}{Device Types / Memory Balloon Device / Device Operation / Page Poison}
+
+Normative statements in this section apply if the
+VIRTIO_BALLOON_F_PAGE_POISON feature has been negotiated.
+
+The device MAY use the content of \field{poison_val} as a hint to guest
+behavior.
+
+\subsubsection{Free Page Reporting}\label{sec:Device Types / Memory Balloon Device / Device Operation / Free Page Reporting}
+
+Free Page Reporting provides a mechanism similar to balloon inflation,
+however it does not provide a deflation queue. Reported free pages can
+be reused by the driver after the reporting request has been acknowledged
+without notifying the device.
+
+The driver will begin reporting free pages. When exactly and which free
+pages are reported is up to the driver.
+
+\begin{enumerate}
+
+\item The driver determines it has enough pages available to begin
+ reporting free pages.
+
+\item The driver gathers free pages into a scatter-gather list and adds
+ them to the reporting_vq.
+
+\item The device acknowledges the reporting request by using the
+ reporting_vq descriptor.
+
+\item Once the device has acknowledged the report, the driver can reuse the
+ reported free pages when needed (e.g., by putting them back to free page
+ lists in the guest operating system).
+
+\item The driver can then continue to gather and report free pages until it
+ has determined it has reported a sufficient quantity of pages.
+
+\end{enumerate}
+
+\drivernormative{\paragraph}{Free Page Reporting}{Device Types / Memory Balloon Device / Device Operation / Free Page Reporting}
+
+Normative statements in this section apply if the
+VIRTIO_BALLOON_F_PAGE_REPORTING feature has been negotiated.
+
+If the VIRTIO_BALLOON_F_PAGE_POISON feature has not been negotiated, then
+the driver MUST treat all reported pages as uninitialized memory.
+
+If the VIRTIO_BALLOON_F_PAGE_POISON feature has been negotiated, the
+driver MUST initialize all free pages with \field{poison_val} before
+reporting them.
+
+The driver MUST NOT use the reported pages until the device has
+acknowledged the reporting request.
+
+The driver MAY report free pages any time after DRIVER_OK is set.
+
+The driver SHOULD attempt to report large pages rather than smaller ones.
+
+The driver SHOULD avoid reading/writing reported pages if
+not strictly necessary.
+
+\devicenormative{\paragraph}{Free Page Reporting}{Device Types / Memory Balloon Device / Device Operation / Free Page Reporting}
+
+Normative statements in this section apply if the
+VIRTIO_BALLOON_F_PAGE_REPORTING feature has been negotiated.
+
+If the VIRTIO_BALLOON_F_PAGE_POISON feature has not been negotiated, the
+device MAY modify the contents of any page supplied in a report request
+before acknowledging that request by using the reporting_vq descriptor.
+
+If the VIRTIO_BALLOON_F_PAGE_POISON feature has been negotiated, the device
+MUST NOT modify the the content of a reported page to a value other than
+\field{poison_val}.
diff --git a/device-types/virtio-mem-balloon/driver-conformance.tex b/device-types/virtio-mem-balloon/driver-conformance.tex
new file mode 100644
index 0000000..f898d74
--- /dev/null
+++ b/device-types/virtio-mem-balloon/driver-conformance.tex
@@ -0,0 +1,12 @@
+\conformance{\subsection}{Traditional Memory Balloon Driver Conformance}\label{sec:Conformance / Driver Conformance / Traditional Memory Balloon Driver Conformance}
+
+A traditional memory balloon driver MUST conform to the following normative statements:
+
+\begin{itemize}
+\item \ref{drivernormative:Device Types / Memory Balloon Device / Feature bits}
+\item \ref{drivernormative:Device Types / Memory Balloon Device / Device Operation}
+\item \ref{drivernormative:Device Types / Memory Balloon Device / Device Operation / Memory Statistics}
+\item \ref{drivernormative:Device Types / Memory Balloon Device / Device Operation / Free Page Hinting}
+\item \ref{drivernormative:Device Types / Memory Balloon Device / Device Operation / Page Poison}
+\item \ref{drivernormative:Device Types / Memory Balloon Device / Device Operation / Free Page Reporting}
+\end{itemize}
--
2.26.2
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]