[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Qemu-devel] [PULL 27/30] docs: Correct outdated information on QAPI
From: |
Eric Blake |
Subject: |
[Qemu-devel] [PULL 27/30] docs: Correct outdated information on QAPI |
Date: |
Thu, 1 Mar 2018 13:42:42 -0600 |
From: Markus Armbruster <address@hidden>
* 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 <address@hidden>
Message-Id: <address@hidden>
Reviewed-by: Eric Blake <address@hidden>
Reviewed-by: Marc-André Lureau <address@hidden>
Reviewed-by: Michael Roth <address@hidden>
Signed-off-by: Eric Blake <address@hidden>
---
docs/devel/writing-qmp-commands.txt | 25 +++++++++----------------
docs/interop/qmp-intro.txt | 3 ++-
2 files changed, 11 insertions(+), 17 deletions(-)
diff --git a/docs/devel/writing-qmp-commands.txt
b/docs/devel/writing-qmp-commands.txt
index 776b3b41ca0..50385eff27c 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:
diff --git a/docs/interop/qmp-intro.txt b/docs/interop/qmp-intro.txt
index adbc94abb1d..430fe1b7472 100644
--- a/docs/interop/qmp-intro.txt
+++ b/docs/interop/qmp-intro.txt
@@ -78,7 +78,8 @@ Escape character is '^]'.
}
}
-Please, refer to the qapi-schema.json file for a complete command reference.
+Please refer to docs/interop/qemu-qmp-ref.* for a complete command
+reference, generated from qapi-schema.json.
QMP wiki page
-------------
--
2.14.3
- [Qemu-devel] [PULL 14/30] qapi: Concentrate QAPISchemaParser.exprs updates in .__init__(), (continued)
- [Qemu-devel] [PULL 14/30] qapi: Concentrate QAPISchemaParser.exprs updates in .__init__(), Eric Blake, 2018/03/01
- [Qemu-devel] [PULL 16/30] qapi: Generate in source order, Eric Blake, 2018/03/01
- [Qemu-devel] [PULL 17/30] qapi: Record 'include' directives in intermediate representation, Eric Blake, 2018/03/01
- [Qemu-devel] [PULL 18/30] qapi: Rename generated qmp-marshal.c to qmp-commands.c, Eric Blake, 2018/03/01
- [Qemu-devel] [PULL 21/30] qapi/common: Fix guardname() for funny filenames, Eric Blake, 2018/03/01
- [Qemu-devel] [PULL 20/30] qapi/types qapi/visit: Generate built-in stuff into separate files, Eric Blake, 2018/03/01
- [Qemu-devel] [PULL 19/30] qapi: Make code-generating visitors use QAPIGen more, Eric Blake, 2018/03/01
- [Qemu-devel] [PULL 22/30] qapi: Generate separate .h, .c for each module, Eric Blake, 2018/03/01
- [Qemu-devel] [PULL 24/30] watchdog: Consolidate QAPI into single file, Eric Blake, 2018/03/01
- [Qemu-devel] [PULL 26/30] docs/devel/writing-qmp-commands: Update for modular QAPI, Eric Blake, 2018/03/01
- [Qemu-devel] [PULL 27/30] docs: Correct outdated information on QAPI,
Eric Blake <=
- [Qemu-devel] [PULL 30/30] qapi: Don't create useless directory qapi-generated, Eric Blake, 2018/03/01
- [Qemu-devel] [PULL 23/30] Include less of the generated modular QAPI headers, Eric Blake, 2018/03/01
- [Qemu-devel] [PULL 29/30] Fix up dangling references to qmp-commands.* in comment and doc, Eric Blake, 2018/03/01
- [Qemu-devel] [PULL 28/30] qapi: Move qapi-schema.json to qapi/, rename generated files, Eric Blake, 2018/03/01
- [Qemu-devel] [PULL 25/30] qapi: Empty out qapi-schema.json, Eric Blake, 2018/03/01
- Re: [Qemu-devel] [PULL 00/30] QAPI patches for 2018-03-01, no-reply, 2018/03/01
- Re: [Qemu-devel] [PULL 00/30] QAPI patches for 2018-03-01, no-reply, 2018/03/01
- Re: [Qemu-devel] [PULL 00/30] QAPI patches for 2018-03-01, no-reply, 2018/03/01