into the QAPI framework implementation.
For an in-depth introduction to the QAPI framework, please refer to
-docs/qapi-code-gen.txt. For documentation about the QMP protocol,
-start with docs/qmp-intro.txt.
+docs/devel/qapi-code-gen.txt. For documentation about the QMP protocol,
+start with docs/interop/qmp-intro.txt.
== Overview ==
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
- added to the qmp.c file
+ added to the monitor/qmp-cmds.c file
3. At this point the command can be tested under the QMP protocol
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
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' }
The next step is to write the "hello-world" implementation. As explained
earlier, it's preferable for commands to live in QEMU subsystems. But
-"hello-world" doesn't pertain to any, so we put its implementation in qmp.c:
+"hello-world" doesn't pertain to any, so we put its implementation in
+monitor/qmp-cmds.c:
void qmp_hello_world(Error **errp)
{
stands for "string". The QAPI also supports integers, booleans, enumerations
and user defined types.
-Now, let's update our C implementation in qmp.c:
+Now, let's update our C implementation in monitor/qmp-cmds.c:
void qmp_hello_world(bool has_message, const char *message, Error **errp)
{
}
}
-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 ===
}
}
-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
With the introduction of the QAPI, HMP commands make QMP calls. Most of the
time HMP commands are simple wrappers. All HMP commands implementation exist in
-the hmp.c file.
+the monitor/hmp-cmds.c file.
Here's the implementation of the "hello-world" HMP command:
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:
Another important detail is that HMP's "info" commands don't go into the
hmp-commands.hx. Instead, they go into the info_cmds[] table, which is defined
-in the monitor.c file. The entry for the "info alarmclock" follows:
+in the monitor/misc.c file. The entry for the "info alarmclock" follows:
{
.name = "alarmclock",
projects / mirror_qemu.git / blobdiff