# -*- 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. ## # = 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 } ## # @object-add: # # Create a QOM object. # # @qom-type: the class name for the object to be created # # @id: the name of the new object # # @props: a dictionary of properties to be passed to the backend. Deprecated # since 5.0, specify the properties on the top level instead. It is an # error to specify the same option both on the top level and in @props. # # 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', '*props': 'any'}, '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'} }