docs/interop/qmp-spec: How to force known good parser state

Section "QGA Synchronization" specifies that sending "a raw 0xFF
sentinel byte" makes the server "reset its state and discard all
pending data prior to the sentinel."  What actually happens there is a
lexical error, which will produce one or more error responses.
Moreover, it's not specific to QGA.

Create new section "Forcing the JSON parser into known-good state" to
document the technique properly.  Rewrite section "QGA
Synchronization" to document just the other direction, i.e. command
guest-sync-delimited.

Section "Protocol Specification" mentions "synchronization bytes
(documented below)".  Delete that.

While there, fix it not to claim '"Server" is QEMU itself', but
'"Server" is either QEMU or the QEMU Guest Agent'.

Signed-off-by: Markus Armbruster <armbru@redhat.com>
Reviewed-by: Eric Blake <eblake@redhat.com>
Message-Id: <20180823164025.12553-2-armbru@redhat.com>

docs/interop/qmp-spec.txt

@@ -20,9 +20,9 @@ operating system.
 2. Protocol Specification
 =========================
 
-This section details the protocol format. For the purpose of this document
+This section details the protocol format. For the purpose of this
-"Client" is any application which is using QMP to communicate with QEMU and
+document, "Server" is either QEMU or the QEMU Guest Agent, and
-"Server" is QEMU itself.
+"Client" is any application communicating with it via QMP.
 
 JSON data structures, when mentioned in this document, are always in the
 following format:
@@ -34,9 +34,8 @@ by the JSON standard:
 
 http://www.ietf.org/rfc/rfc7159.txt
 
-The protocol is always encoded in UTF-8 except for synchronization
+The server expects its input to be encoded in UTF-8, and sends its
-bytes (documented below); although thanks to json-string escape
+output encoded in ASCII.
-sequences, the server will reply using only the strict ASCII subset.
 
 For convenience, json-object members mentioned in this document will
 be in a certain order. However, in real protocol usage they can be in
@@ -215,16 +214,31 @@ Some events are rate-limited to at most one per second.  If additional
 dropped, and the last one is delayed.  "Similar" normally means same
 event type.  See qmp-events.txt for details.
 
-2.6 QGA Synchronization
+2.6 Forcing the JSON parser into known-good state
+-------------------------------------------------
+
+Incomplete or invalid input can leave the server's JSON parser in a
+state where it can't parse additional commands.  To get it back into
+known-good state, the client should provoke a lexical error.
+
+The cleanest way to do that is sending an ASCII control character
+other than '\t' (horizontal tab), '\r' (carriage return), or '\n' (new
+line).
+
+Sadly, older versions of QEMU can fail to flag this as an error.  If a
+client needs to deal with them, it should send a 0xFF byte.
+
+2.7 QGA Synchronization
 -----------------------
 
-When using QGA, an additional synchronization feature is built into
+When a client connects to QGA over a transport lacking proper
-the protocol.  If the Client sends a raw 0xFF sentinel byte (not valid
+connection semantics such as virtio-serial, QGA may have read partial
-JSON), then the Server will reset its state and discard all pending
+input from a previous client.  The client needs to force QGA's parser
-data prior to the sentinel.  Conversely, if the Client makes use of
+into known-good state using the previous section's technique.
-the 'guest-sync-delimited' command, the Server will send a raw 0xFF
+Moreover, the client may receive output a previous client didn't read.
-sentinel byte prior to its response, to aid the Client in discarding
+To help with skipping that output, QGA provides the
-any data prior to the sentinel.
+'guest-sync-delimited' command.  Refer to its documentation for
+details.
 
 
 3. QMP Examples