[PATCH RFC] balloon: add VIRTIO_BALLOON_F_PAGE_REPORTING_HOLD

From: Zhang JianMing <[email protected]>

Define a new balloon feature bit which lets the driver announce that it
will retain reported pages after the reporting request has been
acknowledged, instead of returning them to the guest free page lists
immediately, and reuse them only when needed.

The current text of the Free Page Reporting section already allows the
driver to "reuse the reported free pages when needed" after
acknowledgement, but the device cannot observe whether a given driver
will return the pages immediately or keep them. The new bit makes this
explicit and negotiated, in the same informational spirit as
VIRTIO_BALLOON_F_PAGE_POISON. It adds no new driver obligation and
requires no new device action.

Motivation: on guests whose memory manager touches every freed page
(e.g. Windows), pages returned to the guest free lists immediately
after a report are dirtied again within seconds, and the host-side
benefit of the report is lost. Retaining reported pages inside the
driver preserves it; measurements and a reference QEMU patch were
posted to the virtio-comment list on 2026-08-17.

Signed-off-by: Zhang JianMing <[email protected]>
---
Hi all,

Following up on the proposal from 2026-08-17 ("virtio-balloon:
proposal - free page reporting hold") with a concrete spec change, now
as a patch against the current master.

Additional notes beyond the commit message:

- Feature bit number: bit 6 is the next free bit in the current
  master. I am aware of the balloon DEVICE_INIT* series discussed on
  this list in April/May; if any of those lands first and takes bit
  6, this patch should be renumbered accordingly; happy to rebase.

- Implementation status: a reference QEMU patch (property
  "free-page-reporting-hold", default off, requires
  free-page-reporting) was included with the original proposal. A
  Windows virtio-balloon driver prototype retains reported pages and
  releases them gradually under memory pressure.

Comments welcome, in particular on the bit number, the feature name,
and whether the device normative statement is strong enough.

---
 device-types/balloon/description.tex | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/device-types/balloon/description.tex b/device-types/balloon/description.tex
index a1d9603..4a367bf 100644
--- a/device-types/balloon/description.tex
+++ b/device-types/balloon/description.tex
@@ -48,6 +48,10 @@ guest memory statistics to the host.
     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.
+\item[ VIRTIO_BALLOON_F_PAGE_REPORTING_HOLD(6) ] A hint to the device, that
+    the driver will retain the reported pages after the reporting request
+    has been acknowledged, instead of returning them to the guest free page
+    lists immediately. The driver will reuse such pages only when needed.
 
 \end{description}
 
@@ -598,6 +602,11 @@ pages are reported is up to the driver.
 
 \end{enumerate}
 
+If the VIRTIO_BALLOON_F_PAGE_REPORTING_HOLD feature has been negotiated,
+the driver may retain the reported pages after the reporting request has
+been acknowledged, instead of returning them to the guest free page lists
+immediately, and reuse them only when needed.
+
 \drivernormative{\paragraph}{Free Page Reporting}{Device Types / Memory Balloon Device / Device Operation / Free Page Reporting}
 
 Normative statements in this section apply if the
@@ -629,6 +638,11 @@ 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_REPORTING_HOLD feature has been negotiated,
+the device MUST NOT assume that a reported page is returned to the guest
+free page lists at any particular time after the reporting request has been
+acknowledged.
+
 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}.
-- 
2.23.0.windows.1