target/riscv: vmfirst find-first-set mask bit
[qemu.git] / 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'} }