]>
Commit | Line | Data |
---|---|---|
c577ff62 | 1 | # -*- Mode: Python -*- |
f7160f32 | 2 | # vim: filetype=python |
c577ff62 MA |
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 | # | |
1bb3d7d9 MAL |
30 | # @default-value: the default value, if any (since 5.0) |
31 | # | |
c577ff62 MA |
32 | # Since: 1.2 |
33 | ## | |
34 | { 'struct': 'ObjectPropertyInfo', | |
1bb3d7d9 MAL |
35 | 'data': { 'name': 'str', |
36 | 'type': 'str', | |
37 | '*description': 'str', | |
38 | '*default-value': 'any' } } | |
c577ff62 MA |
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 | |
26ec4e53 PM |
193 | # links between different devices and/or objects. These properties |
194 | # are not included in the output of this command. | |
c577ff62 MA |
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 | # @object-add: | |
207 | # | |
208 | # Create a QOM object. | |
209 | # | |
210 | # @qom-type: the class name for the object to be created | |
211 | # | |
212 | # @id: the name of the new object | |
213 | # | |
5f07c4d6 KW |
214 | # @props: a dictionary of properties to be passed to the backend. Deprecated |
215 | # since 5.0, specify the properties on the top level instead. It is an | |
216 | # error to specify the same option both on the top level and in @props. | |
217 | # | |
218 | # Additional arguments depend on qom-type and are passed to the backend | |
219 | # unchanged. | |
c577ff62 MA |
220 | # |
221 | # Returns: Nothing on success | |
222 | # Error if @qom-type is not a valid class name | |
223 | # | |
224 | # Since: 2.0 | |
225 | # | |
226 | # Example: | |
227 | # | |
228 | # -> { "execute": "object-add", | |
229 | # "arguments": { "qom-type": "rng-random", "id": "rng1", | |
5f07c4d6 | 230 | # "filename": "/dev/hwrng" } } |
c577ff62 MA |
231 | # <- { "return": {} } |
232 | # | |
233 | ## | |
234 | { 'command': 'object-add', | |
5f07c4d6 KW |
235 | 'data': {'qom-type': 'str', 'id': 'str', '*props': 'any'}, |
236 | 'gen': false } # so we can get the additional arguments | |
c577ff62 MA |
237 | |
238 | ## | |
239 | # @object-del: | |
240 | # | |
241 | # Remove a QOM object. | |
242 | # | |
243 | # @id: the name of the QOM object to remove | |
244 | # | |
245 | # Returns: Nothing on success | |
246 | # Error if @id is not a valid id for a QOM object | |
247 | # | |
248 | # Since: 2.0 | |
249 | # | |
250 | # Example: | |
251 | # | |
252 | # -> { "execute": "object-del", "arguments": { "id": "rng1" } } | |
253 | # <- { "return": {} } | |
254 | # | |
255 | ## | |
256 | { 'command': 'object-del', 'data': {'id': 'str'} } |