mirror of
https://github.com/qemu/qemu.git
synced 2024-12-17 09:13:44 +08:00
docs/devel: add example of command returning unstructured text
This illustrates how to add a QMP command returning unstructured text, following the guidelines added in the previous patch. The example uses a simplified version of 'info roms'. Reviewed-by: Eric Blake <eblake@redhat.com> Signed-off-by: Daniel P. Berrangé <berrange@redhat.com>
This commit is contained in:
parent
f2de406f29
commit
a45cfcbb01
@ -374,7 +374,9 @@ best practices. An example where this approach is taken is the QMP
|
||||
command "x-query-registers". This returns a formatted dump of the
|
||||
architecture specific CPU state. The way the data is formatted varies
|
||||
across QEMU targets, is liable to change over time, and is only
|
||||
intended to be consumed as an opaque string by machines.
|
||||
intended to be consumed as an opaque string by machines. Refer to the
|
||||
`Writing a debugging aid returning unstructured text`_ section for
|
||||
an illustration.
|
||||
|
||||
User Defined Types
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
@ -642,3 +644,100 @@ has to traverse the list, it's shown below for reference::
|
||||
|
||||
qapi_free_TimerAlarmMethodList(method_list);
|
||||
}
|
||||
|
||||
Writing a debugging aid returning unstructured text
|
||||
---------------------------------------------------
|
||||
|
||||
As discussed in section `Modelling data in QAPI`_, it is required that
|
||||
commands expecting machine usage be using fine-grained QAPI data types.
|
||||
The exception to this rule applies when the command is solely intended
|
||||
as a debugging aid and allows for returning unstructured text. This is
|
||||
commonly needed for query commands that report aspects of QEMU's
|
||||
internal state that are useful to human operators.
|
||||
|
||||
In this example we will consider a simplified variant of the HMP
|
||||
command ``info roms``. Following the earlier rules, this command will
|
||||
need to live under the ``x-`` name prefix, so its QMP implementation
|
||||
will be called ``x-query-roms``. It will have no parameters and will
|
||||
return a single text string::
|
||||
|
||||
{ 'struct': 'HumanReadableText',
|
||||
'data': { 'human-readable-text': 'str' } }
|
||||
|
||||
{ 'command': 'x-query-roms',
|
||||
'returns': 'HumanReadableText' }
|
||||
|
||||
The ``HumanReadableText`` struct is intended to be used for all
|
||||
commands, under the ``x-`` name prefix that are returning unstructured
|
||||
text targetted at humans. It should never be used for commands outside
|
||||
the ``x-`` name prefix, as those should be using structured QAPI types.
|
||||
|
||||
Implementing the QMP command
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
The QMP implementation will typically involve creating a ``GString``
|
||||
object and printing formatted data into it::
|
||||
|
||||
HumanReadableText *qmp_x_query_roms(Error **errp)
|
||||
{
|
||||
g_autoptr(GString) buf = g_string_new("");
|
||||
Rom *rom;
|
||||
|
||||
QTAILQ_FOREACH(rom, &roms, next) {
|
||||
g_string_append_printf("%s size=0x%06zx name=\"%s\"\n",
|
||||
memory_region_name(rom->mr),
|
||||
rom->romsize,
|
||||
rom->name);
|
||||
}
|
||||
|
||||
return human_readable_text_from_str(buf);
|
||||
}
|
||||
|
||||
|
||||
Implementing the HMP command
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Now that the QMP command is in place, we can also make it available in
|
||||
the human monitor (HMP) as shown in previous examples. The HMP
|
||||
implementations will all look fairly similar, as all they need do is
|
||||
invoke the QMP command and then print the resulting text or error
|
||||
message. Here's the implementation of the "info roms" HMP command::
|
||||
|
||||
void hmp_info_roms(Monitor *mon, const QDict *qdict)
|
||||
{
|
||||
Error err = NULL;
|
||||
g_autoptr(HumanReadableText) info = qmp_x_query_roms(&err);
|
||||
|
||||
if (hmp_handle_error(mon, err)) {
|
||||
return;
|
||||
}
|
||||
monitor_printf(mon, "%s", info->human_readable_text);
|
||||
}
|
||||
|
||||
Also, you have to add the function's prototype to the hmp.h file.
|
||||
|
||||
There's one last step to actually make the command available to
|
||||
monitor users, we should add it to the hmp-commands-info.hx file::
|
||||
|
||||
{
|
||||
.name = "roms",
|
||||
.args_type = "",
|
||||
.params = "",
|
||||
.help = "show roms",
|
||||
.cmd = hmp_info_roms,
|
||||
},
|
||||
|
||||
The case of writing a HMP info handler that calls a no-parameter QMP query
|
||||
command is quite common. To simplify the implementation there is a general
|
||||
purpose HMP info handler for this scenario. All that is required to expose
|
||||
a no-parameter QMP query command via HMP is to declare it using the
|
||||
'.cmd_info_hrt' field to point to the QMP handler, and leave the '.cmd'
|
||||
field NULL::
|
||||
|
||||
{
|
||||
.name = "roms",
|
||||
.args_type = "",
|
||||
.params = "",
|
||||
.help = "show roms",
|
||||
.cmd_info_hrt = qmp_x_query_roms,
|
||||
},
|
||||
|
Loading…
Reference in New Issue
Block a user