docs/devel/writing-monitor-commands.rst

7 This document doesn't discuss QMP protocol level details, nor does it dive
29 1. Define the command and any types it needs in the appropriate QAPI
33    the command should be exported by some QEMU subsystem. But it can also be
39    done if it does make sense to have the functionality in HMP. The HMP command
101 command carries some meaningful action in QEMU but here it will just print
104 Our command will be called "hello-world". It takes no arguments, nor does it
118 The "command" keyword defines a new QMP command. It instructs QAPI to
123 earlier, it's preferable for commands to live in QEMU subsystems. But
137 3. It takes an "Error \*\*" argument. This is required. Later we will see how to
141 5. Printing to the terminal is discouraged for QMP commands, we do it here
142    because it's the easiest way to demonstrate a QMP command
144 You're done. Now build QEMU, run it as suggested in the "Testing" section,
150 you don't see it then something went wrong.
173 Notice the new 'data' member in the schema. It specifies an argument
175 'int'.  Also notice the asterisk, it's used to mark the argument
203 Time to test our new version of the "hello-world" command. Build QEMU, run it as
229 it does contain it, we want the "hello-world" command to return an error::
248 Let's test the example above. Build QEMU, run it as defined in the "Testing"
278 Now that the QMP command is in place, we can also make it available in the human
297 Add it to monitor/hmp-cmds.c.  Also, add its prototype to
314 we should add it to the hmp-commands.hx file::
330 command. It might be instructive to check the command's documentation with
354 a field appears to need parsing, then it should be split into separate
361 data, it is not expected that machines will need to parse the result.
363 be justified by the potential benefit. In such cases, it is permitted
365 however, it is mandatory for the command to be marked unstable.
381 more information about it, please check the "-option-rom" command-line
418 Notice the "returns" keyword. As its name suggests, it's used to define the
424 It's time to implement the qmp_query_option_roms() function.  Add to
451 2. Type OptionRomInfoList is also generated.  It's a singly linked
458    generates a function to free its types and it cannot distinguish
461    member, it comes with a 'has_bootindex' member that needs to be set
464 Time to test the new command. Build QEMU, run it as described in the "Testing"
505 It's important to notice that hmp_info_option_roms() calls
511 string, then you should g_free() to free it.
515 errors; you could instead pass it &error_abort then.
539 As discussed in section `Modelling data in QAPI`_, it is required that
547 ``x-query-roms`` in qapi/machine.json.  It has no parameters and
568 struct with a string member. It is intended to be used for all
579 object and printing formatted data into it, like this::
596 The actual implementation emits more information.  You can find it in
603 Now that the QMP command is in place, we can also make it available in
623 monitor users, we should add it to the hmp-commands-info.hx file::
636 a no-parameter QMP query command via HMP is to declare it using the