| Message ID | 1443189844-20341-7-git-send-email-marcandre.lureau@redhat.com |
|---|---|
| State | New |
| Headers | show |
On 09/25/2015 08:03 AM, marcandre.lureau@redhat.com wrote: > From: Marc-André Lureau <marcandre.lureau@redhat.com> > > Moving the remaining bits of documentation to the schema files. > > Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com> > --- > qapi-schema.json | 48 ++++++++++++++++++++++++++++++++++++++++++- > qmp-commands.hx | 62 -------------------------------------------------------- > 2 files changed, 47 insertions(+), 63 deletions(-) > > diff --git a/qapi-schema.json b/qapi-schema.json > index 1383011..c8ee75d 100644 > --- a/qapi-schema.json > +++ b/qapi-schema.json > @@ -1,6 +1,52 @@ > # -*- 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. Do we really still have that clean division? > +# > +# 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. The server replies in a single line, but the client is free to send in multiple lines. > +# > +# Also, the following notation is used to denote data flow: > +# > +# Example: > +# > +# | -> data issued by the Client > +# | <- Server data response > +# > +# Please, refer to the QMP specification (QMP/qmp-spec.txt) for detailed > +# information on the Server command and response formats. Stale comment, pointing to the wrong file name (commit 7537fe04 moved it from QMP/ to docs/qmp/) (and Markus has a patch pending that moves it from docs/qmp/qmp-spec.txt to docs/qmp-spec.txt). > +# > +# = 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. Wow - some of this stuff has bit-rotted over time. I don't know how much command completion we support for QMP (I guess it depends whether you are using qmp-shell or a straight monitor connection), and while we do still have badly defined commands, they are now the exception and we have made a lot of progress in fixing things. > +# > +# 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 Umm, we still don't have a documented deprecation policy. > +# > +# 2. DO NOT rely on anything which is not explicit documented s/explicit/explicitly/ > +# > +# 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 Schema > > # QAPI common definitions > { 'include': 'qapi/common.json' }
----- Original Message ----- > On 09/25/2015 08:03 AM, marcandre.lureau@redhat.com wrote: > > From: Marc-André Lureau <marcandre.lureau@redhat.com> > > > > Moving the remaining bits of documentation to the schema files. > > > > Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com> > > --- > > qapi-schema.json | 48 ++++++++++++++++++++++++++++++++++++++++++- > > qmp-commands.hx | 62 > > -------------------------------------------------------- > > 2 files changed, 47 insertions(+), 63 deletions(-) > > > > diff --git a/qapi-schema.json b/qapi-schema.json > > index 1383011..c8ee75d 100644 > > --- a/qapi-schema.json > > +++ b/qapi-schema.json > > @@ -1,6 +1,52 @@ > > # -*- 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. > > Do we really still have that clean division? snip Could we leave the content change for a later patch? The point was not to rewrite the documentation, but simply to move it.
On 09/25/2015 09:29 AM, Marc-André Lureau wrote: > > > ----- Original Message ----- >> On 09/25/2015 08:03 AM, marcandre.lureau@redhat.com wrote: >>> From: Marc-André Lureau <marcandre.lureau@redhat.com> >>> >>> Moving the remaining bits of documentation to the schema files. >>> >>> Signed-off-by: Marc-André Lureau <marcandre.lureau@redhat.com> >>> --- >>> qapi-schema.json | 48 ++++++++++++++++++++++++++++++++++++++++++- >>> qmp-commands.hx | 62 >>> -------------------------------------------------------- >>> 2 files changed, 47 insertions(+), 63 deletions(-) >>> >> Do we really still have that clean division? > > snip > > Could we leave the content change for a later patch? The point was not to rewrite the documentation, but simply to move it. Probably fine that way, but I also don't want to forget about the content change (so even if it is not done in this patch, it should still be part of the series).
diff --git a/qapi-schema.json b/qapi-schema.json index 1383011..c8ee75d 100644 --- a/qapi-schema.json +++ b/qapi-schema.json @@ -1,6 +1,52 @@ # -*- 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 +# +# Please, refer to the QMP specification (QMP/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 Schema # QAPI common definitions { 'include': 'qapi/common.json' } diff --git a/qmp-commands.hx b/qmp-commands.hx index c09918b..3a7af18 100644 --- a/qmp-commands.hx +++ b/qmp-commands.hx @@ -1,65 +1,3 @@ -HXCOMM QMP dispatch table and documentation -HXCOMM Text between SQMP and EQMP is copied to the QMP documentation file and -HXCOMM does not show up in the other formats. - -SQMP - 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 (QMP/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. - -EQMP - { .name = "quit", .args_type = "",