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