aboutsummaryrefslogtreecommitdiff
path: root/docs/devel
diff options
context:
space:
mode:
authorMarkus Armbruster <armbru@redhat.com>2018-02-11 10:36:04 +0100
committerEric Blake <eblake@redhat.com>2018-03-02 13:45:51 -0600
commitbb46af41b9e7328626d2ecd37e48acbeb6832bc0 (patch)
tree8b4c38420021b2a8e348b80f90027aaf63552527 /docs/devel
parentbfe873e988614cdfcd3f9078e14e6f94afeba04a (diff)
docs: Correct outdated information on QAPI
* Fix guidance on error classes * Point to generated documentation * Drop plea for documentation, because the QAPI code generator enforces it since commit 3313b6124b * Minor tweaks here and there Signed-off-by: Markus Armbruster <armbru@redhat.com> Message-Id: <20180211093607.27351-27-armbru@redhat.com> Reviewed-by: Eric Blake <eblake@redhat.com> Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com> Reviewed-by: Michael Roth <mdroth@linux.vnet.ibm.com> Signed-off-by: Eric Blake <eblake@redhat.com>
Diffstat (limited to 'docs/devel')
-rw-r--r--docs/devel/writing-qmp-commands.txt25
1 files changed, 9 insertions, 16 deletions
diff --git a/docs/devel/writing-qmp-commands.txt b/docs/devel/writing-qmp-commands.txt
index 776b3b41ca..50385eff27 100644
--- a/docs/devel/writing-qmp-commands.txt
+++ b/docs/devel/writing-qmp-commands.txt
@@ -36,9 +36,9 @@ very simple and get more complex as we progress.
For all the examples in the next sections, the test setup is the same and is
shown here.
-First, QEMU should be started as:
+First, QEMU should be started like this:
-# /path/to/your/source/qemu [...] \
+# qemu-system-TARGET [...] \
-chardev socket,id=qmp,port=4444,host=localhost,server \
-mon chardev=qmp,mode=control,pretty=on
@@ -179,7 +179,7 @@ described in the "Testing" section and then send two commands:
}
}
-You should see "Hello, world" and "we love qemu" in the terminal running qemu,
+You should see "Hello, world" and "We love qemu" in the terminal running qemu,
if you don't see these strings, then something went wrong.
=== Errors ===
@@ -221,30 +221,23 @@ The QMP server's response should be:
}
}
-As a general rule, all QMP errors should use ERROR_CLASS_GENERIC_ERROR
-(done by default when using error_setg()). There are two exceptions to
-this rule:
+Note that error_setg() produces a "GenericError" class. In general,
+all QMP errors should have that error class. There are two exceptions
+to this rule:
- 1. A non-generic ErrorClass value exists* for the failure you want to report
- (eg. DeviceNotFound)
+ 1. To support a management application's need to recognize a specific
+ error for special handling
- 2. Management applications have to take special action on the failure you
- want to report, hence you have to add a new ErrorClass value so that they
- can check for it
+ 2. Backward compatibility
If the failure you want to report falls into one of the two cases above,
use error_set() with a second argument of an ErrorClass value.
- * All existing ErrorClass values are defined in the qapi-schema.json file
-
=== Command Documentation ===
There's only one step missing to make "hello-world"'s implementation complete,
and that's its documentation in the schema file.
-This is very important. No QMP command will be accepted in QEMU without proper
-documentation.
-
There are many examples of such documentation in the schema file already, but
here goes "hello-world"'s new entry for qapi/misc.json: