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