1# -*- Mode: Python -*- 2# vim: filetype=python 3# 4 5## 6# = Miscellanea 7## 8 9{ 'include': 'common.json' } 10 11## 12# @add_client: 13# 14# Allow client connections for VNC, Spice and socket based 15# character devices to be passed in to QEMU via SCM_RIGHTS. 16# 17# If the FD associated with @fdname is not a socket, the command will fail and 18# the FD will be closed. 19# 20# @protocol: protocol name. Valid names are "vnc", "spice", "@dbus-display" or 21# the name of a character device (eg. from -chardev id=XXXX) 22# 23# @fdname: file descriptor name previously passed via 'getfd' command 24# 25# @skipauth: whether to skip authentication. Only applies 26# to "vnc" and "spice" protocols 27# 28# @tls: whether to perform TLS. Only applies to the "spice" 29# protocol 30# 31# Returns: nothing on success. 32# 33# Since: 0.14 34# 35# Example: 36# 37# -> { "execute": "add_client", "arguments": { "protocol": "vnc", 38# "fdname": "myclient" } } 39# <- { "return": {} } 40# 41## 42{ 'command': 'add_client', 43 'data': { 'protocol': 'str', 'fdname': 'str', '*skipauth': 'bool', 44 '*tls': 'bool' } } 45 46## 47# @NameInfo: 48# 49# Guest name information. 50# 51# @name: The name of the guest 52# 53# Since: 0.14 54## 55{ 'struct': 'NameInfo', 'data': {'*name': 'str'} } 56 57## 58# @query-name: 59# 60# Return the name information of a guest. 61# 62# Returns: @NameInfo of the guest 63# 64# Since: 0.14 65# 66# Example: 67# 68# -> { "execute": "query-name" } 69# <- { "return": { "name": "qemu-name" } } 70# 71## 72{ 'command': 'query-name', 'returns': 'NameInfo', 'allow-preconfig': true } 73 74## 75# @IOThreadInfo: 76# 77# Information about an iothread 78# 79# @id: the identifier of the iothread 80# 81# @thread-id: ID of the underlying host thread 82# 83# @poll-max-ns: maximum polling time in ns, 0 means polling is disabled 84# (since 2.9) 85# 86# @poll-grow: how many ns will be added to polling time, 0 means that it's not 87# configured (since 2.9) 88# 89# @poll-shrink: how many ns will be removed from polling time, 0 means that 90# it's not configured (since 2.9) 91# 92# @aio-max-batch: maximum number of requests in a batch for the AIO engine, 93# 0 means that the engine will use its default (since 6.1) 94# 95# Since: 2.0 96## 97{ 'struct': 'IOThreadInfo', 98 'data': {'id': 'str', 99 'thread-id': 'int', 100 'poll-max-ns': 'int', 101 'poll-grow': 'int', 102 'poll-shrink': 'int', 103 'aio-max-batch': 'int' } } 104 105## 106# @query-iothreads: 107# 108# Returns a list of information about each iothread. 109# 110# Note: this list excludes the QEMU main loop thread, which is not declared 111# using the -object iothread command-line option. It is always the main thread 112# of the process. 113# 114# Returns: a list of @IOThreadInfo for each iothread 115# 116# Since: 2.0 117# 118# Example: 119# 120# -> { "execute": "query-iothreads" } 121# <- { "return": [ 122# { 123# "id":"iothread0", 124# "thread-id":3134 125# }, 126# { 127# "id":"iothread1", 128# "thread-id":3135 129# } 130# ] 131# } 132# 133## 134{ 'command': 'query-iothreads', 'returns': ['IOThreadInfo'], 135 'allow-preconfig': true } 136 137## 138# @stop: 139# 140# Stop all guest VCPU execution. 141# 142# Since: 0.14 143# 144# Notes: This function will succeed even if the guest is already in the stopped 145# state. In "inmigrate" state, it will ensure that the guest 146# remains paused once migration finishes, as if the -S option was 147# passed on the command line. 148# 149# Example: 150# 151# -> { "execute": "stop" } 152# <- { "return": {} } 153# 154## 155{ 'command': 'stop' } 156 157## 158# @cont: 159# 160# Resume guest VCPU execution. 161# 162# Since: 0.14 163# 164# Returns: If successful, nothing 165# 166# Notes: This command will succeed if the guest is currently running. It 167# will also succeed if the guest is in the "inmigrate" state; in 168# this case, the effect of the command is to make sure the guest 169# starts once migration finishes, removing the effect of the -S 170# command line option if it was passed. 171# 172# Example: 173# 174# -> { "execute": "cont" } 175# <- { "return": {} } 176# 177## 178{ 'command': 'cont' } 179 180## 181# @x-exit-preconfig: 182# 183# Exit from "preconfig" state 184# 185# This command makes QEMU exit the preconfig state and proceed with 186# VM initialization using configuration data provided on the command line 187# and via the QMP monitor during the preconfig state. The command is only 188# available during the preconfig state (i.e. when the --preconfig command 189# line option was in use). 190# 191# Features: 192# @unstable: This command is experimental. 193# 194# Since: 3.0 195# 196# Returns: nothing 197# 198# Example: 199# 200# -> { "execute": "x-exit-preconfig" } 201# <- { "return": {} } 202# 203## 204{ 'command': 'x-exit-preconfig', 'allow-preconfig': true, 205 'features': [ 'unstable' ] } 206 207## 208# @human-monitor-command: 209# 210# Execute a command on the human monitor and return the output. 211# 212# @command-line: the command to execute in the human monitor 213# 214# @cpu-index: The CPU to use for commands that require an implicit CPU 215# 216# Features: 217# @savevm-monitor-nodes: If present, HMP command savevm only snapshots 218# monitor-owned nodes if they have no parents. 219# This allows the use of 'savevm' with 220# -blockdev. (since 4.2) 221# 222# Returns: the output of the command as a string 223# 224# Since: 0.14 225# 226# Notes: This command only exists as a stop-gap. Its use is highly 227# discouraged. The semantics of this command are not 228# guaranteed: this means that command names, arguments and 229# responses can change or be removed at ANY time. Applications 230# that rely on long term stability guarantees should NOT 231# use this command. 232# 233# Known limitations: 234# 235# * This command is stateless, this means that commands that depend 236# on state information (such as getfd) might not work 237# 238# * Commands that prompt the user for data don't currently work 239# 240# Example: 241# 242# -> { "execute": "human-monitor-command", 243# "arguments": { "command-line": "info kvm" } } 244# <- { "return": "kvm support: enabled\r\n" } 245# 246## 247{ 'command': 'human-monitor-command', 248 'data': {'command-line': 'str', '*cpu-index': 'int'}, 249 'returns': 'str', 250 'features': [ 'savevm-monitor-nodes' ] } 251 252## 253# @getfd: 254# 255# Receive a file descriptor via SCM rights and assign it a name 256# 257# @fdname: file descriptor name 258# 259# Returns: Nothing on success 260# 261# Since: 0.14 262# 263# Notes: If @fdname already exists, the file descriptor assigned to 264# it will be closed and replaced by the received file 265# descriptor. 266# 267# The 'closefd' command can be used to explicitly close the 268# file descriptor when it is no longer needed. 269# 270# Example: 271# 272# -> { "execute": "getfd", "arguments": { "fdname": "fd1" } } 273# <- { "return": {} } 274# 275## 276{ 'command': 'getfd', 'data': {'fdname': 'str'} } 277 278## 279# @closefd: 280# 281# Close a file descriptor previously passed via SCM rights 282# 283# @fdname: file descriptor name 284# 285# Returns: Nothing on success 286# 287# Since: 0.14 288# 289# Example: 290# 291# -> { "execute": "closefd", "arguments": { "fdname": "fd1" } } 292# <- { "return": {} } 293# 294## 295{ 'command': 'closefd', 'data': {'fdname': 'str'} } 296 297## 298# @AddfdInfo: 299# 300# Information about a file descriptor that was added to an fd set. 301# 302# @fdset-id: The ID of the fd set that @fd was added to. 303# 304# @fd: The file descriptor that was received via SCM rights and 305# added to the fd set. 306# 307# Since: 1.2 308## 309{ 'struct': 'AddfdInfo', 'data': {'fdset-id': 'int', 'fd': 'int'} } 310 311## 312# @add-fd: 313# 314# Add a file descriptor, that was passed via SCM rights, to an fd set. 315# 316# @fdset-id: The ID of the fd set to add the file descriptor to. 317# 318# @opaque: A free-form string that can be used to describe the fd. 319# 320# Returns: - @AddfdInfo on success 321# - If file descriptor was not received, FdNotSupplied 322# - If @fdset-id is a negative value, InvalidParameterValue 323# 324# Notes: The list of fd sets is shared by all monitor connections. 325# 326# If @fdset-id is not specified, a new fd set will be created. 327# 328# Since: 1.2 329# 330# Example: 331# 332# -> { "execute": "add-fd", "arguments": { "fdset-id": 1 } } 333# <- { "return": { "fdset-id": 1, "fd": 3 } } 334# 335## 336{ 'command': 'add-fd', 337 'data': { '*fdset-id': 'int', 338 '*opaque': 'str' }, 339 'returns': 'AddfdInfo' } 340 341## 342# @remove-fd: 343# 344# Remove a file descriptor from an fd set. 345# 346# @fdset-id: The ID of the fd set that the file descriptor belongs to. 347# 348# @fd: The file descriptor that is to be removed. 349# 350# Returns: - Nothing on success 351# - If @fdset-id or @fd is not found, FdNotFound 352# 353# Since: 1.2 354# 355# Notes: The list of fd sets is shared by all monitor connections. 356# 357# If @fd is not specified, all file descriptors in @fdset-id 358# will be removed. 359# 360# Example: 361# 362# -> { "execute": "remove-fd", "arguments": { "fdset-id": 1, "fd": 3 } } 363# <- { "return": {} } 364# 365## 366{ 'command': 'remove-fd', 'data': {'fdset-id': 'int', '*fd': 'int'} } 367 368## 369# @FdsetFdInfo: 370# 371# Information about a file descriptor that belongs to an fd set. 372# 373# @fd: The file descriptor value. 374# 375# @opaque: A free-form string that can be used to describe the fd. 376# 377# Since: 1.2 378## 379{ 'struct': 'FdsetFdInfo', 380 'data': {'fd': 'int', '*opaque': 'str'} } 381 382## 383# @FdsetInfo: 384# 385# Information about an fd set. 386# 387# @fdset-id: The ID of the fd set. 388# 389# @fds: A list of file descriptors that belong to this fd set. 390# 391# Since: 1.2 392## 393{ 'struct': 'FdsetInfo', 394 'data': {'fdset-id': 'int', 'fds': ['FdsetFdInfo']} } 395 396## 397# @query-fdsets: 398# 399# Return information describing all fd sets. 400# 401# Returns: A list of @FdsetInfo 402# 403# Since: 1.2 404# 405# Note: The list of fd sets is shared by all monitor connections. 406# 407# Example: 408# 409# -> { "execute": "query-fdsets" } 410# <- { "return": [ 411# { 412# "fds": [ 413# { 414# "fd": 30, 415# "opaque": "rdonly:/path/to/file" 416# }, 417# { 418# "fd": 24, 419# "opaque": "rdwr:/path/to/file" 420# } 421# ], 422# "fdset-id": 1 423# }, 424# { 425# "fds": [ 426# { 427# "fd": 28 428# }, 429# { 430# "fd": 29 431# } 432# ], 433# "fdset-id": 0 434# } 435# ] 436# } 437# 438## 439{ 'command': 'query-fdsets', 'returns': ['FdsetInfo'] } 440 441## 442# @CommandLineParameterType: 443# 444# Possible types for an option parameter. 445# 446# @string: accepts a character string 447# 448# @boolean: accepts "on" or "off" 449# 450# @number: accepts a number 451# 452# @size: accepts a number followed by an optional suffix (K)ilo, 453# (M)ega, (G)iga, (T)era 454# 455# Since: 1.5 456## 457{ 'enum': 'CommandLineParameterType', 458 'data': ['string', 'boolean', 'number', 'size'] } 459 460## 461# @CommandLineParameterInfo: 462# 463# Details about a single parameter of a command line option. 464# 465# @name: parameter name 466# 467# @type: parameter @CommandLineParameterType 468# 469# @help: human readable text string, not suitable for parsing. 470# 471# @default: default value string (since 2.1) 472# 473# Since: 1.5 474## 475{ 'struct': 'CommandLineParameterInfo', 476 'data': { 'name': 'str', 477 'type': 'CommandLineParameterType', 478 '*help': 'str', 479 '*default': 'str' } } 480 481## 482# @CommandLineOptionInfo: 483# 484# Details about a command line option, including its list of parameter details 485# 486# @option: option name 487# 488# @parameters: an array of @CommandLineParameterInfo 489# 490# Since: 1.5 491## 492{ 'struct': 'CommandLineOptionInfo', 493 'data': { 'option': 'str', 'parameters': ['CommandLineParameterInfo'] } } 494 495## 496# @query-command-line-options: 497# 498# Query command line option schema. 499# 500# @option: option name 501# 502# Returns: list of @CommandLineOptionInfo for all options (or for the given 503# @option). Returns an error if the given @option doesn't exist. 504# 505# Since: 1.5 506# 507# Example: 508# 509# -> { "execute": "query-command-line-options", 510# "arguments": { "option": "option-rom" } } 511# <- { "return": [ 512# { 513# "parameters": [ 514# { 515# "name": "romfile", 516# "type": "string" 517# }, 518# { 519# "name": "bootindex", 520# "type": "number" 521# } 522# ], 523# "option": "option-rom" 524# } 525# ] 526# } 527# 528## 529{'command': 'query-command-line-options', 530 'data': { '*option': 'str' }, 531 'returns': ['CommandLineOptionInfo'], 532 'allow-preconfig': true } 533 534## 535# @RTC_CHANGE: 536# 537# Emitted when the guest changes the RTC time. 538# 539# @offset: offset in seconds between base RTC clock (as specified 540# by -rtc base), and new RTC clock value 541# 542# @qom-path: path to the RTC object in the QOM tree 543# 544# Note: This event is rate-limited. 545# It is not guaranteed that the RTC in the system implements 546# this event, or even that the system has an RTC at all. 547# 548# Since: 0.13 549# 550# Example: 551# 552# <- { "event": "RTC_CHANGE", 553# "data": { "offset": 78 }, 554# "timestamp": { "seconds": 1267020223, "microseconds": 435656 } } 555# 556## 557{ 'event': 'RTC_CHANGE', 558 'data': { 'offset': 'int', 'qom-path': 'str' } } 559 560## 561# @VFU_CLIENT_HANGUP: 562# 563# Emitted when the client of a TYPE_VFIO_USER_SERVER closes the 564# communication channel 565# 566# @vfu-id: ID of the TYPE_VFIO_USER_SERVER object. It is the last component 567# of @vfu-qom-path referenced below 568# 569# @vfu-qom-path: path to the TYPE_VFIO_USER_SERVER object in the QOM tree 570# 571# @dev-id: ID of attached PCI device 572# 573# @dev-qom-path: path to attached PCI device in the QOM tree 574# 575# Since: 7.1 576# 577# Example: 578# 579# <- { "event": "VFU_CLIENT_HANGUP", 580# "data": { "vfu-id": "vfu1", 581# "vfu-qom-path": "/objects/vfu1", 582# "dev-id": "sas1", 583# "dev-qom-path": "/machine/peripheral/sas1" }, 584# "timestamp": { "seconds": 1265044230, "microseconds": 450486 } } 585# 586## 587{ 'event': 'VFU_CLIENT_HANGUP', 588 'data': { 'vfu-id': 'str', 'vfu-qom-path': 'str', 589 'dev-id': 'str', 'dev-qom-path': 'str' } } 590