| blob | 92b0fea76cb187e7c910e4ba41d3843b5d926d08 |
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
22 # four forms:
23 #
24 # 1) A primitive type such as 'u8', 'u16', 'bool', 'str', or
25 # 'double'. These types are mapped to the appropriate JSON
26 # type.
27 #
28 # 2) A child type in the form 'child<subtype>' where subtype is a
29 # qdev device type name. Child properties create the
30 # composition tree.
31 #
32 # 3) A link type in the form 'link<subtype>' where subtype is a
33 # qdev device type name. Link properties form the device model
34 # graph.
35 #
36 # @description: if specified, the description of the property.
37 #
38 # @default-value: the default value, if any (since 5.0)
39 #
40 # Since: 1.2
41 ##
42 { 'struct': 'ObjectPropertyInfo',
43 'data': { 'name': 'str',
44 'type': 'str',
45 '*description': 'str',
46 '*default-value': 'any' } }
48 ##
49 # @qom-list:
50 #
51 # This command will list any properties of a object given a path in
52 # the object model.
53 #
54 # @path: the path within the object model. See @qom-get for a
55 # description of this parameter.
56 #
57 # Returns: a list of @ObjectPropertyInfo that describe the properties
58 # of the object.
59 #
60 # Since: 1.2
61 #
62 # Example:
63 #
64 # -> { "execute": "qom-list",
65 # "arguments": { "path": "/chardevs" } }
66 # <- { "return": [ { "name": "type", "type": "string" },
67 # { "name": "parallel0", "type": "child<chardev-vc>" },
68 # { "name": "serial0", "type": "child<chardev-vc>" },
69 # { "name": "mon0", "type": "child<chardev-stdio>" } ] }
70 ##
71 { 'command': 'qom-list',
72 'data': { 'path': 'str' },
73 'returns': [ 'ObjectPropertyInfo' ],
74 'allow-preconfig': true }
76 ##
77 # @qom-get:
78 #
79 # This command will get a property from a object model path and return
80 # the value.
81 #
82 # @path: The path within the object model. There are two forms of
83 # supported paths--absolute and partial paths.
84 #
85 # Absolute paths are derived from the root object and can follow
86 # child<> or link<> properties. Since they can follow link<>
87 # properties, they can be arbitrarily long. Absolute paths look
88 # like absolute filenames and are prefixed with a leading slash.
89 #
90 # Partial paths look like relative filenames. They do not begin
91 # with a prefix. The matching rules for partial paths are subtle
92 # but designed to make specifying objects easy. At each level of
93 # the composition tree, the partial path is matched as an absolute
94 # path. The first match is not returned. At least two matches
95 # are searched for. A successful result is only returned if only
96 # one match is found. If more than one match is found, a flag is
97 # return to indicate that the match was ambiguous.
98 #
99 # @property: The property name to read
100 #
101 # Returns: The property value. The type depends on the property type.
102 # child<> and link<> properties are returned as #str pathnames.
103 # All integer property types (u8, u16, etc) are returned as #int.
104 #
105 # Since: 1.2
106 #
107 # Examples:
108 #
109 # 1. Use absolute path
110 #
111 # -> { "execute": "qom-get",
112 # "arguments": { "path": "/machine/unattached/device[0]",
113 # "property": "hotplugged" } }
114 # <- { "return": false }
115 #
116 # 2. Use partial path
117 #
118 # -> { "execute": "qom-get",
119 # "arguments": { "path": "unattached/sysbus",
120 # "property": "type" } }
121 # <- { "return": "System" }
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.
138 # See @qom-get 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 { 'command': 'qom-set',
151 'data': { 'path': 'str', 'property': 'str', 'value': 'any' },
152 'allow-preconfig': true }
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' } }
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
177 # 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
182 # are found
183 #
184 # Since: 1.1
185 ##
186 { 'command': 'qom-list-types',
187 'data': { '*implements': 'str', '*abstract': 'bool' },
188 'returns': [ 'ObjectTypeInfo' ],
189 'allow-preconfig': true }
191 ##
192 # @qom-list-properties:
193 #
194 # List properties associated with a QOM object.
195 #
196 # @typename: the type name of an object
197 #
198 # Note: objects can create properties at runtime, for example to
199 # describe links between different devices and/or objects. These
200 # properties are not included in the output of this command.
201 #
202 # Returns: a list of ObjectPropertyInfo describing object properties
203 #
204 # Since: 2.12
205 ##
206 { 'command': 'qom-list-properties',
207 'data': { 'typename': 'str'},
208 'returns': [ 'ObjectPropertyInfo' ],
209 'allow-preconfig': true }
211 ##
212 # @CanHostSocketcanProperties:
213 #
214 # Properties for can-host-socketcan objects.
215 #
216 # @if: interface name of the host system CAN bus to connect to
217 #
218 # @canbus: object ID of the can-bus object to connect to the host
219 # interface
220 #
221 # Since: 2.12
222 ##
223 { 'struct': 'CanHostSocketcanProperties',
224 'data': { 'if': 'str',
225 'canbus': 'str' } }
227 ##
228 # @ColoCompareProperties:
229 #
230 # Properties for colo-compare objects.
231 #
232 # @primary_in: name of the character device backend to use for the
233 # primary input (incoming packets are redirected to @outdev)
234 #
235 # @secondary_in: name of the character device backend to use for
236 # secondary input (incoming packets are only compared to the input
237 # on @primary_in and then dropped)
238 #
239 # @outdev: name of the character device backend to use for output
240 #
241 # @iothread: name of the iothread to run in
242 #
243 # @notify_dev: name of the character device backend to be used to
244 # communicate with the remote colo-frame (only for Xen COLO)
245 #
246 # @compare_timeout: the maximum time to hold a packet from @primary_in
247 # for comparison with an incoming packet on @secondary_in in
248 # milliseconds (default: 3000)
249 #
250 # @expired_scan_cycle: the interval at which colo-compare checks
251 # whether packets from @primary have timed out, in milliseconds
252 # (default: 3000)
253 #
254 # @max_queue_size: the maximum number of packets to keep in the queue
255 # for comparing with incoming packets from @secondary_in. If the
256 # queue is full and additional packets are received, the
257 # additional packets are dropped. (default: 1024)
258 #
259 # @vnet_hdr_support: if true, vnet header support is enabled
260 # (default: false)
261 #
262 # Since: 2.8
263 ##
264 { 'struct': 'ColoCompareProperties',
265 'data': { 'primary_in': 'str',
266 'secondary_in': 'str',
267 'outdev': 'str',
268 'iothread': 'str',
269 '*notify_dev': 'str',
270 '*compare_timeout': 'uint64',
271 '*expired_scan_cycle': 'uint32',
272 '*max_queue_size': 'uint32',
273 '*vnet_hdr_support': 'bool' } }
275 ##
276 # @CryptodevBackendProperties:
277 #
278 # Properties for cryptodev-backend and cryptodev-backend-builtin
279 # objects.
280 #
281 # @queues: the number of queues for the cryptodev backend. Ignored
282 # for cryptodev-backend and must be 1 for
283 # cryptodev-backend-builtin. (default: 1)
284 #
285 # @throttle-bps: limit total bytes per second (Since 8.0)
286 #
287 # @throttle-ops: limit total operations per second (Since 8.0)
288 #
289 # Since: 2.8
290 ##
291 { 'struct': 'CryptodevBackendProperties',
292 'data': { '*queues': 'uint32',
293 '*throttle-bps': 'uint64',
294 '*throttle-ops': 'uint64' } }
296 ##
297 # @CryptodevVhostUserProperties:
298 #
299 # Properties for cryptodev-vhost-user objects.
300 #
301 # @chardev: the name of a Unix domain socket character device that
302 # connects to the vhost-user server
303 #
304 # Since: 2.12
305 ##
306 { 'struct': 'CryptodevVhostUserProperties',
307 'base': 'CryptodevBackendProperties',
308 'data': { 'chardev': 'str' } }
310 ##
311 # @DBusVMStateProperties:
312 #
313 # Properties for dbus-vmstate objects.
314 #
315 # @addr: the name of the DBus bus to connect to
316 #
317 # @id-list: a comma separated list of DBus IDs of helpers whose data
318 # should be included in the VM state on migration
319 #
320 # Since: 5.0
321 ##
322 { 'struct': 'DBusVMStateProperties',
323 'data': { 'addr': 'str' ,
324 '*id-list': 'str' } }
326 ##
327 # @NetfilterInsert:
328 #
329 # Indicates where to insert a netfilter relative to a given other
330 # filter.
331 #
332 # @before: insert before the specified filter
333 #
334 # @behind: insert behind the specified filter
335 #
336 # Since: 5.0
337 ##
338 { 'enum': 'NetfilterInsert',
339 'data': [ 'before', 'behind' ] }
341 ##
342 # @NetfilterProperties:
343 #
344 # Properties for objects of classes derived from netfilter.
345 #
346 # @netdev: id of the network device backend to filter
347 #
348 # @queue: indicates which queue(s) to filter (default: all)
349 #
350 # @status: indicates whether the filter is enabled ("on") or disabled
351 # ("off") (default: "on")
352 #
353 # @position: specifies where the filter should be inserted in the
354 # filter list. "head" means the filter is inserted at the head of
355 # the filter list, before any existing filters. "tail" means the
356 # filter is inserted at the tail of the filter list, behind any
357 # existing filters (default). "id=<id>" means the filter is
358 # inserted before or behind the filter specified by <id>,
359 # depending on the @insert property. (default: "tail")
360 #
361 # @insert: where to insert the filter relative to the filter given in
362 # @position. Ignored if @position is "head" or "tail".
363 # (default: behind)
364 #
365 # Since: 2.5
366 ##
367 { 'struct': 'NetfilterProperties',
368 'data': { 'netdev': 'str',
369 '*queue': 'NetFilterDirection',
370 '*status': 'str',
371 '*position': 'str',
372 '*insert': 'NetfilterInsert' } }
374 ##
375 # @FilterBufferProperties:
376 #
377 # Properties for filter-buffer objects.
378 #
379 # @interval: a non-zero interval in microseconds. All packets
380 # arriving in the given interval are delayed until the end of the
381 # interval.
382 #
383 # Since: 2.5
384 ##
385 { 'struct': 'FilterBufferProperties',
386 'base': 'NetfilterProperties',
387 'data': { 'interval': 'uint32' } }
389 ##
390 # @FilterDumpProperties:
391 #
392 # Properties for filter-dump objects.
393 #
394 # @file: the filename where the dumped packets should be stored
395 #
396 # @maxlen: maximum number of bytes in a packet that are stored
397 # (default: 65536)
398 #
399 # Since: 2.5
400 ##
401 { 'struct': 'FilterDumpProperties',
402 'base': 'NetfilterProperties',
403 'data': { 'file': 'str',
404 '*maxlen': 'uint32' } }
406 ##
407 # @FilterMirrorProperties:
408 #
409 # Properties for filter-mirror objects.
410 #
411 # @outdev: the name of a character device backend to which all
412 # incoming packets are mirrored
413 #
414 # @vnet_hdr_support: if true, vnet header support is enabled
415 # (default: false)
416 #
417 # Since: 2.6
418 ##
419 { 'struct': 'FilterMirrorProperties',
420 'base': 'NetfilterProperties',
421 'data': { 'outdev': 'str',
422 '*vnet_hdr_support': 'bool' } }
424 ##
425 # @FilterRedirectorProperties:
426 #
427 # Properties for filter-redirector objects.
428 #
429 # At least one of @indev or @outdev must be present. If both are
430 # present, they must not refer to the same character device backend.
431 #
432 # @indev: the name of a character device backend from which packets
433 # are received and redirected to the filtered network device
434 #
435 # @outdev: the name of a character device backend to which all
436 # incoming packets are redirected
437 #
438 # @vnet_hdr_support: if true, vnet header support is enabled
439 # (default: false)
440 #
441 # Since: 2.6
442 ##
443 { 'struct': 'FilterRedirectorProperties',
444 'base': 'NetfilterProperties',
445 'data': { '*indev': 'str',
446 '*outdev': 'str',
447 '*vnet_hdr_support': 'bool' } }
449 ##
450 # @FilterRewriterProperties:
451 #
452 # Properties for filter-rewriter objects.
453 #
454 # @vnet_hdr_support: if true, vnet header support is enabled
455 # (default: false)
456 #
457 # Since: 2.8
458 ##
459 { 'struct': 'FilterRewriterProperties',
460 'base': 'NetfilterProperties',
461 'data': { '*vnet_hdr_support': 'bool' } }
463 ##
464 # @InputBarrierProperties:
465 #
466 # Properties for input-barrier objects.
467 #
468 # @name: the screen name as declared in the screens section of
469 # barrier.conf
470 #
471 # @server: hostname of the Barrier server (default: "localhost")
472 #
473 # @port: TCP port of the Barrier server (default: "24800")
474 #
475 # @x-origin: x coordinate of the leftmost pixel on the guest screen
476 # (default: "0")
477 #
478 # @y-origin: y coordinate of the topmost pixel on the guest screen
479 # (default: "0")
480 #
481 # @width: the width of secondary screen in pixels (default: "1920")
482 #
483 # @height: the height of secondary screen in pixels (default: "1080")
484 #
485 # Since: 4.2
486 ##
487 { 'struct': 'InputBarrierProperties',
488 'data': { 'name': 'str',
489 '*server': 'str',
490 '*port': 'str',
491 '*x-origin': 'str',
492 '*y-origin': 'str',
493 '*width': 'str',
494 '*height': 'str' } }
496 ##
497 # @InputLinuxProperties:
498 #
499 # Properties for input-linux objects.
500 #
501 # @evdev: the path of the host evdev device to use
502 #
503 # @grab_all: if true, grab is toggled for all devices (e.g. both
504 # keyboard and mouse) instead of just one device (default: false)
505 #
506 # @repeat: enables auto-repeat events (default: false)
507 #
508 # @grab-toggle: the key or key combination that toggles device grab
509 # (default: ctrl-ctrl)
510 #
511 # Since: 2.6
512 ##
513 { 'struct': 'InputLinuxProperties',
514 'data': { 'evdev': 'str',
515 '*grab_all': 'bool',
516 '*repeat': 'bool',
517 '*grab-toggle': 'GrabToggleKeys' } }
519 ##
520 # @EventLoopBaseProperties:
521 #
522 # Common properties for event loops
523 #
524 # @aio-max-batch: maximum number of requests in a batch for the AIO
525 # engine, 0 means that the engine will use its default.
526 # (default: 0)
527 #
528 # @thread-pool-min: minimum number of threads reserved in the thread
529 # pool (default:0)
530 #
531 # @thread-pool-max: maximum number of threads the thread pool can
532 # contain (default:64)
533 #
534 # Since: 7.1
535 ##
536 { 'struct': 'EventLoopBaseProperties',
537 'data': { '*aio-max-batch': 'int',
538 '*thread-pool-min': 'int',
539 '*thread-pool-max': 'int' } }
541 ##
542 # @IothreadProperties:
543 #
544 # Properties for iothread objects.
545 #
546 # @poll-max-ns: the maximum number of nanoseconds to busy wait for
547 # events. 0 means polling is disabled (default: 32768 on POSIX
548 # hosts, 0 otherwise)
549 #
550 # @poll-grow: the multiplier used to increase the polling time when
551 # the algorithm detects it is missing events due to not polling
552 # long enough. 0 selects a default behaviour (default: 0)
553 #
554 # @poll-shrink: the divisor used to decrease the polling time when the
555 # algorithm detects it is spending too long polling without
556 # encountering events. 0 selects a default behaviour (default: 0)
557 #
558 # The @aio-max-batch option is available since 6.1.
559 #
560 # Since: 2.0
561 ##
562 { 'struct': 'IothreadProperties',
563 'base': 'EventLoopBaseProperties',
564 'data': { '*poll-max-ns': 'int',
565 '*poll-grow': 'int',
566 '*poll-shrink': 'int' } }
568 ##
569 # @MainLoopProperties:
570 #
571 # Properties for the main-loop object.
572 #
573 # Since: 7.1
574 ##
575 { 'struct': 'MainLoopProperties',
576 'base': 'EventLoopBaseProperties',
577 'data': {} }
579 ##
580 # @MemoryBackendProperties:
581 #
582 # Properties for objects of classes derived from memory-backend.
583 #
584 # @merge: if true, mark the memory as mergeable (default depends on
585 # the machine type)
586 #
587 # @dump: if true, include the memory in core dumps (default depends on
588 # the machine type)
589 #
590 # @host-nodes: the list of NUMA host nodes to bind the memory to
591 #
592 # @policy: the NUMA policy (default: 'default')
593 #
594 # @prealloc: if true, preallocate memory (default: false)
595 #
596 # @prealloc-threads: number of CPU threads to use for prealloc
597 # (default: 1)
598 #
599 # @prealloc-context: thread context to use for creation of
600 # preallocation threads (default: none) (since 7.2)
601 #
602 # @share: if false, the memory is private to QEMU; if true, it is
603 # shared (default false for backends memory-backend-file and
604 # memory-backend-ram, true for backends memory-backend-epc,
605 # memory-backend-memfd, and memory-backend-shm)
606 #
607 # @reserve: if true, reserve swap space (or huge pages) if applicable
608 # (default: true) (since 6.1)
609 #
610 # @size: size of the memory region in bytes
611 #
612 # @x-use-canonical-path-for-ramblock-id: if true, the canonical path
613 # is used for ramblock-id. Disable this for 4.0 machine types or
614 # older to allow migration with newer QEMU versions.
615 # (default: false generally, but true for machine types <= 4.0)
616 #
617 # Note: prealloc=true and reserve=false cannot be set at the same
618 # time. With reserve=true, the behavior depends on the operating
619 # system: for example, Linux will not reserve swap space for
620 # shared file mappings -- "not applicable". In contrast,
621 # reserve=false will bail out if it cannot be configured
622 # accordingly.
623 #
624 # Since: 2.1
625 ##
626 { 'struct': 'MemoryBackendProperties',
627 'data': { '*dump': 'bool',
628 '*host-nodes': ['uint16'],
629 '*merge': 'bool',
630 '*policy': 'HostMemPolicy',
631 '*prealloc': 'bool',
632 '*prealloc-threads': 'uint32',
633 '*prealloc-context': 'str',
634 '*share': 'bool',
635 '*reserve': 'bool',
636 'size': 'size',
637 '*x-use-canonical-path-for-ramblock-id': 'bool' } }
639 ##
640 # @MemoryBackendFileProperties:
641 #
642 # Properties for memory-backend-file objects.
643 #
644 # @align: the base address alignment when QEMU mmap(2)s @mem-path.
645 # Some backend stores specified by @mem-path require an alignment
646 # different than the default one used by QEMU, e.g. the device DAX
647 # /dev/dax0.0 requires 2M alignment rather than 4K. In such cases,
648 # users can specify the required alignment via this option. 0
649 # selects a default alignment (currently the page size).
650 # (default: 0)
651 #
652 # @offset: the offset into the target file that the region starts at.
653 # You can use this option to back multiple regions with a single
654 # file. Must be a multiple of the page size.
655 # (default: 0) (since 8.1)
656 #
657 # @discard-data: if true, the file contents can be destroyed when QEMU
658 # exits, to avoid unnecessarily flushing data to the backing file.
659 # Note that @discard-data is only an optimization, and QEMU might
660 # not discard file contents if it aborts unexpectedly or is
661 # terminated using SIGKILL. (default: false)
662 #
663 # @mem-path: the path to either a shared memory or huge page
664 # filesystem mount
665 #
666 # @pmem: specifies whether the backing file specified by @mem-path is
667 # in host persistent memory that can be accessed using the SNIA
668 # NVM programming model (e.g. Intel NVDIMM).
669 #
670 # @readonly: if true, the backing file is opened read-only; if false,
671 # it is opened read-write. (default: false)
672 #
673 # @rom: whether to create Read Only Memory (ROM) that cannot be
674 # modified by the VM. Any write attempts to such ROM will be
675 # denied. Most use cases want writable RAM instead of ROM.
676 # However, selected use cases, like R/O NVDIMMs, can benefit from
677 # ROM. If set to 'on', create ROM; if set to 'off', create
678 # writable RAM; if set to 'auto', the value of the @readonly
679 # property is used. This property is primarily helpful when we
680 # want to have proper RAM in configurations that would
681 # traditionally create ROM before this property was introduced: VM
682 # templating, where we want to open a file readonly (@readonly set
683 # to true) and mark the memory to be private for QEMU (@share set
684 # to false). For this use case, we need writable RAM instead of
685 # ROM, and want to set this property to 'off'. (default: auto,
686 # since 8.2)
687 #
688 # Since: 2.1
689 ##
690 { 'struct': 'MemoryBackendFileProperties',
691 'base': 'MemoryBackendProperties',
692 'data': { '*align': 'size',
693 '*offset': 'size',
694 '*discard-data': 'bool',
695 'mem-path': 'str',
696 '*pmem': { 'type': 'bool', 'if': 'CONFIG_LIBPMEM' },
697 '*readonly': 'bool',
698 '*rom': 'OnOffAuto' } }
700 ##
701 # @MemoryBackendMemfdProperties:
702 #
703 # Properties for memory-backend-memfd objects.
704 #
705 # @hugetlb: if true, the file to be created resides in the hugetlbfs
706 # filesystem (default: false)
707 #
708 # @hugetlbsize: the hugetlb page size on systems that support multiple
709 # hugetlb page sizes (it must be a power of 2 value supported by
710 # the system). 0 selects a default page size. This option is
711 # ignored if @hugetlb is false. (default: 0)
712 #
713 # @seal: if true, create a sealed-file, which will block further
714 # resizing of the memory (default: true)
715 #
716 # Since: 2.12
717 ##
718 { 'struct': 'MemoryBackendMemfdProperties',
719 'base': 'MemoryBackendProperties',
720 'data': { '*hugetlb': 'bool',
721 '*hugetlbsize': 'size',
722 '*seal': 'bool' } }
724 ##
725 # @MemoryBackendShmProperties:
726 #
727 # Properties for memory-backend-shm objects.
728 #
729 # This memory backend supports only shared memory, which is the
730 # default.
731 #
732 # Since: 9.1
733 ##
734 { 'struct': 'MemoryBackendShmProperties',
735 'base': 'MemoryBackendProperties',
736 'data': { },
737 'if': 'CONFIG_POSIX' }
739 ##
740 # @MemoryBackendEpcProperties:
741 #
742 # Properties for memory-backend-epc objects.
743 #
744 # The @merge boolean option is false by default with epc
745 #
746 # The @dump boolean option is false by default with epc
747 #
748 # Since: 6.2
749 ##
750 { 'struct': 'MemoryBackendEpcProperties',
751 'base': 'MemoryBackendProperties',
752 'data': {} }
754 ##
755 # @PrManagerHelperProperties:
756 #
757 # Properties for pr-manager-helper objects.
758 #
759 # @path: the path to a Unix domain socket for connecting to the
760 # external helper
761 #
762 # Since: 2.11
763 ##
764 { 'struct': 'PrManagerHelperProperties',
765 'data': { 'path': 'str' } }
767 ##
768 # @QtestProperties:
769 #
770 # Properties for qtest objects.
771 #
772 # @chardev: the chardev to be used to receive qtest commands on.
773 #
774 # @log: the path to a log file
775 #
776 # Since: 6.0
777 ##
778 { 'struct': 'QtestProperties',
779 'data': { 'chardev': 'str',
780 '*log': 'str' } }
782 ##
783 # @RemoteObjectProperties:
784 #
785 # Properties for x-remote-object objects.
786 #
787 # @fd: file descriptor name previously passed via 'getfd' command
788 #
789 # @devid: the id of the device to be associated with the file
790 # descriptor
791 #
792 # Since: 6.0
793 ##
794 { 'struct': 'RemoteObjectProperties',
795 'data': { 'fd': 'str', 'devid': 'str' } }
797 ##
798 # @VfioUserServerProperties:
799 #
800 # Properties for x-vfio-user-server objects.
801 #
802 # @socket: socket to be used by the libvfio-user library
803 #
804 # @device: the ID of the device to be emulated at the server
805 #
806 # Since: 7.1
807 ##
808 { 'struct': 'VfioUserServerProperties',
809 'data': { 'socket': 'SocketAddress', 'device': 'str' } }
811 ##
812 # @IOMMUFDProperties:
813 #
814 # Properties for iommufd objects.
815 #
816 # @fd: file descriptor name previously passed via 'getfd' command,
817 # which represents a pre-opened /dev/iommu. This allows the
818 # iommufd object to be shared across several subsystems (VFIO,
819 # VDPA, ...), and the file descriptor to be shared with other
820 # process, e.g. DPDK. (default: QEMU opens /dev/iommu by itself)
821 #
822 # Since: 9.0
823 ##
824 { 'struct': 'IOMMUFDProperties',
825 'data': { '*fd': 'str' } }
827 ##
828 # @AcpiGenericInitiatorProperties:
829 #
830 # Properties for acpi-generic-initiator objects.
831 #
832 # @pci-dev: PCI device ID to be associated with the node
833 #
834 # @node: NUMA node associated with the PCI device
835 #
836 # Since: 9.0
837 ##
838 { 'struct': 'AcpiGenericInitiatorProperties',
839 'data': { 'pci-dev': 'str',
840 'node': 'uint32' } }
842 ##
843 # @RngProperties:
844 #
845 # Properties for objects of classes derived from rng.
846 #
847 # @opened: if true, the device is opened immediately when applying
848 # this option and will probably fail when processing the next
849 # option. Don't use; only provided for compatibility.
850 # (default: false)
851 #
852 # Features:
853 #
854 # @deprecated: Member @opened is deprecated. Setting true doesn't
855 # make sense, and false is already the default.
856 #
857 # Since: 1.3
858 ##
859 { 'struct': 'RngProperties',
860 'data': { '*opened': { 'type': 'bool', 'features': ['deprecated'] } } }
862 ##
863 # @RngEgdProperties:
864 #
865 # Properties for rng-egd objects.
866 #
867 # @chardev: the name of a character device backend that provides the
868 # connection to the RNG daemon
869 #
870 # Since: 1.3
871 ##
872 { 'struct': 'RngEgdProperties',
873 'base': 'RngProperties',
874 'data': { 'chardev': 'str' } }
876 ##
877 # @RngRandomProperties:
878 #
879 # Properties for rng-random objects.
880 #
881 # @filename: the filename of the device on the host to obtain entropy
882 # from (default: "/dev/urandom")
883 #
884 # Since: 1.3
885 ##
886 { 'struct': 'RngRandomProperties',
887 'base': 'RngProperties',
888 'data': { '*filename': 'str' } }
890 ##
891 # @SevCommonProperties:
892 #
893 # Properties common to objects that are derivatives of sev-common.
894 #
895 # @sev-device: SEV device to use (default: "/dev/sev")
896 #
897 # @cbitpos: C-bit location in page table entry (default: 0)
898 #
899 # @reduced-phys-bits: number of bits in physical addresses that become
900 # unavailable when SEV is enabled
901 #
902 # @kernel-hashes: if true, add hashes of kernel/initrd/cmdline to a
903 # designated guest firmware page for measured boot with -kernel
904 # (default: false) (since 6.2)
905 #
906 # Since: 9.1
907 ##
908 { 'struct': 'SevCommonProperties',
909 'data': { '*sev-device': 'str',
910 '*cbitpos': 'uint32',
911 'reduced-phys-bits': 'uint32',
912 '*kernel-hashes': 'bool' } }
914 ##
915 # @SevGuestProperties:
916 #
917 # Properties for sev-guest objects.
918 #
919 # @dh-cert-file: guest owners DH certificate (encoded with base64)
920 #
921 # @session-file: guest owners session parameters (encoded with base64)
922 #
923 # @policy: SEV policy value (default: 0x1)
924 #
925 # @handle: SEV firmware handle (default: 0)
926 #
927 # @legacy-vm-type: Use legacy KVM_SEV_INIT KVM interface for creating the VM.
928 # The newer KVM_SEV_INIT2 interface syncs additional vCPU
929 # state when initializing the VMSA structures, which will
930 # result in a different guest measurement. Set this to
931 # maintain compatibility with older QEMU or kernel versions
932 # that rely on legacy KVM_SEV_INIT behavior.
933 # (default: false) (since 9.1)
934 #
935 # Since: 2.12
936 ##
937 { 'struct': 'SevGuestProperties',
938 'base': 'SevCommonProperties',
939 'data': { '*dh-cert-file': 'str',
940 '*session-file': 'str',
941 '*policy': 'uint32',
942 '*handle': 'uint32',
943 '*legacy-vm-type': 'bool' } }
945 ##
946 # @SevSnpGuestProperties:
947 #
948 # Properties for sev-snp-guest objects. Most of these are direct
949 # arguments for the KVM_SNP_* interfaces documented in the Linux
950 # kernel source under
951 # Documentation/arch/x86/amd-memory-encryption.rst, which are in turn
952 # closely coupled with the SNP_INIT/SNP_LAUNCH_* firmware commands
953 # documented in the SEV-SNP Firmware ABI Specification (Rev 0.9).
954 #
955 # More usage information is also available in the QEMU source tree
956 # under docs/amd-memory-encryption.
957 #
958 # @policy: the 'POLICY' parameter to the SNP_LAUNCH_START command, as
959 # defined in the SEV-SNP firmware ABI (default: 0x30000)
960 #
961 # @guest-visible-workarounds: 16-byte, base64-encoded blob to report
962 # hypervisor-defined workarounds, corresponding to the 'GOSVW'
963 # parameter of the SNP_LAUNCH_START command defined in the SEV-SNP
964 # firmware ABI (default: all-zero)
965 #
966 # @id-block: 96-byte, base64-encoded blob to provide the 'ID Block'
967 # structure for the SNP_LAUNCH_FINISH command defined in the
968 # SEV-SNP firmware ABI (default: all-zero)
969 #
970 # @id-auth: 4096-byte, base64-encoded blob to provide the 'ID
971 # Authentication Information Structure' for the SNP_LAUNCH_FINISH
972 # command defined in the SEV-SNP firmware ABI (default: all-zero)
973 #
974 # @author-key-enabled: true if 'id-auth' blob contains the 'AUTHOR_KEY'
975 # field defined SEV-SNP firmware ABI (default: false)
976 #
977 # @host-data: 32-byte, base64-encoded, user-defined blob to provide to
978 # the guest, as documented for the 'HOST_DATA' parameter of the
979 # SNP_LAUNCH_FINISH command in the SEV-SNP firmware ABI (default:
980 # all-zero)
981 #
982 # @vcek-disabled: Guests are by default allowed to choose between VLEK
983 # (Versioned Loaded Endorsement Key) or VCEK (Versioned Chip
984 # Endorsement Key) when requesting attestation reports from
985 # firmware. Set this to true to disable the use of VCEK.
986 # (default: false) (since: 9.1)
987 #
988 # Since: 9.1
989 ##
990 { 'struct': 'SevSnpGuestProperties',
991 'base': 'SevCommonProperties',
992 'data': {
993 '*policy': 'uint64',
994 '*guest-visible-workarounds': 'str',
995 '*id-block': 'str',
996 '*id-auth': 'str',
997 '*author-key-enabled': 'bool',
998 '*host-data': 'str',
999 '*vcek-disabled': 'bool' } }
1001 ##
1002 # @ThreadContextProperties:
1003 #
1004 # Properties for thread context objects.
1005 #
1006 # @cpu-affinity: the list of host CPU numbers used as CPU affinity for
1007 # all threads created in the thread context (default: QEMU main
1008 # thread CPU affinity)
1009 #
1010 # @node-affinity: the list of host node numbers that will be resolved
1011 # to a list of host CPU numbers used as CPU affinity. This is a
1012 # shortcut for specifying the list of host CPU numbers belonging
1013 # to the host nodes manually by setting @cpu-affinity.
1014 # (default: QEMU main thread affinity)
1015 #
1016 # Since: 7.2
1017 ##
1018 { 'struct': 'ThreadContextProperties',
1019 'data': { '*cpu-affinity': ['uint16'],
1020 '*node-affinity': ['uint16'] } }
1023 ##
1024 # @ObjectType:
1025 #
1026 # Features:
1027 #
1028 # @unstable: Member @x-remote-object is experimental.
1029 #
1030 # Since: 6.0
1031 ##
1032 { 'enum': 'ObjectType',
1033 'data': [
1034 'acpi-generic-initiator',
1035 'authz-list',
1036 'authz-listfile',
1037 'authz-pam',
1038 'authz-simple',
1039 'can-bus',
1040 { 'name': 'can-host-socketcan',
1041 'if': 'CONFIG_LINUX' },
1042 'colo-compare',
1043 'cryptodev-backend',
1044 'cryptodev-backend-builtin',
1045 'cryptodev-backend-lkcf',
1046 { 'name': 'cryptodev-vhost-user',
1047 'if': 'CONFIG_VHOST_CRYPTO' },
1048 'dbus-vmstate',
1049 'filter-buffer',
1050 'filter-dump',
1051 'filter-mirror',
1052 'filter-redirector',
1053 'filter-replay',
1054 'filter-rewriter',
1055 'input-barrier',
1056 { 'name': 'input-linux',
1057 'if': 'CONFIG_LINUX' },
1058 'iommufd',
1059 'iothread',
1060 'main-loop',
1061 { 'name': 'memory-backend-epc',
1062 'if': 'CONFIG_LINUX' },
1063 'memory-backend-file',
1064 { 'name': 'memory-backend-memfd',
1065 'if': 'CONFIG_LINUX' },
1066 'memory-backend-ram',
1067 { 'name': 'memory-backend-shm',
1068 'if': 'CONFIG_POSIX' },
1069 'pef-guest',
1070 { 'name': 'pr-manager-helper',
1071 'if': 'CONFIG_LINUX' },
1072 'qtest',
1073 'rng-builtin',
1074 'rng-egd',
1075 { 'name': 'rng-random',
1076 'if': 'CONFIG_POSIX' },
1077 'secret',
1078 { 'name': 'secret_keyring',
1079 'if': 'CONFIG_SECRET_KEYRING' },
1080 'sev-guest',
1081 'sev-snp-guest',
1082 'thread-context',
1083 's390-pv-guest',
1084 'throttle-group',
1085 'tls-creds-anon',
1086 'tls-creds-psk',
1087 'tls-creds-x509',
1088 'tls-cipher-suites',
1089 { 'name': 'x-remote-object', 'features': [ 'unstable' ] },
1090 { 'name': 'x-vfio-user-server', 'features': [ 'unstable' ] }
1091 ] }
1093 ##
1094 # @ObjectOptions:
1095 #
1096 # Describes the options of a user creatable QOM object.
1097 #
1098 # @qom-type: the class name for the object to be created
1099 #
1100 # @id: the name of the new object
1101 #
1102 # Since: 6.0
1103 ##
1104 { 'union': 'ObjectOptions',
1105 'base': { 'qom-type': 'ObjectType',
1106 'id': 'str' },
1107 'discriminator': 'qom-type',
1108 'data': {
1109 'acpi-generic-initiator': 'AcpiGenericInitiatorProperties',
1110 'authz-list': 'AuthZListProperties',
1111 'authz-listfile': 'AuthZListFileProperties',
1112 'authz-pam': 'AuthZPAMProperties',
1113 'authz-simple': 'AuthZSimpleProperties',
1114 'can-host-socketcan': { 'type': 'CanHostSocketcanProperties',
1115 'if': 'CONFIG_LINUX' },
1116 'colo-compare': 'ColoCompareProperties',
1117 'cryptodev-backend': 'CryptodevBackendProperties',
1118 'cryptodev-backend-builtin': 'CryptodevBackendProperties',
1119 'cryptodev-backend-lkcf': 'CryptodevBackendProperties',
1120 'cryptodev-vhost-user': { 'type': 'CryptodevVhostUserProperties',
1121 'if': 'CONFIG_VHOST_CRYPTO' },
1122 'dbus-vmstate': 'DBusVMStateProperties',
1123 'filter-buffer': 'FilterBufferProperties',
1124 'filter-dump': 'FilterDumpProperties',
1125 'filter-mirror': 'FilterMirrorProperties',
1126 'filter-redirector': 'FilterRedirectorProperties',
1127 'filter-replay': 'NetfilterProperties',
1128 'filter-rewriter': 'FilterRewriterProperties',
1129 'input-barrier': 'InputBarrierProperties',
1130 'input-linux': { 'type': 'InputLinuxProperties',
1131 'if': 'CONFIG_LINUX' },
1132 'iommufd': 'IOMMUFDProperties',
1133 'iothread': 'IothreadProperties',
1134 'main-loop': 'MainLoopProperties',
1135 'memory-backend-epc': { 'type': 'MemoryBackendEpcProperties',
1136 'if': 'CONFIG_LINUX' },
1137 'memory-backend-file': 'MemoryBackendFileProperties',
1138 'memory-backend-memfd': { 'type': 'MemoryBackendMemfdProperties',
1139 'if': 'CONFIG_LINUX' },
1140 'memory-backend-ram': 'MemoryBackendProperties',
1141 'memory-backend-shm': { 'type': 'MemoryBackendShmProperties',
1142 'if': 'CONFIG_POSIX' },
1143 'pr-manager-helper': { 'type': 'PrManagerHelperProperties',
1144 'if': 'CONFIG_LINUX' },
1145 'qtest': 'QtestProperties',
1146 'rng-builtin': 'RngProperties',
1147 'rng-egd': 'RngEgdProperties',
1148 'rng-random': { 'type': 'RngRandomProperties',
1149 'if': 'CONFIG_POSIX' },
1150 'secret': 'SecretProperties',
1151 'secret_keyring': { 'type': 'SecretKeyringProperties',
1152 'if': 'CONFIG_SECRET_KEYRING' },
1153 'sev-guest': 'SevGuestProperties',
1154 'sev-snp-guest': 'SevSnpGuestProperties',
1155 'thread-context': 'ThreadContextProperties',
1156 'throttle-group': 'ThrottleGroupProperties',
1157 'tls-creds-anon': 'TlsCredsAnonProperties',
1158 'tls-creds-psk': 'TlsCredsPskProperties',
1159 'tls-creds-x509': 'TlsCredsX509Properties',
1160 'tls-cipher-suites': 'TlsCredsProperties',
1161 'x-remote-object': 'RemoteObjectProperties',
1162 'x-vfio-user-server': 'VfioUserServerProperties'
1163 } }
1165 ##
1166 # @object-add:
1167 #
1168 # Create a QOM object.
1169 #
1170 # Errors:
1171 # - Error if @qom-type is not a valid class name
1172 #
1173 # Since: 2.0
1174 #
1175 # Example:
1176 #
1177 # -> { "execute": "object-add",
1178 # "arguments": { "qom-type": "rng-random", "id": "rng1",
1179 # "filename": "/dev/hwrng" } }
1180 # <- { "return": {} }
1181 ##
1182 { 'command': 'object-add', 'data': 'ObjectOptions', 'boxed': true,
1183 'allow-preconfig': true }
1185 ##
1186 # @object-del:
1187 #
1188 # Remove a QOM object.
1189 #
1190 # @id: the name of the QOM object to remove
1191 #
1192 # Errors:
1193 # - Error if @id is not a valid id for a QOM object
1194 #
1195 # Since: 2.0
1196 #
1197 # Example:
1198 #
1199 # -> { "execute": "object-del", "arguments": { "id": "rng1" } }
1200 # <- { "return": {} }
1201 ##
1202 { 'command': 'object-del', 'data': {'id': 'str'},
1203 'allow-preconfig': true }