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