[virtio-comment] [PATCH v8 0/3] virtio-spec: Add documentation for recently added balloon features

[virtio-comment] [PATCH v8 0/3] virtio-spec: Add documentation for recently added balloon features

[Alexander Duyck]

This patch set is meant to add documentation for balloon features that have
been recently added to the Linux kernel[1,2] and that were recently added
to QEMU[3].

Fixes: https://github.com/oasis-tcs/virtio-spec/issues/84

Changes since RFC:
Incorporated suggestions from Cornelia Huck
Fixed a few additional spelling errors

Changes since v1:
Incorporated additional suggestions from Cornelia Huck
Dropped documentation referring to free page reporting from page poison patch

Changes since v2:
Rewrote multiple statements based on input from David Hildenbrand
  Dropped use of balloon and deflate from page hinting description
  Dropped use of free page reporting from page poison description
  Cleaned up several spots that didn't match RFC2119 style comments
  Added conformance links.
  Various other clean-ups.
Updated balloon command IDs based on input from Cornelia Huck

Changes since v3:
Reordered patches to place free page hinting at end of patch set
  Moved contents out of patch to poison and free page reporting patches
  Updated patch description to document some known issues with feature
Further clean-ups based on input from David Hildenbrand

Changes since v4:
Further clean-ups for page hinting based on input from David Hildenbrand

Changes since v5:
Reverted patcher order changes from v3 placing hinting as first patch
Addressed comments and added Reviewed-by from Cornelia Huck
Addressed further items I found in free page hinting
  Added requirement that output buffers be 4 bytes in size
  Replaced reference to descriptor with buffer
  Replaced references to free_page_hint_vq with free_page_vq

Changes since v6:
Fixed line that was left over from a merge conflict
Added Reviewed-by from David Hildenbrand
Created issue and added "Fixes" to cover page

Changes since v7:
Removed comments from patch 1 describing issues that we fixed or addressed
Added Acked-by for patch 1 from Cornelia Huck

[1]: https://lore.kernel.org/lkml/20200211224416.29318.44077.stgit@localhost.localdomain/
[2]: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=b0c504f154718904ae49349147e3b7e6ae91ffdc
[3]: https://lists.oasis-open.org/archives/virtio-dev/202004/msg00180.html

---

Alexander Duyck (3):
      content: Document balloon feature free page hints
      content: Document balloon feature page poison
      content: Document balloon feature free page reporting


 conformance.tex |    6 +
 content.tex     |  286 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 286 insertions(+), 6 deletions(-)

--


This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.

Subscribe: virtio-comment-subscribe@lists.oasis-open.org
Unsubscribe: virtio-comment-unsubscribe@lists.oasis-open.org
List help: virtio-comment-help@lists.oasis-open.org
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/

[virtio-comment] [PATCH v8 1/3] content: Document balloon feature free page hints

[Alexander Duyck]

From: Alexander Duyck <alexander.h.duyck@linux.intel.com>

Free page hints allow the balloon driver to provide information on what
pages are not currently in use so that we can avoid the cost of copying
them in migration scenarios. Add a feature description for free page hints
describing basic functioning and requirements.

Acked-by: Cornelia Huck <cohuck@redhat.com>
Reviewed-by: David Hildenbrand <david@redhat.com>
Signed-off-by: Alexander Duyck <alexander.h.duyck@linux.intel.com>
---
 conformance.tex |    2 +
 content.tex     |  161 +++++++++++++++++++++++++++++++++++++++++++++++++++++--
 2 files changed, 157 insertions(+), 6 deletions(-)

diff --git a/conformance.tex b/conformance.tex
index b6fdec090383..a14e26edfcb2 100644
--- a/conformance.tex
+++ b/conformance.tex
@@ -149,6 +149,7 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets}
 \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}
 \end{itemize}
 
 \conformance{\subsection}{SCSI Host Driver Conformance}\label{sec:Conformance / Driver Conformance / SCSI Host Driver Conformance}
@@ -331,6 +332,7 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets}
 \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}
 \end{itemize}
 
 \conformance{\subsection}{SCSI Host Device Conformance}\label{sec:Conformance / Device Conformance / SCSI Host Device Conformance}
diff --git a/content.tex b/content.tex
index 91735e3eb018..76dfce919b97 100644
--- a/content.tex
+++ b/content.tex
@@ -5005,10 +5005,13 @@ \subsection{Virtqueues}\label{sec:Device Types / Memory Balloon Device / Virtque
 \begin{description}
 \item[0] inflateq
 \item[1] deflateq
-\item[2] statsq.
+\item[2] statsq
+\item[3] free_page_vq
 \end{description}
 
-  Virtqueue 2 only exists if VIRTIO_BALLOON_F_STATS_VQ set.
+  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.
 
 \subsection{Feature bits}\label{sec:Device Types / Memory Balloon Device / Feature bits}
 \begin{description}
@@ -5019,6 +5022,10 @@ \subsection{Feature bits}\label{sec:Device Types / Memory Balloon Device / Featu
     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.
 
 \end{description}
 
@@ -5042,13 +5049,17 @@ \subsection{Feature bits}\label{sec:Device Types / Memory Balloon Device / Featu
 VIRTIO_BALLOON_F_MUST_TELL_HOST is not negotiated.
 
 \subsection{Device configuration layout}\label{sec:Device Types / Memory Balloon Device / Device configuration layout}
-  Both fields of this configuration
-  are always available.
+  \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 and is read-only by
+    the driver.
 
 \begin{lstlisting}
 struct virtio_balloon_config {
         le32 num_pages;
         le32 actual;
+        le32 free_page_hint_cmd_id;
 };
 \end{lstlisting}
 
@@ -5072,9 +5083,15 @@ \subsection{Device Initialization}\label{sec:Device Types / Memory Balloon Devic
   \begin{enumerate}
   \item Identify the stats virtqueue.
   \item Add one empty buffer to the stats virtqueue.
-  \item DRIVER_OK is set: device operation begins.
-  \item Notify the device about the stats virtqueue buffer.
   \end{enumerate}
+
+\item If the VIRTIO_BALLOON_F_FREE_PAGE_HINT feature bit is negotiated,
+  identify the free_page_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.
 \end{enumerate}
 
 \subsection{Device Operation}\label{sec:Device Types / Memory Balloon Device / Device Operation}
@@ -5345,6 +5362,138 @@ \subsubsection{Memory Statistics Tags}\label{sec:Device Types / Memory Balloon D
   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.
+
 \section{SCSI Host Device}\label{sec:Device Types / SCSI Host Device}
 
 The virtio SCSI host device groups together one or more virtual



This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.

Subscribe: virtio-comment-subscribe@lists.oasis-open.org
Unsubscribe: virtio-comment-unsubscribe@lists.oasis-open.org
List help: virtio-comment-help@lists.oasis-open.org
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/

[virtio-comment] [PATCH v8 2/3] content: Document balloon feature page poison

[Alexander Duyck]

From: Alexander Duyck <alexander.h.duyck@linux.intel.com>

Page poison provides a way for the guest to notify the host that it is
initializing or poisoning freed pages with some specific poison value. As a
result of this we can infer a couple traits about the guest:

1. Free pages will contain a specific pattern within the guest.
2. Modifying free pages from this value may cause an error in the guest.
3. Pages will be immediately written to by the driver when deflated.

There are currently no existing features that make use of this data. In the
upcoming feature free page reporting we will need to make use of this to
identify if we can evict pages from the guest without causing data
corruption.

Add documentation for the page poison feature describing the basic
functionality and requirements.

Reviewed-by: Cornelia Huck <cohuck@redhat.com>
Reviewed-by: David Hildenbrand <david@redhat.com>
Signed-off-by: Alexander Duyck <alexander.h.duyck@linux.intel.com>
---
 conformance.tex |    2 ++
 content.tex     |   46 ++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 48 insertions(+)

diff --git a/conformance.tex b/conformance.tex
index a14e26edfcb2..5038b36324ac 100644
--- a/conformance.tex
+++ b/conformance.tex
@@ -150,6 +150,7 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets}
 \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}
 \end{itemize}
 
 \conformance{\subsection}{SCSI Host Driver Conformance}\label{sec:Conformance / Driver Conformance / SCSI Host Driver Conformance}
@@ -333,6 +334,7 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets}
 \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}
 \end{itemize}
 
 \conformance{\subsection}{SCSI Host Device Conformance}\label{sec:Conformance / Device Conformance / SCSI Host Device Conformance}
diff --git a/content.tex b/content.tex
index 76dfce919b97..0569d633e3ba 100644
--- a/content.tex
+++ b/content.tex
@@ -5026,6 +5026,9 @@ \subsection{Feature bits}\label{sec:Device Types / Memory Balloon Device / Featu
     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.
 
 \end{description}
 
@@ -5033,6 +5036,10 @@ \subsection{Feature bits}\label{sec:Device Types / Memory Balloon Device / Featu
 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).
+
 \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
@@ -5054,12 +5061,15 @@ \subsection{Device configuration layout}\label{sec:Device Types / Memory Balloon
   \field{free_page_hint_cmd_id} is available if
     VIRTIO_BALLOON_F_FREE_PAGE_HINT has been negotiated and 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}
 
@@ -5087,6 +5097,8 @@ \subsection{Device Initialization}\label{sec:Device Types / Memory Balloon Devic
 
 \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 DRIVER_OK is set: device operation begins.
 
@@ -5494,6 +5506,40 @@ \subsubsection{Free Page Hinting}\label{sec:Device Types / Memory Balloon Device
 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.
+
+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.
+
 \section{SCSI Host Device}\label{sec:Device Types / SCSI Host Device}
 
 The virtio SCSI host device groups together one or more virtual



This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.

Subscribe: virtio-comment-subscribe@lists.oasis-open.org
Unsubscribe: virtio-comment-unsubscribe@lists.oasis-open.org
List help: virtio-comment-help@lists.oasis-open.org
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/

[virtio-comment] [PATCH v8 3/3] content: Document balloon feature free page reporting

[Alexander Duyck]

From: Alexander Duyck <alexander.h.duyck@linux.intel.com>

Free page reporting is a feature that allows the guest to proactively
report unused pages to the host. By making use of this feature is is
possible to reduce the overall memory footprint of the guest in cases where
some significant portion of the memory is idle. Add documentation for the
free page reporting feature describing the functionality and requirements.

Reviewed-by: Cornelia Huck <cohuck@redhat.com>
Reviewed-by: David Hildenbrand <david@redhat.com>
Signed-off-by: Alexander Duyck <alexander.h.duyck@linux.intel.com>
---
 conformance.tex |    2 +
 content.tex     |   81 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 82 insertions(+), 1 deletion(-)

diff --git a/conformance.tex b/conformance.tex
index 5038b36324ac..5496a25e93ef 100644
--- a/conformance.tex
+++ b/conformance.tex
@@ -151,6 +151,7 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets}
 \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}
 
 \conformance{\subsection}{SCSI Host Driver Conformance}\label{sec:Conformance / Driver Conformance / SCSI Host Driver Conformance}
@@ -335,6 +336,7 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets}
 \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}
 
 \conformance{\subsection}{SCSI Host Device Conformance}\label{sec:Conformance / Device Conformance / SCSI Host Device Conformance}
diff --git a/content.tex b/content.tex
index 0569d633e3ba..2f6ddc64b9c0 100644
--- a/content.tex
+++ b/content.tex
@@ -5007,12 +5007,15 @@ \subsection{Virtqueues}\label{sec:Device Types / Memory Balloon Device / Virtque
 \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
@@ -5029,6 +5032,8 @@ \subsection{Feature bits}\label{sec:Device Types / Memory Balloon Device / Featu
 \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}
 
@@ -5040,6 +5045,10 @@ \subsection{Feature bits}\label{sec:Device Types / Memory Balloon Device / Featu
 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
@@ -5099,11 +5108,15 @@ \subsection{Device Initialization}\label{sec:Device Types / Memory Balloon Devic
   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}
@@ -5510,7 +5523,8 @@ \subsubsection{Page Poison}\label{sec:Device Types / Memory Balloon Device / Dev
 
 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.
+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.
@@ -5540,6 +5554,71 @@ \subsubsection{Page Poison}\label{sec:Device Types / Memory Balloon Device / Dev
 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}.
+
 \section{SCSI Host Device}\label{sec:Device Types / SCSI Host Device}
 
 The virtio SCSI host device groups together one or more virtual



This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.

Subscribe: virtio-comment-subscribe@lists.oasis-open.org
Unsubscribe: virtio-comment-unsubscribe@lists.oasis-open.org
List help: virtio-comment-help@lists.oasis-open.org
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/

[virtio-comment] Re: [PATCH v8 0/3] virtio-spec: Add documentation for recently added balloon features

[Cornelia Huck]

On Tue, 25 Aug 2020 07:44:55 -0700
Alexander Duyck <alexander.duyck@gmail.com> wrote:

> This patch set is meant to add documentation for balloon features that have
> been recently added to the Linux kernel[1,2] and that were recently added
> to QEMU[3].
> 
> Fixes: https://github.com/oasis-tcs/virtio-spec/issues/84
> 
> Changes since RFC:
> Incorporated suggestions from Cornelia Huck
> Fixed a few additional spelling errors
> 
> Changes since v1:
> Incorporated additional suggestions from Cornelia Huck
> Dropped documentation referring to free page reporting from page poison patch
> 
> Changes since v2:
> Rewrote multiple statements based on input from David Hildenbrand
>   Dropped use of balloon and deflate from page hinting description
>   Dropped use of free page reporting from page poison description
>   Cleaned up several spots that didn't match RFC2119 style comments
>   Added conformance links.
>   Various other clean-ups.
> Updated balloon command IDs based on input from Cornelia Huck
> 
> Changes since v3:
> Reordered patches to place free page hinting at end of patch set
>   Moved contents out of patch to poison and free page reporting patches
>   Updated patch description to document some known issues with feature
> Further clean-ups based on input from David Hildenbrand
> 
> Changes since v4:
> Further clean-ups for page hinting based on input from David Hildenbrand
> 
> Changes since v5:
> Reverted patcher order changes from v3 placing hinting as first patch
> Addressed comments and added Reviewed-by from Cornelia Huck
> Addressed further items I found in free page hinting
>   Added requirement that output buffers be 4 bytes in size
>   Replaced reference to descriptor with buffer
>   Replaced references to free_page_hint_vq with free_page_vq
> 
> Changes since v6:
> Fixed line that was left over from a merge conflict
> Added Reviewed-by from David Hildenbrand
> Created issue and added "Fixes" to cover page
> 
> Changes since v7:
> Removed comments from patch 1 describing issues that we fixed or addressed
> Added Acked-by for patch 1 from Cornelia Huck
> 
> [1]: https://lore.kernel.org/lkml/20200211224416.29318.44077.stgit@localhost.localdomain/
> [2]: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=b0c504f154718904ae49349147e3b7e6ae91ffdc
> [3]: https://lists.oasis-open.org/archives/virtio-dev/202004/msg00180.html
> 
> ---
> 
> Alexander Duyck (3):
>       content: Document balloon feature free page hints
>       content: Document balloon feature page poison
>       content: Document balloon feature free page reporting
> 
> 
>  conformance.tex |    6 +
>  content.tex     |  286 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-
>  2 files changed, 286 insertions(+), 6 deletions(-)
> 
> --
> 

I think this is good to vote on now.


This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.

Subscribe: virtio-comment-subscribe@lists.oasis-open.org
Unsubscribe: virtio-comment-unsubscribe@lists.oasis-open.org
List help: virtio-comment-help@lists.oasis-open.org
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/

[virtio-comment] Re: [PATCH v8 0/3] virtio-spec: Add documentation for recently added balloon features

[Alexander Duyck]

On Tue, Aug 25, 2020 at 8:01 AM Cornelia Huck <cohuck@redhat.com> wrote:
>
> On Tue, 25 Aug 2020 07:44:55 -0700
> Alexander Duyck <alexander.duyck@gmail.com> wrote:
>
> > This patch set is meant to add documentation for balloon features that have
> > been recently added to the Linux kernel[1,2] and that were recently added
> > to QEMU[3].
> >
> > Fixes: https://github.com/oasis-tcs/virtio-spec/issues/84
> >
> > Changes since RFC:
> > Incorporated suggestions from Cornelia Huck
> > Fixed a few additional spelling errors
> >
> > Changes since v1:
> > Incorporated additional suggestions from Cornelia Huck
> > Dropped documentation referring to free page reporting from page poison patch
> >
> > Changes since v2:
> > Rewrote multiple statements based on input from David Hildenbrand
> >   Dropped use of balloon and deflate from page hinting description
> >   Dropped use of free page reporting from page poison description
> >   Cleaned up several spots that didn't match RFC2119 style comments
> >   Added conformance links.
> >   Various other clean-ups.
> > Updated balloon command IDs based on input from Cornelia Huck
> >
> > Changes since v3:
> > Reordered patches to place free page hinting at end of patch set
> >   Moved contents out of patch to poison and free page reporting patches
> >   Updated patch description to document some known issues with feature
> > Further clean-ups based on input from David Hildenbrand
> >
> > Changes since v4:
> > Further clean-ups for page hinting based on input from David Hildenbrand
> >
> > Changes since v5:
> > Reverted patcher order changes from v3 placing hinting as first patch
> > Addressed comments and added Reviewed-by from Cornelia Huck
> > Addressed further items I found in free page hinting
> >   Added requirement that output buffers be 4 bytes in size
> >   Replaced reference to descriptor with buffer
> >   Replaced references to free_page_hint_vq with free_page_vq
> >
> > Changes since v6:
> > Fixed line that was left over from a merge conflict
> > Added Reviewed-by from David Hildenbrand
> > Created issue and added "Fixes" to cover page
> >
> > Changes since v7:
> > Removed comments from patch 1 describing issues that we fixed or addressed
> > Added Acked-by for patch 1 from Cornelia Huck
> >
> > [1]: https://lore.kernel.org/lkml/20200211224416.29318.44077.stgit@localhost.localdomain/
> > [2]: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=b0c504f154718904ae49349147e3b7e6ae91ffdc
> > [3]: https://lists.oasis-open.org/archives/virtio-dev/202004/msg00180.html
> >
> > ---
> >
> > Alexander Duyck (3):
> >       content: Document balloon feature free page hints
> >       content: Document balloon feature page poison
> >       content: Document balloon feature free page reporting
> >
> >
> >  conformance.tex |    6 +
> >  content.tex     |  286 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-
> >  2 files changed, 286 insertions(+), 6 deletions(-)
> >
> > --
> >
>
> I think this is good to vote on now.

Thanks for the review feedback. If there are no other comments then I
request a vote for inclusion.

Fixes: https://github.com/oasis-tcs/virtio-spec/issues/84

- Alex

This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.

Subscribe: virtio-comment-subscribe@lists.oasis-open.org
Unsubscribe: virtio-comment-unsubscribe@lists.oasis-open.org
List help: virtio-comment-help@lists.oasis-open.org
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/

[virtio-comment] Re: [PATCH v8 0/3] virtio-spec: Add documentation for recently added balloon features

[Michael S. Tsirkin]

On Tue, Aug 25, 2020 at 01:40:25PM -0700, Alexander Duyck wrote:
> On Tue, Aug 25, 2020 at 8:01 AM Cornelia Huck <cohuck@redhat.com> wrote:
> >
> > On Tue, 25 Aug 2020 07:44:55 -0700
> > Alexander Duyck <alexander.duyck@gmail.com> wrote:
> >
> > > This patch set is meant to add documentation for balloon features that have
> > > been recently added to the Linux kernel[1,2] and that were recently added
> > > to QEMU[3].
> > >
> > > Fixes: https://github.com/oasis-tcs/virtio-spec/issues/84
> > >
> > > Changes since RFC:
> > > Incorporated suggestions from Cornelia Huck
> > > Fixed a few additional spelling errors
> > >
> > > Changes since v1:
> > > Incorporated additional suggestions from Cornelia Huck
> > > Dropped documentation referring to free page reporting from page poison patch
> > >
> > > Changes since v2:
> > > Rewrote multiple statements based on input from David Hildenbrand
> > >   Dropped use of balloon and deflate from page hinting description
> > >   Dropped use of free page reporting from page poison description
> > >   Cleaned up several spots that didn't match RFC2119 style comments
> > >   Added conformance links.
> > >   Various other clean-ups.
> > > Updated balloon command IDs based on input from Cornelia Huck
> > >
> > > Changes since v3:
> > > Reordered patches to place free page hinting at end of patch set
> > >   Moved contents out of patch to poison and free page reporting patches
> > >   Updated patch description to document some known issues with feature
> > > Further clean-ups based on input from David Hildenbrand
> > >
> > > Changes since v4:
> > > Further clean-ups for page hinting based on input from David Hildenbrand
> > >
> > > Changes since v5:
> > > Reverted patcher order changes from v3 placing hinting as first patch
> > > Addressed comments and added Reviewed-by from Cornelia Huck
> > > Addressed further items I found in free page hinting
> > >   Added requirement that output buffers be 4 bytes in size
> > >   Replaced reference to descriptor with buffer
> > >   Replaced references to free_page_hint_vq with free_page_vq
> > >
> > > Changes since v6:
> > > Fixed line that was left over from a merge conflict
> > > Added Reviewed-by from David Hildenbrand
> > > Created issue and added "Fixes" to cover page
> > >
> > > Changes since v7:
> > > Removed comments from patch 1 describing issues that we fixed or addressed
> > > Added Acked-by for patch 1 from Cornelia Huck
> > >
> > > [1]: https://lore.kernel.org/lkml/20200211224416.29318.44077.stgit@localhost.localdomain/
> > > [2]: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=b0c504f154718904ae49349147e3b7e6ae91ffdc
> > > [3]: https://lists.oasis-open.org/archives/virtio-dev/202004/msg00180.html
> > >
> > > ---
> > >
> > > Alexander Duyck (3):
> > >       content: Document balloon feature free page hints
> > >       content: Document balloon feature page poison
> > >       content: Document balloon feature free page reporting
> > >
> > >
> > >  conformance.tex |    6 +
> > >  content.tex     |  286 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-
> > >  2 files changed, 286 insertions(+), 6 deletions(-)
> > >
> > > --
> > >
> >
> > I think this is good to vote on now.
> 
> Thanks for the review feedback. If there are no other comments then I
> request a vote for inclusion.
> 
> Fixes: https://github.com/oasis-tcs/virtio-spec/issues/84
> 
> - Alex

Ballot created at https://www.oasis-open.org/committees/ballot.php?id=3521
Once it concludes, would appreciate a reminder to merge the patch.
Thanks!

-- 
MST


This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.

Subscribe: virtio-comment-subscribe@lists.oasis-open.org
Unsubscribe: virtio-comment-unsubscribe@lists.oasis-open.org
List help: virtio-comment-help@lists.oasis-open.org
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/

[virtio-comment] Re: [virtio-dev] [PATCH v8 1/3] content: Document balloon feature free page hints

[Jan Kiszka]

On 25.08.20 16:45, Alexander Duyck wrote:
> From: Alexander Duyck <alexander.h.duyck@linux.intel.com>
> 
> Free page hints allow the balloon driver to provide information on what
> pages are not currently in use so that we can avoid the cost of copying
> them in migration scenarios. Add a feature description for free page hints
> describing basic functioning and requirements.
> 
> Acked-by: Cornelia Huck <cohuck@redhat.com>
> Reviewed-by: David Hildenbrand <david@redhat.com>
> Signed-off-by: Alexander Duyck <alexander.h.duyck@linux.intel.com>
> ---
>  conformance.tex |    2 +
>  content.tex     |  161 +++++++++++++++++++++++++++++++++++++++++++++++++++++--
>  2 files changed, 157 insertions(+), 6 deletions(-)
> 
> diff --git a/conformance.tex b/conformance.tex
> index b6fdec090383..a14e26edfcb2 100644
> --- a/conformance.tex
> +++ b/conformance.tex
> @@ -149,6 +149,7 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets}
>  \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}
>  \end{itemize}
>  
>  \conformance{\subsection}{SCSI Host Driver Conformance}\label{sec:Conformance / Driver Conformance / SCSI Host Driver Conformance}
> @@ -331,6 +332,7 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets}
>  \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}
>  \end{itemize}
>  
>  \conformance{\subsection}{SCSI Host Device Conformance}\label{sec:Conformance / Device Conformance / SCSI Host Device Conformance}
> diff --git a/content.tex b/content.tex
> index 91735e3eb018..76dfce919b97 100644
> --- a/content.tex
> +++ b/content.tex
> @@ -5005,10 +5005,13 @@ \subsection{Virtqueues}\label{sec:Device Types / Memory Balloon Device / Virtque
>  \begin{description}
>  \item[0] inflateq
>  \item[1] deflateq
> -\item[2] statsq.
> +\item[2] statsq
> +\item[3] free_page_vq
>  \end{description}
>  
> -  Virtqueue 2 only exists if VIRTIO_BALLOON_F_STATS_VQ set.
> +  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.
>  
>  \subsection{Feature bits}\label{sec:Device Types / Memory Balloon Device / Feature bits}
>  \begin{description}
> @@ -5019,6 +5022,10 @@ \subsection{Feature bits}\label{sec:Device Types / Memory Balloon Device / Featu
>      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.
>  
>  \end{description}
>  
> @@ -5042,13 +5049,17 @@ \subsection{Feature bits}\label{sec:Device Types / Memory Balloon Device / Featu
>  VIRTIO_BALLOON_F_MUST_TELL_HOST is not negotiated.
>  
>  \subsection{Device configuration layout}\label{sec:Device Types / Memory Balloon Device / Device configuration layout}
> -  Both fields of this configuration
> -  are always available.
> +  \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 and is read-only by
> +    the driver.

This reads at least to me like "...if VIRTIO_BALLOON_F_FREE_PAGE_HINT
... is read-only by the driver". I suspect you rather meant
"free_page_hint_cmd_id is read-only...". Maybe split up into two sentences?

Jan

-- 
Siemens AG, Corporate Technology, CT RDA IOT SES-DE
Corporate Competence Center Embedded Linux

This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.

Subscribe: virtio-comment-subscribe@lists.oasis-open.org
Unsubscribe: virtio-comment-unsubscribe@lists.oasis-open.org
List help: virtio-comment-help@lists.oasis-open.org
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/

[virtio-comment] Re: [virtio-dev] [PATCH v8 1/3] content: Document balloon feature free page hints

[Alexander Duyck]

On Fri, Sep 4, 2020 at 8:20 AM Jan Kiszka <jan.kiszka@siemens.com> wrote:
>
> On 25.08.20 16:45, Alexander Duyck wrote:
> > From: Alexander Duyck <alexander.h.duyck@linux.intel.com>
> >
> > Free page hints allow the balloon driver to provide information on what
> > pages are not currently in use so that we can avoid the cost of copying
> > them in migration scenarios. Add a feature description for free page hints
> > describing basic functioning and requirements.
> >
> > Acked-by: Cornelia Huck <cohuck@redhat.com>
> > Reviewed-by: David Hildenbrand <david@redhat.com>
> > Signed-off-by: Alexander Duyck <alexander.h.duyck@linux.intel.com>
> > ---
> >  conformance.tex |    2 +
> >  content.tex     |  161 +++++++++++++++++++++++++++++++++++++++++++++++++++++--
> >  2 files changed, 157 insertions(+), 6 deletions(-)
> >
> > diff --git a/conformance.tex b/conformance.tex
> > index b6fdec090383..a14e26edfcb2 100644
> > --- a/conformance.tex
> > +++ b/conformance.tex
> > @@ -149,6 +149,7 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets}
> >  \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}
> >  \end{itemize}
> >
> >  \conformance{\subsection}{SCSI Host Driver Conformance}\label{sec:Conformance / Driver Conformance / SCSI Host Driver Conformance}
> > @@ -331,6 +332,7 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets}
> >  \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}
> >  \end{itemize}
> >
> >  \conformance{\subsection}{SCSI Host Device Conformance}\label{sec:Conformance / Device Conformance / SCSI Host Device Conformance}
> > diff --git a/content.tex b/content.tex
> > index 91735e3eb018..76dfce919b97 100644
> > --- a/content.tex
> > +++ b/content.tex
> > @@ -5005,10 +5005,13 @@ \subsection{Virtqueues}\label{sec:Device Types / Memory Balloon Device / Virtque
> >  \begin{description}
> >  \item[0] inflateq
> >  \item[1] deflateq
> > -\item[2] statsq.
> > +\item[2] statsq
> > +\item[3] free_page_vq
> >  \end{description}
> >
> > -  Virtqueue 2 only exists if VIRTIO_BALLOON_F_STATS_VQ set.
> > +  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.
> >
> >  \subsection{Feature bits}\label{sec:Device Types / Memory Balloon Device / Feature bits}
> >  \begin{description}
> > @@ -5019,6 +5022,10 @@ \subsection{Feature bits}\label{sec:Device Types / Memory Balloon Device / Featu
> >      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.
> >
> >  \end{description}
> >
> > @@ -5042,13 +5049,17 @@ \subsection{Feature bits}\label{sec:Device Types / Memory Balloon Device / Featu
> >  VIRTIO_BALLOON_F_MUST_TELL_HOST is not negotiated.
> >
> >  \subsection{Device configuration layout}\label{sec:Device Types / Memory Balloon Device / Device configuration layout}
> > -  Both fields of this configuration
> > -  are always available.
> > +  \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 and is read-only by
> > +    the driver.
>
> This reads at least to me like "...if VIRTIO_BALLOON_F_FREE_PAGE_HINT
> ... is read-only by the driver". I suspect you rather meant
> "free_page_hint_cmd_id is read-only...". Maybe split up into two sentences?

Yes, the intention is:
1. free_page_hint_cmd_id is only available if
VIRTIO_BALLOON_F_FREE_PAGE_HINT has been negotiated
2. free_page_hint_cmd_id is read only by the driver

If needed I suppose we could break it up by splitting it into two
sentences, or adding "the field" after the "and".

Thanks.

- Alex

This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.

Subscribe: virtio-comment-subscribe@lists.oasis-open.org
Unsubscribe: virtio-comment-unsubscribe@lists.oasis-open.org
List help: virtio-comment-help@lists.oasis-open.org
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/

[virtio-comment] Re: [PATCH v8 0/3] virtio-spec: Add documentation for recently added balloon features

[Alexander Duyck]

On Tue, Sep 1, 2020 at 7:34 AM Michael S. Tsirkin <mst@redhat.com> wrote:
>
> On Tue, Aug 25, 2020 at 01:40:25PM -0700, Alexander Duyck wrote:
> > On Tue, Aug 25, 2020 at 8:01 AM Cornelia Huck <cohuck@redhat.com> wrote:
> > >
> > > On Tue, 25 Aug 2020 07:44:55 -0700
> > > Alexander Duyck <alexander.duyck@gmail.com> wrote:
> > >
> > > > This patch set is meant to add documentation for balloon features that have
> > > > been recently added to the Linux kernel[1,2] and that were recently added
> > > > to QEMU[3].
> > > >
> > > > Fixes: https://github.com/oasis-tcs/virtio-spec/issues/84
> > > >
> > > > Changes since RFC:
> > > > Incorporated suggestions from Cornelia Huck
> > > > Fixed a few additional spelling errors
> > > >
> > > > Changes since v1:
> > > > Incorporated additional suggestions from Cornelia Huck
> > > > Dropped documentation referring to free page reporting from page poison patch
> > > >
> > > > Changes since v2:
> > > > Rewrote multiple statements based on input from David Hildenbrand
> > > >   Dropped use of balloon and deflate from page hinting description
> > > >   Dropped use of free page reporting from page poison description
> > > >   Cleaned up several spots that didn't match RFC2119 style comments
> > > >   Added conformance links.
> > > >   Various other clean-ups.
> > > > Updated balloon command IDs based on input from Cornelia Huck
> > > >
> > > > Changes since v3:
> > > > Reordered patches to place free page hinting at end of patch set
> > > >   Moved contents out of patch to poison and free page reporting patches
> > > >   Updated patch description to document some known issues with feature
> > > > Further clean-ups based on input from David Hildenbrand
> > > >
> > > > Changes since v4:
> > > > Further clean-ups for page hinting based on input from David Hildenbrand
> > > >
> > > > Changes since v5:
> > > > Reverted patcher order changes from v3 placing hinting as first patch
> > > > Addressed comments and added Reviewed-by from Cornelia Huck
> > > > Addressed further items I found in free page hinting
> > > >   Added requirement that output buffers be 4 bytes in size
> > > >   Replaced reference to descriptor with buffer
> > > >   Replaced references to free_page_hint_vq with free_page_vq
> > > >
> > > > Changes since v6:
> > > > Fixed line that was left over from a merge conflict
> > > > Added Reviewed-by from David Hildenbrand
> > > > Created issue and added "Fixes" to cover page
> > > >
> > > > Changes since v7:
> > > > Removed comments from patch 1 describing issues that we fixed or addressed
> > > > Added Acked-by for patch 1 from Cornelia Huck
> > > >
> > > > [1]: https://lore.kernel.org/lkml/20200211224416.29318.44077.stgit@localhost.localdomain/
> > > > [2]: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=b0c504f154718904ae49349147e3b7e6ae91ffdc
> > > > [3]: https://lists.oasis-open.org/archives/virtio-dev/202004/msg00180.html
> > > >
> > > > ---
> > > >
> > > > Alexander Duyck (3):
> > > >       content: Document balloon feature free page hints
> > > >       content: Document balloon feature page poison
> > > >       content: Document balloon feature free page reporting
> > > >
> > > >
> > > >  conformance.tex |    6 +
> > > >  content.tex     |  286 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-
> > > >  2 files changed, 286 insertions(+), 6 deletions(-)
> > > >
> > > > --
> > > >
> > >
> > > I think this is good to vote on now.
> >
> > Thanks for the review feedback. If there are no other comments then I
> > request a vote for inclusion.
> >
> > Fixes: https://github.com/oasis-tcs/virtio-spec/issues/84
> >
> > - Alex
>
> Ballot created at https://www.oasis-open.org/committees/ballot.php?id=3521
> Once it concludes, would appreciate a reminder to merge the patch.
> Thanks!

So it looks like it was voted down due to a bad link in the ballot.
The correct link that references the patch set is in the bugzilla. Do
I need to resubmit the patch set or can a new ballot be created?

Thanks.

- Alex

This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.

Subscribe: virtio-comment-subscribe@lists.oasis-open.org
Unsubscribe: virtio-comment-unsubscribe@lists.oasis-open.org
List help: virtio-comment-help@lists.oasis-open.org
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/

[virtio-comment] Re: [PATCH v8 0/3] virtio-spec: Add documentation for recently added balloon features

[Cornelia Huck]

On Thu, 10 Sep 2020 07:50:29 -0700
Alexander Duyck <alexander.duyck@gmail.com> wrote:

> On Tue, Sep 1, 2020 at 7:34 AM Michael S. Tsirkin <mst@redhat.com> wrote:
> >
> > On Tue, Aug 25, 2020 at 01:40:25PM -0700, Alexander Duyck wrote:  
> > > On Tue, Aug 25, 2020 at 8:01 AM Cornelia Huck <cohuck@redhat.com> wrote:  
> > > >
> > > > On Tue, 25 Aug 2020 07:44:55 -0700
> > > > Alexander Duyck <alexander.duyck@gmail.com> wrote:
> > > >  
> > > > > This patch set is meant to add documentation for balloon features that have
> > > > > been recently added to the Linux kernel[1,2] and that were recently added
> > > > > to QEMU[3].
> > > > >
> > > > > Fixes: https://github.com/oasis-tcs/virtio-spec/issues/84
> > > > >
> > > > > Changes since RFC:
> > > > > Incorporated suggestions from Cornelia Huck
> > > > > Fixed a few additional spelling errors
> > > > >
> > > > > Changes since v1:
> > > > > Incorporated additional suggestions from Cornelia Huck
> > > > > Dropped documentation referring to free page reporting from page poison patch
> > > > >
> > > > > Changes since v2:
> > > > > Rewrote multiple statements based on input from David Hildenbrand
> > > > >   Dropped use of balloon and deflate from page hinting description
> > > > >   Dropped use of free page reporting from page poison description
> > > > >   Cleaned up several spots that didn't match RFC2119 style comments
> > > > >   Added conformance links.
> > > > >   Various other clean-ups.
> > > > > Updated balloon command IDs based on input from Cornelia Huck
> > > > >
> > > > > Changes since v3:
> > > > > Reordered patches to place free page hinting at end of patch set
> > > > >   Moved contents out of patch to poison and free page reporting patches
> > > > >   Updated patch description to document some known issues with feature
> > > > > Further clean-ups based on input from David Hildenbrand
> > > > >
> > > > > Changes since v4:
> > > > > Further clean-ups for page hinting based on input from David Hildenbrand
> > > > >
> > > > > Changes since v5:
> > > > > Reverted patcher order changes from v3 placing hinting as first patch
> > > > > Addressed comments and added Reviewed-by from Cornelia Huck
> > > > > Addressed further items I found in free page hinting
> > > > >   Added requirement that output buffers be 4 bytes in size
> > > > >   Replaced reference to descriptor with buffer
> > > > >   Replaced references to free_page_hint_vq with free_page_vq
> > > > >
> > > > > Changes since v6:
> > > > > Fixed line that was left over from a merge conflict
> > > > > Added Reviewed-by from David Hildenbrand
> > > > > Created issue and added "Fixes" to cover page
> > > > >
> > > > > Changes since v7:
> > > > > Removed comments from patch 1 describing issues that we fixed or addressed
> > > > > Added Acked-by for patch 1 from Cornelia Huck
> > > > >
> > > > > [1]: https://lore.kernel.org/lkml/20200211224416.29318.44077.stgit@localhost.localdomain/
> > > > > [2]: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=b0c504f154718904ae49349147e3b7e6ae91ffdc
> > > > > [3]: https://lists.oasis-open.org/archives/virtio-dev/202004/msg00180.html
> > > > >
> > > > > ---
> > > > >
> > > > > Alexander Duyck (3):
> > > > >       content: Document balloon feature free page hints
> > > > >       content: Document balloon feature page poison
> > > > >       content: Document balloon feature free page reporting
> > > > >
> > > > >
> > > > >  conformance.tex |    6 +
> > > > >  content.tex     |  286 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-
> > > > >  2 files changed, 286 insertions(+), 6 deletions(-)
> > > > >
> > > > > --
> > > > >  
> > > >
> > > > I think this is good to vote on now.  
> > >
> > > Thanks for the review feedback. If there are no other comments then I
> > > request a vote for inclusion.
> > >
> > > Fixes: https://github.com/oasis-tcs/virtio-spec/issues/84
> > >
> > > - Alex  
> >
> > Ballot created at https://www.oasis-open.org/committees/ballot.php?id=3521
> > Once it concludes, would appreciate a reminder to merge the patch.
> > Thanks!  
> 
> So it looks like it was voted down due to a bad link in the ballot.

Yeah, that wrong link was really unfortunate.

> The correct link that references the patch set is in the bugzilla. Do
> I need to resubmit the patch set or can a new ballot be created?

I think we just need a new vote -- Michael?

> 
> Thanks.
> 
> - Alex
> 


This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.

Subscribe: virtio-comment-subscribe@lists.oasis-open.org
Unsubscribe: virtio-comment-unsubscribe@lists.oasis-open.org
List help: virtio-comment-help@lists.oasis-open.org
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/

Re: [virtio-comment] Re: [virtio-dev] [PATCH v8 1/3] content: Document balloon feature free page hints

[Jan Kiszka]

On 04.09.20 18:56, Alexander Duyck wrote:
> On Fri, Sep 4, 2020 at 8:20 AM Jan Kiszka <jan.kiszka@siemens.com> wrote:
>>
>> On 25.08.20 16:45, Alexander Duyck wrote:
>>> From: Alexander Duyck <alexander.h.duyck@linux.intel.com>
>>>
>>> Free page hints allow the balloon driver to provide information on what
>>> pages are not currently in use so that we can avoid the cost of copying
>>> them in migration scenarios. Add a feature description for free page hints
>>> describing basic functioning and requirements.
>>>
>>> Acked-by: Cornelia Huck <cohuck@redhat.com>
>>> Reviewed-by: David Hildenbrand <david@redhat.com>
>>> Signed-off-by: Alexander Duyck <alexander.h.duyck@linux.intel.com>
>>> ---
>>>  conformance.tex |    2 +
>>>  content.tex     |  161 +++++++++++++++++++++++++++++++++++++++++++++++++++++--
>>>  2 files changed, 157 insertions(+), 6 deletions(-)
>>>
>>> diff --git a/conformance.tex b/conformance.tex
>>> index b6fdec090383..a14e26edfcb2 100644
>>> --- a/conformance.tex
>>> +++ b/conformance.tex
>>> @@ -149,6 +149,7 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets}
>>>  \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}
>>>  \end{itemize}
>>>
>>>  \conformance{\subsection}{SCSI Host Driver Conformance}\label{sec:Conformance / Driver Conformance / SCSI Host Driver Conformance}
>>> @@ -331,6 +332,7 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets}
>>>  \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}
>>>  \end{itemize}
>>>
>>>  \conformance{\subsection}{SCSI Host Device Conformance}\label{sec:Conformance / Device Conformance / SCSI Host Device Conformance}
>>> diff --git a/content.tex b/content.tex
>>> index 91735e3eb018..76dfce919b97 100644
>>> --- a/content.tex
>>> +++ b/content.tex
>>> @@ -5005,10 +5005,13 @@ \subsection{Virtqueues}\label{sec:Device Types / Memory Balloon Device / Virtque
>>>  \begin{description}
>>>  \item[0] inflateq
>>>  \item[1] deflateq
>>> -\item[2] statsq.
>>> +\item[2] statsq
>>> +\item[3] free_page_vq
>>>  \end{description}
>>>
>>> -  Virtqueue 2 only exists if VIRTIO_BALLOON_F_STATS_VQ set.
>>> +  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.
>>>
>>>  \subsection{Feature bits}\label{sec:Device Types / Memory Balloon Device / Feature bits}
>>>  \begin{description}
>>> @@ -5019,6 +5022,10 @@ \subsection{Feature bits}\label{sec:Device Types / Memory Balloon Device / Featu
>>>      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.
>>>
>>>  \end{description}
>>>
>>> @@ -5042,13 +5049,17 @@ \subsection{Feature bits}\label{sec:Device Types / Memory Balloon Device / Featu
>>>  VIRTIO_BALLOON_F_MUST_TELL_HOST is not negotiated.
>>>
>>>  \subsection{Device configuration layout}\label{sec:Device Types / Memory Balloon Device / Device configuration layout}
>>> -  Both fields of this configuration
>>> -  are always available.
>>> +  \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 and is read-only by
>>> +    the driver.
>>
>> This reads at least to me like "...if VIRTIO_BALLOON_F_FREE_PAGE_HINT
>> ... is read-only by the driver". I suspect you rather meant
>> "free_page_hint_cmd_id is read-only...". Maybe split up into two sentences?
> 
> Yes, the intention is:
> 1. free_page_hint_cmd_id is only available if
> VIRTIO_BALLOON_F_FREE_PAGE_HINT has been negotiated
> 2. free_page_hint_cmd_id is read only by the driver
> 
> If needed I suppose we could break it up by splitting it into two
> sentences, or adding "the field" after the "and".
> 

I'm fine with both options but please adjust this - on top (Michael just
opened the voting for this version again due to the formal typo in round 1).

Jan

-- 
Siemens AG, Corporate Technology, CT RDA IOT SES-DE
Corporate Competence Center Embedded Linux

This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.

Subscribe: virtio-comment-subscribe@lists.oasis-open.org
Unsubscribe: virtio-comment-unsubscribe@lists.oasis-open.org
List help: virtio-comment-help@lists.oasis-open.org
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/

Re: [virtio-comment] Re: [virtio-dev] [PATCH v8 1/3] content: Document balloon feature free page hints

[Alexander Duyck]

On Thu, Sep 10, 2020 at 10:28 PM Jan Kiszka <jan.kiszka@siemens.com> wrote:
>
> On 04.09.20 18:56, Alexander Duyck wrote:
> > On Fri, Sep 4, 2020 at 8:20 AM Jan Kiszka <jan.kiszka@siemens.com> wrote:
> >>
> >> On 25.08.20 16:45, Alexander Duyck wrote:
> >>> From: Alexander Duyck <alexander.h.duyck@linux.intel.com>
> >>>
> >>> Free page hints allow the balloon driver to provide information on what
> >>> pages are not currently in use so that we can avoid the cost of copying
> >>> them in migration scenarios. Add a feature description for free page hints
> >>> describing basic functioning and requirements.
> >>>
> >>> Acked-by: Cornelia Huck <cohuck@redhat.com>
> >>> Reviewed-by: David Hildenbrand <david@redhat.com>
> >>> Signed-off-by: Alexander Duyck <alexander.h.duyck@linux.intel.com>
> >>> ---
> >>>  conformance.tex |    2 +
> >>>  content.tex     |  161 +++++++++++++++++++++++++++++++++++++++++++++++++++++--
> >>>  2 files changed, 157 insertions(+), 6 deletions(-)
> >>>
> >>> diff --git a/conformance.tex b/conformance.tex
> >>> index b6fdec090383..a14e26edfcb2 100644
> >>> --- a/conformance.tex
> >>> +++ b/conformance.tex
> >>> @@ -149,6 +149,7 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets}
> >>>  \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}
> >>>  \end{itemize}
> >>>
> >>>  \conformance{\subsection}{SCSI Host Driver Conformance}\label{sec:Conformance / Driver Conformance / SCSI Host Driver Conformance}
> >>> @@ -331,6 +332,7 @@ \section{Conformance Targets}\label{sec:Conformance / Conformance Targets}
> >>>  \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}
> >>>  \end{itemize}
> >>>
> >>>  \conformance{\subsection}{SCSI Host Device Conformance}\label{sec:Conformance / Device Conformance / SCSI Host Device Conformance}
> >>> diff --git a/content.tex b/content.tex
> >>> index 91735e3eb018..76dfce919b97 100644
> >>> --- a/content.tex
> >>> +++ b/content.tex
> >>> @@ -5005,10 +5005,13 @@ \subsection{Virtqueues}\label{sec:Device Types / Memory Balloon Device / Virtque
> >>>  \begin{description}
> >>>  \item[0] inflateq
> >>>  \item[1] deflateq
> >>> -\item[2] statsq.
> >>> +\item[2] statsq
> >>> +\item[3] free_page_vq
> >>>  \end{description}
> >>>
> >>> -  Virtqueue 2 only exists if VIRTIO_BALLOON_F_STATS_VQ set.
> >>> +  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.
> >>>
> >>>  \subsection{Feature bits}\label{sec:Device Types / Memory Balloon Device / Feature bits}
> >>>  \begin{description}
> >>> @@ -5019,6 +5022,10 @@ \subsection{Feature bits}\label{sec:Device Types / Memory Balloon Device / Featu
> >>>      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.
> >>>
> >>>  \end{description}
> >>>
> >>> @@ -5042,13 +5049,17 @@ \subsection{Feature bits}\label{sec:Device Types / Memory Balloon Device / Featu
> >>>  VIRTIO_BALLOON_F_MUST_TELL_HOST is not negotiated.
> >>>
> >>>  \subsection{Device configuration layout}\label{sec:Device Types / Memory Balloon Device / Device configuration layout}
> >>> -  Both fields of this configuration
> >>> -  are always available.
> >>> +  \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 and is read-only by
> >>> +    the driver.
> >>
> >> This reads at least to me like "...if VIRTIO_BALLOON_F_FREE_PAGE_HINT
> >> ... is read-only by the driver". I suspect you rather meant
> >> "free_page_hint_cmd_id is read-only...". Maybe split up into two sentences?
> >
> > Yes, the intention is:
> > 1. free_page_hint_cmd_id is only available if
> > VIRTIO_BALLOON_F_FREE_PAGE_HINT has been negotiated
> > 2. free_page_hint_cmd_id is read only by the driver
> >
> > If needed I suppose we could break it up by splitting it into two
> > sentences, or adding "the field" after the "and".
> >
>
> I'm fine with both options but please adjust this - on top (Michael just
> opened the voting for this version again due to the formal typo in round 1).
>
> Jan

Since the patch set is being voted on is there a preferred method for
making this sort of update? I'm just wondering if I should do an
additional incremental patch, just submit a replacement for this
patch, or make the change and resubmit the entire patch set?

Thanks.

- Alex

This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.

Subscribe: virtio-comment-subscribe@lists.oasis-open.org
Unsubscribe: virtio-comment-unsubscribe@lists.oasis-open.org
List help: virtio-comment-help@lists.oasis-open.org
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/

Re: [virtio-comment] Re: [virtio-dev] [PATCH v8 1/3] content: Document balloon feature free page hints

[Cornelia Huck]

On Fri, 11 Sep 2020 08:11:15 -0700
Alexander Duyck <alexander.duyck@gmail.com> wrote:

> On Thu, Sep 10, 2020 at 10:28 PM Jan Kiszka <jan.kiszka@siemens.com> wrote:
> >
> > On 04.09.20 18:56, Alexander Duyck wrote:  
> > > On Fri, Sep 4, 2020 at 8:20 AM Jan Kiszka <jan.kiszka@siemens.com> wrote:  
> > >>
> > >> On 25.08.20 16:45, Alexander Duyck wrote:  

> > >>> @@ -5042,13 +5049,17 @@ \subsection{Feature bits}\label{sec:Device Types / Memory Balloon Device / Featu
> > >>>  VIRTIO_BALLOON_F_MUST_TELL_HOST is not negotiated.
> > >>>
> > >>>  \subsection{Device configuration layout}\label{sec:Device Types / Memory Balloon Device / Device configuration layout}
> > >>> -  Both fields of this configuration
> > >>> -  are always available.
> > >>> +  \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 and is read-only by
> > >>> +    the driver.  
> > >>
> > >> This reads at least to me like "...if VIRTIO_BALLOON_F_FREE_PAGE_HINT
> > >> ... is read-only by the driver". I suspect you rather meant
> > >> "free_page_hint_cmd_id is read-only...". Maybe split up into two sentences?  
> > >
> > > Yes, the intention is:
> > > 1. free_page_hint_cmd_id is only available if
> > > VIRTIO_BALLOON_F_FREE_PAGE_HINT has been negotiated
> > > 2. free_page_hint_cmd_id is read only by the driver
> > >
> > > If needed I suppose we could break it up by splitting it into two
> > > sentences, or adding "the field" after the "and".
> > >  
> >
> > I'm fine with both options but please adjust this - on top (Michael just
> > opened the voting for this version again due to the formal typo in round 1).
> >
> > Jan  
> 
> Since the patch set is being voted on is there a preferred method for
> making this sort of update? I'm just wondering if I should do an
> additional incremental patch, just submit a replacement for this
> patch, or make the change and resubmit the entire patch set?

I think doing an additional patch on top and then doing another vote on
that is the best way to handle this. (Or maybe it is minor enough to
simply merge the incremental patch?)


This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.

Subscribe: virtio-comment-subscribe@lists.oasis-open.org
Unsubscribe: virtio-comment-unsubscribe@lists.oasis-open.org
List help: virtio-comment-help@lists.oasis-open.org
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/

[virtio-comment] [PATCH v8 4/3] content: Minor change to clarify free_page_hint_cmd_id

[Alexander Duyck]

From: Alexander Duyck <alexander.h.duyck@linux.intel.com>

The original wording was a bit unclear and could have been misinterpreted
as indicating that VIRTIO_BALLOON_FREE_PAGE_HINT was read-only instead of
the field free_page_hint_cmd_id. To clarify that break it up into two
sentences making it clear that the field is only available if the feature
is negotiated, and that the field is read-only.

Signed-off-by: Alexander Duyck <alexander.h.duyck@linux.intel.com>
---

So this patch addresses a minor nit that was pointed out after the ballot
had already been created. If need be I can either open a new bugzilla and
request a ballot to have it added.

 content.tex |    4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/content.tex b/content.tex
index 76dfce919b97..f74090491534 100644
--- a/content.tex
+++ b/content.tex
@@ -5052,8 +5052,8 @@ \subsection{Device configuration layout}\label{sec:Device Types / Memory Balloon
   \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 and is read-only by
-    the driver.
+    VIRTIO_BALLOON_F_FREE_PAGE_HINT has been negotiated. The field is
+    read-only by the driver.
 
 \begin{lstlisting}
 struct virtio_balloon_config {



This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.

Subscribe: virtio-comment-subscribe@lists.oasis-open.org
Unsubscribe: virtio-comment-unsubscribe@lists.oasis-open.org
List help: virtio-comment-help@lists.oasis-open.org
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/

[virtio-comment] Re: [PATCH v8 4/3] content: Minor change to clarify free_page_hint_cmd_id

[Cornelia Huck]

On Mon, 14 Sep 2020 12:44:09 -0700
Alexander Duyck <alexander.duyck@gmail.com> wrote:

> From: Alexander Duyck <alexander.h.duyck@linux.intel.com>
> 
> The original wording was a bit unclear and could have been misinterpreted
> as indicating that VIRTIO_BALLOON_FREE_PAGE_HINT was read-only instead of
> the field free_page_hint_cmd_id. To clarify that break it up into two
> sentences making it clear that the field is only available if the feature
> is negotiated, and that the field is read-only.
> 
> Signed-off-by: Alexander Duyck <alexander.h.duyck@linux.intel.com>
> ---
> 
> So this patch addresses a minor nit that was pointed out after the ballot
> had already been created. If need be I can either open a new bugzilla and
> request a ballot to have it added.
> 
>  content.tex |    4 ++--
>  1 file changed, 2 insertions(+), 2 deletions(-)
> 
> diff --git a/content.tex b/content.tex
> index 76dfce919b97..f74090491534 100644
> --- a/content.tex
> +++ b/content.tex
> @@ -5052,8 +5052,8 @@ \subsection{Device configuration layout}\label{sec:Device Types / Memory Balloon
>    \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 and is read-only by
> -    the driver.
> +    VIRTIO_BALLOON_F_FREE_PAGE_HINT has been negotiated. The field is
> +    read-only by the driver.
>  
>  \begin{lstlisting}
>  struct virtio_balloon_config {
> 
> 

Reviewed-by: Cornelia Huck <cohuck@redhat.com>


This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.

Subscribe: virtio-comment-subscribe@lists.oasis-open.org
Unsubscribe: virtio-comment-unsubscribe@lists.oasis-open.org
List help: virtio-comment-help@lists.oasis-open.org
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/

Re: [virtio-comment] Re: [virtio-dev] [PATCH v8 1/3] content: Document balloon feature free page hints

[Michael S. Tsirkin]

On Mon, Sep 14, 2020 at 08:13:55AM +0200, Cornelia Huck wrote:
> On Fri, 11 Sep 2020 08:11:15 -0700
> Alexander Duyck <alexander.duyck@gmail.com> wrote:
> 
> > On Thu, Sep 10, 2020 at 10:28 PM Jan Kiszka <jan.kiszka@siemens.com> wrote:
> > >
> > > On 04.09.20 18:56, Alexander Duyck wrote:  
> > > > On Fri, Sep 4, 2020 at 8:20 AM Jan Kiszka <jan.kiszka@siemens.com> wrote:  
> > > >>
> > > >> On 25.08.20 16:45, Alexander Duyck wrote:  
> 
> > > >>> @@ -5042,13 +5049,17 @@ \subsection{Feature bits}\label{sec:Device Types / Memory Balloon Device / Featu
> > > >>>  VIRTIO_BALLOON_F_MUST_TELL_HOST is not negotiated.
> > > >>>
> > > >>>  \subsection{Device configuration layout}\label{sec:Device Types / Memory Balloon Device / Device configuration layout}
> > > >>> -  Both fields of this configuration
> > > >>> -  are always available.
> > > >>> +  \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 and is read-only by
> > > >>> +    the driver.  
> > > >>
> > > >> This reads at least to me like "...if VIRTIO_BALLOON_F_FREE_PAGE_HINT
> > > >> ... is read-only by the driver". I suspect you rather meant
> > > >> "free_page_hint_cmd_id is read-only...". Maybe split up into two sentences?  
> > > >
> > > > Yes, the intention is:
> > > > 1. free_page_hint_cmd_id is only available if
> > > > VIRTIO_BALLOON_F_FREE_PAGE_HINT has been negotiated
> > > > 2. free_page_hint_cmd_id is read only by the driver
> > > >
> > > > If needed I suppose we could break it up by splitting it into two
> > > > sentences, or adding "the field" after the "and".
> > > >  
> > >
> > > I'm fine with both options but please adjust this - on top (Michael just
> > > opened the voting for this version again due to the formal typo in round 1).
> > >
> > > Jan  
> > 
> > Since the patch set is being voted on is there a preferred method for
> > making this sort of update? I'm just wondering if I should do an
> > additional incremental patch, just submit a replacement for this
> > patch, or make the change and resubmit the entire patch set?
> 
> I think doing an additional patch on top and then doing another vote on
> that is the best way to handle this. (Or maybe it is minor enough to
> simply merge the incremental patch?)

yes, this sounds good to me


This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.

Subscribe: virtio-comment-subscribe@lists.oasis-open.org
Unsubscribe: virtio-comment-unsubscribe@lists.oasis-open.org
List help: virtio-comment-help@lists.oasis-open.org
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/

Re: [virtio-comment] Re: [virtio-dev] [PATCH v8 1/3] content: Document balloon feature free page hints

[Cornelia Huck]

On Wed, 16 Sep 2020 09:28:34 -0400
"Michael S. Tsirkin" <mst@redhat.com> wrote:

> On Mon, Sep 14, 2020 at 08:13:55AM +0200, Cornelia Huck wrote:
> > On Fri, 11 Sep 2020 08:11:15 -0700
> > Alexander Duyck <alexander.duyck@gmail.com> wrote:
> >   
> > > On Thu, Sep 10, 2020 at 10:28 PM Jan Kiszka <jan.kiszka@siemens.com> wrote:  
> > > >
> > > > On 04.09.20 18:56, Alexander Duyck wrote:    
> > > > > On Fri, Sep 4, 2020 at 8:20 AM Jan Kiszka <jan.kiszka@siemens.com> wrote:    
> > > > >>
> > > > >> On 25.08.20 16:45, Alexander Duyck wrote:    
> >   
> > > > >>> @@ -5042,13 +5049,17 @@ \subsection{Feature bits}\label{sec:Device Types / Memory Balloon Device / Featu
> > > > >>>  VIRTIO_BALLOON_F_MUST_TELL_HOST is not negotiated.
> > > > >>>
> > > > >>>  \subsection{Device configuration layout}\label{sec:Device Types / Memory Balloon Device / Device configuration layout}
> > > > >>> -  Both fields of this configuration
> > > > >>> -  are always available.
> > > > >>> +  \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 and is read-only by
> > > > >>> +    the driver.    
> > > > >>
> > > > >> This reads at least to me like "...if VIRTIO_BALLOON_F_FREE_PAGE_HINT
> > > > >> ... is read-only by the driver". I suspect you rather meant
> > > > >> "free_page_hint_cmd_id is read-only...". Maybe split up into two sentences?    
> > > > >
> > > > > Yes, the intention is:
> > > > > 1. free_page_hint_cmd_id is only available if
> > > > > VIRTIO_BALLOON_F_FREE_PAGE_HINT has been negotiated
> > > > > 2. free_page_hint_cmd_id is read only by the driver
> > > > >
> > > > > If needed I suppose we could break it up by splitting it into two
> > > > > sentences, or adding "the field" after the "and".
> > > > >    
> > > >
> > > > I'm fine with both options but please adjust this - on top (Michael just
> > > > opened the voting for this version again due to the formal typo in round 1).
> > > >
> > > > Jan    
> > > 
> > > Since the patch set is being voted on is there a preferred method for
> > > making this sort of update? I'm just wondering if I should do an
> > > additional incremental patch, just submit a replacement for this
> > > patch, or make the change and resubmit the entire patch set?  
> > 
> > I think doing an additional patch on top and then doing another vote on
> > that is the best way to handle this. (Or maybe it is minor enough to
> > simply merge the incremental patch?)  
> 
> yes, this sounds good to me

Which one of the options, actually? I'd be happy to merge a proper
patch on top (which I'd consider a trivial fix.)


This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.

Subscribe: virtio-comment-subscribe@lists.oasis-open.org
Unsubscribe: virtio-comment-unsubscribe@lists.oasis-open.org
List help: virtio-comment-help@lists.oasis-open.org
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/

Re: [virtio-comment] Re: [virtio-dev] [PATCH v8 1/3] content: Document balloon feature free page hints

[Alexander Duyck]

On Wed, Nov 11, 2020 at 10:03 AM Cornelia Huck <cohuck@redhat.com> wrote:
>
> On Wed, 16 Sep 2020 09:28:34 -0400
> "Michael S. Tsirkin" <mst@redhat.com> wrote:
>
> > On Mon, Sep 14, 2020 at 08:13:55AM +0200, Cornelia Huck wrote:
> > > On Fri, 11 Sep 2020 08:11:15 -0700
> > > Alexander Duyck <alexander.duyck@gmail.com> wrote:
> > >
> > > > On Thu, Sep 10, 2020 at 10:28 PM Jan Kiszka <jan.kiszka@siemens.com> wrote:
> > > > >
> > > > > On 04.09.20 18:56, Alexander Duyck wrote:
> > > > > > On Fri, Sep 4, 2020 at 8:20 AM Jan Kiszka <jan.kiszka@siemens.com> wrote:
> > > > > >>
> > > > > >> On 25.08.20 16:45, Alexander Duyck wrote:
> > >
> > > > > >>> @@ -5042,13 +5049,17 @@ \subsection{Feature bits}\label{sec:Device Types / Memory Balloon Device / Featu
> > > > > >>>  VIRTIO_BALLOON_F_MUST_TELL_HOST is not negotiated.
> > > > > >>>
> > > > > >>>  \subsection{Device configuration layout}\label{sec:Device Types / Memory Balloon Device / Device configuration layout}
> > > > > >>> -  Both fields of this configuration
> > > > > >>> -  are always available.
> > > > > >>> +  \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 and is read-only by
> > > > > >>> +    the driver.
> > > > > >>
> > > > > >> This reads at least to me like "...if VIRTIO_BALLOON_F_FREE_PAGE_HINT
> > > > > >> ... is read-only by the driver". I suspect you rather meant
> > > > > >> "free_page_hint_cmd_id is read-only...". Maybe split up into two sentences?
> > > > > >
> > > > > > Yes, the intention is:
> > > > > > 1. free_page_hint_cmd_id is only available if
> > > > > > VIRTIO_BALLOON_F_FREE_PAGE_HINT has been negotiated
> > > > > > 2. free_page_hint_cmd_id is read only by the driver
> > > > > >
> > > > > > If needed I suppose we could break it up by splitting it into two
> > > > > > sentences, or adding "the field" after the "and".
> > > > > >
> > > > >
> > > > > I'm fine with both options but please adjust this - on top (Michael just
> > > > > opened the voting for this version again due to the formal typo in round 1).
> > > > >
> > > > > Jan
> > > >
> > > > Since the patch set is being voted on is there a preferred method for
> > > > making this sort of update? I'm just wondering if I should do an
> > > > additional incremental patch, just submit a replacement for this
> > > > patch, or make the change and resubmit the entire patch set?
> > >
> > > I think doing an additional patch on top and then doing another vote on
> > > that is the best way to handle this. (Or maybe it is minor enough to
> > > simply merge the incremental patch?)
> >
> > yes, this sounds good to me
>
> Which one of the options, actually? I'd be happy to merge a proper
> patch on top (which I'd consider a trivial fix.)

I had submitted a 4/3 for this set that was meant to fix it, but
looking it over I don't think it would apply cleanly as I think I had
only applied the patch it fixed and didn't have the poison patch
applied when I generated it. If you need I can resubmit that patch as
a trivial fix since it is only a 2 line change.

Thanks.

- Alex

This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.

Subscribe: virtio-comment-subscribe@lists.oasis-open.org
Unsubscribe: virtio-comment-unsubscribe@lists.oasis-open.org
List help: virtio-comment-help@lists.oasis-open.org
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/

Re: [virtio-comment] Re: [virtio-dev] [PATCH v8 1/3] content: Document balloon feature free page hints

[Cornelia Huck]

On Wed, 11 Nov 2020 14:09:23 -0800
Alexander Duyck <alexander.duyck@gmail.com> wrote:

> On Wed, Nov 11, 2020 at 10:03 AM Cornelia Huck <cohuck@redhat.com> wrote:
> >
> > On Wed, 16 Sep 2020 09:28:34 -0400
> > "Michael S. Tsirkin" <mst@redhat.com> wrote:
> >  
> > > On Mon, Sep 14, 2020 at 08:13:55AM +0200, Cornelia Huck wrote:  
> > > > On Fri, 11 Sep 2020 08:11:15 -0700
> > > > Alexander Duyck <alexander.duyck@gmail.com> wrote:
> > > >  
> > > > > On Thu, Sep 10, 2020 at 10:28 PM Jan Kiszka <jan.kiszka@siemens.com> wrote:  
> > > > > >
> > > > > > On 04.09.20 18:56, Alexander Duyck wrote:  
> > > > > > > On Fri, Sep 4, 2020 at 8:20 AM Jan Kiszka <jan.kiszka@siemens.com> wrote:  
> > > > > > >>
> > > > > > >> On 25.08.20 16:45, Alexander Duyck wrote:  
> > > >  
> > > > > > >>> @@ -5042,13 +5049,17 @@ \subsection{Feature bits}\label{sec:Device Types / Memory Balloon Device / Featu
> > > > > > >>>  VIRTIO_BALLOON_F_MUST_TELL_HOST is not negotiated.
> > > > > > >>>
> > > > > > >>>  \subsection{Device configuration layout}\label{sec:Device Types / Memory Balloon Device / Device configuration layout}
> > > > > > >>> -  Both fields of this configuration
> > > > > > >>> -  are always available.
> > > > > > >>> +  \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 and is read-only by
> > > > > > >>> +    the driver.  
> > > > > > >>
> > > > > > >> This reads at least to me like "...if VIRTIO_BALLOON_F_FREE_PAGE_HINT
> > > > > > >> ... is read-only by the driver". I suspect you rather meant
> > > > > > >> "free_page_hint_cmd_id is read-only...". Maybe split up into two sentences?  
> > > > > > >
> > > > > > > Yes, the intention is:
> > > > > > > 1. free_page_hint_cmd_id is only available if
> > > > > > > VIRTIO_BALLOON_F_FREE_PAGE_HINT has been negotiated
> > > > > > > 2. free_page_hint_cmd_id is read only by the driver
> > > > > > >
> > > > > > > If needed I suppose we could break it up by splitting it into two
> > > > > > > sentences, or adding "the field" after the "and".
> > > > > > >  
> > > > > >
> > > > > > I'm fine with both options but please adjust this - on top (Michael just
> > > > > > opened the voting for this version again due to the formal typo in round 1).
> > > > > >
> > > > > > Jan  
> > > > >
> > > > > Since the patch set is being voted on is there a preferred method for
> > > > > making this sort of update? I'm just wondering if I should do an
> > > > > additional incremental patch, just submit a replacement for this
> > > > > patch, or make the change and resubmit the entire patch set?  
> > > >
> > > > I think doing an additional patch on top and then doing another vote on
> > > > that is the best way to handle this. (Or maybe it is minor enough to
> > > > simply merge the incremental patch?)  
> > >
> > > yes, this sounds good to me  
> >
> > Which one of the options, actually? I'd be happy to merge a proper
> > patch on top (which I'd consider a trivial fix.)  
> 
> I had submitted a 4/3 for this set that was meant to fix it, but
> looking it over I don't think it would apply cleanly as I think I had
> only applied the patch it fixed and didn't have the poison patch
> applied when I generated it. If you need I can resubmit that patch as
> a trivial fix since it is only a 2 line change.

Thanks, that would be great.

> 
> Thanks.
> 
> - Alex
> 


This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.

Subscribe: virtio-comment-subscribe@lists.oasis-open.org
Unsubscribe: virtio-comment-unsubscribe@lists.oasis-open.org
List help: virtio-comment-help@lists.oasis-open.org
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/

Re: [virtio-comment] Re: [virtio-dev] [PATCH v8 1/3] content: Document balloon feature free page hints

[Alexander Duyck]

On Wed, Nov 11, 2020 at 11:45 PM Cornelia Huck <cohuck@redhat.com> wrote:
>
> On Wed, 11 Nov 2020 14:09:23 -0800
> Alexander Duyck <alexander.duyck@gmail.com> wrote:
>
> > On Wed, Nov 11, 2020 at 10:03 AM Cornelia Huck <cohuck@redhat.com> wrote:
> > >
> > > On Wed, 16 Sep 2020 09:28:34 -0400
> > > "Michael S. Tsirkin" <mst@redhat.com> wrote:
> > >
> > > > On Mon, Sep 14, 2020 at 08:13:55AM +0200, Cornelia Huck wrote:
> > > > > On Fri, 11 Sep 2020 08:11:15 -0700
> > > > > Alexander Duyck <alexander.duyck@gmail.com> wrote:
> > > > >
> > > > > > On Thu, Sep 10, 2020 at 10:28 PM Jan Kiszka <jan.kiszka@siemens.com> wrote:
> > > > > > >
> > > > > > > On 04.09.20 18:56, Alexander Duyck wrote:
> > > > > > > > On Fri, Sep 4, 2020 at 8:20 AM Jan Kiszka <jan.kiszka@siemens.com> wrote:
> > > > > > > >>
> > > > > > > >> On 25.08.20 16:45, Alexander Duyck wrote:
> > > > >
> > > > > > > >>> @@ -5042,13 +5049,17 @@ \subsection{Feature bits}\label{sec:Device Types / Memory Balloon Device / Featu
> > > > > > > >>>  VIRTIO_BALLOON_F_MUST_TELL_HOST is not negotiated.
> > > > > > > >>>
> > > > > > > >>>  \subsection{Device configuration layout}\label{sec:Device Types / Memory Balloon Device / Device configuration layout}
> > > > > > > >>> -  Both fields of this configuration
> > > > > > > >>> -  are always available.
> > > > > > > >>> +  \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 and is read-only by
> > > > > > > >>> +    the driver.
> > > > > > > >>
> > > > > > > >> This reads at least to me like "...if VIRTIO_BALLOON_F_FREE_PAGE_HINT
> > > > > > > >> ... is read-only by the driver". I suspect you rather meant
> > > > > > > >> "free_page_hint_cmd_id is read-only...". Maybe split up into two sentences?
> > > > > > > >
> > > > > > > > Yes, the intention is:
> > > > > > > > 1. free_page_hint_cmd_id is only available if
> > > > > > > > VIRTIO_BALLOON_F_FREE_PAGE_HINT has been negotiated
> > > > > > > > 2. free_page_hint_cmd_id is read only by the driver
> > > > > > > >
> > > > > > > > If needed I suppose we could break it up by splitting it into two
> > > > > > > > sentences, or adding "the field" after the "and".
> > > > > > > >
> > > > > > >
> > > > > > > I'm fine with both options but please adjust this - on top (Michael just
> > > > > > > opened the voting for this version again due to the formal typo in round 1).
> > > > > > >
> > > > > > > Jan
> > > > > >
> > > > > > Since the patch set is being voted on is there a preferred method for
> > > > > > making this sort of update? I'm just wondering if I should do an
> > > > > > additional incremental patch, just submit a replacement for this
> > > > > > patch, or make the change and resubmit the entire patch set?
> > > > >
> > > > > I think doing an additional patch on top and then doing another vote on
> > > > > that is the best way to handle this. (Or maybe it is minor enough to
> > > > > simply merge the incremental patch?)
> > > >
> > > > yes, this sounds good to me
> > >
> > > Which one of the options, actually? I'd be happy to merge a proper
> > > patch on top (which I'd consider a trivial fix.)
> >
> > I had submitted a 4/3 for this set that was meant to fix it, but
> > looking it over I don't think it would apply cleanly as I think I had
> > only applied the patch it fixed and didn't have the poison patch
> > applied when I generated it. If you need I can resubmit that patch as
> > a trivial fix since it is only a 2 line change.
>
> Thanks, that would be great.

No problem. I just submitted it as a standalone patch and added the
Reviewed-by you had added when I submitted before.

Thanks.

- Alex

This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.

Subscribe: virtio-comment-subscribe@lists.oasis-open.org
Unsubscribe: virtio-comment-unsubscribe@lists.oasis-open.org
List help: virtio-comment-help@lists.oasis-open.org
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/