bwlp/qemu.git/docs/interop/qmp-spec.txt, branch spice_video_codecs

docs/interop/qmp-spec: Document the request queue limit

2021-02-04T12:20:29+00:00

Signed-off-by: Markus Armbruster Message-Id: <20210127144734.2367693-1-armbru@redhat.com> Reviewed-by: John Snow

docs/interop/qmp-spec: Point to the QEMU QMP reference manual

2020-09-03T07:58:02+00:00

Commit 4d8bb958fa0..231aaf3a821 integrated the contents of docs/qmp-events.txt into QAPI schema doc comments. It left dangling references to qmp-events.txt behind. Fix to point to the QEMU QMP reference manual generated from the QAPI schema. Add a similar reference for commands. Cc: Marc-André Lureau Signed-off-by: Markus Armbruster Message-Id: <20200806081147.3123652-2-armbru@redhat.com> Reviewed-by: Marc-André Lureau

docs: Update references to JSON RFC

2018-12-13T18:10:06+00:00

RFC8259 obsoletes RFC7159. Fix a couple of URLs to point to the newer version. Signed-off-by: Eric Blake Message-Id: <20181203175702.128701-1-eblake@redhat.com> Reviewed-by: Markus Armbruster Signed-off-by: Markus Armbruster

monitor: Suspend monitor instead dropping commands

2018-12-12T08:55:57+00:00

When a QMP client sends in-band commands more quickly that we can process them, we can either queue them without limit (QUEUE), drop commands when the queue is full (DROP), or suspend receiving commands when the queue is full (SUSPEND). None of them is ideal: * QUEUE lets a misbehaving client make QEMU eat memory without bounds. Not such a hot idea. * With DROP, the client has to cope with dropped in-band commands. To inform the client, we send a COMMAND_DROPPED event then. The event is flawed by design in two ways: it's ambiguous (see commit d621cfe0a17), and it brings back the "eat memory without bounds" problem. * With SUSPEND, the client has to manage the flow of in-band commands to keep the monitor available for out-of-band commands. We currently DROP. Switch to SUSPEND. Managing the flow of in-band commands to keep the monitor available for out-of-band commands isn't really hard: just count the number of "outstanding" in-band commands (commands sent minus replies received), and if it exceeds the limit, hold back additional ones until it drops below the limit again. Note that we need to be careful pairing the suspend with a resume, or else the monitor will hang, possibly forever. And here since we need to make sure both: (1) popping request from the req queue, and (2) reading length of the req queue will be in the same critical section, we let the pop function take the corresponding queue lock when there is a request, then we release the lock from the caller. Reviewed-by: Marc-André Lureau Signed-off-by: Peter Xu Message-Id: <20181009062718.1914-2-peterx@redhat.com> Signed-off-by: Markus Armbruster

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

2018-08-24T18:25:48+00:00

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 Reviewed-by: Eric Blake Message-Id: <20180823164025.12553-2-armbru@redhat.com>

qmp: Redo how the client requests out-of-band execution

2018-07-03T21:18:56+00:00

Commit cf869d53172 "qmp: support out-of-band (oob) execution" added a general mechanism for command-independent arguments just for an out-of-band flag: The "control" key is introduced to store this extra flag. "control" field is used to store arguments that are shared by all the commands, rather than command specific arguments. Let "run-oob" be the first. However, it failed to reject unknown members of "control". For instance, in QMP command {"execute": "query-name", "id": 42, "control": {"crap": true}} "crap" gets silently ignored. Instead of fixing this, revert the general "control" mechanism (because YAGNI), and do it the way I initially proposed, with key "exec-oob". Simpler code, simpler interface. An out-of-band command {"execute": "migrate-pause", "id": 42, "control": {"run-oob": true}} becomes {"exec-oob": "migrate-pause", "id": 42} Signed-off-by: Markus Armbruster Reviewed-by: Eric Blake Message-Id: <20180703085358.13941-13-armbru@redhat.com> [Commit message typo fixed]

qmp: Make "id" optional again even in "oob" monitors

2018-07-03T21:18:56+00:00

Commit cf869d53172 "qmp: support out-of-band (oob) execution" made "id" mandatory for all commands when the client accepted capability "oob". This is rather onerous when you play with QMP by hand, and unnecessarily so: only out-of-band commands need an ID for reliable matching of response to command. Revert that part of commit cf869d53172 for now, but have documentation advise on the need to use "id" with out-of-band commands. Signed-off-by: Markus Armbruster Message-Id: <20180703085358.13941-8-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé Reviewed-by: Eric Blake

docs/interop/qmp: Improve OOB documentation

2018-07-03T21:09:31+00:00

OOB documentation is spread over qmp-spec.txt sections 2.2.1 Capabilities and 2.3 Issuing Commands. The amount of detail is a bit distracting there. Move the meat of the matter to new section 2.3.1 Out of band execution. Throw in a few other improvements while there: * 2.2 Server Greeting: Drop advice to search entire capabilities array; should be obvious. * 3. QMP Examples - 3.1 Server Greeting: Update greeting to the one we expect for the release. Now shows capability "oob". Update qmp-intro.txt likewise. - 3.2 Capabilities negotiation: Show client accepting capability "oob". - 3.7 Out-of-band execution: New. Signed-off-by: Markus Armbruster Reviewed-by: Eric Blake Message-Id: <20180703085358.13941-4-armbru@redhat.com> [Whitespace tidied up]

qmp: Say "out-of-band" instead of "Out-Of-Band"

2018-07-03T09:46:54+00:00

Affects documentation and a few error messages. Signed-off-by: Markus Armbruster Reviewed-by: Eric Blake Message-Id: <20180703085358.13941-2-armbru@redhat.com>

docs: update QMP documents for OOB commands

2018-03-19T19:58:36+00:00

Update both the developer and spec for the new QMP OOB (Out-Of-Band) command. Signed-off-by: Peter Xu Message-Id: <20180309090006.10018-2-peterx@redhat.com> Reviewed-by: Eric Blake [eblake: grammar tweaks] Signed-off-by: Eric Blake