Ok, so here's what I ended up with.
Any feedback welcome...
Rusty.
diff --git a/virtio-v1.0-wd01-part1-specification.txt b/virtio-v1.0-wd01-part1-specification.txt
index b2d3cd9..4e795d2 100644
--- a/virtio-v1.0-wd01-part1-specification.txt
+++ b/virtio-v1.0-wd01-part1-specification.txt
@@ -1713,6 +1713,15 @@ Discovering what devices are available and their type is bus-dependent.
| 12 | virtio CAIF |
+------------+--------------------+
+100.4.1. Legacy Interface: Device Types
+================
++------------+--------------------+
+| Device ID | Virtio Device |
++------------+--------------------+
++------------+--------------------+
+| 5 | memory ballooning |
++------------+--------------------+
+
2.4.1. Network Device
====================
@@ -2468,7 +2477,7 @@ When the driver requires random bytes, it places the descriptor
of one or more buffers in the queue. It will be completely filled
by random data by the device.
-2.4.5. Memory Balloon Device
+2.4.5. Legacy Interface: Memory Balloon Device
===========================
The virtio memory balloon device is a primitive device for
@@ -2479,17 +2488,17 @@ changes in allowance of underlying physical memory. If the
feature is negotiated, the device can also be used to communicate
guest memory statistics to the host.
-2.4.5.1. Device ID
+2.4.5.1. Legacy Interface: Device ID
-----------------
5
-2.4.5.2. Virtqueues
+2.4.5.2. Legacy Interface: Virtqueues
------------------
0:inflateq. 1:deflateq. 2:statsq.
Virtqueue 2 only exists if VIRTIO_BALLON_F_STATS_VQ set.
-2.4.5.3. Feature bits
+2.4.5.3. Legacy Interface: Feature bits
--------------------
VIRTIO_BALLOON_F_MUST_TELL_HOST (0) Host must be told before
pages from the balloon are used.
@@ -2497,7 +2506,7 @@ guest memory statistics to the host.
VIRTIO_BALLOON_F_STATS_VQ (1) A virtqueue for reporting guest
memory statistics is present.
-2.4.5.4. Device configuration layout
+2.4.5.4. Legacy Interface: Device configuration layout
-----------------------------------
Both fields of this configuration
are always available. Note that they are little endian, despite
@@ -2508,7 +2517,7 @@ guest memory statistics to the host.
u32 actual;
};
-2.4.5.5. Device Initialization
+2.4.5.5. Legacy Interface: Device Initialization
-----------------------------
1. The inflate and deflate virtqueues are identified.
@@ -2522,7 +2531,7 @@ guest memory statistics to the host.
Device operation begins immediately.
-2.4.5.6. Device Operation
+2.4.5.6. Legacy Interface: Device Operation
------------------------
Memory Ballooning The device is driven by the receipt of a
@@ -2558,7 +2567,7 @@ configuration change interrupt.
deflation, the “actual” field of the configuration should be
updated to reflect the new number of pages in the balloon.[27]
-2.4.5.6.1. Memory Statistics
+2.4.5.6.1. Legacy Interface: Memory Statistics
---------------------------
The stats virtqueue is atypical because communication is driven
@@ -2598,7 +2607,7 @@ as follows:
u64 val;
} __attribute__((packed));
-2.4.5.6.2. Memory Statistics Tags
+2.4.5.6.2. Legacy Interface: Memory Statistics Tags
--------------------------------
VIRTIO_BALLOON_S_SWAP_IN The amount of memory that has been
@@ -3141,6 +3150,124 @@ contents of the event field. The following events are defined:
For simplicity, as of this version of the specification the host must
never report this event for MMC devices.
+100.2.4.5. Memory Balloon Device
+===========================
+
+The virtio memory balloon device is a primitive device for managing
+guest memory: the device asks for a certain amount of memory, and the
+guest supplies it. This allows the guest to adapt to changes in
+allowance of underlying physical memory. The device can also be used
+to communicate guest memory statistics to the host.
+
+100.2.4.5.1. Device ID
+-----------------
+ 13
+
+100.2.4.5.2. Virtqueues
+------------------
+ 0:inputq. 1:outputq.
+
+
+100.2.4.5.3. Feature bits
+--------------------
+ None defined.
+
+100.2.4.5.4. Device configuration layout
+-----------------------------------
+
+The read-only configuration field indicates the granularity of memory
+which can be added to the balloon. This is typically reflects the
+page size of the host (eg. 12 for 4096-byte pages).
+
+ struct virtio_balloon_config {
+ u32 page_bits;
+ }
+
+100.2.4.5.5. Device Initialization
+-----------------------------
+
+1. At least one struct virtio_balloon_request buffer should be placed
+ in the inputq.
+
+2. The balloon starts empty (size 0).
+
+100.2.4.5.6. Device Operation
+------------------------
+
+The device is driven by receipt of a command in the input queue:
+
+ struct virtio_balloon_req {
+#define VIRTIO_BALLOON_REQ_RESIZE 0
+#define VIRTIO_BALLOON_REQ_STATS 1
+ u32 type;
+ u32 reserved;
+ u64 value;
+ }
+
+1. A VIRTIO_BALLOON_REQ_RESIZE command indicates the balloon target
+ size (in bytes) in the value field. If the current balloon size is
+ smaller than the target, the guest should add pages to the balloon
+ as soon as possible. If the current balloon is larger than the
+ target, the guest may withdraw pages.
+
+2. To add pages to the balloon, the physical addresses of the pages
+ are sent using the output queue. The number of pages is implied in
+ the message length, and each page value must be a multiple of the
+ page size indicated in struct virtio_balloon_config.
+
+ struct virtio_balloon_pages {
+#define VIRTIO_BALLOON_RESP_PAGES 0
+ u32 type; // VIRTIO_BALLOON_RESP_PAGES
+ u64 page[];
+ };
+
+3. To withdraw a page from the balloon, it can simply be accessed.
+ The contents at this point will be undefined. The device should
+ keep count of how many pages remain in the balloon so it can
+ correctly respond to future resize requests.
+
+4. A VIRTIO_BALLOON_REQ_STATS command indicates that the balloon
+ should report what stats are available.
+
+5. To report stats, the following message is sent to the output queue.
+ Indeterminable stats must not be reported.
+
+ struct virtio_balloon_stats {
+#define VIRTIO_BALLOON_RESP_STATS 1
+ u32 type; // VIRTIO_BALLOON_RESP_STATS
+ struct {
+#define VIRTIO_BALLOON_TAG_SWAP_IN 0
+#define VIRTIO_BALLOON_TAG_SWAP_OUT 1
+#define VIRTIO_BALLOON_TAG_MAJFLT 2
+#define VIRTIO_BALLOON_TAG_MINFLT 3
+#define VIRTIO_BALLOON_TAG_MEMFREE 4
+#define VIRTIO_BALLOON_TAG_MEMTOT 5
+ u64 tag;
+ u64 value;
+ }[];
+ };
+
+100.2.4.5.6.2. Memory Statistics Tags
+--------------------------------
+
+ VIRTIO_BALLOON_TAG_SWAP_IN The amount of memory that has been
+ swapped in (in bytes).
+
+ VIRTIO_BALLOON_TAG_SWAP_OUT The amount of memory that has been
+ swapped out to disk (in bytes).
+
+ VIRTIO_BALLOON_TAG_MAJFLT The number of major page faults that
+ have occurred.
+
+ VIRTIO_BALLOON_TAG_MINFLT The number of minor page faults that
+ have occurred.
+
+ VIRTIO_BALLOON_TAG_MEMFREE The amount of memory not being used
+ for any purpose (in bytes).
+
+ VIRTIO_BALLOON_TAG_MEMTOT The total amount of memory available
+ (in bytes).
+
2.5. Reserved Feature Bits
=========================
