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
   9 ##
  10 # = QEMU Object Model (QOM)
  11 ##
  12
  13 ##
  14 # @ObjectPropertyInfo:
  15 #
  16 # @name: the name of the property
  17 #
  18 # @type: the type of the property.  This will typically come in one of four
  19 #        forms:
  20 #
  21 #        1) A primitive type such as 'u8', 'u16', 'bool', 'str', or 'double'.
  22 #           These types are mapped to the appropriate JSON type.
  23 #
  24 #        2) A child type in the form 'child<subtype>' where subtype is a qdev
  25 #           device type name.  Child properties create the composition tree.
  26 #
  27 #        3) A link type in the form 'link<subtype>' where subtype is a qdev
  28 #           device type name.  Link properties form the device model graph.
  29 #
  30 # @description: if specified, the description of the property.
  31 #
  32 # @default-value: the default value, if any (since 5.0)
  33 #
  34 # Since: 1.2
  35 ##
  36 { 'struct': 'ObjectPropertyInfo',
  37   'data': { 'name': 'str',
  38             'type': 'str',
  39             '*description': 'str',
  40             '*default-value': 'any' } }
  41
  42 ##
  43 # @qom-list:
  44 #
  45 # This command will list any properties of a object given a path in the object
  46 # model.
  47 #
  48 # @path: the path within the object model.  See @qom-get for a description of
  49 #        this parameter.
  50 #
  51 # Returns: a list of @ObjectPropertyInfo that describe the properties of the
  52 #          object.
  53 #
  54 # Since: 1.2
  55 #
  56 # Example:
  57 #
  58 # -> { "execute": "qom-list",
  59 #      "arguments": { "path": "/chardevs" } }
  60 # <- { "return": [ { "name": "type", "type": "string" },
  61 #                  { "name": "parallel0", "type": "child<chardev-vc>" },
  62 #                  { "name": "serial0", "type": "child<chardev-vc>" },
  63 #                  { "name": "mon0", "type": "child<chardev-stdio>" } ] }
  64 #
  65 ##
  66 { 'command': 'qom-list',
  67   'data': { 'path': 'str' },
  68   'returns': [ 'ObjectPropertyInfo' ],
  69   'allow-preconfig': true }
  70
  71 ##
  72 # @qom-get:
  73 #
  74 # This command will get a property from a object model path and return the
  75 # value.
  76 #
  77 # @path: The path within the object model.  There are two forms of supported
  78 #        paths--absolute and partial paths.
  79 #
  80 #        Absolute paths are derived from the root object and can follow child<>
  81 #        or link<> properties.  Since they can follow link<> properties, they
  82 #        can be arbitrarily long.  Absolute paths look like absolute filenames
  83 #        and are prefixed  with a leading slash.
  84 #
  85 #        Partial paths look like relative filenames.  They do not begin
  86 #        with a prefix.  The matching rules for partial paths are subtle but
  87 #        designed to make specifying objects easy.  At each level of the
  88 #        composition tree, the partial path is matched as an absolute path.
  89 #        The first match is not returned.  At least two matches are searched
  90 #        for.  A successful result is only returned if only one match is
  91 #        found.  If more than one match is found, a flag is return to
  92 #        indicate that the match was ambiguous.
  93 #
  94 # @property: The property name to read
  95 #
  96 # Returns: The property value.  The type depends on the property
  97 #          type. child<> and link<> properties are returned as #str
  98 #          pathnames.  All integer property types (u8, u16, etc) are
  99 #          returned as #int.
 100 #
 101 # Since: 1.2
 102 #
 103 # Example:
 104 #
 105 # 1. Use absolute path
 106 #
 107 # -> { "execute": "qom-get",
 108 #      "arguments": { "path": "/machine/unattached/device[0]",
 109 #                     "property": "hotplugged" } }
 110 # <- { "return": false }
 111 #
 112 # 2. Use partial path
 113 #
 114 # -> { "execute": "qom-get",
 115 #      "arguments": { "path": "unattached/sysbus",
 116 #                     "property": "type" } }
 117 # <- { "return": "System" }
 118 #
 119 ##
 120 { 'command': 'qom-get',
 121   'data': { 'path': 'str', 'property': 'str' },
 122   'returns': 'any',
 123   'allow-preconfig': true }
 124
 125 ##
 126 # @qom-set:
 127 #
 128 # This command will set a property from a object model path.
 129 #
 130 # @path: see @qom-get for a description of this parameter
 131 #
 132 # @property: the property name to set
 133 #
 134 # @value: a value who's type is appropriate for the property type.  See @qom-get
 135 #         for a description of type mapping.
 136 #
 137 # Since: 1.2
 138 #
 139 # Example:
 140 #
 141 # -> { "execute": "qom-set",
 142 #      "arguments": { "path": "/machine",
 143 #                     "property": "graphics",
 144 #                     "value": false } }
 145 # <- { "return": {} }
 146 #
 147 ##
 148 { 'command': 'qom-set',
 149   'data': { 'path': 'str', 'property': 'str', 'value': 'any' },
 150   'allow-preconfig': true }
 151
 152 ##
 153 # @ObjectTypeInfo:
 154 #
 155 # This structure describes a search result from @qom-list-types
 156 #
 157 # @name: the type name found in the search
 158 #
 159 # @abstract: the type is abstract and can't be directly instantiated.
 160 #            Omitted if false. (since 2.10)
 161 #
 162 # @parent: Name of parent type, if any (since 2.10)
 163 #
 164 # Since: 1.1
 165 ##
 166 { 'struct': 'ObjectTypeInfo',
 167   'data': { 'name': 'str', '*abstract': 'bool', '*parent': 'str' } }
 168
 169 ##
 170 # @qom-list-types:
 171 #
 172 # This command will return a list of types given search parameters
 173 #
 174 # @implements: if specified, only return types that implement this type name
 175 #
 176 # @abstract: if true, include abstract types in the results
 177 #
 178 # Returns: a list of @ObjectTypeInfo or an empty list if no results are found
 179 #
 180 # Since: 1.1
 181 ##
 182 { 'command': 'qom-list-types',
 183   'data': { '*implements': 'str', '*abstract': 'bool' },
 184   'returns': [ 'ObjectTypeInfo' ],
 185   'allow-preconfig': true }
 186
 187 ##
 188 # @qom-list-properties:
 189 #
 190 # List properties associated with a QOM object.
 191 #
 192 # @typename: the type name of an object
 193 #
 194 # Note: objects can create properties at runtime, for example to describe
 195 #       links between different devices and/or objects. These properties
 196 #       are not included in the output of this command.
 197 #
 198 # Returns: a list of ObjectPropertyInfo describing object properties
 199 #
 200 # Since: 2.12
 201 ##
 202 { 'command': 'qom-list-properties',
 203   'data': { 'typename': 'str'},
 204   'returns': [ 'ObjectPropertyInfo' ],
 205   'allow-preconfig': true }
 206
 207 ##
 208 # @IothreadProperties:
 209 #
 210 # Properties for iothread objects.
 211 #
 212 # @poll-max-ns: the maximum number of nanoseconds to busy wait for events.
 213 #               0 means polling is disabled (default: 32768 on POSIX hosts,
 214 #               0 otherwise)
 215 #
 216 # @poll-grow: the multiplier used to increase the polling time when the
 217 #             algorithm detects it is missing events due to not polling long
 218 #             enough. 0 selects a default behaviour (default: 0)
 219 #
 220 # @poll-shrink: the divisor used to decrease the polling time when the
 221 #               algorithm detects it is spending too long polling without
 222 #               encountering events. 0 selects a default behaviour (default: 0)
 223 #
 224 # Since: 2.0
 225 ##
 226 { 'struct': 'IothreadProperties',
 227   'data': { '*poll-max-ns': 'int',
 228             '*poll-grow': 'int',
 229             '*poll-shrink': 'int' } }
 230
 231 ##
 232 # @ObjectType:
 233 #
 234 # Since: 6.0
 235 ##
 236 { 'enum': 'ObjectType',
 237   'data': [
 238     'authz-list',
 239     'authz-listfile',
 240     'authz-pam',
 241     'authz-simple',
 242     'iothread'
 243   ] }
 244
 245 ##
 246 # @ObjectOptions:
 247 #
 248 # Describes the options of a user creatable QOM object.
 249 #
 250 # @qom-type: the class name for the object to be created
 251 #
 252 # @id: the name of the new object
 253 #
 254 # Since: 6.0
 255 ##
 256 { 'union': 'ObjectOptions',
 257   'base': { 'qom-type': 'ObjectType',
 258             'id': 'str' },
 259   'discriminator': 'qom-type',
 260   'data': {
 261       'authz-list':                 'AuthZListProperties',
 262       'authz-listfile':             'AuthZListFileProperties',
 263       'authz-pam':                  'AuthZPAMProperties',
 264       'authz-simple':               'AuthZSimpleProperties',
 265       'iothread':                   'IothreadProperties'
 266   } }
 267
 268 ##
 269 # @object-add:
 270 #
 271 # Create a QOM object.
 272 #
 273 # @qom-type: the class name for the object to be created
 274 #
 275 # @id: the name of the new object
 276 #
 277 # Additional arguments depend on qom-type and are passed to the backend
 278 # unchanged.
 279 #
 280 # Returns: Nothing on success
 281 #          Error if @qom-type is not a valid class name
 282 #
 283 # Since: 2.0
 284 #
 285 # Example:
 286 #
 287 # -> { "execute": "object-add",
 288 #      "arguments": { "qom-type": "rng-random", "id": "rng1",
 289 #                     "filename": "/dev/hwrng" } }
 290 # <- { "return": {} }
 291 #
 292 ##
 293 { 'command': 'object-add',
 294   'data': {'qom-type': 'str', 'id': 'str'},
 295   'gen': false } # so we can get the additional arguments
 296
 297 ##
 298 # @object-del:
 299 #
 300 # Remove a QOM object.
 301 #
 302 # @id: the name of the QOM object to remove
 303 #
 304 # Returns: Nothing on success
 305 #          Error if @id is not a valid id for a QOM object
 306 #
 307 # Since: 2.0
 308 #
 309 # Example:
 310 #
 311 # -> { "execute": "object-del", "arguments": { "id": "rng1" } }
 312 # <- { "return": {} }
 313 #
 314 ##
 315 { 'command': 'object-del', 'data': {'id': 'str'} }