]>
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 | ||
8825587b | 7 | { 'include': 'authz.json' } |
381bd744 | 8 | { 'include': 'block-core.json' } |
913d9063 | 9 | { 'include': 'common.json' } |
39c4c27d | 10 | { 'include': 'crypto.json' } |
8825587b | 11 | |
c577ff62 MA |
12 | ## |
13 | # = QEMU Object Model (QOM) | |
14 | ## | |
15 | ||
16 | ## | |
17 | # @ObjectPropertyInfo: | |
18 | # | |
19 | # @name: the name of the property | |
20 | # | |
21 | # @type: the type of the property. This will typically come in one of four | |
22 | # forms: | |
23 | # | |
24 | # 1) A primitive type such as 'u8', 'u16', 'bool', 'str', or 'double'. | |
25 | # These types are mapped to the appropriate JSON type. | |
26 | # | |
27 | # 2) A child type in the form 'child<subtype>' where subtype is a qdev | |
28 | # device type name. Child properties create the composition tree. | |
29 | # | |
30 | # 3) A link type in the form 'link<subtype>' where subtype is a qdev | |
31 | # device type name. Link properties form the device model graph. | |
32 | # | |
33 | # @description: if specified, the description of the property. | |
34 | # | |
1bb3d7d9 MAL |
35 | # @default-value: the default value, if any (since 5.0) |
36 | # | |
c577ff62 MA |
37 | # Since: 1.2 |
38 | ## | |
39 | { 'struct': 'ObjectPropertyInfo', | |
1bb3d7d9 MAL |
40 | 'data': { 'name': 'str', |
41 | 'type': 'str', | |
42 | '*description': 'str', | |
43 | '*default-value': 'any' } } | |
c577ff62 MA |
44 | |
45 | ## | |
46 | # @qom-list: | |
47 | # | |
48 | # This command will list any properties of a object given a path in the object | |
49 | # model. | |
50 | # | |
51 | # @path: the path within the object model. See @qom-get for a description of | |
52 | # this parameter. | |
53 | # | |
54 | # Returns: a list of @ObjectPropertyInfo that describe the properties of the | |
55 | # object. | |
56 | # | |
57 | # Since: 1.2 | |
58 | # | |
59 | # Example: | |
60 | # | |
61 | # -> { "execute": "qom-list", | |
62 | # "arguments": { "path": "/chardevs" } } | |
63 | # <- { "return": [ { "name": "type", "type": "string" }, | |
64 | # { "name": "parallel0", "type": "child<chardev-vc>" }, | |
65 | # { "name": "serial0", "type": "child<chardev-vc>" }, | |
66 | # { "name": "mon0", "type": "child<chardev-stdio>" } ] } | |
67 | # | |
68 | ## | |
69 | { 'command': 'qom-list', | |
70 | 'data': { 'path': 'str' }, | |
71 | 'returns': [ 'ObjectPropertyInfo' ], | |
72 | 'allow-preconfig': true } | |
73 | ||
74 | ## | |
75 | # @qom-get: | |
76 | # | |
77 | # This command will get a property from a object model path and return the | |
78 | # value. | |
79 | # | |
80 | # @path: The path within the object model. There are two forms of supported | |
81 | # paths--absolute and partial paths. | |
82 | # | |
83 | # Absolute paths are derived from the root object and can follow child<> | |
84 | # or link<> properties. Since they can follow link<> properties, they | |
85 | # can be arbitrarily long. Absolute paths look like absolute filenames | |
86 | # and are prefixed with a leading slash. | |
87 | # | |
88 | # Partial paths look like relative filenames. They do not begin | |
89 | # with a prefix. The matching rules for partial paths are subtle but | |
90 | # designed to make specifying objects easy. At each level of the | |
91 | # composition tree, the partial path is matched as an absolute path. | |
92 | # The first match is not returned. At least two matches are searched | |
93 | # for. A successful result is only returned if only one match is | |
94 | # found. If more than one match is found, a flag is return to | |
95 | # indicate that the match was ambiguous. | |
96 | # | |
97 | # @property: The property name to read | |
98 | # | |
99 | # Returns: The property value. The type depends on the property | |
100 | # type. child<> and link<> properties are returned as #str | |
101 | # pathnames. All integer property types (u8, u16, etc) are | |
102 | # returned as #int. | |
103 | # | |
104 | # Since: 1.2 | |
105 | # | |
106 | # Example: | |
107 | # | |
108 | # 1. Use absolute path | |
109 | # | |
110 | # -> { "execute": "qom-get", | |
111 | # "arguments": { "path": "/machine/unattached/device[0]", | |
112 | # "property": "hotplugged" } } | |
113 | # <- { "return": false } | |
114 | # | |
115 | # 2. Use partial path | |
116 | # | |
117 | # -> { "execute": "qom-get", | |
118 | # "arguments": { "path": "unattached/sysbus", | |
119 | # "property": "type" } } | |
120 | # <- { "return": "System" } | |
121 | # | |
122 | ## | |
123 | { 'command': 'qom-get', | |
124 | 'data': { 'path': 'str', 'property': 'str' }, | |
125 | 'returns': 'any', | |
126 | 'allow-preconfig': true } | |
127 | ||
128 | ## | |
129 | # @qom-set: | |
130 | # | |
131 | # This command will set a property from a object model path. | |
132 | # | |
133 | # @path: see @qom-get for a description of this parameter | |
134 | # | |
135 | # @property: the property name to set | |
136 | # | |
137 | # @value: a value who's type is appropriate for the property type. See @qom-get | |
138 | # for a description of type mapping. | |
139 | # | |
140 | # Since: 1.2 | |
141 | # | |
142 | # Example: | |
143 | # | |
144 | # -> { "execute": "qom-set", | |
145 | # "arguments": { "path": "/machine", | |
146 | # "property": "graphics", | |
147 | # "value": false } } | |
148 | # <- { "return": {} } | |
149 | # | |
150 | ## | |
151 | { 'command': 'qom-set', | |
152 | 'data': { 'path': 'str', 'property': 'str', 'value': 'any' }, | |
153 | 'allow-preconfig': true } | |
154 | ||
155 | ## | |
156 | # @ObjectTypeInfo: | |
157 | # | |
158 | # This structure describes a search result from @qom-list-types | |
159 | # | |
160 | # @name: the type name found in the search | |
161 | # | |
162 | # @abstract: the type is abstract and can't be directly instantiated. | |
163 | # Omitted if false. (since 2.10) | |
164 | # | |
165 | # @parent: Name of parent type, if any (since 2.10) | |
166 | # | |
167 | # Since: 1.1 | |
168 | ## | |
169 | { 'struct': 'ObjectTypeInfo', | |
170 | 'data': { 'name': 'str', '*abstract': 'bool', '*parent': 'str' } } | |
171 | ||
172 | ## | |
173 | # @qom-list-types: | |
174 | # | |
175 | # This command will return a list of types given search parameters | |
176 | # | |
177 | # @implements: if specified, only return types that implement this type name | |
178 | # | |
179 | # @abstract: if true, include abstract types in the results | |
180 | # | |
181 | # Returns: a list of @ObjectTypeInfo or an empty list if no results are found | |
182 | # | |
183 | # Since: 1.1 | |
184 | ## | |
185 | { 'command': 'qom-list-types', | |
186 | 'data': { '*implements': 'str', '*abstract': 'bool' }, | |
187 | 'returns': [ 'ObjectTypeInfo' ], | |
188 | 'allow-preconfig': true } | |
189 | ||
190 | ## | |
191 | # @qom-list-properties: | |
192 | # | |
193 | # List properties associated with a QOM object. | |
194 | # | |
195 | # @typename: the type name of an object | |
196 | # | |
197 | # Note: objects can create properties at runtime, for example to describe | |
26ec4e53 PM |
198 | # links between different devices and/or objects. These properties |
199 | # are not included in the output of this command. | |
c577ff62 MA |
200 | # |
201 | # Returns: a list of ObjectPropertyInfo describing object properties | |
202 | # | |
203 | # Since: 2.12 | |
204 | ## | |
205 | { 'command': 'qom-list-properties', | |
206 | 'data': { 'typename': 'str'}, | |
207 | 'returns': [ 'ObjectPropertyInfo' ], | |
208 | 'allow-preconfig': true } | |
209 | ||
a68d909e KW |
210 | ## |
211 | # @CryptodevBackendProperties: | |
212 | # | |
213 | # Properties for cryptodev-backend and cryptodev-backend-builtin objects. | |
214 | # | |
215 | # @queues: the number of queues for the cryptodev backend. Ignored for | |
216 | # cryptodev-backend and must be 1 for cryptodev-backend-builtin. | |
217 | # (default: 1) | |
218 | # | |
219 | # Since: 2.8 | |
220 | ## | |
221 | { 'struct': 'CryptodevBackendProperties', | |
222 | 'data': { '*queues': 'uint32' } } | |
223 | ||
224 | ## | |
225 | # @CryptodevVhostUserProperties: | |
226 | # | |
227 | # Properties for cryptodev-vhost-user objects. | |
228 | # | |
229 | # @chardev: the name of a Unix domain socket character device that connects to | |
230 | # the vhost-user server | |
231 | # | |
232 | # Since: 2.12 | |
233 | ## | |
234 | { 'struct': 'CryptodevVhostUserProperties', | |
235 | 'base': 'CryptodevBackendProperties', | |
236 | 'data': { 'chardev': 'str' } } | |
237 | ||
d7ef29c4 KW |
238 | ## |
239 | # @DBusVMStateProperties: | |
240 | # | |
241 | # Properties for dbus-vmstate objects. | |
242 | # | |
243 | # @addr: the name of the DBus bus to connect to | |
244 | # | |
245 | # @id-list: a comma separated list of DBus IDs of helpers whose data should be | |
246 | # included in the VM state on migration | |
247 | # | |
248 | # Since: 5.0 | |
249 | ## | |
250 | { 'struct': 'DBusVMStateProperties', | |
251 | 'data': { 'addr': 'str' , | |
252 | '*id-list': 'str' } } | |
253 | ||
2273b241 KW |
254 | ## |
255 | # @IothreadProperties: | |
256 | # | |
257 | # Properties for iothread objects. | |
258 | # | |
259 | # @poll-max-ns: the maximum number of nanoseconds to busy wait for events. | |
260 | # 0 means polling is disabled (default: 32768 on POSIX hosts, | |
261 | # 0 otherwise) | |
262 | # | |
263 | # @poll-grow: the multiplier used to increase the polling time when the | |
264 | # algorithm detects it is missing events due to not polling long | |
265 | # enough. 0 selects a default behaviour (default: 0) | |
266 | # | |
267 | # @poll-shrink: the divisor used to decrease the polling time when the | |
268 | # algorithm detects it is spending too long polling without | |
269 | # encountering events. 0 selects a default behaviour (default: 0) | |
270 | # | |
271 | # Since: 2.0 | |
272 | ## | |
273 | { 'struct': 'IothreadProperties', | |
274 | 'data': { '*poll-max-ns': 'int', | |
275 | '*poll-grow': 'int', | |
276 | '*poll-shrink': 'int' } } | |
277 | ||
913d9063 KW |
278 | ## |
279 | # @MemoryBackendProperties: | |
280 | # | |
281 | # Properties for objects of classes derived from memory-backend. | |
282 | # | |
283 | # @merge: if true, mark the memory as mergeable (default depends on the machine | |
284 | # type) | |
285 | # | |
286 | # @dump: if true, include the memory in core dumps (default depends on the | |
287 | # machine type) | |
288 | # | |
289 | # @host-nodes: the list of NUMA host nodes to bind the memory to | |
290 | # | |
291 | # @policy: the NUMA policy (default: 'default') | |
292 | # | |
293 | # @prealloc: if true, preallocate memory (default: false) | |
294 | # | |
295 | # @prealloc-threads: number of CPU threads to use for prealloc (default: 1) | |
296 | # | |
297 | # @share: if false, the memory is private to QEMU; if true, it is shared | |
298 | # (default: false) | |
299 | # | |
300 | # @size: size of the memory region in bytes | |
301 | # | |
302 | # @x-use-canonical-path-for-ramblock-id: if true, the canoncial path is used | |
303 | # for ramblock-id. Disable this for 4.0 | |
304 | # machine types or older to allow | |
305 | # migration with newer QEMU versions. | |
306 | # This option is considered stable | |
307 | # despite the x- prefix. (default: | |
308 | # false generally, but true for machine | |
309 | # types <= 4.0) | |
310 | # | |
311 | # Since: 2.1 | |
312 | ## | |
313 | { 'struct': 'MemoryBackendProperties', | |
314 | 'data': { '*dump': 'bool', | |
315 | '*host-nodes': ['uint16'], | |
316 | '*merge': 'bool', | |
317 | '*policy': 'HostMemPolicy', | |
318 | '*prealloc': 'bool', | |
319 | '*prealloc-threads': 'uint32', | |
320 | '*share': 'bool', | |
321 | 'size': 'size', | |
322 | '*x-use-canonical-path-for-ramblock-id': 'bool' } } | |
323 | ||
324 | ## | |
325 | # @MemoryBackendFileProperties: | |
326 | # | |
327 | # Properties for memory-backend-file objects. | |
328 | # | |
329 | # @align: the base address alignment when QEMU mmap(2)s @mem-path. Some | |
330 | # backend stores specified by @mem-path require an alignment different | |
331 | # than the default one used by QEMU, e.g. the device DAX /dev/dax0.0 | |
332 | # requires 2M alignment rather than 4K. In such cases, users can | |
333 | # specify the required alignment via this option. | |
334 | # 0 selects a default alignment (currently the page size). (default: 0) | |
335 | # | |
336 | # @discard-data: if true, the file contents can be destroyed when QEMU exits, | |
337 | # to avoid unnecessarily flushing data to the backing file. Note | |
338 | # that ``discard-data`` is only an optimization, and QEMU might | |
339 | # not discard file contents if it aborts unexpectedly or is | |
340 | # terminated using SIGKILL. (default: false) | |
341 | # | |
342 | # @mem-path: the path to either a shared memory or huge page filesystem mount | |
343 | # | |
344 | # @pmem: specifies whether the backing file specified by @mem-path is in | |
345 | # host persistent memory that can be accessed using the SNIA NVM | |
346 | # programming model (e.g. Intel NVDIMM). | |
347 | # | |
348 | # @readonly: if true, the backing file is opened read-only; if false, it is | |
349 | # opened read-write. (default: false) | |
350 | # | |
351 | # Since: 2.1 | |
352 | ## | |
353 | { 'struct': 'MemoryBackendFileProperties', | |
354 | 'base': 'MemoryBackendProperties', | |
355 | 'data': { '*align': 'size', | |
356 | '*discard-data': 'bool', | |
357 | 'mem-path': 'str', | |
358 | '*pmem': { 'type': 'bool', 'if': 'defined(CONFIG_LIBPMEM)' }, | |
359 | '*readonly': 'bool' } } | |
360 | ||
361 | ## | |
362 | # @MemoryBackendMemfdProperties: | |
363 | # | |
364 | # Properties for memory-backend-memfd objects. | |
365 | # | |
366 | # The @share boolean option is true by default with memfd. | |
367 | # | |
368 | # @hugetlb: if true, the file to be created resides in the hugetlbfs filesystem | |
369 | # (default: false) | |
370 | # | |
371 | # @hugetlbsize: the hugetlb page size on systems that support multiple hugetlb | |
372 | # page sizes (it must be a power of 2 value supported by the | |
373 | # system). 0 selects a default page size. This option is ignored | |
374 | # if @hugetlb is false. (default: 0) | |
375 | # | |
376 | # @seal: if true, create a sealed-file, which will block further resizing of | |
377 | # the memory (default: true) | |
378 | # | |
379 | # Since: 2.12 | |
380 | ## | |
381 | { 'struct': 'MemoryBackendMemfdProperties', | |
382 | 'base': 'MemoryBackendProperties', | |
383 | 'data': { '*hugetlb': 'bool', | |
384 | '*hugetlbsize': 'size', | |
385 | '*seal': 'bool' } } | |
386 | ||
6815bc1d KW |
387 | ## |
388 | # @RngProperties: | |
389 | # | |
390 | # Properties for objects of classes derived from rng. | |
391 | # | |
392 | # @opened: if true, the device is opened immediately when applying this option | |
393 | # and will probably fail when processing the next option. Don't use; | |
394 | # only provided for compatibility. (default: false) | |
395 | # | |
396 | # Features: | |
397 | # @deprecated: Member @opened is deprecated. Setting true doesn't make sense, | |
398 | # and false is already the default. | |
399 | # | |
400 | # Since: 1.3 | |
401 | ## | |
402 | { 'struct': 'RngProperties', | |
403 | 'data': { '*opened': { 'type': 'bool', 'features': ['deprecated'] } } } | |
404 | ||
405 | ## | |
406 | # @RngEgdProperties: | |
407 | # | |
408 | # Properties for rng-egd objects. | |
409 | # | |
410 | # @chardev: the name of a character device backend that provides the connection | |
411 | # to the RNG daemon | |
412 | # | |
413 | # Since: 1.3 | |
414 | ## | |
415 | { 'struct': 'RngEgdProperties', | |
416 | 'base': 'RngProperties', | |
417 | 'data': { 'chardev': 'str' } } | |
418 | ||
419 | ## | |
420 | # @RngRandomProperties: | |
421 | # | |
422 | # Properties for rng-random objects. | |
423 | # | |
424 | # @filename: the filename of the device on the host to obtain entropy from | |
425 | # (default: "/dev/urandom") | |
426 | # | |
427 | # Since: 1.3 | |
428 | ## | |
429 | { 'struct': 'RngRandomProperties', | |
430 | 'base': 'RngProperties', | |
431 | 'data': { '*filename': 'str' } } | |
432 | ||
2273b241 KW |
433 | ## |
434 | # @ObjectType: | |
435 | # | |
436 | # Since: 6.0 | |
437 | ## | |
438 | { 'enum': 'ObjectType', | |
439 | 'data': [ | |
8825587b KW |
440 | 'authz-list', |
441 | 'authz-listfile', | |
442 | 'authz-pam', | |
443 | 'authz-simple', | |
a68d909e KW |
444 | 'cryptodev-backend', |
445 | 'cryptodev-backend-builtin', | |
446 | { 'name': 'cryptodev-vhost-user', | |
447 | 'if': 'defined(CONFIG_VIRTIO_CRYPTO) && defined(CONFIG_VHOST_CRYPTO)' }, | |
d7ef29c4 | 448 | 'dbus-vmstate', |
913d9063 KW |
449 | 'iothread', |
450 | 'memory-backend-file', | |
451 | { 'name': 'memory-backend-memfd', | |
452 | 'if': 'defined(CONFIG_LINUX)' }, | |
6815bc1d KW |
453 | 'memory-backend-ram', |
454 | 'rng-builtin', | |
455 | 'rng-egd', | |
381bd744 | 456 | 'rng-random', |
39c4c27d KW |
457 | 'secret', |
458 | 'secret_keyring', | |
d09e4937 KW |
459 | 'throttle-group', |
460 | 'tls-creds-anon', | |
461 | 'tls-creds-psk', | |
462 | 'tls-creds-x509', | |
463 | 'tls-cipher-suites' | |
2273b241 KW |
464 | ] } |
465 | ||
466 | ## | |
467 | # @ObjectOptions: | |
468 | # | |
469 | # Describes the options of a user creatable QOM object. | |
470 | # | |
471 | # @qom-type: the class name for the object to be created | |
472 | # | |
473 | # @id: the name of the new object | |
474 | # | |
475 | # Since: 6.0 | |
476 | ## | |
477 | { 'union': 'ObjectOptions', | |
478 | 'base': { 'qom-type': 'ObjectType', | |
479 | 'id': 'str' }, | |
480 | 'discriminator': 'qom-type', | |
481 | 'data': { | |
8825587b KW |
482 | 'authz-list': 'AuthZListProperties', |
483 | 'authz-listfile': 'AuthZListFileProperties', | |
484 | 'authz-pam': 'AuthZPAMProperties', | |
485 | 'authz-simple': 'AuthZSimpleProperties', | |
a68d909e KW |
486 | 'cryptodev-backend': 'CryptodevBackendProperties', |
487 | 'cryptodev-backend-builtin': 'CryptodevBackendProperties', | |
488 | 'cryptodev-vhost-user': { 'type': 'CryptodevVhostUserProperties', | |
489 | 'if': 'defined(CONFIG_VIRTIO_CRYPTO) && defined(CONFIG_VHOST_CRYPTO)' }, | |
d7ef29c4 | 490 | 'dbus-vmstate': 'DBusVMStateProperties', |
913d9063 KW |
491 | 'iothread': 'IothreadProperties', |
492 | 'memory-backend-file': 'MemoryBackendFileProperties', | |
493 | 'memory-backend-memfd': { 'type': 'MemoryBackendMemfdProperties', | |
494 | 'if': 'defined(CONFIG_LINUX)' }, | |
6815bc1d KW |
495 | 'memory-backend-ram': 'MemoryBackendProperties', |
496 | 'rng-builtin': 'RngProperties', | |
497 | 'rng-egd': 'RngEgdProperties', | |
381bd744 | 498 | 'rng-random': 'RngRandomProperties', |
39c4c27d KW |
499 | 'secret': 'SecretProperties', |
500 | 'secret_keyring': 'SecretKeyringProperties', | |
d09e4937 KW |
501 | 'throttle-group': 'ThrottleGroupProperties', |
502 | 'tls-creds-anon': 'TlsCredsAnonProperties', | |
503 | 'tls-creds-psk': 'TlsCredsPskProperties', | |
504 | 'tls-creds-x509': 'TlsCredsX509Properties', | |
505 | 'tls-cipher-suites': 'TlsCredsProperties' | |
2273b241 KW |
506 | } } |
507 | ||
c577ff62 MA |
508 | ## |
509 | # @object-add: | |
510 | # | |
511 | # Create a QOM object. | |
512 | # | |
513 | # @qom-type: the class name for the object to be created | |
514 | # | |
515 | # @id: the name of the new object | |
516 | # | |
5f07c4d6 KW |
517 | # Additional arguments depend on qom-type and are passed to the backend |
518 | # unchanged. | |
c577ff62 MA |
519 | # |
520 | # Returns: Nothing on success | |
521 | # Error if @qom-type is not a valid class name | |
522 | # | |
523 | # Since: 2.0 | |
524 | # | |
525 | # Example: | |
526 | # | |
527 | # -> { "execute": "object-add", | |
528 | # "arguments": { "qom-type": "rng-random", "id": "rng1", | |
5f07c4d6 | 529 | # "filename": "/dev/hwrng" } } |
c577ff62 MA |
530 | # <- { "return": {} } |
531 | # | |
532 | ## | |
533 | { 'command': 'object-add', | |
50243407 | 534 | 'data': {'qom-type': 'str', 'id': 'str'}, |
5f07c4d6 | 535 | 'gen': false } # so we can get the additional arguments |
c577ff62 MA |
536 | |
537 | ## | |
538 | # @object-del: | |
539 | # | |
540 | # Remove a QOM object. | |
541 | # | |
542 | # @id: the name of the QOM object to remove | |
543 | # | |
544 | # Returns: Nothing on success | |
545 | # Error if @id is not a valid id for a QOM object | |
546 | # | |
547 | # Since: 2.0 | |
548 | # | |
549 | # Example: | |
550 | # | |
551 | # -> { "execute": "object-del", "arguments": { "id": "rng1" } } | |
552 | # <- { "return": {} } | |
553 | # | |
554 | ## | |
555 | { 'command': 'object-del', 'data': {'id': 'str'} } |