aboutsummaryrefslogtreecommitdiff
path: root/qapi-schema-guest.json
diff options
context:
space:
mode:
authorMichael Roth <mdroth@linux.vnet.ibm.com>2012-02-07 13:56:48 -0600
committerMichael Roth <mdroth@linux.vnet.ibm.com>2012-03-12 15:09:23 -0500
commit3cf0bed8369267184e5dc5b58882811519d67437 (patch)
treea9c32d61d08ec7ab795b1b2cc4d74252087e1130 /qapi-schema-guest.json
parent3424fc9f16a1e7d1c48eb6d605eb0ca63e199ec2 (diff)
downloadqemu-3cf0bed8369267184e5dc5b58882811519d67437.zip
qemu-3cf0bed8369267184e5dc5b58882811519d67437.tar.gz
qemu-3cf0bed8369267184e5dc5b58882811519d67437.tar.bz2
qemu-ga: add guest-sync-delimited
guest-sync leaves it as an exercise to the user as to how to reliably obtain the response to guest-sync if the client had previously read in a partial response (due qemu-ga previously being restarted mid-"sentence" due to reboot, forced restart, etc). qemu-ga handles this situation on its end by having a client precede their guest-sync request with a 0xFF byte (invalid UTF-8), which qemu-ga/QEMU JSON parsers will treat as a flush event. Thus we can reliably flush the qemu-ga parser state in preparation for receiving the guest-sync request. guest-sync-delimited provides the same functionality for a client: when a guest-sync-delimited is issued, qemu-ga will precede it's response with a 0xFF byte that the client can use as an indicator to flush its buffer/parser state in preparation for reliably receiving the guest-sync-delimited response. It is also useful as an optimization for clients, since, after issuing a guest-sync-delimited, clients can safely discard all stale data read from the channel until the 0xFF is found. More information available on the wiki: http://wiki.qemu.org/Features/QAPI/GuestAgent#QEMU_Guest_Agent_Protocol Signed-off-by: Michael Roth <mdroth@linux.vnet.ibm.com>
Diffstat (limited to 'qapi-schema-guest.json')
-rw-r--r--qapi-schema-guest.json48
1 files changed, 47 insertions, 1 deletions
diff --git a/qapi-schema-guest.json b/qapi-schema-guest.json
index 12b5d4f..cf18876 100644
--- a/qapi-schema-guest.json
+++ b/qapi-schema-guest.json
@@ -1,6 +1,41 @@
# *-*- Mode: Python -*-*
##
+#
+# Echo back a unique integer value, and prepend to response a
+# leading sentinel byte (0xFF) the client can check scan for.
+#
+# This is used by clients talking to the guest agent over the
+# wire to ensure the stream is in sync and doesn't contain stale
+# data from previous client. It must be issued upon initial
+# connection, and after any client-side timeouts (including
+# timeouts on receiving a response to this command).
+#
+# After issuing this request, all guest agent responses should be
+# ignored until the response containing the unique integer value
+# the client passed in is returned. Receival of the 0xFF sentinel
+# byte must be handled as an indication that the client's
+# lexer/tokenizer/parser state should be flushed/reset in
+# preparation for reliably receiving the subsequent response. As
+# an optimization, clients may opt to ignore all data until a
+# sentinel value is receiving to avoid unecessary processing of
+# stale data.
+#
+# Similarly, clients should also precede this *request*
+# with a 0xFF byte to make sure the guest agent flushes any
+# partially read JSON data from a previous client connection.
+#
+# @id: randomly generated 64-bit integer
+#
+# Returns: The unique integer id passed in by the client
+#
+# Since: 1.1
+# ##
+{ 'command': 'guest-sync-delimited'
+ 'data': { 'id': 'int' },
+ 'returns': 'int' }
+
+##
# @guest-sync:
#
# Echo back a unique integer value
@@ -13,8 +48,19 @@
# partially-delivered JSON text in such a way that this response
# can be obtained.
#
+# In cases where a partial stale response was previously
+# received by the client, this cannot always be done reliably.
+# One particular scenario being if qemu-ga responses are fed
+# character-by-character into a JSON parser. In these situations,
+# using guest-sync-delimited may be optimal.
+#
+# For clients that fetch responses line by line and convert them
+# to JSON objects, guest-sync should be sufficient, but note that
+# in cases where the channel is dirty some attempts at parsing the
+# response may result in a parser error.
+#
# Such clients should also precede this command
-# with a 0xFF byte to make such the guest agent flushes any
+# with a 0xFF byte to make sure the guest agent flushes any
# partially read JSON data from a previous session.
#
# @id: randomly generated 64-bit integer