qapi/misc.json

   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 # @protocol: protocol name. Valid names are "vnc", "spice" or the
  18 #            name of a character device (eg. from -chardev id=XXXX)
  19 #
  20 # @fdname: file descriptor name previously passed via 'getfd' command
  21 #
  22 # @skipauth: whether to skip authentication. Only applies
  23 #            to "vnc" and "spice" protocols
  24 #
  25 # @tls: whether to perform TLS. Only applies to the "spice"
  26 #       protocol
  27 #
  28 # Returns: nothing on success.
  29 #
  30 # Since: 0.14.0
  31 #
  32 # Example:
  33 #
  34 # -> { "execute": "add_client", "arguments": { "protocol": "vnc",
  35 #                                              "fdname": "myclient" } }
  36 # <- { "return": {} }
  37 #
  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.0
  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.0
  62 #
  63 # Example:
  64 #
  65 # -> { "execute": "query-name" }
  66 # <- { "return": { "name": "qemu-name" } }
  67 #
  68 ##
  69 { 'command': 'query-name', 'returns': 'NameInfo', 'allow-preconfig': true }
  70
  71 ##
  72 # @KvmInfo:
  73 #
  74 # Information about support for KVM acceleration
  75 #
  76 # @enabled: true if KVM acceleration is active
  77 #
  78 # @present: true if KVM acceleration is built into this executable
  79 #
  80 # Since: 0.14.0
  81 ##
  82 { 'struct': 'KvmInfo', 'data': {'enabled': 'bool', 'present': 'bool'} }
  83
  84 ##
  85 # @query-kvm:
  86 #
  87 # Returns information about KVM acceleration
  88 #
  89 # Returns: @KvmInfo
  90 #
  91 # Since: 0.14.0
  92 #
  93 # Example:
  94 #
  95 # -> { "execute": "query-kvm" }
  96 # <- { "return": { "enabled": true, "present": true } }
  97 #
  98 ##
  99 { 'command': 'query-kvm', 'returns': 'KvmInfo' }
 100
 101 ##
 102 # @IOThreadInfo:
 103 #
 104 # Information about an iothread
 105 #
 106 # @id: the identifier of the iothread
 107 #
 108 # @thread-id: ID of the underlying host thread
 109 #
 110 # @poll-max-ns: maximum polling time in ns, 0 means polling is disabled
 111 #               (since 2.9)
 112 #
 113 # @poll-grow: how many ns will be added to polling time, 0 means that it's not
 114 #             configured (since 2.9)
 115 #
 116 # @poll-shrink: how many ns will be removed from polling time, 0 means that
 117 #               it's not configured (since 2.9)
 118 #
 119 # Since: 2.0
 120 ##
 121 { 'struct': 'IOThreadInfo',
 122   'data': {'id': 'str',
 123            'thread-id': 'int',
 124            'poll-max-ns': 'int',
 125            'poll-grow': 'int',
 126            'poll-shrink': 'int' } }
 127
 128 ##
 129 # @query-iothreads:
 130 #
 131 # Returns a list of information about each iothread.
 132 #
 133 # Note: this list excludes the QEMU main loop thread, which is not declared
 134 #       using the -object iothread command-line option.  It is always the main thread
 135 #       of the process.
 136 #
 137 # Returns: a list of @IOThreadInfo for each iothread
 138 #
 139 # Since: 2.0
 140 #
 141 # Example:
 142 #
 143 # -> { "execute": "query-iothreads" }
 144 # <- { "return": [
 145 #          {
 146 #             "id":"iothread0",
 147 #             "thread-id":3134
 148 #          },
 149 #          {
 150 #             "id":"iothread1",
 151 #             "thread-id":3135
 152 #          }
 153 #       ]
 154 #    }
 155 #
 156 ##
 157 { 'command': 'query-iothreads', 'returns': ['IOThreadInfo'],
 158   'allow-preconfig': true }
 159
 160 ##
 161 # @stop:
 162 #
 163 # Stop all guest VCPU execution.
 164 #
 165 # Since:  0.14.0
 166 #
 167 # Notes: This function will succeed even if the guest is already in the stopped
 168 #        state.  In "inmigrate" state, it will ensure that the guest
 169 #        remains paused once migration finishes, as if the -S option was
 170 #        passed on the command line.
 171 #
 172 # Example:
 173 #
 174 # -> { "execute": "stop" }
 175 # <- { "return": {} }
 176 #
 177 ##
 178 { 'command': 'stop' }
 179
 180 ##
 181 # @cont:
 182 #
 183 # Resume guest VCPU execution.
 184 #
 185 # Since:  0.14.0
 186 #
 187 # Returns:  If successful, nothing
 188 #
 189 # Notes: This command will succeed if the guest is currently running.  It
 190 #        will also succeed if the guest is in the "inmigrate" state; in
 191 #        this case, the effect of the command is to make sure the guest
 192 #        starts once migration finishes, removing the effect of the -S
 193 #        command line option if it was passed.
 194 #
 195 # Example:
 196 #
 197 # -> { "execute": "cont" }
 198 # <- { "return": {} }
 199 #
 200 ##
 201 { 'command': 'cont' }
 202
 203 ##
 204 # @x-exit-preconfig:
 205 #
 206 # Exit from "preconfig" state
 207 #
 208 # This command makes QEMU exit the preconfig state and proceed with
 209 # VM initialization using configuration data provided on the command line
 210 # and via the QMP monitor during the preconfig state. The command is only
 211 # available during the preconfig state (i.e. when the --preconfig command
 212 # line option was in use).
 213 #
 214 # Since 3.0
 215 #
 216 # Returns: nothing
 217 #
 218 # Example:
 219 #
 220 # -> { "execute": "x-exit-preconfig" }
 221 # <- { "return": {} }
 222 #
 223 ##
 224 { 'command': 'x-exit-preconfig', 'allow-preconfig': true }
 225
 226 ##
 227 # @human-monitor-command:
 228 #
 229 # Execute a command on the human monitor and return the output.
 230 #
 231 # @command-line: the command to execute in the human monitor
 232 #
 233 # @cpu-index: The CPU to use for commands that require an implicit CPU
 234 #
 235 # Features:
 236 # @savevm-monitor-nodes: If present, HMP command savevm only snapshots
 237 #                        monitor-owned nodes if they have no parents.
 238 #                        This allows the use of 'savevm' with
 239 #                        -blockdev. (since 4.2)
 240 #
 241 # Returns: the output of the command as a string
 242 #
 243 # Since: 0.14.0
 244 #
 245 # Notes: This command only exists as a stop-gap.  Its use is highly
 246 #        discouraged.  The semantics of this command are not
 247 #        guaranteed: this means that command names, arguments and
 248 #        responses can change or be removed at ANY time.  Applications
 249 #        that rely on long term stability guarantees should NOT
 250 #        use this command.
 251 #
 252 #        Known limitations:
 253 #
 254 #        * This command is stateless, this means that commands that depend
 255 #          on state information (such as getfd) might not work
 256 #
 257 #        * Commands that prompt the user for data don't currently work
 258 #
 259 # Example:
 260 #
 261 # -> { "execute": "human-monitor-command",
 262 #      "arguments": { "command-line": "info kvm" } }
 263 # <- { "return": "kvm support: enabled\r\n" }
 264 #
 265 ##
 266 { 'command': 'human-monitor-command',
 267   'data': {'command-line': 'str', '*cpu-index': 'int'},
 268   'returns': 'str',
 269   'features': [ 'savevm-monitor-nodes' ] }
 270
 271 ##
 272 # @change:
 273 #
 274 # This command is multiple commands multiplexed together.
 275 #
 276 # @device: This is normally the name of a block device but it may also be 'vnc'.
 277 #          when it's 'vnc', then sub command depends on @target
 278 #
 279 # @target: If @device is a block device, then this is the new filename.
 280 #          If @device is 'vnc', then if the value 'password' selects the vnc
 281 #          change password command.   Otherwise, this specifies a new server URI
 282 #          address to listen to for VNC connections.
 283 #
 284 # @arg: If @device is a block device, then this is an optional format to open
 285 #       the device with.
 286 #       If @device is 'vnc' and @target is 'password', this is the new VNC
 287 #       password to set.  See change-vnc-password for additional notes.
 288 #
 289 # Features:
 290 # @deprecated: This command is deprecated.  For changing block
 291 #              devices, use 'blockdev-change-medium' instead; for changing VNC
 292 #              parameters, use 'change-vnc-password' instead.
 293 #
 294 # Returns: - Nothing on success.
 295 #          - If @device is not a valid block device, DeviceNotFound
 296 #
 297 # Since: 0.14.0
 298 #
 299 # Example:
 300 #
 301 # 1. Change a removable medium
 302 #
 303 # -> { "execute": "change",
 304 #      "arguments": { "device": "ide1-cd0",
 305 #                     "target": "/srv/images/Fedora-12-x86_64-DVD.iso" } }
 306 # <- { "return": {} }
 307 #
 308 # 2. Change VNC password
 309 #
 310 # -> { "execute": "change",
 311 #      "arguments": { "device": "vnc", "target": "password",
 312 #                     "arg": "foobar1" } }
 313 # <- { "return": {} }
 314 #
 315 ##
 316 { 'command': 'change',
 317   'data': {'device': 'str', 'target': 'str', '*arg': 'str'},
 318   'features': [ 'deprecated' ] }
 319
 320 ##
 321 # @xen-set-global-dirty-log:
 322 #
 323 # Enable or disable the global dirty log mode.
 324 #
 325 # @enable: true to enable, false to disable.
 326 #
 327 # Returns: nothing
 328 #
 329 # Since: 1.3
 330 #
 331 # Example:
 332 #
 333 # -> { "execute": "xen-set-global-dirty-log",
 334 #      "arguments": { "enable": true } }
 335 # <- { "return": {} }
 336 #
 337 ##
 338 { 'command': 'xen-set-global-dirty-log', 'data': { 'enable': 'bool' } }
 339
 340 ##
 341 # @getfd:
 342 #
 343 # Receive a file descriptor via SCM rights and assign it a name
 344 #
 345 # @fdname: file descriptor name
 346 #
 347 # Returns: Nothing on success
 348 #
 349 # Since: 0.14.0
 350 #
 351 # Notes: If @fdname already exists, the file descriptor assigned to
 352 #        it will be closed and replaced by the received file
 353 #        descriptor.
 354 #
 355 #        The 'closefd' command can be used to explicitly close the
 356 #        file descriptor when it is no longer needed.
 357 #
 358 # Example:
 359 #
 360 # -> { "execute": "getfd", "arguments": { "fdname": "fd1" } }
 361 # <- { "return": {} }
 362 #
 363 ##
 364 { 'command': 'getfd', 'data': {'fdname': 'str'} }
 365
 366 ##
 367 # @closefd:
 368 #
 369 # Close a file descriptor previously passed via SCM rights
 370 #
 371 # @fdname: file descriptor name
 372 #
 373 # Returns: Nothing on success
 374 #
 375 # Since: 0.14.0
 376 #
 377 # Example:
 378 #
 379 # -> { "execute": "closefd", "arguments": { "fdname": "fd1" } }
 380 # <- { "return": {} }
 381 #
 382 ##
 383 { 'command': 'closefd', 'data': {'fdname': 'str'} }
 384
 385 ##
 386 # @AddfdInfo:
 387 #
 388 # Information about a file descriptor that was added to an fd set.
 389 #
 390 # @fdset-id: The ID of the fd set that @fd was added to.
 391 #
 392 # @fd: The file descriptor that was received via SCM rights and
 393 #      added to the fd set.
 394 #
 395 # Since: 1.2.0
 396 ##
 397 { 'struct': 'AddfdInfo', 'data': {'fdset-id': 'int', 'fd': 'int'} }
 398
 399 ##
 400 # @add-fd:
 401 #
 402 # Add a file descriptor, that was passed via SCM rights, to an fd set.
 403 #
 404 # @fdset-id: The ID of the fd set to add the file descriptor to.
 405 #
 406 # @opaque: A free-form string that can be used to describe the fd.
 407 #
 408 # Returns: - @AddfdInfo on success
 409 #          - If file descriptor was not received, FdNotSupplied
 410 #          - If @fdset-id is a negative value, InvalidParameterValue
 411 #
 412 # Notes: The list of fd sets is shared by all monitor connections.
 413 #
 414 #        If @fdset-id is not specified, a new fd set will be created.
 415 #
 416 # Since: 1.2.0
 417 #
 418 # Example:
 419 #
 420 # -> { "execute": "add-fd", "arguments": { "fdset-id": 1 } }
 421 # <- { "return": { "fdset-id": 1, "fd": 3 } }
 422 #
 423 ##
 424 { 'command': 'add-fd',
 425   'data': { '*fdset-id': 'int',
 426             '*opaque': 'str' },
 427   'returns': 'AddfdInfo' }
 428
 429 ##
 430 # @remove-fd:
 431 #
 432 # Remove a file descriptor from an fd set.
 433 #
 434 # @fdset-id: The ID of the fd set that the file descriptor belongs to.
 435 #
 436 # @fd: The file descriptor that is to be removed.
 437 #
 438 # Returns: - Nothing on success
 439 #          - If @fdset-id or @fd is not found, FdNotFound
 440 #
 441 # Since: 1.2.0
 442 #
 443 # Notes: The list of fd sets is shared by all monitor connections.
 444 #
 445 #        If @fd is not specified, all file descriptors in @fdset-id
 446 #        will be removed.
 447 #
 448 # Example:
 449 #
 450 # -> { "execute": "remove-fd", "arguments": { "fdset-id": 1, "fd": 3 } }
 451 # <- { "return": {} }
 452 #
 453 ##
 454 { 'command': 'remove-fd', 'data': {'fdset-id': 'int', '*fd': 'int'} }
 455
 456 ##
 457 # @FdsetFdInfo:
 458 #
 459 # Information about a file descriptor that belongs to an fd set.
 460 #
 461 # @fd: The file descriptor value.
 462 #
 463 # @opaque: A free-form string that can be used to describe the fd.
 464 #
 465 # Since: 1.2.0
 466 ##
 467 { 'struct': 'FdsetFdInfo',
 468   'data': {'fd': 'int', '*opaque': 'str'} }
 469
 470 ##
 471 # @FdsetInfo:
 472 #
 473 # Information about an fd set.
 474 #
 475 # @fdset-id: The ID of the fd set.
 476 #
 477 # @fds: A list of file descriptors that belong to this fd set.
 478 #
 479 # Since: 1.2.0
 480 ##
 481 { 'struct': 'FdsetInfo',
 482   'data': {'fdset-id': 'int', 'fds': ['FdsetFdInfo']} }
 483
 484 ##
 485 # @query-fdsets:
 486 #
 487 # Return information describing all fd sets.
 488 #
 489 # Returns: A list of @FdsetInfo
 490 #
 491 # Since: 1.2.0
 492 #
 493 # Note: The list of fd sets is shared by all monitor connections.
 494 #
 495 # Example:
 496 #
 497 # -> { "execute": "query-fdsets" }
 498 # <- { "return": [
 499 #        {
 500 #          "fds": [
 501 #            {
 502 #              "fd": 30,
 503 #              "opaque": "rdonly:/path/to/file"
 504 #            },
 505 #            {
 506 #              "fd": 24,
 507 #              "opaque": "rdwr:/path/to/file"
 508 #            }
 509 #          ],
 510 #          "fdset-id": 1
 511 #        },
 512 #        {
 513 #          "fds": [
 514 #            {
 515 #              "fd": 28
 516 #            },
 517 #            {
 518 #              "fd": 29
 519 #            }
 520 #          ],
 521 #          "fdset-id": 0
 522 #        }
 523 #      ]
 524 #    }
 525 #
 526 ##
 527 { 'command': 'query-fdsets', 'returns': ['FdsetInfo'] }
 528
 529 ##
 530 # @CommandLineParameterType:
 531 #
 532 # Possible types for an option parameter.
 533 #
 534 # @string: accepts a character string
 535 #
 536 # @boolean: accepts "on" or "off"
 537 #
 538 # @number: accepts a number
 539 #
 540 # @size: accepts a number followed by an optional suffix (K)ilo,
 541 #        (M)ega, (G)iga, (T)era
 542 #
 543 # Since: 1.5
 544 ##
 545 { 'enum': 'CommandLineParameterType',
 546   'data': ['string', 'boolean', 'number', 'size'] }
 547
 548 ##
 549 # @CommandLineParameterInfo:
 550 #
 551 # Details about a single parameter of a command line option.
 552 #
 553 # @name: parameter name
 554 #
 555 # @type: parameter @CommandLineParameterType
 556 #
 557 # @help: human readable text string, not suitable for parsing.
 558 #
 559 # @default: default value string (since 2.1)
 560 #
 561 # Since: 1.5
 562 ##
 563 { 'struct': 'CommandLineParameterInfo',
 564   'data': { 'name': 'str',
 565             'type': 'CommandLineParameterType',
 566             '*help': 'str',
 567             '*default': 'str' } }
 568
 569 ##
 570 # @CommandLineOptionInfo:
 571 #
 572 # Details about a command line option, including its list of parameter details
 573 #
 574 # @option: option name
 575 #
 576 # @parameters: an array of @CommandLineParameterInfo
 577 #
 578 # Since: 1.5
 579 ##
 580 { 'struct': 'CommandLineOptionInfo',
 581   'data': { 'option': 'str', 'parameters': ['CommandLineParameterInfo'] } }
 582
 583 ##
 584 # @query-command-line-options:
 585 #
 586 # Query command line option schema.
 587 #
 588 # @option: option name
 589 #
 590 # Returns: list of @CommandLineOptionInfo for all options (or for the given
 591 #          @option).  Returns an error if the given @option doesn't exist.
 592 #
 593 # Since: 1.5
 594 #
 595 # Example:
 596 #
 597 # -> { "execute": "query-command-line-options",
 598 #      "arguments": { "option": "option-rom" } }
 599 # <- { "return": [
 600 #         {
 601 #             "parameters": [
 602 #                 {
 603 #                     "name": "romfile",
 604 #                     "type": "string"
 605 #                 },
 606 #                 {
 607 #                     "name": "bootindex",
 608 #                     "type": "number"
 609 #                 }
 610 #             ],
 611 #             "option": "option-rom"
 612 #         }
 613 #      ]
 614 #    }
 615 #
 616 ##
 617 {'command': 'query-command-line-options',
 618  'data': { '*option': 'str' },
 619  'returns': ['CommandLineOptionInfo'],
 620  'allow-preconfig': true }
 621
 622 ##
 623 # @xen-load-devices-state:
 624 #
 625 # Load the state of all devices from file. The RAM and the block devices
 626 # of the VM are not loaded by this command.
 627 #
 628 # @filename: the file to load the state of the devices from as binary
 629 #            data. See xen-save-devices-state.txt for a description of the binary
 630 #            format.
 631 #
 632 # Since: 2.7
 633 #
 634 # Example:
 635 #
 636 # -> { "execute": "xen-load-devices-state",
 637 #      "arguments": { "filename": "/tmp/resume" } }
 638 # <- { "return": {} }
 639 #
 640 ##
 641 { 'command': 'xen-load-devices-state', 'data': {'filename': 'str'} }