| blob | b600b1b7a7c36c57de3790be3516b74555869062 |
1 # -*- Mode: Python -*-
2 # vim: filetype=python
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.
7 { 'include': 'authz.json' }
8 { 'include': 'block-core.json' }
9 { 'include': 'common.json' }
10 { 'include': 'crypto.json' }
12 ##
13 # = QEMU Object Model (QOM)
14 ##
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 #
35 # @default-value: the default value, if any (since 5.0)
36 #
37 # Since: 1.2
38 ##
39 { 'struct': 'ObjectPropertyInfo',
40 'data': { 'name': 'str',
41 'type': 'str',
42 '*description': 'str',
43 '*default-value': 'any' } }
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 }
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 }
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 }
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' } }
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 }
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
198 # links between different devices and/or objects. These properties
199 # are not included in the output of this command.
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 }
210 ##
211 # @CanHostSocketcanProperties:
212 #
213 # Properties for can-host-socketcan objects.
214 #
215 # @if: interface name of the host system CAN bus to connect to
216 #
217 # @canbus: object ID of the can-bus object to connect to the host interface
218 #
219 # Since: 2.12
220 ##
221 { 'struct': 'CanHostSocketcanProperties',
222 'data': { 'if': 'str',
223 'canbus': 'str' } }
225 ##
226 # @CryptodevBackendProperties:
227 #
228 # Properties for cryptodev-backend and cryptodev-backend-builtin objects.
229 #
230 # @queues: the number of queues for the cryptodev backend. Ignored for
231 # cryptodev-backend and must be 1 for cryptodev-backend-builtin.
232 # (default: 1)
233 #
234 # Since: 2.8
235 ##
236 { 'struct': 'CryptodevBackendProperties',
237 'data': { '*queues': 'uint32' } }
239 ##
240 # @CryptodevVhostUserProperties:
241 #
242 # Properties for cryptodev-vhost-user objects.
243 #
244 # @chardev: the name of a Unix domain socket character device that connects to
245 # the vhost-user server
246 #
247 # Since: 2.12
248 ##
249 { 'struct': 'CryptodevVhostUserProperties',
250 'base': 'CryptodevBackendProperties',
251 'data': { 'chardev': 'str' } }
253 ##
254 # @DBusVMStateProperties:
255 #
256 # Properties for dbus-vmstate objects.
257 #
258 # @addr: the name of the DBus bus to connect to
259 #
260 # @id-list: a comma separated list of DBus IDs of helpers whose data should be
261 # included in the VM state on migration
262 #
263 # Since: 5.0
264 ##
265 { 'struct': 'DBusVMStateProperties',
266 'data': { 'addr': 'str' ,
267 '*id-list': 'str' } }
269 ##
270 # @IothreadProperties:
271 #
272 # Properties for iothread objects.
273 #
274 # @poll-max-ns: the maximum number of nanoseconds to busy wait for events.
275 # 0 means polling is disabled (default: 32768 on POSIX hosts,
276 # 0 otherwise)
277 #
278 # @poll-grow: the multiplier used to increase the polling time when the
279 # algorithm detects it is missing events due to not polling long
280 # enough. 0 selects a default behaviour (default: 0)
281 #
282 # @poll-shrink: the divisor used to decrease the polling time when the
283 # algorithm detects it is spending too long polling without
284 # encountering events. 0 selects a default behaviour (default: 0)
285 #
286 # Since: 2.0
287 ##
288 { 'struct': 'IothreadProperties',
289 'data': { '*poll-max-ns': 'int',
290 '*poll-grow': 'int',
291 '*poll-shrink': 'int' } }
293 ##
294 # @MemoryBackendProperties:
295 #
296 # Properties for objects of classes derived from memory-backend.
297 #
298 # @merge: if true, mark the memory as mergeable (default depends on the machine
299 # type)
300 #
301 # @dump: if true, include the memory in core dumps (default depends on the
302 # machine type)
303 #
304 # @host-nodes: the list of NUMA host nodes to bind the memory to
305 #
306 # @policy: the NUMA policy (default: 'default')
307 #
308 # @prealloc: if true, preallocate memory (default: false)
309 #
310 # @prealloc-threads: number of CPU threads to use for prealloc (default: 1)
311 #
312 # @share: if false, the memory is private to QEMU; if true, it is shared
313 # (default: false)
314 #
315 # @size: size of the memory region in bytes
316 #
317 # @x-use-canonical-path-for-ramblock-id: if true, the canoncial path is used
318 # for ramblock-id. Disable this for 4.0
319 # machine types or older to allow
320 # migration with newer QEMU versions.
321 # This option is considered stable
322 # despite the x- prefix. (default:
323 # false generally, but true for machine
324 # types <= 4.0)
325 #
326 # Since: 2.1
327 ##
328 { 'struct': 'MemoryBackendProperties',
329 'data': { '*dump': 'bool',
330 '*host-nodes': ['uint16'],
331 '*merge': 'bool',
332 '*policy': 'HostMemPolicy',
333 '*prealloc': 'bool',
334 '*prealloc-threads': 'uint32',
335 '*share': 'bool',
336 'size': 'size',
337 '*x-use-canonical-path-for-ramblock-id': 'bool' } }
339 ##
340 # @MemoryBackendFileProperties:
341 #
342 # Properties for memory-backend-file objects.
343 #
344 # @align: the base address alignment when QEMU mmap(2)s @mem-path. Some
345 # backend stores specified by @mem-path require an alignment different
346 # than the default one used by QEMU, e.g. the device DAX /dev/dax0.0
347 # requires 2M alignment rather than 4K. In such cases, users can
348 # specify the required alignment via this option.
349 # 0 selects a default alignment (currently the page size). (default: 0)
350 #
351 # @discard-data: if true, the file contents can be destroyed when QEMU exits,
352 # to avoid unnecessarily flushing data to the backing file. Note
353 # that ``discard-data`` is only an optimization, and QEMU might
354 # not discard file contents if it aborts unexpectedly or is
355 # terminated using SIGKILL. (default: false)
356 #
357 # @mem-path: the path to either a shared memory or huge page filesystem mount
358 #
359 # @pmem: specifies whether the backing file specified by @mem-path is in
360 # host persistent memory that can be accessed using the SNIA NVM
361 # programming model (e.g. Intel NVDIMM).
362 #
363 # @readonly: if true, the backing file is opened read-only; if false, it is
364 # opened read-write. (default: false)
365 #
366 # Since: 2.1
367 ##
368 { 'struct': 'MemoryBackendFileProperties',
369 'base': 'MemoryBackendProperties',
370 'data': { '*align': 'size',
371 '*discard-data': 'bool',
372 'mem-path': 'str',
373 '*pmem': { 'type': 'bool', 'if': 'defined(CONFIG_LIBPMEM)' },
374 '*readonly': 'bool' } }
376 ##
377 # @MemoryBackendMemfdProperties:
378 #
379 # Properties for memory-backend-memfd objects.
380 #
381 # The @share boolean option is true by default with memfd.
382 #
383 # @hugetlb: if true, the file to be created resides in the hugetlbfs filesystem
384 # (default: false)
385 #
386 # @hugetlbsize: the hugetlb page size on systems that support multiple hugetlb
387 # page sizes (it must be a power of 2 value supported by the
388 # system). 0 selects a default page size. This option is ignored
389 # if @hugetlb is false. (default: 0)
390 #
391 # @seal: if true, create a sealed-file, which will block further resizing of
392 # the memory (default: true)
393 #
394 # Since: 2.12
395 ##
396 { 'struct': 'MemoryBackendMemfdProperties',
397 'base': 'MemoryBackendProperties',
398 'data': { '*hugetlb': 'bool',
399 '*hugetlbsize': 'size',
400 '*seal': 'bool' } }
402 ##
403 # @RngProperties:
404 #
405 # Properties for objects of classes derived from rng.
406 #
407 # @opened: if true, the device is opened immediately when applying this option
408 # and will probably fail when processing the next option. Don't use;
409 # only provided for compatibility. (default: false)
410 #
411 # Features:
412 # @deprecated: Member @opened is deprecated. Setting true doesn't make sense,
413 # and false is already the default.
414 #
415 # Since: 1.3
416 ##
417 { 'struct': 'RngProperties',
418 'data': { '*opened': { 'type': 'bool', 'features': ['deprecated'] } } }
420 ##
421 # @RngEgdProperties:
422 #
423 # Properties for rng-egd objects.
424 #
425 # @chardev: the name of a character device backend that provides the connection
426 # to the RNG daemon
427 #
428 # Since: 1.3
429 ##
430 { 'struct': 'RngEgdProperties',
431 'base': 'RngProperties',
432 'data': { 'chardev': 'str' } }
434 ##
435 # @RngRandomProperties:
436 #
437 # Properties for rng-random objects.
438 #
439 # @filename: the filename of the device on the host to obtain entropy from
440 # (default: "/dev/urandom")
441 #
442 # Since: 1.3
443 ##
444 { 'struct': 'RngRandomProperties',
445 'base': 'RngProperties',
446 'data': { '*filename': 'str' } }
448 ##
449 # @ObjectType:
450 #
451 # Since: 6.0
452 ##
453 { 'enum': 'ObjectType',
454 'data': [
455 'authz-list',
456 'authz-listfile',
457 'authz-pam',
458 'authz-simple',
459 'can-bus',
460 'can-host-socketcan',
461 'cryptodev-backend',
462 'cryptodev-backend-builtin',
463 { 'name': 'cryptodev-vhost-user',
464 'if': 'defined(CONFIG_VIRTIO_CRYPTO) && defined(CONFIG_VHOST_CRYPTO)' },
465 'dbus-vmstate',
466 'iothread',
467 'memory-backend-file',
468 { 'name': 'memory-backend-memfd',
469 'if': 'defined(CONFIG_LINUX)' },
470 'memory-backend-ram',
471 'rng-builtin',
472 'rng-egd',
473 'rng-random',
474 'secret',
475 'secret_keyring',
476 'throttle-group',
477 'tls-creds-anon',
478 'tls-creds-psk',
479 'tls-creds-x509',
480 'tls-cipher-suites'
481 ] }
483 ##
484 # @ObjectOptions:
485 #
486 # Describes the options of a user creatable QOM object.
487 #
488 # @qom-type: the class name for the object to be created
489 #
490 # @id: the name of the new object
491 #
492 # Since: 6.0
493 ##
494 { 'union': 'ObjectOptions',
495 'base': { 'qom-type': 'ObjectType',
496 'id': 'str' },
497 'discriminator': 'qom-type',
498 'data': {
499 'authz-list': 'AuthZListProperties',
500 'authz-listfile': 'AuthZListFileProperties',
501 'authz-pam': 'AuthZPAMProperties',
502 'authz-simple': 'AuthZSimpleProperties',
503 'can-host-socketcan': 'CanHostSocketcanProperties',
504 'cryptodev-backend': 'CryptodevBackendProperties',
505 'cryptodev-backend-builtin': 'CryptodevBackendProperties',
506 'cryptodev-vhost-user': { 'type': 'CryptodevVhostUserProperties',
507 'if': 'defined(CONFIG_VIRTIO_CRYPTO) && defined(CONFIG_VHOST_CRYPTO)' },
508 'dbus-vmstate': 'DBusVMStateProperties',
509 'iothread': 'IothreadProperties',
510 'memory-backend-file': 'MemoryBackendFileProperties',
511 'memory-backend-memfd': { 'type': 'MemoryBackendMemfdProperties',
512 'if': 'defined(CONFIG_LINUX)' },
513 'memory-backend-ram': 'MemoryBackendProperties',
514 'rng-builtin': 'RngProperties',
515 'rng-egd': 'RngEgdProperties',
516 'rng-random': 'RngRandomProperties',
517 'secret': 'SecretProperties',
518 'secret_keyring': 'SecretKeyringProperties',
519 'throttle-group': 'ThrottleGroupProperties',
520 'tls-creds-anon': 'TlsCredsAnonProperties',
521 'tls-creds-psk': 'TlsCredsPskProperties',
522 'tls-creds-x509': 'TlsCredsX509Properties',
523 'tls-cipher-suites': 'TlsCredsProperties'
524 } }
526 ##
527 # @object-add:
528 #
529 # Create a QOM object.
530 #
531 # @qom-type: the class name for the object to be created
532 #
533 # @id: the name of the new object
534 #
535 # Additional arguments depend on qom-type and are passed to the backend
536 # unchanged.
537 #
538 # Returns: Nothing on success
539 # Error if @qom-type is not a valid class name
540 #
541 # Since: 2.0
542 #
543 # Example:
544 #
545 # -> { "execute": "object-add",
546 # "arguments": { "qom-type": "rng-random", "id": "rng1",
547 # "filename": "/dev/hwrng" } }
548 # <- { "return": {} }
549 #
550 ##
551 { 'command': 'object-add',
552 'data': {'qom-type': 'str', 'id': 'str'},
553 'gen': false } # so we can get the additional arguments
555 ##
556 # @object-del:
557 #
558 # Remove a QOM object.
559 #
560 # @id: the name of the QOM object to remove
561 #
562 # Returns: Nothing on success
563 # Error if @id is not a valid id for a QOM object
564 #
565 # Since: 2.0
566 #
567 # Example:
568 #
569 # -> { "execute": "object-del", "arguments": { "id": "rng1" } }
570 # <- { "return": {} }
571 #
572 ##
573 { 'command': 'object-del', 'data': {'id': 'str'} }