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