[PATCH] virtio-ccw: document GPR4/GPR2 cookie values

virtio-ccw on kvm can use a cookie value passed to guest
to optimize channel/VQ lookups.
Document this.

VIRTIO-29

Signed-off-by: Michael S. Tsirkin <>
---
 virtio-v1.0-wd01-part1-specification.txt | 24 +++++++++++++++++++++++-
 1 file changed, 23 insertions(+), 1 deletion(-)

diff --git a/virtio-v1.0-wd01-part1-specification.txt b/virtio-v1.0-wd01-part1-specification.txt
index 7f60dcc..cafc34f 100644
--- a/virtio-v1.0-wd01-part1-specification.txt
+++ b/virtio-v1.0-wd01-part1-specification.txt
@@ -1283,7 +1283,29 @@ For notifying the host of virtqueue buffers, the guest
 unfortunately can't use a channel command (the asynchronous
 characteristics of channel I/O interact badly with the host block
 I/O backend). Instead, it uses a diagnose 0x500 call with subcode
-3 specifying the queue.
+3 specifying the queue, as follows:
+
++------+-------------------+--------------+
+| GPR  |   Input Value     | Output Value |
++------+-------------------+--------------+
++------+-------------------+--------------+
+|  1   |       0x3         |              |
++------+-------------------+--------------+
+|  2   |  Subchannel ID    | Host Cookie  |
++------+-------------------+--------------+
+|  3   | Virtqueue number  |              |
++------+-------------------+--------------+
+|  4   |   Host Cookie     |              |
++------+-------------------+--------------+
+
+Host cookie is an optional per-virtqueue 64 bit value that can be
+used by the hypervisor to speed up the notification execution.
+For each notification, the output value is returned in GPR2 and
+should be passed in GPR4 for the next notification:
+
+        info->cookie = do_notify(schid,
+                                 virtqueue_get_queue_index(vq),
+                                 info->cookie);
 
 2.3.3.3.3. Early printk for Virtio Consoles
 -------------------------------------------
-- 
MST