Unclear/contradictory requirements for Traditional Mem Balloon

[hcsch]

While implementing a VIRTO traditional mem balloon driver from scratch I stumbled across the following two points I considered to be somewhat unclear in the spec currently. Perhaps these can be cleared up in a future version.

Deflate on OOM

In the driver normative section there is first a general permission to use pages (after (acknowledged) deflation presumably) from the balloon if actual < num_pages.

virtio-spec/device-types/balloon/description.tex

Lines 182 to 183 in 16718cb

	The driver MAY use pages from the balloon when \field{num_pages} is
	less than the actual number of pages in the balloon.

Immediately after that however this permission is modified regardless of whether or not the VIRTIO_BALLOON_F_DEFLATE_ON_OOM feature has been negotiated.

virtio-spec/device-types/balloon/description.tex

Lines 188 to 198 in 16718cb

	If VIRTIO_BALLOON_F_DEFLATE_ON_OOM has not been negotiated, the
	driver MUST NOT use pages from the balloon when \field{num_pages}
	is less than or equal to the actual number of pages in the
	balloon.
	If VIRTIO_BALLOON_F_DEFLATE_ON_OOM has been negotiated, the
	driver MAY use pages from the balloon when \field{num_pages}
	is less than or equal to the actual number of pages in the
	balloon if this is required for system stability
	(e.g. if memory is required by applications running within
	the guest).

Here the condition is also actual <= num_pages instead of actual < num_pages.

If a driver implements the feature and it is negotiated, it must not use (or deflate?) pages unless the device requests it by changing num_pages. However if the feature has not been implemented it is not as clear as it could be that pages may not be used. Is the first general permission simply a forgotten remainder from a previous spec version? Is it left in to document that drivers implementing an older version of the spec may use pages even without the feature?

inflateq/deflateq submission format

The format for submission of the pages to the inflateq/deflateq is described as a "32-bit array". Perhaps this should be rephrased to an "array of le32 elements" or something similar for clarity. Linux seem to implement it as such.

virtio-spec/device-types/balloon/description.tex

Lines 151 to 154 in 16718cb

	\item The driver constructs an array of addresses of unused memory
	pages. These addresses are divided by 4096\footnote{This is historical, and independent of the guest page size.
	} and the descriptor
	describing the resulting 32-bit array is added to the inflateq.

For legacy versions behaviour does not seem to be described by the spec on this point. Linux seems to use guest-endian elements in that case.
https://github.com/torvalds/linux/blob/aef17cb3d3c43854002956f24c24ec8e1a0e3546/drivers/virtio/virtio_balloon.c#L238-L239

[hcsch]

Regarding the device operation requirements described in 5.5.6.1 conditional on DEFLATE_ON_OOM:

Is it possible that the condition num_pages "less than or equal" actual was accidentally inverted in the specification and the correct wording should be as follows?

If VIRTIO_BALLOON_F_DEFLATE_ON_OOM has not been negotiated, the driver MUST NOT use pages from the balloon when num_pages is less than greater than or equal to the actual number of pages in the balloon.

If VIRTIO_BALLOON_F_DEFLATE_ON_OOM has been negotiated, the driver MAY use pages from the balloon when num_pages is less than greater than to the actual number of pages in the balloon if this is required for system stability (e.g. if memory is required by applications running within the guest).

This would exactly complement the general permission to deflate when num_pages < actual at the beginning of the section, rather than contradict it.
As per 5.5.6 if num_pages is "is greater than the actual number of pages, the balloon wants more memory from the guest. If it is less than actual, the balloon doesn’t need it all." This means to me that when num_pages < actual the balloon is inflated more than requested by the host and the guest should be able to deflate pages up to the target, 5.5.6.1 seems to forbid this however.

cloud-hypervisor documents the feature as a permission to deflate even when num_pages >= actual for example: https://github.com/cloud-hypervisor/cloud-hypervisor/blob/v46.0/docs/balloon.md#deflate_on_oom
In practice deflation seems to always be allowed:
https://github.com/cloud-hypervisor/cloud-hypervisor/blob/v46.0/virtio-devices/src/balloon.rs#L377-L390
https://github.com/cloud-hypervisor/cloud-hypervisor/blob/v46.0/virtio-devices/src/balloon.rs#L284

QEMU can advertise the feature, but ignores its state and seems to always allow deflation:
https://gitlab.com/qemu-project/qemu/-/blob/v10.0.0/hw/virtio/virtio-balloon.c#L445
https://gitlab.com/qemu-project/qemu/-/blob/v10.0.0/hw/virtio/virtio-balloon.c#L143-168

Similarly crosvm seems to also always allow deflation:
https://github.com/google/crosvm/blob/940eaae7246300bb01e1efb8c3d21ea93e0e63cd/devices/src/virtio/balloon.rs#L924