qemu/qapi/misc.json
<<
>>
Prefs
   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
  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
  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##
  69{ 'command': 'query-name', 'returns': 'NameInfo', 'allow-preconfig': true }
  70
  71##
  72# @IOThreadInfo:
  73#
  74# Information about an iothread
  75#
  76# @id: the identifier of the iothread
  77#
  78# @thread-id: ID of the underlying host thread
  79#
  80# @poll-max-ns: maximum polling time in ns, 0 means polling is disabled
  81#               (since 2.9)
  82#
  83# @poll-grow: how many ns will be added to polling time, 0 means that it's not
  84#             configured (since 2.9)
  85#
  86# @poll-shrink: how many ns will be removed from polling time, 0 means that
  87#               it's not configured (since 2.9)
  88#
  89# @aio-max-batch: maximum number of requests in a batch for the AIO engine,
  90#                 0 means that the engine will use its default (since 6.1)
  91#
  92# Since: 2.0
  93##
  94{ 'struct': 'IOThreadInfo',
  95  'data': {'id': 'str',
  96           'thread-id': 'int',
  97           'poll-max-ns': 'int',
  98           'poll-grow': 'int',
  99           'poll-shrink': 'int',
 100           'aio-max-batch': 'int' } }
 101
 102##
 103# @query-iothreads:
 104#
 105# Returns a list of information about each iothread.
 106#
 107# Note: this list excludes the QEMU main loop thread, which is not declared
 108#       using the -object iothread command-line option.  It is always the main thread
 109#       of the process.
 110#
 111# Returns: a list of @IOThreadInfo for each iothread
 112#
 113# Since: 2.0
 114#
 115# Example:
 116#
 117# -> { "execute": "query-iothreads" }
 118# <- { "return": [
 119#          {
 120#             "id":"iothread0",
 121#             "thread-id":3134
 122#          },
 123#          {
 124#             "id":"iothread1",
 125#             "thread-id":3135
 126#          }
 127#       ]
 128#    }
 129#
 130##
 131{ 'command': 'query-iothreads', 'returns': ['IOThreadInfo'],
 132  'allow-preconfig': true }
 133
 134##
 135# @stop:
 136#
 137# Stop all guest VCPU execution.
 138#
 139# Since:  0.14
 140#
 141# Notes: This function will succeed even if the guest is already in the stopped
 142#        state.  In "inmigrate" state, it will ensure that the guest
 143#        remains paused once migration finishes, as if the -S option was
 144#        passed on the command line.
 145#
 146# Example:
 147#
 148# -> { "execute": "stop" }
 149# <- { "return": {} }
 150#
 151##
 152{ 'command': 'stop' }
 153
 154##
 155# @cont:
 156#
 157# Resume guest VCPU execution.
 158#
 159# Since:  0.14
 160#
 161# Returns:  If successful, nothing
 162#
 163# Notes: This command will succeed if the guest is currently running.  It
 164#        will also succeed if the guest is in the "inmigrate" state; in
 165#        this case, the effect of the command is to make sure the guest
 166#        starts once migration finishes, removing the effect of the -S
 167#        command line option if it was passed.
 168#
 169# Example:
 170#
 171# -> { "execute": "cont" }
 172# <- { "return": {} }
 173#
 174##
 175{ 'command': 'cont' }
 176
 177##
 178# @x-exit-preconfig:
 179#
 180# Exit from "preconfig" state
 181#
 182# This command makes QEMU exit the preconfig state and proceed with
 183# VM initialization using configuration data provided on the command line
 184# and via the QMP monitor during the preconfig state. The command is only
 185# available during the preconfig state (i.e. when the --preconfig command
 186# line option was in use).
 187#
 188# Features:
 189# @unstable: This command is experimental.
 190#
 191# Since 3.0
 192#
 193# Returns: nothing
 194#
 195# Example:
 196#
 197# -> { "execute": "x-exit-preconfig" }
 198# <- { "return": {} }
 199#
 200##
 201{ 'command': 'x-exit-preconfig', 'allow-preconfig': true,
 202  'features': [ 'unstable' ] }
 203
 204##
 205# @human-monitor-command:
 206#
 207# Execute a command on the human monitor and return the output.
 208#
 209# @command-line: the command to execute in the human monitor
 210#
 211# @cpu-index: The CPU to use for commands that require an implicit CPU
 212#
 213# Features:
 214# @savevm-monitor-nodes: If present, HMP command savevm only snapshots
 215#                        monitor-owned nodes if they have no parents.
 216#                        This allows the use of 'savevm' with
 217#                        -blockdev. (since 4.2)
 218#
 219# Returns: the output of the command as a string
 220#
 221# Since: 0.14
 222#
 223# Notes: This command only exists as a stop-gap.  Its use is highly
 224#        discouraged.  The semantics of this command are not
 225#        guaranteed: this means that command names, arguments and
 226#        responses can change or be removed at ANY time.  Applications
 227#        that rely on long term stability guarantees should NOT
 228#        use this command.
 229#
 230#        Known limitations:
 231#
 232#        * This command is stateless, this means that commands that depend
 233#          on state information (such as getfd) might not work
 234#
 235#        * Commands that prompt the user for data don't currently work
 236#
 237# Example:
 238#
 239# -> { "execute": "human-monitor-command",
 240#      "arguments": { "command-line": "info kvm" } }
 241# <- { "return": "kvm support: enabled\r\n" }
 242#
 243##
 244{ 'command': 'human-monitor-command',
 245  'data': {'command-line': 'str', '*cpu-index': 'int'},
 246  'returns': 'str',
 247  'features': [ 'savevm-monitor-nodes' ] }
 248
 249##
 250# @getfd:
 251#
 252# Receive a file descriptor via SCM rights and assign it a name
 253#
 254# @fdname: file descriptor name
 255#
 256# Returns: Nothing on success
 257#
 258# Since: 0.14
 259#
 260# Notes: If @fdname already exists, the file descriptor assigned to
 261#        it will be closed and replaced by the received file
 262#        descriptor.
 263#
 264#        The 'closefd' command can be used to explicitly close the
 265#        file descriptor when it is no longer needed.
 266#
 267# Example:
 268#
 269# -> { "execute": "getfd", "arguments": { "fdname": "fd1" } }
 270# <- { "return": {} }
 271#
 272##
 273{ 'command': 'getfd', 'data': {'fdname': 'str'} }
 274
 275##
 276# @closefd:
 277#
 278# Close a file descriptor previously passed via SCM rights
 279#
 280# @fdname: file descriptor name
 281#
 282# Returns: Nothing on success
 283#
 284# Since: 0.14
 285#
 286# Example:
 287#
 288# -> { "execute": "closefd", "arguments": { "fdname": "fd1" } }
 289# <- { "return": {} }
 290#
 291##
 292{ 'command': 'closefd', 'data': {'fdname': 'str'} }
 293
 294##
 295# @AddfdInfo:
 296#
 297# Information about a file descriptor that was added to an fd set.
 298#
 299# @fdset-id: The ID of the fd set that @fd was added to.
 300#
 301# @fd: The file descriptor that was received via SCM rights and
 302#      added to the fd set.
 303#
 304# Since: 1.2
 305##
 306{ 'struct': 'AddfdInfo', 'data': {'fdset-id': 'int', 'fd': 'int'} }
 307
 308##
 309# @add-fd:
 310#
 311# Add a file descriptor, that was passed via SCM rights, to an fd set.
 312#
 313# @fdset-id: The ID of the fd set to add the file descriptor to.
 314#
 315# @opaque: A free-form string that can be used to describe the fd.
 316#
 317# Returns: - @AddfdInfo on success
 318#          - If file descriptor was not received, FdNotSupplied
 319#          - If @fdset-id is a negative value, InvalidParameterValue
 320#
 321# Notes: The list of fd sets is shared by all monitor connections.
 322#
 323#        If @fdset-id is not specified, a new fd set will be created.
 324#
 325# Since: 1.2
 326#
 327# Example:
 328#
 329# -> { "execute": "add-fd", "arguments": { "fdset-id": 1 } }
 330# <- { "return": { "fdset-id": 1, "fd": 3 } }
 331#
 332##
 333{ 'command': 'add-fd',
 334  'data': { '*fdset-id': 'int',
 335            '*opaque': 'str' },
 336  'returns': 'AddfdInfo' }
 337
 338##
 339# @remove-fd:
 340#
 341# Remove a file descriptor from an fd set.
 342#
 343# @fdset-id: The ID of the fd set that the file descriptor belongs to.
 344#
 345# @fd: The file descriptor that is to be removed.
 346#
 347# Returns: - Nothing on success
 348#          - If @fdset-id or @fd is not found, FdNotFound
 349#
 350# Since: 1.2
 351#
 352# Notes: The list of fd sets is shared by all monitor connections.
 353#
 354#        If @fd is not specified, all file descriptors in @fdset-id
 355#        will be removed.
 356#
 357# Example:
 358#
 359# -> { "execute": "remove-fd", "arguments": { "fdset-id": 1, "fd": 3 } }
 360# <- { "return": {} }
 361#
 362##
 363{ 'command': 'remove-fd', 'data': {'fdset-id': 'int', '*fd': 'int'} }
 364
 365##
 366# @FdsetFdInfo:
 367#
 368# Information about a file descriptor that belongs to an fd set.
 369#
 370# @fd: The file descriptor value.
 371#
 372# @opaque: A free-form string that can be used to describe the fd.
 373#
 374# Since: 1.2
 375##
 376{ 'struct': 'FdsetFdInfo',
 377  'data': {'fd': 'int', '*opaque': 'str'} }
 378
 379##
 380# @FdsetInfo:
 381#
 382# Information about an fd set.
 383#
 384# @fdset-id: The ID of the fd set.
 385#
 386# @fds: A list of file descriptors that belong to this fd set.
 387#
 388# Since: 1.2
 389##
 390{ 'struct': 'FdsetInfo',
 391  'data': {'fdset-id': 'int', 'fds': ['FdsetFdInfo']} }
 392
 393##
 394# @query-fdsets:
 395#
 396# Return information describing all fd sets.
 397#
 398# Returns: A list of @FdsetInfo
 399#
 400# Since: 1.2
 401#
 402# Note: The list of fd sets is shared by all monitor connections.
 403#
 404# Example:
 405#
 406# -> { "execute": "query-fdsets" }
 407# <- { "return": [
 408#        {
 409#          "fds": [
 410#            {
 411#              "fd": 30,
 412#              "opaque": "rdonly:/path/to/file"
 413#            },
 414#            {
 415#              "fd": 24,
 416#              "opaque": "rdwr:/path/to/file"
 417#            }
 418#          ],
 419#          "fdset-id": 1
 420#        },
 421#        {
 422#          "fds": [
 423#            {
 424#              "fd": 28
 425#            },
 426#            {
 427#              "fd": 29
 428#            }
 429#          ],
 430#          "fdset-id": 0
 431#        }
 432#      ]
 433#    }
 434#
 435##
 436{ 'command': 'query-fdsets', 'returns': ['FdsetInfo'] }
 437
 438##
 439# @CommandLineParameterType:
 440#
 441# Possible types for an option parameter.
 442#
 443# @string: accepts a character string
 444#
 445# @boolean: accepts "on" or "off"
 446#
 447# @number: accepts a number
 448#
 449# @size: accepts a number followed by an optional suffix (K)ilo,
 450#        (M)ega, (G)iga, (T)era
 451#
 452# Since: 1.5
 453##
 454{ 'enum': 'CommandLineParameterType',
 455  'data': ['string', 'boolean', 'number', 'size'] }
 456
 457##
 458# @CommandLineParameterInfo:
 459#
 460# Details about a single parameter of a command line option.
 461#
 462# @name: parameter name
 463#
 464# @type: parameter @CommandLineParameterType
 465#
 466# @help: human readable text string, not suitable for parsing.
 467#
 468# @default: default value string (since 2.1)
 469#
 470# Since: 1.5
 471##
 472{ 'struct': 'CommandLineParameterInfo',
 473  'data': { 'name': 'str',
 474            'type': 'CommandLineParameterType',
 475            '*help': 'str',
 476            '*default': 'str' } }
 477
 478##
 479# @CommandLineOptionInfo:
 480#
 481# Details about a command line option, including its list of parameter details
 482#
 483# @option: option name
 484#
 485# @parameters: an array of @CommandLineParameterInfo
 486#
 487# Since: 1.5
 488##
 489{ 'struct': 'CommandLineOptionInfo',
 490  'data': { 'option': 'str', 'parameters': ['CommandLineParameterInfo'] } }
 491
 492##
 493# @query-command-line-options:
 494#
 495# Query command line option schema.
 496#
 497# @option: option name
 498#
 499# Returns: list of @CommandLineOptionInfo for all options (or for the given
 500#          @option).  Returns an error if the given @option doesn't exist.
 501#
 502# Since: 1.5
 503#
 504# Example:
 505#
 506# -> { "execute": "query-command-line-options",
 507#      "arguments": { "option": "option-rom" } }
 508# <- { "return": [
 509#         {
 510#             "parameters": [
 511#                 {
 512#                     "name": "romfile",
 513#                     "type": "string"
 514#                 },
 515#                 {
 516#                     "name": "bootindex",
 517#                     "type": "number"
 518#                 }
 519#             ],
 520#             "option": "option-rom"
 521#         }
 522#      ]
 523#    }
 524#
 525##
 526{'command': 'query-command-line-options',
 527 'data': { '*option': 'str' },
 528 'returns': ['CommandLineOptionInfo'],
 529 'allow-preconfig': true }
 530