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