diff options
Diffstat (limited to 'docs/devel/writing-qmp-commands.txt')
| -rw-r--r-- | docs/devel/writing-qmp-commands.txt | 39 |
1 files changed, 16 insertions, 23 deletions
diff --git a/docs/devel/writing-qmp-commands.txt b/docs/devel/writing-qmp-commands.txt index 4f5b24c0c4..9dfc62bf5a 100644 --- a/docs/devel/writing-qmp-commands.txt +++ b/docs/devel/writing-qmp-commands.txt @@ -15,8 +15,8 @@ start with docs/interop/qmp-intro.txt. Generally speaking, the following steps should be taken in order to write a new QMP command. -1. Write the command's and type(s) specification in the QAPI schema file - (qapi-schema.json in the root source directory) +1. Define the command and any types it needs in the appropriate QAPI + schema module. 2. Write the QMP command itself, which is a regular C function. Preferably, the command should be exported by some QEMU subsystem. But it can also be @@ -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 @@ -88,8 +88,9 @@ command carries some meaningful action in QEMU but here it will just print Our command will be called "hello-world". It takes no arguments, nor does it return any data. -The first step is to add the following line to the bottom of the -qapi-schema.json file: +The first step is defining the command in the appropriate QAPI schema +module. We pick module qapi/misc.json, and add the following line at +the bottom: { 'command': 'hello-world' } @@ -178,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 === @@ -220,32 +221,25 @@ 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 the qapi-schema.json file: +here goes "hello-world"'s new entry for qapi/misc.json: ## # @hello-world @@ -425,8 +419,7 @@ There are a number of things to be noticed: allocated by the implementation. This is so because the QAPI also generates a function to free its types and it cannot distinguish between dynamically or statically allocated strings -6. You have to include the "qmp-commands.h" header file in qemu-timer.c, - otherwise qemu won't build +6. You have to include "qapi/qapi-commands-misc.h" in qemu-timer.c Time to test the new command. Build qemu, run it as described in the "Testing" section and try this: |