xref: /openbmc/qemu/qapi/misc.json (revision f68c0147)
1# -*- Mode: Python -*-
2# vim: filetype=python
3#
4
5##
6# = Miscellanea
7##
8
9{ 'include': 'common.json' }
10
11##
12# @add_client:
13#
14# Allow client connections for VNC, Spice and socket based
15# character devices to be passed in to QEMU via SCM_RIGHTS.
16#
17# @protocol: protocol name. Valid names are "vnc", "spice" or the
18#            name of a character device (eg. from -chardev id=XXXX)
19#
20# @fdname: file descriptor name previously passed via 'getfd' command
21#
22# @skipauth: whether to skip authentication. Only applies
23#            to "vnc" and "spice" protocols
24#
25# @tls: whether to perform TLS. Only applies to the "spice"
26#       protocol
27#
28# Returns: nothing on success.
29#
30# Since: 0.14.0
31#
32# Example:
33#
34# -> { "execute": "add_client", "arguments": { "protocol": "vnc",
35#                                              "fdname": "myclient" } }
36# <- { "return": {} }
37#
38##
39{ 'command': 'add_client',
40  'data': { 'protocol': 'str', 'fdname': 'str', '*skipauth': 'bool',
41            '*tls': 'bool' } }
42
43##
44# @NameInfo:
45#
46# Guest name information.
47#
48# @name: The name of the guest
49#
50# Since: 0.14.0
51##
52{ 'struct': 'NameInfo', 'data': {'*name': 'str'} }
53
54##
55# @query-name:
56#
57# Return the name information of a guest.
58#
59# Returns: @NameInfo of the guest
60#
61# Since: 0.14.0
62#
63# Example:
64#
65# -> { "execute": "query-name" }
66# <- { "return": { "name": "qemu-name" } }
67#
68##
69{ 'command': 'query-name', 'returns': 'NameInfo', 'allow-preconfig': true }
70
71##
72# @KvmInfo:
73#
74# Information about support for KVM acceleration
75#
76# @enabled: true if KVM acceleration is active
77#
78# @present: true if KVM acceleration is built into this executable
79#
80# Since: 0.14.0
81##
82{ 'struct': 'KvmInfo', 'data': {'enabled': 'bool', 'present': 'bool'} }
83
84##
85# @query-kvm:
86#
87# Returns information about KVM acceleration
88#
89# Returns: @KvmInfo
90#
91# Since: 0.14.0
92#
93# Example:
94#
95# -> { "execute": "query-kvm" }
96# <- { "return": { "enabled": true, "present": true } }
97#
98##
99{ 'command': 'query-kvm', 'returns': 'KvmInfo' }
100
101##
102# @IOThreadInfo:
103#
104# Information about an iothread
105#
106# @id: the identifier of the iothread
107#
108# @thread-id: ID of the underlying host thread
109#
110# @poll-max-ns: maximum polling time in ns, 0 means polling is disabled
111#               (since 2.9)
112#
113# @poll-grow: how many ns will be added to polling time, 0 means that it's not
114#             configured (since 2.9)
115#
116# @poll-shrink: how many ns will be removed from polling time, 0 means that
117#               it's not configured (since 2.9)
118#
119# Since: 2.0
120##
121{ 'struct': 'IOThreadInfo',
122  'data': {'id': 'str',
123           'thread-id': 'int',
124           'poll-max-ns': 'int',
125           'poll-grow': 'int',
126           'poll-shrink': 'int' } }
127
128##
129# @query-iothreads:
130#
131# Returns a list of information about each iothread.
132#
133# Note: this list excludes the QEMU main loop thread, which is not declared
134#       using the -object iothread command-line option.  It is always the main thread
135#       of the process.
136#
137# Returns: a list of @IOThreadInfo for each iothread
138#
139# Since: 2.0
140#
141# Example:
142#
143# -> { "execute": "query-iothreads" }
144# <- { "return": [
145#          {
146#             "id":"iothread0",
147#             "thread-id":3134
148#          },
149#          {
150#             "id":"iothread1",
151#             "thread-id":3135
152#          }
153#       ]
154#    }
155#
156##
157{ 'command': 'query-iothreads', 'returns': ['IOThreadInfo'],
158  'allow-preconfig': true }
159
160##
161# @PciMemoryRange:
162#
163# A PCI device memory region
164#
165# @base: the starting address (guest physical)
166#
167# @limit: the ending address (guest physical)
168#
169# Since: 0.14.0
170##
171{ 'struct': 'PciMemoryRange', 'data': {'base': 'int', 'limit': 'int'} }
172
173##
174# @PciMemoryRegion:
175#
176# Information about a PCI device I/O region.
177#
178# @bar: the index of the Base Address Register for this region
179#
180# @type: - 'io' if the region is a PIO region
181#        - 'memory' if the region is a MMIO region
182#
183# @size: memory size
184#
185# @prefetch: if @type is 'memory', true if the memory is prefetchable
186#
187# @mem_type_64: if @type is 'memory', true if the BAR is 64-bit
188#
189# Since: 0.14.0
190##
191{ 'struct': 'PciMemoryRegion',
192  'data': {'bar': 'int', 'type': 'str', 'address': 'int', 'size': 'int',
193           '*prefetch': 'bool', '*mem_type_64': 'bool' } }
194
195##
196# @PciBusInfo:
197#
198# Information about a bus of a PCI Bridge device
199#
200# @number: primary bus interface number.  This should be the number of the
201#          bus the device resides on.
202#
203# @secondary: secondary bus interface number.  This is the number of the
204#             main bus for the bridge
205#
206# @subordinate: This is the highest number bus that resides below the
207#               bridge.
208#
209# @io_range: The PIO range for all devices on this bridge
210#
211# @memory_range: The MMIO range for all devices on this bridge
212#
213# @prefetchable_range: The range of prefetchable MMIO for all devices on
214#                      this bridge
215#
216# Since: 2.4
217##
218{ 'struct': 'PciBusInfo',
219  'data': {'number': 'int', 'secondary': 'int', 'subordinate': 'int',
220           'io_range': 'PciMemoryRange',
221           'memory_range': 'PciMemoryRange',
222           'prefetchable_range': 'PciMemoryRange' } }
223
224##
225# @PciBridgeInfo:
226#
227# Information about a PCI Bridge device
228#
229# @bus: information about the bus the device resides on
230#
231# @devices: a list of @PciDeviceInfo for each device on this bridge
232#
233# Since: 0.14.0
234##
235{ 'struct': 'PciBridgeInfo',
236  'data': {'bus': 'PciBusInfo', '*devices': ['PciDeviceInfo']} }
237
238##
239# @PciDeviceClass:
240#
241# Information about the Class of a PCI device
242#
243# @desc: a string description of the device's class
244#
245# @class: the class code of the device
246#
247# Since: 2.4
248##
249{ 'struct': 'PciDeviceClass',
250  'data': {'*desc': 'str', 'class': 'int'} }
251
252##
253# @PciDeviceId:
254#
255# Information about the Id of a PCI device
256#
257# @device: the PCI device id
258#
259# @vendor: the PCI vendor id
260#
261# @subsystem: the PCI subsystem id (since 3.1)
262#
263# @subsystem-vendor: the PCI subsystem vendor id (since 3.1)
264#
265# Since: 2.4
266##
267{ 'struct': 'PciDeviceId',
268  'data': {'device': 'int', 'vendor': 'int', '*subsystem': 'int',
269            '*subsystem-vendor': 'int'} }
270
271##
272# @PciDeviceInfo:
273#
274# Information about a PCI device
275#
276# @bus: the bus number of the device
277#
278# @slot: the slot the device is located in
279#
280# @function: the function of the slot used by the device
281#
282# @class_info: the class of the device
283#
284# @id: the PCI device id
285#
286# @irq: if an IRQ is assigned to the device, the IRQ number
287#
288# @irq_pin: the IRQ pin, zero means no IRQ (since 5.1)
289#
290# @qdev_id: the device name of the PCI device
291#
292# @pci_bridge: if the device is a PCI bridge, the bridge information
293#
294# @regions: a list of the PCI I/O regions associated with the device
295#
296# Notes: the contents of @class_info.desc are not stable and should only be
297#        treated as informational.
298#
299# Since: 0.14.0
300##
301{ 'struct': 'PciDeviceInfo',
302  'data': {'bus': 'int', 'slot': 'int', 'function': 'int',
303           'class_info': 'PciDeviceClass', 'id': 'PciDeviceId',
304           '*irq': 'int', 'irq_pin': 'int', 'qdev_id': 'str',
305           '*pci_bridge': 'PciBridgeInfo', 'regions': ['PciMemoryRegion'] }}
306
307##
308# @PciInfo:
309#
310# Information about a PCI bus
311#
312# @bus: the bus index
313#
314# @devices: a list of devices on this bus
315#
316# Since: 0.14.0
317##
318{ 'struct': 'PciInfo', 'data': {'bus': 'int', 'devices': ['PciDeviceInfo']} }
319
320##
321# @query-pci:
322#
323# Return information about the PCI bus topology of the guest.
324#
325# Returns: a list of @PciInfo for each PCI bus. Each bus is
326#          represented by a json-object, which has a key with a json-array of
327#          all PCI devices attached to it. Each device is represented by a
328#          json-object.
329#
330# Since: 0.14.0
331#
332# Example:
333#
334# -> { "execute": "query-pci" }
335# <- { "return": [
336#          {
337#             "bus": 0,
338#             "devices": [
339#                {
340#                   "bus": 0,
341#                   "qdev_id": "",
342#                   "slot": 0,
343#                   "class_info": {
344#                      "class": 1536,
345#                      "desc": "Host bridge"
346#                   },
347#                   "id": {
348#                      "device": 32902,
349#                      "vendor": 4663
350#                   },
351#                   "function": 0,
352#                   "regions": [
353#                   ]
354#                },
355#                {
356#                   "bus": 0,
357#                   "qdev_id": "",
358#                   "slot": 1,
359#                   "class_info": {
360#                      "class": 1537,
361#                      "desc": "ISA bridge"
362#                   },
363#                   "id": {
364#                      "device": 32902,
365#                      "vendor": 28672
366#                   },
367#                   "function": 0,
368#                   "regions": [
369#                   ]
370#                },
371#                {
372#                   "bus": 0,
373#                   "qdev_id": "",
374#                   "slot": 1,
375#                   "class_info": {
376#                      "class": 257,
377#                      "desc": "IDE controller"
378#                   },
379#                   "id": {
380#                      "device": 32902,
381#                      "vendor": 28688
382#                   },
383#                   "function": 1,
384#                   "regions": [
385#                      {
386#                         "bar": 4,
387#                         "size": 16,
388#                         "address": 49152,
389#                         "type": "io"
390#                      }
391#                   ]
392#                },
393#                {
394#                   "bus": 0,
395#                   "qdev_id": "",
396#                   "slot": 2,
397#                   "class_info": {
398#                      "class": 768,
399#                      "desc": "VGA controller"
400#                   },
401#                   "id": {
402#                      "device": 4115,
403#                      "vendor": 184
404#                   },
405#                   "function": 0,
406#                   "regions": [
407#                      {
408#                         "prefetch": true,
409#                         "mem_type_64": false,
410#                         "bar": 0,
411#                         "size": 33554432,
412#                         "address": 4026531840,
413#                         "type": "memory"
414#                      },
415#                      {
416#                         "prefetch": false,
417#                         "mem_type_64": false,
418#                         "bar": 1,
419#                         "size": 4096,
420#                         "address": 4060086272,
421#                         "type": "memory"
422#                      },
423#                      {
424#                         "prefetch": false,
425#                         "mem_type_64": false,
426#                         "bar": 6,
427#                         "size": 65536,
428#                         "address": -1,
429#                         "type": "memory"
430#                      }
431#                   ]
432#                },
433#                {
434#                   "bus": 0,
435#                   "qdev_id": "",
436#                   "irq": 11,
437#                   "slot": 4,
438#                   "class_info": {
439#                      "class": 1280,
440#                      "desc": "RAM controller"
441#                   },
442#                   "id": {
443#                      "device": 6900,
444#                      "vendor": 4098
445#                   },
446#                   "function": 0,
447#                   "regions": [
448#                      {
449#                         "bar": 0,
450#                         "size": 32,
451#                         "address": 49280,
452#                         "type": "io"
453#                      }
454#                   ]
455#                }
456#             ]
457#          }
458#       ]
459#    }
460#
461# Note: This example has been shortened as the real response is too long.
462#
463##
464{ 'command': 'query-pci', 'returns': ['PciInfo'] }
465
466##
467# @stop:
468#
469# Stop all guest VCPU execution.
470#
471# Since:  0.14.0
472#
473# Notes: This function will succeed even if the guest is already in the stopped
474#        state.  In "inmigrate" state, it will ensure that the guest
475#        remains paused once migration finishes, as if the -S option was
476#        passed on the command line.
477#
478# Example:
479#
480# -> { "execute": "stop" }
481# <- { "return": {} }
482#
483##
484{ 'command': 'stop' }
485
486##
487# @system_reset:
488#
489# Performs a hard reset of a guest.
490#
491# Since: 0.14.0
492#
493# Example:
494#
495# -> { "execute": "system_reset" }
496# <- { "return": {} }
497#
498##
499{ 'command': 'system_reset' }
500
501##
502# @system_powerdown:
503#
504# Requests that a guest perform a powerdown operation.
505#
506# Since: 0.14.0
507#
508# Notes: A guest may or may not respond to this command.  This command
509#        returning does not indicate that a guest has accepted the request or
510#        that it has shut down.  Many guests will respond to this command by
511#        prompting the user in some way.
512# Example:
513#
514# -> { "execute": "system_powerdown" }
515# <- { "return": {} }
516#
517##
518{ 'command': 'system_powerdown' }
519
520##
521# @memsave:
522#
523# Save a portion of guest memory to a file.
524#
525# @val: the virtual address of the guest to start from
526#
527# @size: the size of memory region to save
528#
529# @filename: the file to save the memory to as binary data
530#
531# @cpu-index: the index of the virtual CPU to use for translating the
532#             virtual address (defaults to CPU 0)
533#
534# Returns: Nothing on success
535#
536# Since: 0.14.0
537#
538# Notes: Errors were not reliably returned until 1.1
539#
540# Example:
541#
542# -> { "execute": "memsave",
543#      "arguments": { "val": 10,
544#                     "size": 100,
545#                     "filename": "/tmp/virtual-mem-dump" } }
546# <- { "return": {} }
547#
548##
549{ 'command': 'memsave',
550  'data': {'val': 'int', 'size': 'int', 'filename': 'str', '*cpu-index': 'int'} }
551
552##
553# @pmemsave:
554#
555# Save a portion of guest physical memory to a file.
556#
557# @val: the physical address of the guest to start from
558#
559# @size: the size of memory region to save
560#
561# @filename: the file to save the memory to as binary data
562#
563# Returns: Nothing on success
564#
565# Since: 0.14.0
566#
567# Notes: Errors were not reliably returned until 1.1
568#
569# Example:
570#
571# -> { "execute": "pmemsave",
572#      "arguments": { "val": 10,
573#                     "size": 100,
574#                     "filename": "/tmp/physical-mem-dump" } }
575# <- { "return": {} }
576#
577##
578{ 'command': 'pmemsave',
579  'data': {'val': 'int', 'size': 'int', 'filename': 'str'} }
580
581##
582# @cont:
583#
584# Resume guest VCPU execution.
585#
586# Since:  0.14.0
587#
588# Returns:  If successful, nothing
589#
590# Notes: This command will succeed if the guest is currently running.  It
591#        will also succeed if the guest is in the "inmigrate" state; in
592#        this case, the effect of the command is to make sure the guest
593#        starts once migration finishes, removing the effect of the -S
594#        command line option if it was passed.
595#
596# Example:
597#
598# -> { "execute": "cont" }
599# <- { "return": {} }
600#
601##
602{ 'command': 'cont' }
603
604##
605# @x-exit-preconfig:
606#
607# Exit from "preconfig" state
608#
609# This command makes QEMU exit the preconfig state and proceed with
610# VM initialization using configuration data provided on the command line
611# and via the QMP monitor during the preconfig state. The command is only
612# available during the preconfig state (i.e. when the --preconfig command
613# line option was in use).
614#
615# Since 3.0
616#
617# Returns: nothing
618#
619# Example:
620#
621# -> { "execute": "x-exit-preconfig" }
622# <- { "return": {} }
623#
624##
625{ 'command': 'x-exit-preconfig', 'allow-preconfig': true }
626
627##
628# @system_wakeup:
629#
630# Wake up guest from suspend. If the guest has wake-up from suspend
631# support enabled (wakeup-suspend-support flag from
632# query-current-machine), wake-up guest from suspend if the guest is
633# in SUSPENDED state. Return an error otherwise.
634#
635# Since:  1.1
636#
637# Returns:  nothing.
638#
639# Note: prior to 4.0, this command does nothing in case the guest
640#       isn't suspended.
641#
642# Example:
643#
644# -> { "execute": "system_wakeup" }
645# <- { "return": {} }
646#
647##
648{ 'command': 'system_wakeup' }
649
650##
651# @inject-nmi:
652#
653# Injects a Non-Maskable Interrupt into the default CPU (x86/s390) or all CPUs (ppc64).
654# The command fails when the guest doesn't support injecting.
655#
656# Returns:  If successful, nothing
657#
658# Since:  0.14.0
659#
660# Note: prior to 2.1, this command was only supported for x86 and s390 VMs
661#
662# Example:
663#
664# -> { "execute": "inject-nmi" }
665# <- { "return": {} }
666#
667##
668{ 'command': 'inject-nmi' }
669
670##
671# @human-monitor-command:
672#
673# Execute a command on the human monitor and return the output.
674#
675# @command-line: the command to execute in the human monitor
676#
677# @cpu-index: The CPU to use for commands that require an implicit CPU
678#
679# Features:
680# @savevm-monitor-nodes: If present, HMP command savevm only snapshots
681#                        monitor-owned nodes if they have no parents.
682#                        This allows the use of 'savevm' with
683#                        -blockdev. (since 4.2)
684#
685# Returns: the output of the command as a string
686#
687# Since: 0.14.0
688#
689# Notes: This command only exists as a stop-gap.  Its use is highly
690#        discouraged.  The semantics of this command are not
691#        guaranteed: this means that command names, arguments and
692#        responses can change or be removed at ANY time.  Applications
693#        that rely on long term stability guarantees should NOT
694#        use this command.
695#
696#        Known limitations:
697#
698#        * This command is stateless, this means that commands that depend
699#          on state information (such as getfd) might not work
700#
701#        * Commands that prompt the user for data don't currently work
702#
703# Example:
704#
705# -> { "execute": "human-monitor-command",
706#      "arguments": { "command-line": "info kvm" } }
707# <- { "return": "kvm support: enabled\r\n" }
708#
709##
710{ 'command': 'human-monitor-command',
711  'data': {'command-line': 'str', '*cpu-index': 'int'},
712  'returns': 'str',
713  'features': [ 'savevm-monitor-nodes' ] }
714
715##
716# @change:
717#
718# This command is multiple commands multiplexed together.
719#
720# @device: This is normally the name of a block device but it may also be 'vnc'.
721#          when it's 'vnc', then sub command depends on @target
722#
723# @target: If @device is a block device, then this is the new filename.
724#          If @device is 'vnc', then if the value 'password' selects the vnc
725#          change password command.   Otherwise, this specifies a new server URI
726#          address to listen to for VNC connections.
727#
728# @arg: If @device is a block device, then this is an optional format to open
729#       the device with.
730#       If @device is 'vnc' and @target is 'password', this is the new VNC
731#       password to set.  See change-vnc-password for additional notes.
732#
733# Features:
734# @deprecated: This command is deprecated.  For changing block
735#              devices, use 'blockdev-change-medium' instead; for changing VNC
736#              parameters, use 'change-vnc-password' instead.
737#
738# Returns: - Nothing on success.
739#          - If @device is not a valid block device, DeviceNotFound
740#
741# Since: 0.14.0
742#
743# Example:
744#
745# 1. Change a removable medium
746#
747# -> { "execute": "change",
748#      "arguments": { "device": "ide1-cd0",
749#                     "target": "/srv/images/Fedora-12-x86_64-DVD.iso" } }
750# <- { "return": {} }
751#
752# 2. Change VNC password
753#
754# -> { "execute": "change",
755#      "arguments": { "device": "vnc", "target": "password",
756#                     "arg": "foobar1" } }
757# <- { "return": {} }
758#
759##
760{ 'command': 'change',
761  'data': {'device': 'str', 'target': 'str', '*arg': 'str'},
762  'features': [ 'deprecated' ] }
763
764##
765# @xen-set-global-dirty-log:
766#
767# Enable or disable the global dirty log mode.
768#
769# @enable: true to enable, false to disable.
770#
771# Returns: nothing
772#
773# Since: 1.3
774#
775# Example:
776#
777# -> { "execute": "xen-set-global-dirty-log",
778#      "arguments": { "enable": true } }
779# <- { "return": {} }
780#
781##
782{ 'command': 'xen-set-global-dirty-log', 'data': { 'enable': 'bool' } }
783
784##
785# @getfd:
786#
787# Receive a file descriptor via SCM rights and assign it a name
788#
789# @fdname: file descriptor name
790#
791# Returns: Nothing on success
792#
793# Since: 0.14.0
794#
795# Notes: If @fdname already exists, the file descriptor assigned to
796#        it will be closed and replaced by the received file
797#        descriptor.
798#
799#        The 'closefd' command can be used to explicitly close the
800#        file descriptor when it is no longer needed.
801#
802# Example:
803#
804# -> { "execute": "getfd", "arguments": { "fdname": "fd1" } }
805# <- { "return": {} }
806#
807##
808{ 'command': 'getfd', 'data': {'fdname': 'str'} }
809
810##
811# @closefd:
812#
813# Close a file descriptor previously passed via SCM rights
814#
815# @fdname: file descriptor name
816#
817# Returns: Nothing on success
818#
819# Since: 0.14.0
820#
821# Example:
822#
823# -> { "execute": "closefd", "arguments": { "fdname": "fd1" } }
824# <- { "return": {} }
825#
826##
827{ 'command': 'closefd', 'data': {'fdname': 'str'} }
828
829##
830# @MemoryInfo:
831#
832# Actual memory information in bytes.
833#
834# @base-memory: size of "base" memory specified with command line
835#               option -m.
836#
837# @plugged-memory: size of memory that can be hot-unplugged. This field
838#                  is omitted if target doesn't support memory hotplug
839#                  (i.e. CONFIG_MEM_DEVICE not defined at build time).
840#
841# Since: 2.11.0
842##
843{ 'struct': 'MemoryInfo',
844  'data'  : { 'base-memory': 'size', '*plugged-memory': 'size' } }
845
846##
847# @query-memory-size-summary:
848#
849# Return the amount of initially allocated and present hotpluggable (if
850# enabled) memory in bytes.
851#
852# Example:
853#
854# -> { "execute": "query-memory-size-summary" }
855# <- { "return": { "base-memory": 4294967296, "plugged-memory": 0 } }
856#
857# Since: 2.11.0
858##
859{ 'command': 'query-memory-size-summary', 'returns': 'MemoryInfo' }
860
861
862##
863# @AddfdInfo:
864#
865# Information about a file descriptor that was added to an fd set.
866#
867# @fdset-id: The ID of the fd set that @fd was added to.
868#
869# @fd: The file descriptor that was received via SCM rights and
870#      added to the fd set.
871#
872# Since: 1.2.0
873##
874{ 'struct': 'AddfdInfo', 'data': {'fdset-id': 'int', 'fd': 'int'} }
875
876##
877# @add-fd:
878#
879# Add a file descriptor, that was passed via SCM rights, to an fd set.
880#
881# @fdset-id: The ID of the fd set to add the file descriptor to.
882#
883# @opaque: A free-form string that can be used to describe the fd.
884#
885# Returns: - @AddfdInfo on success
886#          - If file descriptor was not received, FdNotSupplied
887#          - If @fdset-id is a negative value, InvalidParameterValue
888#
889# Notes: The list of fd sets is shared by all monitor connections.
890#
891#        If @fdset-id is not specified, a new fd set will be created.
892#
893# Since: 1.2.0
894#
895# Example:
896#
897# -> { "execute": "add-fd", "arguments": { "fdset-id": 1 } }
898# <- { "return": { "fdset-id": 1, "fd": 3 } }
899#
900##
901{ 'command': 'add-fd',
902  'data': { '*fdset-id': 'int',
903            '*opaque': 'str' },
904  'returns': 'AddfdInfo' }
905
906##
907# @remove-fd:
908#
909# Remove a file descriptor from an fd set.
910#
911# @fdset-id: The ID of the fd set that the file descriptor belongs to.
912#
913# @fd: The file descriptor that is to be removed.
914#
915# Returns: - Nothing on success
916#          - If @fdset-id or @fd is not found, FdNotFound
917#
918# Since: 1.2.0
919#
920# Notes: The list of fd sets is shared by all monitor connections.
921#
922#        If @fd is not specified, all file descriptors in @fdset-id
923#        will be removed.
924#
925# Example:
926#
927# -> { "execute": "remove-fd", "arguments": { "fdset-id": 1, "fd": 3 } }
928# <- { "return": {} }
929#
930##
931{ 'command': 'remove-fd', 'data': {'fdset-id': 'int', '*fd': 'int'} }
932
933##
934# @FdsetFdInfo:
935#
936# Information about a file descriptor that belongs to an fd set.
937#
938# @fd: The file descriptor value.
939#
940# @opaque: A free-form string that can be used to describe the fd.
941#
942# Since: 1.2.0
943##
944{ 'struct': 'FdsetFdInfo',
945  'data': {'fd': 'int', '*opaque': 'str'} }
946
947##
948# @FdsetInfo:
949#
950# Information about an fd set.
951#
952# @fdset-id: The ID of the fd set.
953#
954# @fds: A list of file descriptors that belong to this fd set.
955#
956# Since: 1.2.0
957##
958{ 'struct': 'FdsetInfo',
959  'data': {'fdset-id': 'int', 'fds': ['FdsetFdInfo']} }
960
961##
962# @query-fdsets:
963#
964# Return information describing all fd sets.
965#
966# Returns: A list of @FdsetInfo
967#
968# Since: 1.2.0
969#
970# Note: The list of fd sets is shared by all monitor connections.
971#
972# Example:
973#
974# -> { "execute": "query-fdsets" }
975# <- { "return": [
976#        {
977#          "fds": [
978#            {
979#              "fd": 30,
980#              "opaque": "rdonly:/path/to/file"
981#            },
982#            {
983#              "fd": 24,
984#              "opaque": "rdwr:/path/to/file"
985#            }
986#          ],
987#          "fdset-id": 1
988#        },
989#        {
990#          "fds": [
991#            {
992#              "fd": 28
993#            },
994#            {
995#              "fd": 29
996#            }
997#          ],
998#          "fdset-id": 0
999#        }
1000#      ]
1001#    }
1002#
1003##
1004{ 'command': 'query-fdsets', 'returns': ['FdsetInfo'] }
1005
1006##
1007# @AcpiTableOptions:
1008#
1009# Specify an ACPI table on the command line to load.
1010#
1011# At most one of @file and @data can be specified. The list of files specified
1012# by any one of them is loaded and concatenated in order. If both are omitted,
1013# @data is implied.
1014#
1015# Other fields / optargs can be used to override fields of the generic ACPI
1016# table header; refer to the ACPI specification 5.0, section 5.2.6 System
1017# Description Table Header. If a header field is not overridden, then the
1018# corresponding value from the concatenated blob is used (in case of @file), or
1019# it is filled in with a hard-coded value (in case of @data).
1020#
1021# String fields are copied into the matching ACPI member from lowest address
1022# upwards, and silently truncated / NUL-padded to length.
1023#
1024# @sig: table signature / identifier (4 bytes)
1025#
1026# @rev: table revision number (dependent on signature, 1 byte)
1027#
1028# @oem_id: OEM identifier (6 bytes)
1029#
1030# @oem_table_id: OEM table identifier (8 bytes)
1031#
1032# @oem_rev: OEM-supplied revision number (4 bytes)
1033#
1034# @asl_compiler_id: identifier of the utility that created the table
1035#                   (4 bytes)
1036#
1037# @asl_compiler_rev: revision number of the utility that created the
1038#                    table (4 bytes)
1039#
1040# @file: colon (:) separated list of pathnames to load and
1041#        concatenate as table data. The resultant binary blob is expected to
1042#        have an ACPI table header. At least one file is required. This field
1043#        excludes @data.
1044#
1045# @data: colon (:) separated list of pathnames to load and
1046#        concatenate as table data. The resultant binary blob must not have an
1047#        ACPI table header. At least one file is required. This field excludes
1048#        @file.
1049#
1050# Since: 1.5
1051##
1052{ 'struct': 'AcpiTableOptions',
1053  'data': {
1054    '*sig':               'str',
1055    '*rev':               'uint8',
1056    '*oem_id':            'str',
1057    '*oem_table_id':      'str',
1058    '*oem_rev':           'uint32',
1059    '*asl_compiler_id':   'str',
1060    '*asl_compiler_rev':  'uint32',
1061    '*file':              'str',
1062    '*data':              'str' }}
1063
1064##
1065# @CommandLineParameterType:
1066#
1067# Possible types for an option parameter.
1068#
1069# @string: accepts a character string
1070#
1071# @boolean: accepts "on" or "off"
1072#
1073# @number: accepts a number
1074#
1075# @size: accepts a number followed by an optional suffix (K)ilo,
1076#        (M)ega, (G)iga, (T)era
1077#
1078# Since: 1.5
1079##
1080{ 'enum': 'CommandLineParameterType',
1081  'data': ['string', 'boolean', 'number', 'size'] }
1082
1083##
1084# @CommandLineParameterInfo:
1085#
1086# Details about a single parameter of a command line option.
1087#
1088# @name: parameter name
1089#
1090# @type: parameter @CommandLineParameterType
1091#
1092# @help: human readable text string, not suitable for parsing.
1093#
1094# @default: default value string (since 2.1)
1095#
1096# Since: 1.5
1097##
1098{ 'struct': 'CommandLineParameterInfo',
1099  'data': { 'name': 'str',
1100            'type': 'CommandLineParameterType',
1101            '*help': 'str',
1102            '*default': 'str' } }
1103
1104##
1105# @CommandLineOptionInfo:
1106#
1107# Details about a command line option, including its list of parameter details
1108#
1109# @option: option name
1110#
1111# @parameters: an array of @CommandLineParameterInfo
1112#
1113# Since: 1.5
1114##
1115{ 'struct': 'CommandLineOptionInfo',
1116  'data': { 'option': 'str', 'parameters': ['CommandLineParameterInfo'] } }
1117
1118##
1119# @query-command-line-options:
1120#
1121# Query command line option schema.
1122#
1123# @option: option name
1124#
1125# Returns: list of @CommandLineOptionInfo for all options (or for the given
1126#          @option).  Returns an error if the given @option doesn't exist.
1127#
1128# Since: 1.5
1129#
1130# Example:
1131#
1132# -> { "execute": "query-command-line-options",
1133#      "arguments": { "option": "option-rom" } }
1134# <- { "return": [
1135#         {
1136#             "parameters": [
1137#                 {
1138#                     "name": "romfile",
1139#                     "type": "string"
1140#                 },
1141#                 {
1142#                     "name": "bootindex",
1143#                     "type": "number"
1144#                 }
1145#             ],
1146#             "option": "option-rom"
1147#         }
1148#      ]
1149#    }
1150#
1151##
1152{'command': 'query-command-line-options',
1153 'data': { '*option': 'str' },
1154 'returns': ['CommandLineOptionInfo'],
1155 'allow-preconfig': true }
1156
1157##
1158# @PCDIMMDeviceInfo:
1159#
1160# PCDIMMDevice state information
1161#
1162# @id: device's ID
1163#
1164# @addr: physical address, where device is mapped
1165#
1166# @size: size of memory that the device provides
1167#
1168# @slot: slot number at which device is plugged in
1169#
1170# @node: NUMA node number where device is plugged in
1171#
1172# @memdev: memory backend linked with device
1173#
1174# @hotplugged: true if device was hotplugged
1175#
1176# @hotpluggable: true if device if could be added/removed while machine is running
1177#
1178# Since: 2.1
1179##
1180{ 'struct': 'PCDIMMDeviceInfo',
1181  'data': { '*id': 'str',
1182            'addr': 'int',
1183            'size': 'int',
1184            'slot': 'int',
1185            'node': 'int',
1186            'memdev': 'str',
1187            'hotplugged': 'bool',
1188            'hotpluggable': 'bool'
1189          }
1190}
1191
1192##
1193# @VirtioPMEMDeviceInfo:
1194#
1195# VirtioPMEM state information
1196#
1197# @id: device's ID
1198#
1199# @memaddr: physical address in memory, where device is mapped
1200#
1201# @size: size of memory that the device provides
1202#
1203# @memdev: memory backend linked with device
1204#
1205# Since: 4.1
1206##
1207{ 'struct': 'VirtioPMEMDeviceInfo',
1208  'data': { '*id': 'str',
1209            'memaddr': 'size',
1210            'size': 'size',
1211            'memdev': 'str'
1212          }
1213}
1214
1215##
1216# @VirtioMEMDeviceInfo:
1217#
1218# VirtioMEMDevice state information
1219#
1220# @id: device's ID
1221#
1222# @memaddr: physical address in memory, where device is mapped
1223#
1224# @requested-size: the user requested size of the device
1225#
1226# @size: the (current) size of memory that the device provides
1227#
1228# @max-size: the maximum size of memory that the device can provide
1229#
1230# @block-size: the block size of memory that the device provides
1231#
1232# @node: NUMA node number where device is assigned to
1233#
1234# @memdev: memory backend linked with the region
1235#
1236# Since: 5.1
1237##
1238{ 'struct': 'VirtioMEMDeviceInfo',
1239  'data': { '*id': 'str',
1240            'memaddr': 'size',
1241            'requested-size': 'size',
1242            'size': 'size',
1243            'max-size': 'size',
1244            'block-size': 'size',
1245            'node': 'int',
1246            'memdev': 'str'
1247          }
1248}
1249
1250##
1251# @MemoryDeviceInfo:
1252#
1253# Union containing information about a memory device
1254#
1255# nvdimm is included since 2.12. virtio-pmem is included since 4.1.
1256# virtio-mem is included since 5.1.
1257#
1258# Since: 2.1
1259##
1260{ 'union': 'MemoryDeviceInfo',
1261  'data': { 'dimm': 'PCDIMMDeviceInfo',
1262            'nvdimm': 'PCDIMMDeviceInfo',
1263            'virtio-pmem': 'VirtioPMEMDeviceInfo',
1264            'virtio-mem': 'VirtioMEMDeviceInfo'
1265          }
1266}
1267
1268##
1269# @query-memory-devices:
1270#
1271# Lists available memory devices and their state
1272#
1273# Since: 2.1
1274#
1275# Example:
1276#
1277# -> { "execute": "query-memory-devices" }
1278# <- { "return": [ { "data":
1279#                       { "addr": 5368709120,
1280#                         "hotpluggable": true,
1281#                         "hotplugged": true,
1282#                         "id": "d1",
1283#                         "memdev": "/objects/memX",
1284#                         "node": 0,
1285#                         "size": 1073741824,
1286#                         "slot": 0},
1287#                    "type": "dimm"
1288#                  } ] }
1289#
1290##
1291{ 'command': 'query-memory-devices', 'returns': ['MemoryDeviceInfo'] }
1292
1293##
1294# @MEMORY_DEVICE_SIZE_CHANGE:
1295#
1296# Emitted when the size of a memory device changes. Only emitted for memory
1297# devices that can actually change the size (e.g., virtio-mem due to guest
1298# action).
1299#
1300# @id: device's ID
1301# @size: the new size of memory that the device provides
1302#
1303# Note: this event is rate-limited.
1304#
1305# Since: 5.1
1306#
1307# Example:
1308#
1309# <- { "event": "MEMORY_DEVICE_SIZE_CHANGE",
1310#      "data": { "id": "vm0", "size": 1073741824},
1311#      "timestamp": { "seconds": 1588168529, "microseconds": 201316 } }
1312#
1313##
1314{ 'event': 'MEMORY_DEVICE_SIZE_CHANGE',
1315  'data': { '*id': 'str', 'size': 'size' } }
1316
1317
1318##
1319# @MEM_UNPLUG_ERROR:
1320#
1321# Emitted when memory hot unplug error occurs.
1322#
1323# @device: device name
1324#
1325# @msg: Informative message
1326#
1327# Since: 2.4
1328#
1329# Example:
1330#
1331# <- { "event": "MEM_UNPLUG_ERROR"
1332#      "data": { "device": "dimm1",
1333#                "msg": "acpi: device unplug for unsupported device"
1334#      },
1335#      "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
1336#
1337##
1338{ 'event': 'MEM_UNPLUG_ERROR',
1339  'data': { 'device': 'str', 'msg': 'str' } }
1340
1341##
1342# @ACPISlotType:
1343#
1344# @DIMM: memory slot
1345# @CPU: logical CPU slot (since 2.7)
1346##
1347{ 'enum': 'ACPISlotType', 'data': [ 'DIMM', 'CPU' ] }
1348
1349##
1350# @ACPIOSTInfo:
1351#
1352# OSPM Status Indication for a device
1353# For description of possible values of @source and @status fields
1354# see "_OST (OSPM Status Indication)" chapter of ACPI5.0 spec.
1355#
1356# @device: device ID associated with slot
1357#
1358# @slot: slot ID, unique per slot of a given @slot-type
1359#
1360# @slot-type: type of the slot
1361#
1362# @source: an integer containing the source event
1363#
1364# @status: an integer containing the status code
1365#
1366# Since: 2.1
1367##
1368{ 'struct': 'ACPIOSTInfo',
1369  'data'  : { '*device': 'str',
1370              'slot': 'str',
1371              'slot-type': 'ACPISlotType',
1372              'source': 'int',
1373              'status': 'int' } }
1374
1375##
1376# @query-acpi-ospm-status:
1377#
1378# Return a list of ACPIOSTInfo for devices that support status
1379# reporting via ACPI _OST method.
1380#
1381# Since: 2.1
1382#
1383# Example:
1384#
1385# -> { "execute": "query-acpi-ospm-status" }
1386# <- { "return": [ { "device": "d1", "slot": "0", "slot-type": "DIMM", "source": 1, "status": 0},
1387#                  { "slot": "1", "slot-type": "DIMM", "source": 0, "status": 0},
1388#                  { "slot": "2", "slot-type": "DIMM", "source": 0, "status": 0},
1389#                  { "slot": "3", "slot-type": "DIMM", "source": 0, "status": 0}
1390#    ]}
1391#
1392##
1393{ 'command': 'query-acpi-ospm-status', 'returns': ['ACPIOSTInfo'] }
1394
1395##
1396# @ACPI_DEVICE_OST:
1397#
1398# Emitted when guest executes ACPI _OST method.
1399#
1400# @info: OSPM Status Indication
1401#
1402# Since: 2.1
1403#
1404# Example:
1405#
1406# <- { "event": "ACPI_DEVICE_OST",
1407#      "data": { "device": "d1", "slot": "0",
1408#                "slot-type": "DIMM", "source": 1, "status": 0 } }
1409#
1410##
1411{ 'event': 'ACPI_DEVICE_OST',
1412     'data': { 'info': 'ACPIOSTInfo' } }
1413
1414##
1415# @ReplayMode:
1416#
1417# Mode of the replay subsystem.
1418#
1419# @none: normal execution mode. Replay or record are not enabled.
1420#
1421# @record: record mode. All non-deterministic data is written into the
1422#          replay log.
1423#
1424# @play: replay mode. Non-deterministic data required for system execution
1425#        is read from the log.
1426#
1427# Since: 2.5
1428##
1429{ 'enum': 'ReplayMode',
1430  'data': [ 'none', 'record', 'play' ] }
1431
1432##
1433# @xen-load-devices-state:
1434#
1435# Load the state of all devices from file. The RAM and the block devices
1436# of the VM are not loaded by this command.
1437#
1438# @filename: the file to load the state of the devices from as binary
1439#            data. See xen-save-devices-state.txt for a description of the binary
1440#            format.
1441#
1442# Since: 2.7
1443#
1444# Example:
1445#
1446# -> { "execute": "xen-load-devices-state",
1447#      "arguments": { "filename": "/tmp/resume" } }
1448# <- { "return": {} }
1449#
1450##
1451{ 'command': 'xen-load-devices-state', 'data': {'filename': 'str'} }
1452