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