qapi/qom.json

   1 # -*- Mode: Python -*-
   2 # vim: filetype=python
   3 #
   4 # This work is licensed under the terms of the GNU GPL, version 2 or later.
   5 # See the COPYING file in the top-level directory.
   6
   7 { 'include': 'authz.json' }
   8 { 'include': 'block-core.json' }
   9 { 'include': 'common.json' }
  10
  11 ##
  12 # = QEMU Object Model (QOM)
  13 ##
  14
  15 ##
  16 # @ObjectPropertyInfo:
  17 #
  18 # @name: the name of the property
  19 #
  20 # @type: the type of the property.  This will typically come in one of four
  21 #        forms:
  22 #
  23 #        1) A primitive type such as 'u8', 'u16', 'bool', 'str', or 'double'.
  24 #           These types are mapped to the appropriate JSON type.
  25 #
  26 #        2) A child type in the form 'child<subtype>' where subtype is a qdev
  27 #           device type name.  Child properties create the composition tree.
  28 #
  29 #        3) A link type in the form 'link<subtype>' where subtype is a qdev
  30 #           device type name.  Link properties form the device model graph.
  31 #
  32 # @description: if specified, the description of the property.
  33 #
  34 # @default-value: the default value, if any (since 5.0)
  35 #
  36 # Since: 1.2
  37 ##
  38 { 'struct': 'ObjectPropertyInfo',
  39   'data': { 'name': 'str',
  40             'type': 'str',
  41             '*description': 'str',
  42             '*default-value': 'any' } }
  43
  44 ##
  45 # @qom-list:
  46 #
  47 # This command will list any properties of a object given a path in the object
  48 # model.
  49 #
  50 # @path: the path within the object model.  See @qom-get for a description of
  51 #        this parameter.
  52 #
  53 # Returns: a list of @ObjectPropertyInfo that describe the properties of the
  54 #          object.
  55 #
  56 # Since: 1.2
  57 #
  58 # Example:
  59 #
  60 # -> { "execute": "qom-list",
  61 #      "arguments": { "path": "/chardevs" } }
  62 # <- { "return": [ { "name": "type", "type": "string" },
  63 #                  { "name": "parallel0", "type": "child<chardev-vc>" },
  64 #                  { "name": "serial0", "type": "child<chardev-vc>" },
  65 #                  { "name": "mon0", "type": "child<chardev-stdio>" } ] }
  66 #
  67 ##
  68 { 'command': 'qom-list',
  69   'data': { 'path': 'str' },
  70   'returns': [ 'ObjectPropertyInfo' ],
  71   'allow-preconfig': true }
  72
  73 ##
  74 # @qom-get:
  75 #
  76 # This command will get a property from a object model path and return the
  77 # value.
  78 #
  79 # @path: The path within the object model.  There are two forms of supported
  80 #        paths--absolute and partial paths.
  81 #
  82 #        Absolute paths are derived from the root object and can follow child<>
  83 #        or link<> properties.  Since they can follow link<> properties, they
  84 #        can be arbitrarily long.  Absolute paths look like absolute filenames
  85 #        and are prefixed  with a leading slash.
  86 #
  87 #        Partial paths look like relative filenames.  They do not begin
  88 #        with a prefix.  The matching rules for partial paths are subtle but
  89 #        designed to make specifying objects easy.  At each level of the
  90 #        composition tree, the partial path is matched as an absolute path.
  91 #        The first match is not returned.  At least two matches are searched
  92 #        for.  A successful result is only returned if only one match is
  93 #        found.  If more than one match is found, a flag is return to
  94 #        indicate that the match was ambiguous.
  95 #
  96 # @property: The property name to read
  97 #
  98 # Returns: The property value.  The type depends on the property
  99 #          type. child<> and link<> properties are returned as #str
 100 #          pathnames.  All integer property types (u8, u16, etc) are
 101 #          returned as #int.
 102 #
 103 # Since: 1.2
 104 #
 105 # Example:
 106 #
 107 # 1. Use absolute path
 108 #
 109 # -> { "execute": "qom-get",
 110 #      "arguments": { "path": "/machine/unattached/device[0]",
 111 #                     "property": "hotplugged" } }
 112 # <- { "return": false }
 113 #
 114 # 2. Use partial path
 115 #
 116 # -> { "execute": "qom-get",
 117 #      "arguments": { "path": "unattached/sysbus",
 118 #                     "property": "type" } }
 119 # <- { "return": "System" }
 120 #
 121 ##
 122 { 'command': 'qom-get',
 123   'data': { 'path': 'str', 'property': 'str' },
 124   'returns': 'any',
 125   'allow-preconfig': true }
 126
 127 ##
 128 # @qom-set:
 129 #
 130 # This command will set a property from a object model path.
 131 #
 132 # @path: see @qom-get for a description of this parameter
 133 #
 134 # @property: the property name to set
 135 #
 136 # @value: a value who's type is appropriate for the property type.  See @qom-get
 137 #         for a description of type mapping.
 138 #
 139 # Since: 1.2
 140 #
 141 # Example:
 142 #
 143 # -> { "execute": "qom-set",
 144 #      "arguments": { "path": "/machine",
 145 #                     "property": "graphics",
 146 #                     "value": false } }
 147 # <- { "return": {} }
 148 #
 149 ##
 150 { 'command': 'qom-set',
 151   'data': { 'path': 'str', 'property': 'str', 'value': 'any' },
 152   'allow-preconfig': true }
 153
 154 ##
 155 # @ObjectTypeInfo:
 156 #
 157 # This structure describes a search result from @qom-list-types
 158 #
 159 # @name: the type name found in the search
 160 #
 161 # @abstract: the type is abstract and can't be directly instantiated.
 162 #            Omitted if false. (since 2.10)
 163 #
 164 # @parent: Name of parent type, if any (since 2.10)
 165 #
 166 # Since: 1.1
 167 ##
 168 { 'struct': 'ObjectTypeInfo',
 169   'data': { 'name': 'str', '*abstract': 'bool', '*parent': 'str' } }
 170
 171 ##
 172 # @qom-list-types:
 173 #
 174 # This command will return a list of types given search parameters
 175 #
 176 # @implements: if specified, only return types that implement this type name
 177 #
 178 # @abstract: if true, include abstract types in the results
 179 #
 180 # Returns: a list of @ObjectTypeInfo or an empty list if no results are found
 181 #
 182 # Since: 1.1
 183 ##
 184 { 'command': 'qom-list-types',
 185   'data': { '*implements': 'str', '*abstract': 'bool' },
 186   'returns': [ 'ObjectTypeInfo' ],
 187   'allow-preconfig': true }
 188
 189 ##
 190 # @qom-list-properties:
 191 #
 192 # List properties associated with a QOM object.
 193 #
 194 # @typename: the type name of an object
 195 #
 196 # Note: objects can create properties at runtime, for example to describe
 197 #       links between different devices and/or objects. These properties
 198 #       are not included in the output of this command.
 199 #
 200 # Returns: a list of ObjectPropertyInfo describing object properties
 201 #
 202 # Since: 2.12
 203 ##
 204 { 'command': 'qom-list-properties',
 205   'data': { 'typename': 'str'},
 206   'returns': [ 'ObjectPropertyInfo' ],
 207   'allow-preconfig': true }
 208
 209 ##
 210 # @CryptodevBackendProperties:
 211 #
 212 # Properties for cryptodev-backend and cryptodev-backend-builtin objects.
 213 #
 214 # @queues: the number of queues for the cryptodev backend. Ignored for
 215 #          cryptodev-backend and must be 1 for cryptodev-backend-builtin.
 216 #          (default: 1)
 217 #
 218 # Since: 2.8
 219 ##
 220 { 'struct': 'CryptodevBackendProperties',
 221   'data': { '*queues': 'uint32' } }
 222
 223 ##
 224 # @CryptodevVhostUserProperties:
 225 #
 226 # Properties for cryptodev-vhost-user objects.
 227 #
 228 # @chardev: the name of a Unix domain socket character device that connects to
 229 #           the vhost-user server
 230 #
 231 # Since: 2.12
 232 ##
 233 { 'struct': 'CryptodevVhostUserProperties',
 234   'base': 'CryptodevBackendProperties',
 235   'data': { 'chardev': 'str' } }
 236
 237 ##
 238 # @DBusVMStateProperties:
 239 #
 240 # Properties for dbus-vmstate objects.
 241 #
 242 # @addr: the name of the DBus bus to connect to
 243 #
 244 # @id-list: a comma separated list of DBus IDs of helpers whose data should be
 245 #           included in the VM state on migration
 246 #
 247 # Since: 5.0
 248 ##
 249 { 'struct': 'DBusVMStateProperties',
 250   'data': { 'addr': 'str' ,
 251             '*id-list': 'str' } }
 252
 253 ##
 254 # @IothreadProperties:
 255 #
 256 # Properties for iothread objects.
 257 #
 258 # @poll-max-ns: the maximum number of nanoseconds to busy wait for events.
 259 #               0 means polling is disabled (default: 32768 on POSIX hosts,
 260 #               0 otherwise)
 261 #
 262 # @poll-grow: the multiplier used to increase the polling time when the
 263 #             algorithm detects it is missing events due to not polling long
 264 #             enough. 0 selects a default behaviour (default: 0)
 265 #
 266 # @poll-shrink: the divisor used to decrease the polling time when the
 267 #               algorithm detects it is spending too long polling without
 268 #               encountering events. 0 selects a default behaviour (default: 0)
 269 #
 270 # Since: 2.0
 271 ##
 272 { 'struct': 'IothreadProperties',
 273   'data': { '*poll-max-ns': 'int',
 274             '*poll-grow': 'int',
 275             '*poll-shrink': 'int' } }
 276
 277 ##
 278 # @MemoryBackendProperties:
 279 #
 280 # Properties for objects of classes derived from memory-backend.
 281 #
 282 # @merge: if true, mark the memory as mergeable (default depends on the machine
 283 #         type)
 284 #
 285 # @dump: if true, include the memory in core dumps (default depends on the
 286 #        machine type)
 287 #
 288 # @host-nodes: the list of NUMA host nodes to bind the memory to
 289 #
 290 # @policy: the NUMA policy (default: 'default')
 291 #
 292 # @prealloc: if true, preallocate memory (default: false)
 293 #
 294 # @prealloc-threads: number of CPU threads to use for prealloc (default: 1)
 295 #
 296 # @share: if false, the memory is private to QEMU; if true, it is shared
 297 #         (default: false)
 298 #
 299 # @size: size of the memory region in bytes
 300 #
 301 # @x-use-canonical-path-for-ramblock-id: if true, the canoncial path is used
 302 #                                        for ramblock-id. Disable this for 4.0
 303 #                                        machine types or older to allow
 304 #                                        migration with newer QEMU versions.
 305 #                                        This option is considered stable
 306 #                                        despite the x- prefix. (default:
 307 #                                        false generally, but true for machine
 308 #                                        types <= 4.0)
 309 #
 310 # Since: 2.1
 311 ##
 312 { 'struct': 'MemoryBackendProperties',
 313   'data': { '*dump': 'bool',
 314             '*host-nodes': ['uint16'],
 315             '*merge': 'bool',
 316             '*policy': 'HostMemPolicy',
 317             '*prealloc': 'bool',
 318             '*prealloc-threads': 'uint32',
 319             '*share': 'bool',
 320             'size': 'size',
 321             '*x-use-canonical-path-for-ramblock-id': 'bool' } }
 322
 323 ##
 324 # @MemoryBackendFileProperties:
 325 #
 326 # Properties for memory-backend-file objects.
 327 #
 328 # @align: the base address alignment when QEMU mmap(2)s @mem-path. Some
 329 #         backend stores specified by @mem-path require an alignment different
 330 #         than the default one used by QEMU, e.g. the device DAX /dev/dax0.0
 331 #         requires 2M alignment rather than 4K. In such cases, users can
 332 #         specify the required alignment via this option.
 333 #         0 selects a default alignment (currently the page size). (default: 0)
 334 #
 335 # @discard-data: if true, the file contents can be destroyed when QEMU exits,
 336 #                to avoid unnecessarily flushing data to the backing file. Note
 337 #                that ``discard-data`` is only an optimization, and QEMU might
 338 #                not discard file contents if it aborts unexpectedly or is
 339 #                terminated using SIGKILL. (default: false)
 340 #
 341 # @mem-path: the path to either a shared memory or huge page filesystem mount
 342 #
 343 # @pmem: specifies whether the backing file specified by @mem-path is in
 344 #        host persistent memory that can be accessed using the SNIA NVM
 345 #        programming model (e.g. Intel NVDIMM).
 346 #
 347 # @readonly: if true, the backing file is opened read-only; if false, it is
 348 #            opened read-write. (default: false)
 349 #
 350 # Since: 2.1
 351 ##
 352 { 'struct': 'MemoryBackendFileProperties',
 353   'base': 'MemoryBackendProperties',
 354   'data': { '*align': 'size',
 355             '*discard-data': 'bool',
 356             'mem-path': 'str',
 357             '*pmem': { 'type': 'bool', 'if': 'defined(CONFIG_LIBPMEM)' },
 358             '*readonly': 'bool' } }
 359
 360 ##
 361 # @MemoryBackendMemfdProperties:
 362 #
 363 # Properties for memory-backend-memfd objects.
 364 #
 365 # The @share boolean option is true by default with memfd.
 366 #
 367 # @hugetlb: if true, the file to be created resides in the hugetlbfs filesystem
 368 #           (default: false)
 369 #
 370 # @hugetlbsize: the hugetlb page size on systems that support multiple hugetlb
 371 #               page sizes (it must be a power of 2 value supported by the
 372 #               system). 0 selects a default page size. This option is ignored
 373 #               if @hugetlb is false. (default: 0)
 374 #
 375 # @seal: if true, create a sealed-file, which will block further resizing of
 376 #        the memory (default: true)
 377 #
 378 # Since: 2.12
 379 ##
 380 { 'struct': 'MemoryBackendMemfdProperties',
 381   'base': 'MemoryBackendProperties',
 382   'data': { '*hugetlb': 'bool',
 383             '*hugetlbsize': 'size',
 384             '*seal': 'bool' } }
 385
 386 ##
 387 # @RngProperties:
 388 #
 389 # Properties for objects of classes derived from rng.
 390 #
 391 # @opened: if true, the device is opened immediately when applying this option
 392 #          and will probably fail when processing the next option. Don't use;
 393 #          only provided for compatibility. (default: false)
 394 #
 395 # Features:
 396 # @deprecated: Member @opened is deprecated.  Setting true doesn't make sense,
 397 #              and false is already the default.
 398 #
 399 # Since: 1.3
 400 ##
 401 { 'struct': 'RngProperties',
 402   'data': { '*opened': { 'type': 'bool', 'features': ['deprecated'] } } }
 403
 404 ##
 405 # @RngEgdProperties:
 406 #
 407 # Properties for rng-egd objects.
 408 #
 409 # @chardev: the name of a character device backend that provides the connection
 410 #           to the RNG daemon
 411 #
 412 # Since: 1.3
 413 ##
 414 { 'struct': 'RngEgdProperties',
 415   'base': 'RngProperties',
 416   'data': { 'chardev': 'str' } }
 417
 418 ##
 419 # @RngRandomProperties:
 420 #
 421 # Properties for rng-random objects.
 422 #
 423 # @filename: the filename of the device on the host to obtain entropy from
 424 #            (default: "/dev/urandom")
 425 #
 426 # Since: 1.3
 427 ##
 428 { 'struct': 'RngRandomProperties',
 429   'base': 'RngProperties',
 430   'data': { '*filename': 'str' } }
 431
 432 ##
 433 # @ObjectType:
 434 #
 435 # Since: 6.0
 436 ##
 437 { 'enum': 'ObjectType',
 438   'data': [
 439     'authz-list',
 440     'authz-listfile',
 441     'authz-pam',
 442     'authz-simple',
 443     'cryptodev-backend',
 444     'cryptodev-backend-builtin',
 445     { 'name': 'cryptodev-vhost-user',
 446       'if': 'defined(CONFIG_VIRTIO_CRYPTO) && defined(CONFIG_VHOST_CRYPTO)' },
 447     'dbus-vmstate',
 448     'iothread',
 449     'memory-backend-file',
 450     { 'name': 'memory-backend-memfd',
 451       'if': 'defined(CONFIG_LINUX)' },
 452     'memory-backend-ram',
 453     'rng-builtin',
 454     'rng-egd',
 455     'rng-random',
 456     'throttle-group'
 457   ] }
 458
 459 ##
 460 # @ObjectOptions:
 461 #
 462 # Describes the options of a user creatable QOM object.
 463 #
 464 # @qom-type: the class name for the object to be created
 465 #
 466 # @id: the name of the new object
 467 #
 468 # Since: 6.0
 469 ##
 470 { 'union': 'ObjectOptions',
 471   'base': { 'qom-type': 'ObjectType',
 472             'id': 'str' },
 473   'discriminator': 'qom-type',
 474   'data': {
 475       'authz-list':                 'AuthZListProperties',
 476       'authz-listfile':             'AuthZListFileProperties',
 477       'authz-pam':                  'AuthZPAMProperties',
 478       'authz-simple':               'AuthZSimpleProperties',
 479       'cryptodev-backend':          'CryptodevBackendProperties',
 480       'cryptodev-backend-builtin':  'CryptodevBackendProperties',
 481       'cryptodev-vhost-user':       { 'type': 'CryptodevVhostUserProperties',
 482                                       'if': 'defined(CONFIG_VIRTIO_CRYPTO) && defined(CONFIG_VHOST_CRYPTO)' },
 483       'dbus-vmstate':               'DBusVMStateProperties',
 484       'iothread':                   'IothreadProperties',
 485       'memory-backend-file':        'MemoryBackendFileProperties',
 486       'memory-backend-memfd':       { 'type': 'MemoryBackendMemfdProperties',
 487                                       'if': 'defined(CONFIG_LINUX)' },
 488       'memory-backend-ram':         'MemoryBackendProperties',
 489       'rng-builtin':                'RngProperties',
 490       'rng-egd':                    'RngEgdProperties',
 491       'rng-random':                 'RngRandomProperties',
 492       'throttle-group':             'ThrottleGroupProperties'
 493   } }
 494
 495 ##
 496 # @object-add:
 497 #
 498 # Create a QOM object.
 499 #
 500 # @qom-type: the class name for the object to be created
 501 #
 502 # @id: the name of the new object
 503 #
 504 # Additional arguments depend on qom-type and are passed to the backend
 505 # unchanged.
 506 #
 507 # Returns: Nothing on success
 508 #          Error if @qom-type is not a valid class name
 509 #
 510 # Since: 2.0
 511 #
 512 # Example:
 513 #
 514 # -> { "execute": "object-add",
 515 #      "arguments": { "qom-type": "rng-random", "id": "rng1",
 516 #                     "filename": "/dev/hwrng" } }
 517 # <- { "return": {} }
 518 #
 519 ##
 520 { 'command': 'object-add',
 521   'data': {'qom-type': 'str', 'id': 'str'},
 522   'gen': false } # so we can get the additional arguments
 523
 524 ##
 525 # @object-del:
 526 #
 527 # Remove a QOM object.
 528 #
 529 # @id: the name of the QOM object to remove
 530 #
 531 # Returns: Nothing on success
 532 #          Error if @id is not a valid id for a QOM object
 533 #
 534 # Since: 2.0
 535 #
 536 # Example:
 537 #
 538 # -> { "execute": "object-del", "arguments": { "id": "rng1" } }
 539 # <- { "return": {} }
 540 #
 541 ##
 542 { 'command': 'object-del', 'data': {'id': 'str'} }