jcs.org / qemu
qemu with hax to log dma reads & writes jcs.org/2018/11/12/vfio
fork atom

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>

authored by

Markus Armbruster and committed by
Eric Blake bb46af41 bfe873e9

+11 -17
+9 -16
docs/devel/writing-qmp-commands.txt
··· 36 36 For all the examples in the next sections, the test setup is the same and is 37 37 shown here. 38 38 39 - First, QEMU should be started as: 39 + First, QEMU should be started like this: 40 40 41 - # /path/to/your/source/qemu [...] \ 41 + # qemu-system-TARGET [...] \ 42 42 -chardev socket,id=qmp,port=4444,host=localhost,server \ 43 43 -mon chardev=qmp,mode=control,pretty=on 44 44 ··· 179 179 } 180 180 } 181 181 182 - You should see "Hello, world" and "we love qemu" in the terminal running qemu, 182 + You should see "Hello, world" and "We love qemu" in the terminal running qemu, 183 183 if you don't see these strings, then something went wrong. 184 184 185 185 === Errors === ··· 221 221 } 222 222 } 223 223 224 - As a general rule, all QMP errors should use ERROR_CLASS_GENERIC_ERROR 225 - (done by default when using error_setg()). There are two exceptions to 226 - this rule: 224 + Note that error_setg() produces a "GenericError" class. In general, 225 + all QMP errors should have that error class. There are two exceptions 226 + to this rule: 227 227 228 - 1. A non-generic ErrorClass value exists* for the failure you want to report 229 - (eg. DeviceNotFound) 228 + 1. To support a management application's need to recognize a specific 229 + error for special handling 230 230 231 - 2. Management applications have to take special action on the failure you 232 - want to report, hence you have to add a new ErrorClass value so that they 233 - can check for it 231 + 2. Backward compatibility 234 232 235 233 If the failure you want to report falls into one of the two cases above, 236 234 use error_set() with a second argument of an ErrorClass value. 237 235 238 - * All existing ErrorClass values are defined in the qapi-schema.json file 239 - 240 236 === Command Documentation === 241 237 242 238 There's only one step missing to make "hello-world"'s implementation complete, 243 239 and that's its documentation in the schema file. 244 - 245 - This is very important. No QMP command will be accepted in QEMU without proper 246 - documentation. 247 240 248 241 There are many examples of such documentation in the schema file already, but 249 242 here goes "hello-world"'s new entry for qapi/misc.json:
+2 -1
docs/interop/qmp-intro.txt
··· 78 78 } 79 79 } 80 80 81 - Please, refer to the qapi-schema.json file for a complete command reference. 81 + Please refer to docs/interop/qemu-qmp-ref.* for a complete command 82 + reference, generated from qapi-schema.json. 82 83 83 84 QMP wiki page 84 85 -------------