qapi/qom.json

   1 # -*- Mode: Python -*-
   2 #
   3 # This work is licensed under the terms of the GNU GPL, version 2 or later.
   4 # See the COPYING file in the top-level directory.
   5
   6 ##
   7 # = QEMU Object Model (QOM)
   8 ##
   9
  10 ##
  11 # @ObjectPropertyInfo:
  12 #
  13 # @name: the name of the property
  14 #
  15 # @type: the type of the property.  This will typically come in one of four
  16 #        forms:
  17 #
  18 #        1) A primitive type such as 'u8', 'u16', 'bool', 'str', or 'double'.
  19 #           These types are mapped to the appropriate JSON type.
  20 #
  21 #        2) A child type in the form 'child<subtype>' where subtype is a qdev
  22 #           device type name.  Child properties create the composition tree.
  23 #
  24 #        3) A link type in the form 'link<subtype>' where subtype is a qdev
  25 #           device type name.  Link properties form the device model graph.
  26 #
  27 # @description: if specified, the description of the property.
  28 #
  29 # @default-value: the default value, if any (since 5.0)
  30 #
  31 # Since: 1.2
  32 ##
  33 { 'struct': 'ObjectPropertyInfo',
  34   'data': { 'name': 'str',
  35             'type': 'str',
  36             '*description': 'str',
  37             '*default-value': 'any' } }
  38
  39 ##
  40 # @qom-list:
  41 #
  42 # This command will list any properties of a object given a path in the object
  43 # model.
  44 #
  45 # @path: the path within the object model.  See @qom-get for a description of
  46 #        this parameter.
  47 #
  48 # Returns: a list of @ObjectPropertyInfo that describe the properties of the
  49 #          object.
  50 #
  51 # Since: 1.2
  52 #
  53 # Example:
  54 #
  55 # -> { "execute": "qom-list",
  56 #      "arguments": { "path": "/chardevs" } }
  57 # <- { "return": [ { "name": "type", "type": "string" },
  58 #                  { "name": "parallel0", "type": "child<chardev-vc>" },
  59 #                  { "name": "serial0", "type": "child<chardev-vc>" },
  60 #                  { "name": "mon0", "type": "child<chardev-stdio>" } ] }
  61 #
  62 ##
  63 { 'command': 'qom-list',
  64   'data': { 'path': 'str' },
  65   'returns': [ 'ObjectPropertyInfo' ],
  66   'allow-preconfig': true }
  67
  68 ##
  69 # @qom-get:
  70 #
  71 # This command will get a property from a object model path and return the
  72 # value.
  73 #
  74 # @path: The path within the object model.  There are two forms of supported
  75 #        paths--absolute and partial paths.
  76 #
  77 #        Absolute paths are derived from the root object and can follow child<>
  78 #        or link<> properties.  Since they can follow link<> properties, they
  79 #        can be arbitrarily long.  Absolute paths look like absolute filenames
  80 #        and are prefixed  with a leading slash.
  81 #
  82 #        Partial paths look like relative filenames.  They do not begin
  83 #        with a prefix.  The matching rules for partial paths are subtle but
  84 #        designed to make specifying objects easy.  At each level of the
  85 #        composition tree, the partial path is matched as an absolute path.
  86 #        The first match is not returned.  At least two matches are searched
  87 #        for.  A successful result is only returned if only one match is
  88 #        found.  If more than one match is found, a flag is return to
  89 #        indicate that the match was ambiguous.
  90 #
  91 # @property: The property name to read
  92 #
  93 # Returns: The property value.  The type depends on the property
  94 #          type. child<> and link<> properties are returned as #str
  95 #          pathnames.  All integer property types (u8, u16, etc) are
  96 #          returned as #int.
  97 #
  98 # Since: 1.2
  99 #
 100 # Example:
 101 #
 102 # 1. Use absolute path
 103 #
 104 # -> { "execute": "qom-get",
 105 #      "arguments": { "path": "/machine/unattached/device[0]",
 106 #                     "property": "hotplugged" } }
 107 # <- { "return": false }
 108 #
 109 # 2. Use partial path
 110 #
 111 # -> { "execute": "qom-get",
 112 #      "arguments": { "path": "unattached/sysbus",
 113 #                     "property": "type" } }
 114 # <- { "return": "System" }
 115 #
 116 ##
 117 { 'command': 'qom-get',
 118   'data': { 'path': 'str', 'property': 'str' },
 119   'returns': 'any',
 120   'allow-preconfig': true }
 121
 122 ##
 123 # @qom-set:
 124 #
 125 # This command will set a property from a object model path.
 126 #
 127 # @path: see @qom-get for a description of this parameter
 128 #
 129 # @property: the property name to set
 130 #
 131 # @value: a value who's type is appropriate for the property type.  See @qom-get
 132 #         for a description of type mapping.
 133 #
 134 # Since: 1.2
 135 #
 136 # Example:
 137 #
 138 # -> { "execute": "qom-set",
 139 #      "arguments": { "path": "/machine",
 140 #                     "property": "graphics",
 141 #                     "value": false } }
 142 # <- { "return": {} }
 143 #
 144 ##
 145 { 'command': 'qom-set',
 146   'data': { 'path': 'str', 'property': 'str', 'value': 'any' },
 147   'allow-preconfig': true }
 148
 149 ##
 150 # @ObjectTypeInfo:
 151 #
 152 # This structure describes a search result from @qom-list-types
 153 #
 154 # @name: the type name found in the search
 155 #
 156 # @abstract: the type is abstract and can't be directly instantiated.
 157 #            Omitted if false. (since 2.10)
 158 #
 159 # @parent: Name of parent type, if any (since 2.10)
 160 #
 161 # Since: 1.1
 162 ##
 163 { 'struct': 'ObjectTypeInfo',
 164   'data': { 'name': 'str', '*abstract': 'bool', '*parent': 'str' } }
 165
 166 ##
 167 # @qom-list-types:
 168 #
 169 # This command will return a list of types given search parameters
 170 #
 171 # @implements: if specified, only return types that implement this type name
 172 #
 173 # @abstract: if true, include abstract types in the results
 174 #
 175 # Returns: a list of @ObjectTypeInfo or an empty list if no results are found
 176 #
 177 # Since: 1.1
 178 ##
 179 { 'command': 'qom-list-types',
 180   'data': { '*implements': 'str', '*abstract': 'bool' },
 181   'returns': [ 'ObjectTypeInfo' ],
 182   'allow-preconfig': true }
 183
 184 ##
 185 # @qom-list-properties:
 186 #
 187 # List properties associated with a QOM object.
 188 #
 189 # @typename: the type name of an object
 190 #
 191 # Note: objects can create properties at runtime, for example to describe
 192 #       links between different devices and/or objects. These properties
 193 #       are not included in the output of this command.
 194 #
 195 # Returns: a list of ObjectPropertyInfo describing object properties
 196 #
 197 # Since: 2.12
 198 ##
 199 { 'command': 'qom-list-properties',
 200   'data': { 'typename': 'str'},
 201   'returns': [ 'ObjectPropertyInfo' ],
 202   'allow-preconfig': true }
 203
 204 ##
 205 # @object-add:
 206 #
 207 # Create a QOM object.
 208 #
 209 # @qom-type: the class name for the object to be created
 210 #
 211 # @id: the name of the new object
 212 #
 213 # @props: a dictionary of properties to be passed to the backend. Deprecated
 214 #         since 5.0, specify the properties on the top level instead. It is an
 215 #         error to specify the same option both on the top level and in @props.
 216 #
 217 # Additional arguments depend on qom-type and are passed to the backend
 218 # unchanged.
 219 #
 220 # Returns: Nothing on success
 221 #          Error if @qom-type is not a valid class name
 222 #
 223 # Since: 2.0
 224 #
 225 # Example:
 226 #
 227 # -> { "execute": "object-add",
 228 #      "arguments": { "qom-type": "rng-random", "id": "rng1",
 229 #                     "filename": "/dev/hwrng" } }
 230 # <- { "return": {} }
 231 #
 232 ##
 233 { 'command': 'object-add',
 234   'data': {'qom-type': 'str', 'id': 'str', '*props': 'any'},
 235   'gen': false } # so we can get the additional arguments
 236
 237 ##
 238 # @object-del:
 239 #
 240 # Remove a QOM object.
 241 #
 242 # @id: the name of the QOM object to remove
 243 #
 244 # Returns: Nothing on success
 245 #          Error if @id is not a valid id for a QOM object
 246 #
 247 # Since: 2.0
 248 #
 249 # Example:
 250 #
 251 # -> { "execute": "object-del", "arguments": { "id": "rng1" } }
 252 # <- { "return": {} }
 253 #
 254 ##
 255 { 'command': 'object-del', 'data': {'id': 'str'} }