qemu/qapi/qom.json

# -*- Mode: Python -*-
# vim: filetype=python
#
# This work is licensed under the terms of the GNU GPL, version 2 or later.
# See the COPYING file in the top-level directory.

{ 'include': 'authz.json' }
{ 'include': 'block-core.json' }
{ 'include': 'common.json' }
{ 'include': 'crypto.json' }

##
# = QEMU Object Model (QOM)
##

##
# @ObjectPropertyInfo:
#
# @name: the name of the property
#
# @type: the type of the property.  This will typically come in one of four
#        forms:
#
#        1) A primitive type such as 'u8', 'u16', 'bool', 'str', or 'double'.
#           These types are mapped to the appropriate JSON type.
#
#        2) A child type in the form 'child<subtype>' where subtype is a qdev
#           device type name.  Child properties create the composition tree.
#
#        3) A link type in the form 'link<subtype>' where subtype is a qdev
#           device type name.  Link properties form the device model graph.
#
# @description: if specified, the description of the property.
#
# @default-value: the default value, if any (since 5.0)
#
# Since: 1.2
##
{ 'struct': 'ObjectPropertyInfo',
  'data': { 'name': 'str',
            'type': 'str',
            '*description': 'str',
            '*default-value': 'any' } }

##
# @qom-list:
#
# This command will list any properties of a object given a path in the object
# model.
#
# @path: the path within the object model.  See @qom-get for a description of
#        this parameter.
#
# Returns: a list of @ObjectPropertyInfo that describe the properties of the
#          object.
#
# Since: 1.2
#
# Example:
#
# -> { "execute": "qom-list",
#      "arguments": { "path": "/chardevs" } }
# <- { "return": [ { "name": "type", "type": "string" },
#                  { "name": "parallel0", "type": "child<chardev-vc>" },
#                  { "name": "serial0", "type": "child<chardev-vc>" },
#                  { "name": "mon0", "type": "child<chardev-stdio>" } ] }
#
##
{ 'command': 'qom-list',
  'data': { 'path': 'str' },
  'returns': [ 'ObjectPropertyInfo' ],
  'allow-preconfig': true }

##
# @qom-get:
#
# This command will get a property from a object model path and return the
# value.
#
# @path: The path within the object model.  There are two forms of supported
#        paths--absolute and partial paths.
#
#        Absolute paths are derived from the root object and can follow child<>
#        or link<> properties.  Since they can follow link<> properties, they
#        can be arbitrarily long.  Absolute paths look like absolute filenames
#        and are prefixed  with a leading slash.
#
#        Partial paths look like relative filenames.  They do not begin
#        with a prefix.  The matching rules for partial paths are subtle but
#        designed to make specifying objects easy.  At each level of the
#        composition tree, the partial path is matched as an absolute path.
#        The first match is not returned.  At least two matches are searched
#        for.  A successful result is only returned if only one match is
#        found.  If more than one match is found, a flag is return to
#        indicate that the match was ambiguous.
#
# @property: The property name to read
#
# Returns: The property value.  The type depends on the property
#          type. child<> and link<> properties are returned as #str
#          pathnames.  All integer property types (u8, u16, etc) are
#          returned as #int.
#
# Since: 1.2
#
# Example:
#
# 1. Use absolute path
#
# -> { "execute": "qom-get",
#      "arguments": { "path": "/machine/unattached/device[0]",
#                     "property": "hotplugged" } }
# <- { "return": false }
#
# 2. Use partial path
#
# -> { "execute": "qom-get",
#      "arguments": { "path": "unattached/sysbus",
#                     "property": "type" } }
# <- { "return": "System" }
#
##
{ 'command': 'qom-get',
  'data': { 'path': 'str', 'property': 'str' },
  'returns': 'any',
  'allow-preconfig': true }

##
# @qom-set:
#
# This command will set a property from a object model path.
#
# @path: see @qom-get for a description of this parameter
#
# @property: the property name to set
#
# @value: a value who's type is appropriate for the property type.  See @qom-get
#         for a description of type mapping.
#
# Since: 1.2
#
# Example:
#
# -> { "execute": "qom-set",
#      "arguments": { "path": "/machine",
#                     "property": "graphics",
#                     "value": false } }
# <- { "return": {} }
#
##
{ 'command': 'qom-set',
  'data': { 'path': 'str', 'property': 'str', 'value': 'any' },
  'allow-preconfig': true }

##
# @ObjectTypeInfo:
#
# This structure describes a search result from @qom-list-types
#
# @name: the type name found in the search
#
# @abstract: the type is abstract and can't be directly instantiated.
#            Omitted if false. (since 2.10)
#
# @parent: Name of parent type, if any (since 2.10)
#
# Since: 1.1
##
{ 'struct': 'ObjectTypeInfo',
  'data': { 'name': 'str', '*abstract': 'bool', '*parent': 'str' } }

##
# @qom-list-types:
#
# This command will return a list of types given search parameters
#
# @implements: if specified, only return types that implement this type name
#
# @abstract: if true, include abstract types in the results
#
# Returns: a list of @ObjectTypeInfo or an empty list if no results are found
#
# Since: 1.1
##
{ 'command': 'qom-list-types',
  'data': { '*implements': 'str', '*abstract': 'bool' },
  'returns': [ 'ObjectTypeInfo' ],
  'allow-preconfig': true }

##
# @qom-list-properties:
#
# List properties associated with a QOM object.
#
# @typename: the type name of an object
#
# Note: objects can create properties at runtime, for example to describe
#       links between different devices and/or objects. These properties
#       are not included in the output of this command.
#
# Returns: a list of ObjectPropertyInfo describing object properties
#
# Since: 2.12
##
{ 'command': 'qom-list-properties',
  'data': { 'typename': 'str'},
  'returns': [ 'ObjectPropertyInfo' ],
  'allow-preconfig': true }

##
# @CanHostSocketcanProperties:
#
# Properties for can-host-socketcan objects.
#
# @if: interface name of the host system CAN bus to connect to
#
# @canbus: object ID of the can-bus object to connect to the host interface
#
# Since: 2.12
##
{ 'struct': 'CanHostSocketcanProperties',
  'data': { 'if': 'str',
            'canbus': 'str' } }

##
# @ColoCompareProperties:
#
# Properties for colo-compare objects.
#
# @primary_in: name of the character device backend to use for the primary
#              input (incoming packets are redirected to @outdev)
#
# @secondary_in: name of the character device backend to use for secondary
#                input (incoming packets are only compared to the input on
#                @primary_in and then dropped)
#
# @outdev: name of the character device backend to use for output
#
# @iothread: name of the iothread to run in
#
# @notify_dev: name of the character device backend to be used to communicate
#              with the remote colo-frame (only for Xen COLO)
#
# @compare_timeout: the maximum time to hold a packet from @primary_in for
#                   comparison with an incoming packet on @secondary_in in
#                   milliseconds (default: 3000)
#
# @expired_scan_cycle: the interval at which colo-compare checks whether
#                      packets from @primary have timed out, in milliseconds
#                      (default: 3000)
#
# @max_queue_size: the maximum number of packets to keep in the queue for
#                  comparing with incoming packets from @secondary_in.  If the
#                  queue is full and addtional packets are received, the
#                  addtional packets are dropped. (default: 1024)
#
# @vnet_hdr_support: if true, vnet header support is enabled (default: false)
#
# Since: 2.8
##
{ 'struct': 'ColoCompareProperties',
  'data': { 'primary_in': 'str',
            'secondary_in': 'str',
            'outdev': 'str',
            'iothread': 'str',
            '*notify_dev': 'str',
            '*compare_timeout': 'uint64',
            '*expired_scan_cycle': 'uint32',
            '*max_queue_size': 'uint32',
            '*vnet_hdr_support': 'bool' } }

##
# @CryptodevBackendProperties:
#
# Properties for cryptodev-backend and cryptodev-backend-builtin objects.
#
# @queues: the number of queues for the cryptodev backend. Ignored for
#          cryptodev-backend and must be 1 for cryptodev-backend-builtin.
#          (default: 1)
#
# Since: 2.8
##
{ 'struct': 'CryptodevBackendProperties',
  'data': { '*queues': 'uint32' } }

##
# @CryptodevVhostUserProperties:
#
# Properties for cryptodev-vhost-user objects.
#
# @chardev: the name of a Unix domain socket character device that connects to
#           the vhost-user server
#
# Since: 2.12
##
{ 'struct': 'CryptodevVhostUserProperties',
  'base': 'CryptodevBackendProperties',
  'data': { 'chardev': 'str' } }

##
# @DBusVMStateProperties:
#
# Properties for dbus-vmstate objects.
#
# @addr: the name of the DBus bus to connect to
#
# @id-list: a comma separated list of DBus IDs of helpers whose data should be
#           included in the VM state on migration
#
# Since: 5.0
##
{ 'struct': 'DBusVMStateProperties',
  'data': { 'addr': 'str' ,
            '*id-list': 'str' } }

##
# @NetfilterInsert:
#
# Indicates where to insert a netfilter relative to a given other filter.
#
# @before: insert before the specified filter
#
# @behind: insert behind the specified filter
#
# Since: 5.0
##
{ 'enum': 'NetfilterInsert',
  'data': [ 'before', 'behind' ] }

##
# @NetfilterProperties:
#
# Properties for objects of classes derived from netfilter.
#
# @netdev: id of the network device backend to filter
#
# @queue: indicates which queue(s) to filter (default: all)
#
# @status: indicates whether the filter is enabled ("on") or disabled ("off")
#          (default: "on")
#
# @position: specifies where the filter should be inserted in the filter list.
#            "head" means the filter is inserted at the head of the filter list,
#            before any existing filters.
#            "tail" means the filter is inserted at the tail of the filter list,
#            behind any existing filters (default).
#            "id=<id>" means the filter is inserted before or behind the filter
#            specified by <id>, depending on the @insert property.
#            (default: "tail")
#
# @insert: where to insert the filter relative to the filter given in @position.
#          Ignored if @position is "head" or "tail". (default: behind)
#
# Since: 2.5
##
{ 'struct': 'NetfilterProperties',
  'data': { 'netdev': 'str',
            '*queue': 'NetFilterDirection',
            '*status': 'str',
            '*position': 'str',
            '*insert': 'NetfilterInsert' } }

##
# @FilterBufferProperties:
#
# Properties for filter-buffer objects.
#
# @interval: a non-zero interval in microseconds.  All packets arriving in the
#            given interval are delayed until the end of the interval.
#
# Since: 2.5
##
{ 'struct': 'FilterBufferProperties',
  'base': 'NetfilterProperties',
  'data': { 'interval': 'uint32' } }

##
# @FilterDumpProperties:
#
# Properties for filter-dump objects.
#
# @file: the filename where the dumped packets should be stored
#
# @maxlen: maximum number of bytes in a packet that are stored (default: 65536)
#
# Since: 2.5
##
{ 'struct': 'FilterDumpProperties',
  'base': 'NetfilterProperties',
  'data': { 'file': 'str',
            '*maxlen': 'uint32' } }

##
# @FilterMirrorProperties:
#
# Properties for filter-mirror objects.
#
# @outdev: the name of a character device backend to which all incoming packets
#          are mirrored
#
# @vnet_hdr_support: if true, vnet header support is enabled (default: false)
#
# Since: 2.6
##
{ 'struct': 'FilterMirrorProperties',
  'base': 'NetfilterProperties',
  'data': { 'outdev': 'str',
            '*vnet_hdr_support': 'bool' } }

##
# @FilterRedirectorProperties:
#
# Properties for filter-redirector objects.
#
# At least one of @indev or @outdev must be present.  If both are present, they
# must not refer to the same character device backend.
#
# @indev: the name of a character device backend from which packets are
#         received and redirected to the filtered network device
#
# @outdev: the name of a character device backend to which all incoming packets
#          are redirected
#
# @vnet_hdr_support: if true, vnet header support is enabled (default: false)
#
# Since: 2.6
##
{ 'struct': 'FilterRedirectorProperties',
  'base': 'NetfilterProperties',
  'data': { '*indev': 'str',
            '*outdev': 'str',
            '*vnet_hdr_support': 'bool' } }

##
# @FilterRewriterProperties:
#
# Properties for filter-rewriter objects.
#
# @vnet_hdr_support: if true, vnet header support is enabled (default: false)
#
# Since: 2.8
##
{ 'struct': 'FilterRewriterProperties',
  'base': 'NetfilterProperties',
  'data': { '*vnet_hdr_support': 'bool' } }

##
# @IothreadProperties:
#
# Properties for iothread objects.
#
# @poll-max-ns: the maximum number of nanoseconds to busy wait for events.
#               0 means polling is disabled (default: 32768 on POSIX hosts,
#               0 otherwise)
#
# @poll-grow: the multiplier used to increase the polling time when the
#             algorithm detects it is missing events due to not polling long
#             enough. 0 selects a default behaviour (default: 0)
#
# @poll-shrink: the divisor used to decrease the polling time when the
#               algorithm detects it is spending too long polling without
#               encountering events. 0 selects a default behaviour (default: 0)
#
# Since: 2.0
##
{ 'struct': 'IothreadProperties',
  'data': { '*poll-max-ns': 'int',
            '*poll-grow': 'int',
            '*poll-shrink': 'int' } }

##
# @MemoryBackendProperties:
#
# Properties for objects of classes derived from memory-backend.
#
# @merge: if true, mark the memory as mergeable (default depends on the machine
#         type)
#
# @dump: if true, include the memory in core dumps (default depends on the
#        machine type)
#
# @host-nodes: the list of NUMA host nodes to bind the memory to
#
# @policy: the NUMA policy (default: 'default')
#
# @prealloc: if true, preallocate memory (default: false)
#
# @prealloc-threads: number of CPU threads to use for prealloc (default: 1)
#
# @share: if false, the memory is private to QEMU; if true, it is shared
#         (default: false)
#
# @size: size of the memory region in bytes
#
# @x-use-canonical-path-for-ramblock-id: if true, the canoncial path is used
#                                        for ramblock-id. Disable this for 4.0
#                                        machine types or older to allow
#                                        migration with newer QEMU versions.
#                                        This option is considered stable
#                                        despite the x- prefix. (default:
#                                        false generally, but true for machine
#                                        types <= 4.0)
#
# Since: 2.1
##
{ 'struct': 'MemoryBackendProperties',
  'data': { '*dump': 'bool',
            '*host-nodes': ['uint16'],
            '*merge': 'bool',
            '*policy': 'HostMemPolicy',
            '*prealloc': 'bool',
            '*prealloc-threads': 'uint32',
            '*share': 'bool',
            'size': 'size',
            '*x-use-canonical-path-for-ramblock-id': 'bool' } }

##
# @MemoryBackendFileProperties:
#
# Properties for memory-backend-file objects.
#
# @align: the base address alignment when QEMU mmap(2)s @mem-path. Some
#         backend stores specified by @mem-path require an alignment different
#         than the default one used by QEMU, e.g. the device DAX /dev/dax0.0
#         requires 2M alignment rather than 4K. In such cases, users can
#         specify the required alignment via this option.
#         0 selects a default alignment (currently the page size). (default: 0)
#
# @discard-data: if true, the file contents can be destroyed when QEMU exits,
#                to avoid unnecessarily flushing data to the backing file. Note
#                that ``discard-data`` is only an optimization, and QEMU might
#                not discard file contents if it aborts unexpectedly or is
#                terminated using SIGKILL. (default: false)
#
# @mem-path: the path to either a shared memory or huge page filesystem mount
#
# @pmem: specifies whether the backing file specified by @mem-path is in
#        host persistent memory that can be accessed using the SNIA NVM
#        programming model (e.g. Intel NVDIMM).
#
# @readonly: if true, the backing file is opened read-only; if false, it is
#            opened read-write. (default: false)
#
# Since: 2.1
##
{ 'struct': 'MemoryBackendFileProperties',
  'base': 'MemoryBackendProperties',
  'data': { '*align': 'size',
            '*discard-data': 'bool',
            'mem-path': 'str',
            '*pmem': { 'type': 'bool', 'if': 'defined(CONFIG_LIBPMEM)' },
            '*readonly': 'bool' } }

##
# @MemoryBackendMemfdProperties:
#
# Properties for memory-backend-memfd objects.
#
# The @share boolean option is true by default with memfd.
#
# @hugetlb: if true, the file to be created resides in the hugetlbfs filesystem
#           (default: false)
#
# @hugetlbsize: the hugetlb page size on systems that support multiple hugetlb
#               page sizes (it must be a power of 2 value supported by the
#               system). 0 selects a default page size. This option is ignored
#               if @hugetlb is false. (default: 0)
#
# @seal: if true, create a sealed-file, which will block further resizing of
#        the memory (default: true)
#
# Since: 2.12
##
{ 'struct': 'MemoryBackendMemfdProperties',
  'base': 'MemoryBackendProperties',
  'data': { '*hugetlb': 'bool',
            '*hugetlbsize': 'size',
            '*seal': 'bool' } }

##
# @RngProperties:
#
# Properties for objects of classes derived from rng.
#
# @opened: if true, the device is opened immediately when applying this option
#          and will probably fail when processing the next option. Don't use;
#          only provided for compatibility. (default: false)
#
# Features:
# @deprecated: Member @opened is deprecated.  Setting true doesn't make sense,
#              and false is already the default.
#
# Since: 1.3
##
{ 'struct': 'RngProperties',
  'data': { '*opened': { 'type': 'bool', 'features': ['deprecated'] } } }

##
# @RngEgdProperties:
#
# Properties for rng-egd objects.
#
# @chardev: the name of a character device backend that provides the connection
#           to the RNG daemon
#
# Since: 1.3
##
{ 'struct': 'RngEgdProperties',
  'base': 'RngProperties',
  'data': { 'chardev': 'str' } }

##
# @RngRandomProperties:
#
# Properties for rng-random objects.
#
# @filename: the filename of the device on the host to obtain entropy from
#            (default: "/dev/urandom")
#
# Since: 1.3
##
{ 'struct': 'RngRandomProperties',
  'base': 'RngProperties',
  'data': { '*filename': 'str' } }

##
# @ObjectType:
#
# Since: 6.0
##
{ 'enum': 'ObjectType',
  'data': [
    'authz-list',
    'authz-listfile',
    'authz-pam',
    'authz-simple',
    'can-bus',
    'can-host-socketcan',
    'colo-compare',
    'cryptodev-backend',
    'cryptodev-backend-builtin',
    { 'name': 'cryptodev-vhost-user',
      'if': 'defined(CONFIG_VIRTIO_CRYPTO) && defined(CONFIG_VHOST_CRYPTO)' },
    'dbus-vmstate',
    'filter-buffer',
    'filter-dump',
    'filter-mirror',
    'filter-redirector',
    'filter-replay',
    'filter-rewriter',
    'iothread',
    'memory-backend-file',
    { 'name': 'memory-backend-memfd',
      'if': 'defined(CONFIG_LINUX)' },
    'memory-backend-ram',
    'rng-builtin',
    'rng-egd',
    'rng-random',
    'secret',
    'secret_keyring',
    'throttle-group',
    'tls-creds-anon',
    'tls-creds-psk',
    'tls-creds-x509',
    'tls-cipher-suites'
  ] }

##
# @ObjectOptions:
#
# Describes the options of a user creatable QOM object.
#
# @qom-type: the class name for the object to be created
#
# @id: the name of the new object
#
# Since: 6.0
##
{ 'union': 'ObjectOptions',
  'base': { 'qom-type': 'ObjectType',
            'id': 'str' },
  'discriminator': 'qom-type',
  'data': {
      'authz-list':                 'AuthZListProperties',
      'authz-listfile':             'AuthZListFileProperties',
      'authz-pam':                  'AuthZPAMProperties',
      'authz-simple':               'AuthZSimpleProperties',
      'can-host-socketcan':         'CanHostSocketcanProperties',
      'colo-compare':               'ColoCompareProperties',
      'cryptodev-backend':          'CryptodevBackendProperties',
      'cryptodev-backend-builtin':  'CryptodevBackendProperties',
      'cryptodev-vhost-user':       { 'type': 'CryptodevVhostUserProperties',
                                      'if': 'defined(CONFIG_VIRTIO_CRYPTO) && defined(CONFIG_VHOST_CRYPTO)' },
      'dbus-vmstate':               'DBusVMStateProperties',
      'filter-buffer':              'FilterBufferProperties',
      'filter-dump':                'FilterDumpProperties',
      'filter-mirror':              'FilterMirrorProperties',
      'filter-redirector':          'FilterRedirectorProperties',
      'filter-replay':              'NetfilterProperties',
      'filter-rewriter':            'FilterRewriterProperties',
      'iothread':                   'IothreadProperties',
      'memory-backend-file':        'MemoryBackendFileProperties',
      'memory-backend-memfd':       { 'type': 'MemoryBackendMemfdProperties',
                                      'if': 'defined(CONFIG_LINUX)' },
      'memory-backend-ram':         'MemoryBackendProperties',
      'rng-builtin':                'RngProperties',
      'rng-egd':                    'RngEgdProperties',
      'rng-random':                 'RngRandomProperties',
      'secret':                     'SecretProperties',
      'secret_keyring':             'SecretKeyringProperties',
      'throttle-group':             'ThrottleGroupProperties',
      'tls-creds-anon':             'TlsCredsAnonProperties',
      'tls-creds-psk':              'TlsCredsPskProperties',
      'tls-creds-x509':             'TlsCredsX509Properties',
      'tls-cipher-suites':          'TlsCredsProperties'
  } }

##
# @object-add:
#
# Create a QOM object.
#
# @qom-type: the class name for the object to be created
#
# @id: the name of the new object
#
# Additional arguments depend on qom-type and are passed to the backend
# unchanged.
#
# Returns: Nothing on success
#          Error if @qom-type is not a valid class name
#
# Since: 2.0
#
# Example:
#
# -> { "execute": "object-add",
#      "arguments": { "qom-type": "rng-random", "id": "rng1",
#                     "filename": "/dev/hwrng" } }
# <- { "return": {} }
#
##
{ 'command': 'object-add',
  'data': {'qom-type': 'str', 'id': 'str'},
  'gen': false } # so we can get the additional arguments

##
# @object-del:
#
# Remove a QOM object.
#
# @id: the name of the QOM object to remove
#
# Returns: Nothing on success
#          Error if @id is not a valid id for a QOM object
#
# Since: 2.0
#
# Example:
#
# -> { "execute": "object-del", "arguments": { "id": "rng1" } }
# <- { "return": {} }
#
##
{ 'command': 'object-del', 'data': {'id': 'str'} }