aboutsummaryrefslogtreecommitdiff
path: root/docs/interop/qmp-spec.txt
AgeCommit message (Collapse)Author
2021-02-04docs/interop/qmp-spec: Document the request queue limitMarkus Armbruster
Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20210127144734.2367693-1-armbru@redhat.com> Reviewed-by: John Snow <jsnow@redhat.com>
2020-09-03docs/interop/qmp-spec: Point to the QEMU QMP reference manualMarkus Armbruster
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 <marcandre.lureau@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20200806081147.3123652-2-armbru@redhat.com> Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>
2018-12-13docs: Update references to JSON RFCEric Blake
RFC8259 obsoletes RFC7159. Fix a couple of URLs to point to the newer version. Signed-off-by: Eric Blake <eblake@redhat.com> Message-Id: <20181203175702.128701-1-eblake@redhat.com> Reviewed-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
2018-12-12monitor: Suspend monitor instead dropping commandsPeter Xu
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 <marcandre.lureau@redhat.com> Signed-off-by: Peter Xu <peterx@redhat.com> Message-Id: <20181009062718.1914-2-peterx@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com>
2018-08-24docs/interop/qmp-spec: How to force known good parser stateMarkus Armbruster
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>
2018-07-03qmp: Redo how the client requests out-of-band executionMarkus Armbruster
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 <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Message-Id: <20180703085358.13941-13-armbru@redhat.com> [Commit message typo fixed]
2018-07-03qmp: Make "id" optional again even in "oob" monitorsMarkus Armbruster
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 <armbru@redhat.com> Message-Id: <20180703085358.13941-8-armbru@redhat.com> Reviewed-by: Daniel P. Berrangé <berrange@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com>
2018-07-03docs/interop/qmp: Improve OOB documentationMarkus Armbruster
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 <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Message-Id: <20180703085358.13941-4-armbru@redhat.com> [Whitespace tidied up]
2018-07-03qmp: Say "out-of-band" instead of "Out-Of-Band"Markus Armbruster
Affects documentation and a few error messages. Signed-off-by: Markus Armbruster <armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Message-Id: <20180703085358.13941-2-armbru@redhat.com>
2018-03-19docs: update QMP documents for OOB commandsPeter Xu
Update both the developer and spec for the new QMP OOB (Out-Of-Band) command. Signed-off-by: Peter Xu <peterx@redhat.com> Message-Id: <20180309090006.10018-2-peterx@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> [eblake: grammar tweaks] Signed-off-by: Eric Blake <eblake@redhat.com>
2017-06-15docs: create interop/ subdirectoryPaolo Bonzini
This is for the future interoperability & management guide. It includes the QAPI docs, including the automatically generated ones, other socket protocols (vhost-user, VNC), and the qcow2 file format. Signed-off-by: Paolo Bonzini <pbonzini@redhat.com>