From 4d8bb958fa0bf8695c5b38b9f153073c62a989b5 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Marc-Andr=C3=A9=20Lureau?= Date: Mon, 6 Jul 2015 22:13:50 +0200 Subject: [PATCH] qmp-commands: move documentation bits to schema MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit Moving the remaining bits of documentation to the json file (text improvements is not the objective of this patch) Signed-off-by: Marc-André Lureau Signed-off-by: Markus Armbruster --- Makefile | 1 - docs/qmp-commands.txt | 53 --------------------------------------------------- qapi-schema.json | 49 ++++++++++++++++++++++++++++++++++++++++++++++- 3 files changed, 48 insertions(+), 55 deletions(-) delete mode 100644 docs/qmp-commands.txt diff --git a/Makefile b/Makefile index 1a8bfb225c..360a6a24a2 100644 --- a/Makefile +++ b/Makefile @@ -429,7 +429,6 @@ endif install-doc: $(DOCS) $(INSTALL_DIR) "$(DESTDIR)$(qemu_docdir)" $(INSTALL_DATA) qemu-doc.html "$(DESTDIR)$(qemu_docdir)" - $(INSTALL_DATA) $(SRC_PATH)/docs/qmp-commands.txt "$(DESTDIR)$(qemu_docdir)" ifdef CONFIG_POSIX $(INSTALL_DIR) "$(DESTDIR)$(mandir)/man1" $(INSTALL_DATA) qemu.1 "$(DESTDIR)$(mandir)/man1" diff --git a/docs/qmp-commands.txt b/docs/qmp-commands.txt deleted file mode 100644 index 07138cdc8a..0000000000 --- a/docs/qmp-commands.txt +++ /dev/null @@ -1,53 +0,0 @@ - QMP Supported Commands - ---------------------- - -This document describes all commands currently supported by QMP. - -Most of the time their usage is exactly the same as in the user Monitor, this -means that any other document which also describe commands (the manpage, -QEMU's manual, etc) can and should be consulted. - -QMP has two types of commands: regular and query commands. Regular commands -usually change the Virtual Machine's state someway, while query commands just -return information. The sections below are divided accordingly. - -It's important to observe that all communication examples are formatted in -a reader-friendly way, so that they're easier to understand. However, in real -protocol usage, they're emitted as a single line. - -Also, the following notation is used to denote data flow: - --> data issued by the Client -<- Server data response - -Please, refer to the QMP specification (docs/qmp-spec.txt) for detailed -information on the Server command and response formats. - -NOTE: This document is temporary and will be replaced soon. - -1. Stability Considerations -=========================== - -The current QMP command set (described in this file) may be useful for a -number of use cases, however it's limited and several commands have bad -defined semantics, specially with regard to command completion. - -These problems are going to be solved incrementally in the next QEMU releases -and we're going to establish a deprecation policy for badly defined commands. - -If you're planning to adopt QMP, please observe the following: - - 1. The deprecation policy will take effect and be documented soon, please - check the documentation of each used command as soon as a new release of - QEMU is available - - 2. DO NOT rely on anything which is not explicit documented - - 3. Errors, in special, are not documented. Applications should NOT check - for specific errors classes or data (it's strongly recommended to only - check for the "error" key) -2. Regular Commands -=================== - -Server's responses in the examples below are always a success response, please -refer to the QMP specification for more details on error responses. diff --git a/qapi-schema.json b/qapi-schema.json index 661f82b033..ddc878390e 100644 --- a/qapi-schema.json +++ b/qapi-schema.json @@ -1,6 +1,53 @@ # -*- Mode: Python -*- +## +# = Introduction +# +# This document describes all commands currently supported by QMP. +# +# Most of the time their usage is exactly the same as in the user Monitor, this +# means that any other document which also describe commands (the manpage, +# QEMU's manual, etc) can and should be consulted. +# +# QMP has two types of commands: regular and query commands. Regular commands +# usually change the Virtual Machine's state someway, while query commands just +# return information. The sections below are divided accordingly. +# +# It's important to observe that all communication examples are formatted in +# a reader-friendly way, so that they're easier to understand. However, in real +# protocol usage, they're emitted as a single line. +# +# Also, the following notation is used to denote data flow: +# +# Example: +# +# | -> data issued by the Client +# | <- Server data response # -# QAPI Schema +# Please, refer to the QMP specification (docs/qmp-spec.txt) for +# detailed information on the Server command and response formats. +# +# = Stability Considerations +# +# The current QMP command set (described in this file) may be useful for a +# number of use cases, however it's limited and several commands have bad +# defined semantics, specially with regard to command completion. +# +# These problems are going to be solved incrementally in the next QEMU releases +# and we're going to establish a deprecation policy for badly defined commands. +# +# If you're planning to adopt QMP, please observe the following: +# +# 1. The deprecation policy will take effect and be documented soon, please +# check the documentation of each used command as soon as a new release of +# QEMU is available +# +# 2. DO NOT rely on anything which is not explicit documented +# +# 3. Errors, in special, are not documented. Applications should NOT check +# for specific errors classes or data (it's strongly recommended to only +# check for the "error" key) +# +## # QAPI common definitions { 'include': 'qapi/common.json' } -- 2.11.0