Kevin Wolf | fa4dcf5 | 2020-01-29 11:22:37 +0100 | [diff] [blame] | 1 | # -*- Mode: Python -*- |
Andrea Bolognani | f7160f3 | 2020-07-29 20:50:24 +0200 | [diff] [blame] | 2 | # vim: filetype=python |
Kevin Wolf | fa4dcf5 | 2020-01-29 11:22:37 +0100 | [diff] [blame] | 3 | # |
| 4 | |
| 5 | ## |
| 6 | # = QMP monitor control |
| 7 | ## |
| 8 | |
| 9 | ## |
| 10 | # @qmp_capabilities: |
| 11 | # |
| 12 | # Enable QMP capabilities. |
| 13 | # |
Kevin Wolf | fa4dcf5 | 2020-01-29 11:22:37 +0100 | [diff] [blame] | 14 | # @enable: An optional list of QMPCapability values to enable. The |
Markus Armbruster | a937b6a | 2023-04-28 12:54:29 +0200 | [diff] [blame] | 15 | # client must not enable any capability that is not mentioned in |
| 16 | # the QMP greeting message. If the field is not provided, it |
| 17 | # means no QMP capabilities will be enabled. (since 2.12) |
Kevin Wolf | fa4dcf5 | 2020-01-29 11:22:37 +0100 | [diff] [blame] | 18 | # |
John Snow | 14b48aa | 2024-07-16 22:13:08 -0400 | [diff] [blame] | 19 | # .. qmp-example:: |
Kevin Wolf | fa4dcf5 | 2020-01-29 11:22:37 +0100 | [diff] [blame] | 20 | # |
Markus Armbruster | d23055b | 2024-02-16 15:58:34 +0100 | [diff] [blame] | 21 | # -> { "execute": "qmp_capabilities", |
| 22 | # "arguments": { "enable": [ "oob" ] } } |
| 23 | # <- { "return": {} } |
Kevin Wolf | fa4dcf5 | 2020-01-29 11:22:37 +0100 | [diff] [blame] | 24 | # |
Markus Armbruster | 01bed0f | 2024-07-29 08:52:20 +0200 | [diff] [blame] | 25 | # .. note:: This command is valid exactly when first connecting: it |
| 26 | # must be issued before any other command will be accepted, and |
| 27 | # will fail once the monitor is accepting other commands. (see |
| 28 | # :doc:`/interop/qmp-spec`) |
Kevin Wolf | fa4dcf5 | 2020-01-29 11:22:37 +0100 | [diff] [blame] | 29 | # |
Markus Armbruster | 01bed0f | 2024-07-29 08:52:20 +0200 | [diff] [blame] | 30 | # .. note:: The QMP client needs to explicitly enable QMP |
| 31 | # capabilities, otherwise all the QMP capabilities will be turned |
| 32 | # off by default. |
Kevin Wolf | fa4dcf5 | 2020-01-29 11:22:37 +0100 | [diff] [blame] | 33 | # |
| 34 | # Since: 0.13 |
Kevin Wolf | fa4dcf5 | 2020-01-29 11:22:37 +0100 | [diff] [blame] | 35 | ## |
| 36 | { 'command': 'qmp_capabilities', |
| 37 | 'data': { '*enable': [ 'QMPCapability' ] }, |
| 38 | 'allow-preconfig': true } |
| 39 | |
| 40 | ## |
| 41 | # @QMPCapability: |
| 42 | # |
| 43 | # Enumeration of capabilities to be advertised during initial client |
| 44 | # connection, used for agreeing on particular QMP extension behaviors. |
| 45 | # |
Markus Armbruster | a937b6a | 2023-04-28 12:54:29 +0200 | [diff] [blame] | 46 | # @oob: QMP ability to support out-of-band requests. (Please refer to |
Peter Maydell | d565725 | 2023-05-15 17:22:43 +0100 | [diff] [blame] | 47 | # qmp-spec.rst for more information on OOB) |
Kevin Wolf | fa4dcf5 | 2020-01-29 11:22:37 +0100 | [diff] [blame] | 48 | # |
| 49 | # Since: 2.12 |
Kevin Wolf | fa4dcf5 | 2020-01-29 11:22:37 +0100 | [diff] [blame] | 50 | ## |
| 51 | { 'enum': 'QMPCapability', |
| 52 | 'data': [ 'oob' ] } |
| 53 | |
| 54 | ## |
| 55 | # @VersionTriple: |
| 56 | # |
| 57 | # A three-part version number. |
| 58 | # |
| 59 | # @major: The major version number. |
| 60 | # |
| 61 | # @minor: The minor version number. |
| 62 | # |
| 63 | # @micro: The micro version number. |
| 64 | # |
| 65 | # Since: 2.4 |
| 66 | ## |
| 67 | { 'struct': 'VersionTriple', |
| 68 | 'data': {'major': 'int', 'minor': 'int', 'micro': 'int'} } |
| 69 | |
Kevin Wolf | fa4dcf5 | 2020-01-29 11:22:37 +0100 | [diff] [blame] | 70 | ## |
| 71 | # @VersionInfo: |
| 72 | # |
| 73 | # A description of QEMU's version. |
| 74 | # |
Markus Armbruster | a937b6a | 2023-04-28 12:54:29 +0200 | [diff] [blame] | 75 | # @qemu: The version of QEMU. By current convention, a micro version |
| 76 | # of 50 signifies a development branch. A micro version greater |
| 77 | # than or equal to 90 signifies a release candidate for the next |
| 78 | # minor version. A micro version of less than 50 signifies a |
| 79 | # stable release. |
Kevin Wolf | fa4dcf5 | 2020-01-29 11:22:37 +0100 | [diff] [blame] | 80 | # |
Markus Armbruster | a937b6a | 2023-04-28 12:54:29 +0200 | [diff] [blame] | 81 | # @package: QEMU will always set this field to an empty string. |
| 82 | # Downstream versions of QEMU should set this to a non-empty |
| 83 | # string. The exact format depends on the downstream however it |
| 84 | # highly recommended that a unique name is used. |
Kevin Wolf | fa4dcf5 | 2020-01-29 11:22:37 +0100 | [diff] [blame] | 85 | # |
Markus Armbruster | 9bc6e89 | 2020-11-18 07:41:58 +0100 | [diff] [blame] | 86 | # Since: 0.14 |
Kevin Wolf | fa4dcf5 | 2020-01-29 11:22:37 +0100 | [diff] [blame] | 87 | ## |
| 88 | { 'struct': 'VersionInfo', |
| 89 | 'data': {'qemu': 'VersionTriple', 'package': 'str'} } |
| 90 | |
| 91 | ## |
| 92 | # @query-version: |
| 93 | # |
| 94 | # Returns the current version of QEMU. |
| 95 | # |
Markus Armbruster | a937b6a | 2023-04-28 12:54:29 +0200 | [diff] [blame] | 96 | # Returns: A @VersionInfo object describing the current version of |
| 97 | # QEMU. |
Kevin Wolf | fa4dcf5 | 2020-01-29 11:22:37 +0100 | [diff] [blame] | 98 | # |
Markus Armbruster | 9bc6e89 | 2020-11-18 07:41:58 +0100 | [diff] [blame] | 99 | # Since: 0.14 |
Kevin Wolf | fa4dcf5 | 2020-01-29 11:22:37 +0100 | [diff] [blame] | 100 | # |
John Snow | 14b48aa | 2024-07-16 22:13:08 -0400 | [diff] [blame] | 101 | # .. qmp-example:: |
Kevin Wolf | fa4dcf5 | 2020-01-29 11:22:37 +0100 | [diff] [blame] | 102 | # |
Markus Armbruster | d23055b | 2024-02-16 15:58:34 +0100 | [diff] [blame] | 103 | # -> { "execute": "query-version" } |
| 104 | # <- { |
| 105 | # "return":{ |
| 106 | # "qemu":{ |
| 107 | # "major":0, |
| 108 | # "minor":11, |
| 109 | # "micro":5 |
| 110 | # }, |
| 111 | # "package":"" |
| 112 | # } |
| 113 | # } |
Kevin Wolf | fa4dcf5 | 2020-01-29 11:22:37 +0100 | [diff] [blame] | 114 | ## |
| 115 | { 'command': 'query-version', 'returns': 'VersionInfo', |
| 116 | 'allow-preconfig': true } |
| 117 | |
| 118 | ## |
| 119 | # @CommandInfo: |
| 120 | # |
| 121 | # Information about a QMP command |
| 122 | # |
| 123 | # @name: The command name |
| 124 | # |
Markus Armbruster | 9bc6e89 | 2020-11-18 07:41:58 +0100 | [diff] [blame] | 125 | # Since: 0.14 |
Kevin Wolf | fa4dcf5 | 2020-01-29 11:22:37 +0100 | [diff] [blame] | 126 | ## |
| 127 | { 'struct': 'CommandInfo', 'data': {'name': 'str'} } |
| 128 | |
| 129 | ## |
| 130 | # @query-commands: |
| 131 | # |
| 132 | # Return a list of supported QMP commands by this server |
| 133 | # |
| 134 | # Returns: A list of @CommandInfo for all supported commands |
| 135 | # |
Markus Armbruster | 9bc6e89 | 2020-11-18 07:41:58 +0100 | [diff] [blame] | 136 | # Since: 0.14 |
Kevin Wolf | fa4dcf5 | 2020-01-29 11:22:37 +0100 | [diff] [blame] | 137 | # |
John Snow | 14b48aa | 2024-07-16 22:13:08 -0400 | [diff] [blame] | 138 | # .. qmp-example:: |
Kevin Wolf | fa4dcf5 | 2020-01-29 11:22:37 +0100 | [diff] [blame] | 139 | # |
Markus Armbruster | d23055b | 2024-02-16 15:58:34 +0100 | [diff] [blame] | 140 | # -> { "execute": "query-commands" } |
| 141 | # <- { |
| 142 | # "return":[ |
| 143 | # { |
| 144 | # "name":"query-balloon" |
| 145 | # }, |
| 146 | # { |
| 147 | # "name":"system_powerdown" |
John Snow | 9f2b848 | 2024-06-26 18:21:14 -0400 | [diff] [blame] | 148 | # }, |
| 149 | # ... |
Markus Armbruster | d23055b | 2024-02-16 15:58:34 +0100 | [diff] [blame] | 150 | # ] |
| 151 | # } |
Kevin Wolf | fa4dcf5 | 2020-01-29 11:22:37 +0100 | [diff] [blame] | 152 | # |
John Snow | d461c27 | 2024-06-26 18:21:16 -0400 | [diff] [blame] | 153 | # This example has been shortened as the real response is too long. |
Kevin Wolf | fa4dcf5 | 2020-01-29 11:22:37 +0100 | [diff] [blame] | 154 | ## |
| 155 | { 'command': 'query-commands', 'returns': ['CommandInfo'], |
| 156 | 'allow-preconfig': true } |
| 157 | |
| 158 | ## |
Kevin Wolf | fa4dcf5 | 2020-01-29 11:22:37 +0100 | [diff] [blame] | 159 | # @quit: |
| 160 | # |
Markus Armbruster | a937b6a | 2023-04-28 12:54:29 +0200 | [diff] [blame] | 161 | # This command will cause the QEMU process to exit gracefully. While |
| 162 | # every attempt is made to send the QMP response before terminating, |
| 163 | # this is not guaranteed. When using this interface, a premature EOF |
| 164 | # would not be unexpected. |
Kevin Wolf | fa4dcf5 | 2020-01-29 11:22:37 +0100 | [diff] [blame] | 165 | # |
Markus Armbruster | 9bc6e89 | 2020-11-18 07:41:58 +0100 | [diff] [blame] | 166 | # Since: 0.14 |
Kevin Wolf | fa4dcf5 | 2020-01-29 11:22:37 +0100 | [diff] [blame] | 167 | # |
John Snow | 14b48aa | 2024-07-16 22:13:08 -0400 | [diff] [blame] | 168 | # .. qmp-example:: |
Kevin Wolf | fa4dcf5 | 2020-01-29 11:22:37 +0100 | [diff] [blame] | 169 | # |
Markus Armbruster | d23055b | 2024-02-16 15:58:34 +0100 | [diff] [blame] | 170 | # -> { "execute": "quit" } |
| 171 | # <- { "return": {} } |
Kevin Wolf | fa4dcf5 | 2020-01-29 11:22:37 +0100 | [diff] [blame] | 172 | ## |
Paolo Bonzini | ebe3444 | 2020-10-27 06:56:32 -0400 | [diff] [blame] | 173 | { 'command': 'quit', |
| 174 | 'allow-preconfig': true } |
Kevin Wolf | f209872 | 2020-02-24 15:30:04 +0100 | [diff] [blame] | 175 | |
| 176 | ## |
| 177 | # @MonitorMode: |
| 178 | # |
| 179 | # An enumeration of monitor modes. |
| 180 | # |
| 181 | # @readline: HMP monitor (human-oriented command line interface) |
| 182 | # |
| 183 | # @control: QMP monitor (JSON-based machine interface) |
| 184 | # |
| 185 | # Since: 5.0 |
| 186 | ## |
| 187 | { 'enum': 'MonitorMode', 'data': [ 'readline', 'control' ] } |
| 188 | |
| 189 | ## |
| 190 | # @MonitorOptions: |
| 191 | # |
| 192 | # Options to be used for adding a new monitor. |
| 193 | # |
Andrea Bolognani | c0ac533 | 2022-05-03 09:37:36 +0200 | [diff] [blame] | 194 | # @id: Name of the monitor |
Kevin Wolf | f209872 | 2020-02-24 15:30:04 +0100 | [diff] [blame] | 195 | # |
Andrea Bolognani | c0ac533 | 2022-05-03 09:37:36 +0200 | [diff] [blame] | 196 | # @mode: Selects the monitor mode (default: readline in the system |
Markus Armbruster | a937b6a | 2023-04-28 12:54:29 +0200 | [diff] [blame] | 197 | # emulator, control in qemu-storage-daemon) |
Kevin Wolf | f209872 | 2020-02-24 15:30:04 +0100 | [diff] [blame] | 198 | # |
Andrea Bolognani | c0ac533 | 2022-05-03 09:37:36 +0200 | [diff] [blame] | 199 | # @pretty: Enables pretty printing (QMP only) |
Kevin Wolf | f209872 | 2020-02-24 15:30:04 +0100 | [diff] [blame] | 200 | # |
Andrea Bolognani | c0ac533 | 2022-05-03 09:37:36 +0200 | [diff] [blame] | 201 | # @chardev: Name of a character device to expose the monitor on |
Kevin Wolf | f209872 | 2020-02-24 15:30:04 +0100 | [diff] [blame] | 202 | # |
| 203 | # Since: 5.0 |
| 204 | ## |
| 205 | { 'struct': 'MonitorOptions', |
| 206 | 'data': { |
| 207 | '*id': 'str', |
| 208 | '*mode': 'MonitorMode', |
| 209 | '*pretty': 'bool', |
| 210 | 'chardev': 'str' |
| 211 | } } |