1QEMU-QMP-REF(7)                      QEMU                      QEMU-QMP-REF(7)
2
3
4

NAME

6       qemu-qmp-ref - QEMU QMP Reference Manual
7

INTRODUCTION

9       This document describes all commands currently supported by QMP.
10
11       Most  of  the time their usage is exactly the same as in the user Moni‐
12       tor, this means that any other document which  also  describe  commands
13       (the manpage, QEMU's manual, etc) can and should be consulted.
14
15       QMP has two types of commands: regular and query commands. Regular com‐
16       mands usually change the Virtual Machine's state someway,  while  query
17       commands  just  return  information. The sections below are divided ac‐
18       cordingly.
19
20       It's important to observe that all communication examples are formatted
21       in  a  reader-friendly  way, so that they're easier to understand. How‐
22       ever, in real protocol usage, they're emitted as a single line.
23
24       Also, the following notation is used to denote data flow:
25
26       Example:
27
28          -> data issued by the Client
29          <- Server data response
30
31       Please, refer to the QMP specification (docs/interop/qmp-spec.txt)  for
32       detailed information on the Server command and response formats.
33

STABILITY CONSIDERATIONS

35       The  current QMP command set (described in this file) may be useful for
36       a number of use cases, however it's limited and several  commands  have
37       bad defined semantics, specially with regard to command completion.
38
39       These  problems  are  going to be solved incrementally in the next QEMU
40       releases and we're going to establish a deprecation  policy  for  badly
41       defined commands.
42
43       If you're planning to adopt QMP, please observe the following:
44
45          1. The  deprecation  policy will take effect and be documented soon,
46             please check the documentation of each used command as soon as  a
47             new release of QEMU is available
48
49          2. DO NOT rely on anything which is not explicit documented
50
51          3. Errors,  in  special, are not documented. Applications should NOT
52             check for specific errors classes or data (it's  strongly  recom‐
53             mended to only check for the "error" key)
54

QMP ERRORS

56   QapiErrorClass (Enum)
57       QEMU error classes
58
59   Values
60       GenericError
61              this  is  used  for  errors  that don't require a specific error
62              class. This should be the default case for most errors
63
64       CommandNotFound
65              the requested command has not been found
66
67       DeviceNotActive
68              a device has failed to be become active
69
70       DeviceNotFound
71              the requested device has not been found
72
73       KVMMissingCap
74              the requested operation can't be fulfilled  because  a  required
75              KVM capability is missing
76
77   Since
78       1.2
79

COMMON DATA TYPES

81   IoOperationType (Enum)
82       An enumeration of the I/O operation types
83
84   Values
85       read   read operation
86
87       write  write operation
88
89   Since
90       2.1
91
92   OnOffAuto (Enum)
93       An enumeration of three options: on, off, and auto
94
95   Values
96       auto   QEMU selects the value between on and off
97
98       on     Enabled
99
100       off    Disabled
101
102   Since
103       2.2
104
105   OnOffSplit (Enum)
106       An enumeration of three values: on, off, and split
107
108   Values
109       on     Enabled
110
111       off    Disabled
112
113       split  Mixed
114
115   Since
116       2.6
117
118   String (Object)
119       A fat type wrapping 'str', to be embedded in lists.
120
121   Members
122       str: string
123              Not documented
124
125   Since
126       1.2
127
128   StrOrNull (Alternate)
129       This  is  a string value or the explicit lack of a string (null pointer
130       in C).  Intended for cases when 'optional absent' already has a differ‐
131       ent meaning.
132
133   Members
134       s: string
135              the string value
136
137       n: null
138              no string value
139
140   Since
141       2.10
142
143   OffAutoPCIBAR (Enum)
144       An enumeration of options for specifying a PCI BAR
145
146   Values
147       off    The specified feature is disabled
148
149       auto   The PCI BAR for the feature is automatically selected
150
151       bar0   PCI BAR0 is used for the feature
152
153       bar1   PCI BAR1 is used for the feature
154
155       bar2   PCI BAR2 is used for the feature
156
157       bar3   PCI BAR3 is used for the feature
158
159       bar4   PCI BAR4 is used for the feature
160
161       bar5   PCI BAR5 is used for the feature
162
163   Since
164       2.12
165
166   PCIELinkSpeed (Enum)
167       An enumeration of PCIe link speeds in units of GT/s
168
169   Values
170       2_5    2.5GT/s
171
172       5      5.0GT/s
173
174       8      8.0GT/s
175
176       16     16.0GT/s
177
178   Since
179       4.0
180
181   PCIELinkWidth (Enum)
182       An enumeration of PCIe link width
183
184   Values
185       1      x1
186
187       2      x2
188
189       4      x4
190
191       8      x8
192
193       12     x12
194
195       16     x16
196
197       32     x32
198
199   Since
200       4.0
201

SOCKET DATA TYPES

203   NetworkAddressFamily (Enum)
204       The network address family
205
206   Values
207       ipv4   IPV4 family
208
209       ipv6   IPV6 family
210
211       unix   unix socket
212
213       vsock  vsock family (since 2.8)
214
215       unknown
216              otherwise
217
218   Since
219       2.1
220
221   InetSocketAddressBase (Object)
222   Members
223       host: string
224              host part of the address
225
226       port: string
227              port part of the address
228
229   InetSocketAddress (Object)
230       Captures a socket address or address range in the Internet namespace.
231
232   Members
233       numeric: boolean (optional)
234              true  if  the  host/port  are guaranteed to be numeric, false if
235              name resolution should be attempted. Defaults to false.   (Since
236              2.9)
237
238       to: int (optional)
239              If  present,  this is range of possible addresses, with port be‐
240              tween port and to.
241
242       ipv4: boolean (optional)
243              whether to accept IPv4 addresses, default try both IPv4 and IPv6
244
245       ipv6: boolean (optional)
246              whether to accept IPv6 addresses, default try both IPv4 and IPv6
247
248       keep-alive: boolean (optional)
249              enable keep-alive when connecting to this socket. Not  supported
250              for passive sockets. (Since 4.2)
251
252       The members of InetSocketAddressBase
253
254   Since
255       1.3
256
257   UnixSocketAddress (Object)
258       Captures a socket address in the local ("Unix socket") namespace.
259
260   Members
261       path: string
262              filesystem path to use
263
264       abstract: boolean (optional) (If: defined(CONFIG_LINUX))
265              if  true, this is a Linux abstract socket address.  path will be
266              prefixed by a null byte, and optionally padded with null  bytes.
267              Defaults to false.  (Since 5.1)
268
269       tight: boolean (optional) (If: defined(CONFIG_LINUX))
270              if  false, pad an abstract socket address with enough null bytes
271              to make it fill struct sockaddr_un member sun_path.  Defaults to
272              true.  (Since 5.1)
273
274   Since
275       1.3
276
277   VsockSocketAddress (Object)
278       Captures a socket address in the vsock namespace.
279
280   Members
281       cid: string
282              unique host identifier
283
284       port: string
285              port
286
287   Note
288       string  types are used to allow for possible future hostname or service
289       resolution support.
290
291   Since
292       2.8
293
294   SocketAddressLegacy (Object)
295       Captures the address of a socket, which could also be a named file  de‐
296       scriptor
297
298   Members
299       type   One of inet, unix, vsock, fd
300
301       data: InetSocketAddress when type is "inet"
302
303       data: UnixSocketAddress when type is "unix"
304
305       data: VsockSocketAddress when type is "vsock"
306
307       data: String when type is "fd"
308
309   Note
310       This  type is deprecated in favor of SocketAddress.  The difference be‐
311       tween SocketAddressLegacy and SocketAddress is that  the  latter  is  a
312       flat  union rather than a simple union. Flat is nicer because it avoids
313       nesting on the wire, i.e. that form has fewer {}.
314
315   Since
316       1.3
317
318   SocketAddressType (Enum)
319       Available SocketAddress types
320
321   Values
322       inet   Internet address
323
324       unix   Unix domain socket
325
326       vsock  VMCI address
327
328       fd     decimal is for file descriptor number, otherwise a file descrip‐
329              tor  name.  Named file descriptors are permitted in monitor com‐
330              mands, in combination with the 'getfd' command. Decimal file de‐
331              scriptors  are  permitted  at startup or other contexts where no
332              monitor context is active.
333
334   Since
335       2.9
336
337   SocketAddress (Object)
338       Captures the address of a socket, which could also be a named file  de‐
339       scriptor
340
341   Members
342       type: SocketAddressType
343              Transport type
344
345       The members of InetSocketAddress when type is "inet"
346
347       The members of UnixSocketAddress when type is "unix"
348
349       The members of VsockSocketAddress when type is "vsock"
350
351       The members of String when type is "fd"
352
353   Since
354       2.9
355

VM RUN STATE

357   RunState (Enum)
358       An enumeration of VM run states.
359
360   Values
361       debug  QEMU is running on a debugger
362
363       finish-migrate
364              guest is paused to finish the migration process
365
366       inmigrate
367              guest  is  paused  waiting for an incoming migration.  Note that
368              this state does not tell whether the machine will start  at  the
369              end  of  the migration.  This depends on the command-line -S op‐
370              tion and any invocation of 'stop' or 'cont'  that  has  happened
371              since QEMU was started.
372
373       internal-error
374              An  internal error that prevents further guest execution has oc‐
375              curred
376
377       io-error
378              the last IOP has failed and the device is configured to pause on
379              I/O errors
380
381       paused guest has been paused via the 'stop' command
382
383       postmigrate
384              guest is paused following a successful 'migrate'
385
386       prelaunch
387              QEMU was started with -S and guest has not started
388
389       restore-vm
390              guest is paused to restore VM state
391
392       running
393              guest is actively running
394
395       save-vm
396              guest is paused to save the VM state
397
398       shutdown
399              guest is shut down (and -no-shutdown is in use)
400
401       suspended
402              guest is suspended (ACPI S3)
403
404       watchdog
405              the  watchdog  action  is configured to pause and has been trig‐
406              gered
407
408       guest-panicked
409              guest has been panicked as a result of guest OS panic
410
411       colo   guest is paused to save/restore VM state under colo  checkpoint,
412              VM can not get into this state unless colo capability is enabled
413              for migration. (since 2.8)
414
415       preconfig
416              QEMU is paused before board specific init callback is  executed.
417              The  state  is  reachable  only if the --preconfig CLI option is
418              used.  (Since 3.0)
419
420   ShutdownCause (Enum)
421       An enumeration of reasons for a Shutdown.
422
423   Values
424       none   No shutdown request pending
425
426       host-error
427              An error prevents further use of guest
428
429       host-qmp-quit
430              Reaction to the QMP command 'quit'
431
432       host-qmp-system-reset
433              Reaction to the QMP command 'system_reset'
434
435       host-signal
436              Reaction to a signal, such as SIGINT
437
438       host-ui
439              Reaction to a UI event, like window close
440
441       guest-shutdown
442              Guest shutdown/suspend request, via ACPI or other  hardware-spe‐
443              cific means
444
445       guest-reset
446              Guest reset request, and command line turns that into a shutdown
447
448       guest-panic
449              Guest panicked, and command line turns that into a shutdown
450
451       subsystem-reset
452              Partial guest reset that does not trigger QMP events and ignores
453              --no-reboot. This is useful for sanitizing  hypercalls  on  s390
454              that are used during kexec/kdump/boot
455
456   StatusInfo (Object)
457       Information about VCPU run state
458
459   Members
460       running: boolean
461              true if all VCPUs are runnable, false if not runnable
462
463       singlestep: boolean
464              true if VCPUs are in single-step mode
465
466       status: RunState
467              the virtual machine RunState
468
469   Since
470       0.14.0
471
472   Notes
473       singlestep is enabled through the GDB stub
474
475   query-status (Command)
476       Query the run status of all VCPUs
477
478   Returns
479       StatusInfo reflecting all VCPUs
480
481   Since
482       0.14.0
483
484   Example
485          -> { "execute": "query-status" }
486          <- { "return": { "running": true,
487                           "singlestep": false,
488                           "status": "running" } }
489
490   SHUTDOWN (Event)
491       Emitted when the virtual machine has shut down, indicating that qemu is
492       about to exit.
493
494   Arguments
495       guest: boolean
496              If true, the shutdown was triggered by a guest request (such  as
497              a  guest-initiated  ACPI shutdown request or other hardware-spe‐
498              cific action) rather than a host request (such as sending qemu a
499              SIGINT). (since 2.10)
500
501       reason: ShutdownCause
502              The ShutdownCause which resulted in the SHUTDOWN. (since 4.0)
503
504   Note
505       If the command-line option "-no-shutdown" has been specified, qemu will
506       not exit, and a STOP event will eventually follow the SHUTDOWN event
507
508   Since
509       0.12.0
510
511   Example
512          <- { "event": "SHUTDOWN", "data": { "guest": true },
513               "timestamp": { "seconds": 1267040730, "microseconds": 682951 } }
514
515   POWERDOWN (Event)
516       Emitted when the virtual machine is powered down through the power con‐
517       trol system, such as via ACPI.
518
519   Since
520       0.12.0
521
522   Example
523          <- { "event": "POWERDOWN",
524               "timestamp": { "seconds": 1267040730, "microseconds": 682951 } }
525
526   RESET (Event)
527       Emitted when the virtual machine is reset
528
529   Arguments
530       guest: boolean
531              If  true,  the reset was triggered by a guest request (such as a
532              guest-initiated ACPI reboot request or  other  hardware-specific
533              action) rather than a host request (such as the QMP command sys‐
534              tem_reset).  (since 2.10)
535
536       reason: ShutdownCause
537              The ShutdownCause of the RESET. (since 4.0)
538
539   Since
540       0.12.0
541
542   Example
543          <- { "event": "RESET", "data": { "guest": false },
544               "timestamp": { "seconds": 1267041653, "microseconds": 9518 } }
545
546   STOP (Event)
547       Emitted when the virtual machine is stopped
548
549   Since
550       0.12.0
551
552   Example
553          <- { "event": "STOP",
554               "timestamp": { "seconds": 1267041730, "microseconds": 281295 } }
555
556   RESUME (Event)
557       Emitted when the virtual machine resumes execution
558
559   Since
560       0.12.0
561
562   Example
563          <- { "event": "RESUME",
564               "timestamp": { "seconds": 1271770767, "microseconds": 582542 } }
565
566   SUSPEND (Event)
567       Emitted when guest enters a hardware suspension state, for example,  S3
568       state, which is sometimes called standby state
569
570   Since
571       1.1
572
573   Example
574          <- { "event": "SUSPEND",
575               "timestamp": { "seconds": 1344456160, "microseconds": 309119 } }
576
577   SUSPEND_DISK (Event)
578       Emitted  when  guest enters a hardware suspension state with data saved
579       on disk, for example, S4 state, which  is  sometimes  called  hibernate
580       state
581
582   Note
583       QEMU shuts down (similar to event SHUTDOWN) when entering this state
584
585   Since
586       1.2
587
588   Example
589          <-   { "event": "SUSPEND_DISK",
590                 "timestamp": { "seconds": 1344456160, "microseconds": 309119 } }
591
592   WAKEUP (Event)
593       Emitted when the guest has woken up from suspend state and is running
594
595   Since
596       1.1
597
598   Example
599          <- { "event": "WAKEUP",
600               "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
601
602   WATCHDOG (Event)
603       Emitted when the watchdog device's timer is expired
604
605   Arguments
606       action: WatchdogAction
607              action that has been taken
608
609   Note
610       If action is "reset", "shutdown", or "pause" the WATCHDOG event is fol‐
611       lowed respectively by the RESET, SHUTDOWN, or STOP events
612
613   Note
614       This event is rate-limited.
615
616   Since
617       0.13.0
618
619   Example
620          <- { "event": "WATCHDOG",
621               "data": { "action": "reset" },
622               "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
623
624   WatchdogAction (Enum)
625       An enumeration of the actions taken when the watchdog device's timer is
626       expired
627
628   Values
629       reset  system resets
630
631       shutdown
632              system  shutdown,  note  that  it is similar to powerdown, which
633              tries to set to system status and notify guest
634
635       poweroff
636              system poweroff, the emulator program exits
637
638       pause  system pauses, similar to stop
639
640       debug  system enters debug state
641
642       none   nothing is done
643
644       inject-nmi
645              a non-maskable interrupt is injected into the  first  VCPU  (all
646              VCPUS on x86) (since 2.4)
647
648   Since
649       2.1
650
651   watchdog-set-action (Command)
652       Set watchdog action
653
654   Arguments
655       action: WatchdogAction
656              Not documented
657
658   Since
659       2.11
660
661   GUEST_PANICKED (Event)
662       Emitted when guest OS panic is detected
663
664   Arguments
665       action: GuestPanicAction
666              action that has been taken, currently always "pause"
667
668       info: GuestPanicInformation (optional)
669              information about a panic (since 2.9)
670
671   Since
672       1.5
673
674   Example
675          <- { "event": "GUEST_PANICKED",
676               "data": { "action": "pause" } }
677
678   GUEST_CRASHLOADED (Event)
679       Emitted when guest OS crash loaded is detected
680
681   Arguments
682       action: GuestPanicAction
683              action that has been taken, currently always "run"
684
685       info: GuestPanicInformation (optional)
686              information about a panic
687
688   Since
689       5.0
690
691   Example
692          <- { "event": "GUEST_CRASHLOADED",
693               "data": { "action": "run" } }
694
695   GuestPanicAction (Enum)
696       An enumeration of the actions taken when guest OS panic is detected
697
698   Values
699       pause  system pauses
700
701       poweroff
702              Not documented
703
704       run    Not documented
705
706   Since
707       2.1 (poweroff since 2.8, run since 5.0)
708
709   GuestPanicInformationType (Enum)
710       An enumeration of the guest panic information types
711
712   Values
713       hyper-v
714              hyper-v guest panic information type
715
716       s390   s390 guest panic information type (Since: 2.12)
717
718   Since
719       2.9
720
721   GuestPanicInformation (Object)
722       Information about a guest panic
723
724   Members
725       type: GuestPanicInformationType
726              Crash type that defines the hypervisor specific information
727
728       The members of GuestPanicInformationHyperV when type is "hyper-v"
729
730       The members of GuestPanicInformationS390 when type is "s390"
731
732   Since
733       2.9
734
735   GuestPanicInformationHyperV (Object)
736       Hyper-V specific guest panic information (HV crash MSRs)
737
738   Members
739       arg1: int
740              Not documented
741
742       arg2: int
743              Not documented
744
745       arg3: int
746              Not documented
747
748       arg4: int
749              Not documented
750
751       arg5: int
752              Not documented
753
754   Since
755       2.9
756
757   S390CrashReason (Enum)
758       Reason why the CPU is in a crashed state.
759
760   Values
761       unknown
762              no crash reason was set
763
764       disabled-wait
765              the CPU has entered a disabled wait state
766
767       extint-loop
768              clock comparator or cpu timer interrupt with new PSW enabled for
769              external interrupts
770
771       pgmint-loop
772              program interrupt with BAD new PSW
773
774       opint-loop
775              operation exception interrupt with invalid code at  the  program
776              interrupt new PSW
777
778   Since
779       2.12
780
781   GuestPanicInformationS390 (Object)
782       S390 specific guest panic information (PSW)
783
784   Members
785       core: int
786              core id of the CPU that crashed
787
788       psw-mask: int
789              control fields of guest PSW
790
791       psw-addr: int
792              guest instruction address
793
794       reason: S390CrashReason
795              guest crash reason
796
797   Since
798       2.12
799
800   MEMORY_FAILURE (Event)
801       Emitted when a memory failure occurs on host side.
802
803   Arguments
804       recipient: MemoryFailureRecipient
805              recipient is defined as MemoryFailureRecipient.
806
807       action: MemoryFailureAction
808              action  that has been taken. action is defined as MemoryFailure‐
809              Action.
810
811       flags: MemoryFailureFlags
812              flags for MemoryFailureAction. action is defined as  MemoryFail‐
813              ureFlags.
814
815   Since
816       5.2
817
818   Example
819          <- { "event": "MEMORY_FAILURE",
820               "data": { "recipient": "hypervisor",
821                         "action": "fatal",
822                         "flags": { 'action-required': false } }
823
824   MemoryFailureRecipient (Enum)
825       Hardware memory failure occurs, handled by recipient.
826
827   Values
828       hypervisor
829              memory  failure at QEMU process address space.  (none guest mem‐
830              ory, but used by QEMU itself).
831
832       guest  memory failure at guest memory,
833
834   Since
835       5.2
836
837   MemoryFailureAction (Enum)
838       Actions taken by QEMU in response to a hardware memory failure.
839
840   Values
841       ignore the memory failure could be ignored.  This will only be the case
842              for action-optional failures.
843
844       inject memory  failure  occurred in guest memory, the guest enabled MCE
845              handling mechanism, and QEMU could inject the MCE into the guest
846              successfully.
847
848       fatal  the  failure  is unrecoverable.  This occurs for action-required
849              failures if the recipient is the hypervisor; QEMU will exit.
850
851       reset  the failure is unrecoverable but confined to  the  guest.   This
852              occurs  if  the recipient is a guest guest which is not ready to
853              handle memory failures.
854
855   Since
856       5.2
857
858   MemoryFailureFlags (Object)
859       Additional information on memory failures.
860
861   Members
862       action-required: boolean
863              whether a memory failure event is action-required or  action-op‐
864              tional (e.g. a failure during memory scrub).
865
866       recursive: boolean
867              whether  the  failure  occurred  while  the previous failure was
868              still in progress.
869
870   Since
871       5.2
872

CRYPTOGRAPHY

874   QCryptoTLSCredsEndpoint (Enum)
875       The type of network endpoint that will be using the credentials.   Most
876       types  of  credential require different setup / structures depending on
877       whether they will be used in a server versus a client.
878
879   Values
880       client the network endpoint is acting as the client
881
882       server the network endpoint is acting as the server
883
884   Since
885       2.5
886
887   QCryptoSecretFormat (Enum)
888       The data format that the secret is provided in
889
890   Values
891       raw    raw bytes. When encoded in JSON only valid UTF-8  sequences  can
892              be used
893
894       base64 arbitrary base64 encoded binary data
895
896   Since
897       2.6
898
899   QCryptoHashAlgorithm (Enum)
900       The supported algorithms for computing content digests
901
902   Values
903       md5    MD5. Should not be used in any new code, legacy compat only
904
905       sha1   SHA-1. Should not be used in any new code, legacy compat only
906
907       sha224 SHA-224. (since 2.7)
908
909       sha256 SHA-256. Current recommended strong hash.
910
911       sha384 SHA-384. (since 2.7)
912
913       sha512 SHA-512. (since 2.7)
914
915       ripemd160
916              RIPEMD-160. (since 2.7)
917
918   Since
919       2.6
920
921   QCryptoCipherAlgorithm (Enum)
922       The supported algorithms for content encryption ciphers
923
924   Values
925       aes-128
926              AES with 128 bit / 16 byte keys
927
928       aes-192
929              AES with 192 bit / 24 byte keys
930
931       aes-256
932              AES with 256 bit / 32 byte keys
933
934       des-rfb
935              RFB specific variant of single DES. Do not use except in VNC.
936
937       3des   3DES(EDE) with 192 bit / 24 byte keys (since 2.9)
938
939       cast5-128
940              Cast5 with 128 bit / 16 byte keys
941
942       serpent-128
943              Serpent with 128 bit / 16 byte keys
944
945       serpent-192
946              Serpent with 192 bit / 24 byte keys
947
948       serpent-256
949              Serpent with 256 bit / 32 byte keys
950
951       twofish-128
952              Twofish with 128 bit / 16 byte keys
953
954       twofish-192
955              Twofish with 192 bit / 24 byte keys
956
957       twofish-256
958              Twofish with 256 bit / 32 byte keys
959
960   Since
961       2.6
962
963   QCryptoCipherMode (Enum)
964       The supported modes for content encryption ciphers
965
966   Values
967       ecb    Electronic Code Book
968
969       cbc    Cipher Block Chaining
970
971       xts    XEX with tweaked code book and ciphertext stealing
972
973       ctr    Counter (Since 2.8)
974
975   Since
976       2.6
977
978   QCryptoIVGenAlgorithm (Enum)
979       The supported algorithms for generating initialization vectors for full
980       disk encryption. The 'plain' generator should not  be  used  for  disks
981       with  sector  numbers larger than 2^32, except where compatibility with
982       pre-existing Linux dm-crypt volumes is required.
983
984   Values
985       plain  64-bit sector number truncated to 32-bits
986
987       plain64
988              64-bit sector number
989
990       essiv  64-bit sector number encrypted with a hash of the encryption key
991
992   Since
993       2.6
994
995   QCryptoBlockFormat (Enum)
996       The supported full disk encryption formats
997
998   Values
999       qcow   QCow/QCow2 built-in AES-CBC encryption. Use only for  liberating
1000              data from old images.
1001
1002       luks   LUKS encryption format. Recommended for new images
1003
1004   Since
1005       2.6
1006
1007   QCryptoBlockOptionsBase (Object)
1008       The common options that apply to all full disk encryption formats
1009
1010   Members
1011       format: QCryptoBlockFormat
1012              the encryption format
1013
1014   Since
1015       2.6
1016
1017   QCryptoBlockOptionsQCow (Object)
1018       The options that apply to QCow/QCow2 AES-CBC encryption format
1019
1020   Members
1021       key-secret: string (optional)
1022              the  ID  of a QCryptoSecret object providing the decryption key.
1023              Mandatory except when probing image for metadata only.
1024
1025   Since
1026       2.6
1027
1028   QCryptoBlockOptionsLUKS (Object)
1029       The options that apply to LUKS encryption format
1030
1031   Members
1032       key-secret: string (optional)
1033              the ID of a QCryptoSecret object providing the  decryption  key.
1034              Mandatory except when probing image for metadata only.
1035
1036   Since
1037       2.6
1038
1039   QCryptoBlockCreateOptionsLUKS (Object)
1040       The options that apply to LUKS encryption format initialization
1041
1042   Members
1043       cipher-alg: QCryptoCipherAlgorithm (optional)
1044              the  cipher  algorithm for data encryption Currently defaults to
1045              'aes-256'.
1046
1047       cipher-mode: QCryptoCipherMode (optional)
1048              the cipher mode for data encryption Currently defaults to 'xts'
1049
1050       ivgen-alg: QCryptoIVGenAlgorithm (optional)
1051              the  initialization  vector  generator  Currently  defaults   to
1052              'plain64'
1053
1054       ivgen-hash-alg: QCryptoHashAlgorithm (optional)
1055              the  initialization  vector generator hash Currently defaults to
1056              'sha256'
1057
1058       hash-alg: QCryptoHashAlgorithm (optional)
1059              the master key hash algorithm Currently defaults to 'sha256'
1060
1061       iter-time: int (optional)
1062              number of milliseconds to spend in PBKDF passphrase  processing.
1063              Currently defaults to 2000. (since 2.8)
1064
1065       The members of QCryptoBlockOptionsLUKS
1066
1067   Since
1068       2.6
1069
1070   QCryptoBlockOpenOptions (Object)
1071       The  options that are available for all encryption formats when opening
1072       an existing volume
1073
1074   Members
1075       The members of QCryptoBlockOptionsBase
1076
1077       The members of QCryptoBlockOptionsQCow when format is "qcow"
1078
1079       The members of QCryptoBlockOptionsLUKS when format is "luks"
1080
1081   Since
1082       2.6
1083
1084   QCryptoBlockCreateOptions (Object)
1085       The options that are available for all encryption formats when initial‐
1086       izing a new volume
1087
1088   Members
1089       The members of QCryptoBlockOptionsBase
1090
1091       The members of QCryptoBlockOptionsQCow when format is "qcow"
1092
1093       The members of QCryptoBlockCreateOptionsLUKS when format is "luks"
1094
1095   Since
1096       2.6
1097
1098   QCryptoBlockInfoBase (Object)
1099       The common information that applies to all full disk encryption formats
1100
1101   Members
1102       format: QCryptoBlockFormat
1103              the encryption format
1104
1105   Since
1106       2.7
1107
1108   QCryptoBlockInfoLUKSSlot (Object)
1109       Information about the LUKS block encryption key slot options
1110
1111   Members
1112       active: boolean
1113              whether the key slot is currently in use
1114
1115       key-offset: int
1116              offset to the key material in bytes
1117
1118       iters: int (optional)
1119              number of PBKDF2 iterations for key material
1120
1121       stripes: int (optional)
1122              number of stripes for splitting key material
1123
1124   Since
1125       2.7
1126
1127   QCryptoBlockInfoLUKS (Object)
1128       Information about the LUKS block encryption options
1129
1130   Members
1131       cipher-alg: QCryptoCipherAlgorithm
1132              the cipher algorithm for data encryption
1133
1134       cipher-mode: QCryptoCipherMode
1135              the cipher mode for data encryption
1136
1137       ivgen-alg: QCryptoIVGenAlgorithm
1138              the initialization vector generator
1139
1140       ivgen-hash-alg: QCryptoHashAlgorithm (optional)
1141              the initialization vector generator hash
1142
1143       hash-alg: QCryptoHashAlgorithm
1144              the master key hash algorithm
1145
1146       payload-offset: int
1147              offset to the payload data in bytes
1148
1149       master-key-iters: int
1150              number of PBKDF2 iterations for key material
1151
1152       uuid: string
1153              unique identifier for the volume
1154
1155       slots: array of QCryptoBlockInfoLUKSSlot
1156              information about each key slot
1157
1158   Since
1159       2.7
1160
1161   QCryptoBlockInfo (Object)
1162       Information about the block encryption options
1163
1164   Members
1165       The members of QCryptoBlockInfoBase
1166
1167       The members of QCryptoBlockInfoLUKS when format is "luks"
1168
1169   Since
1170       2.7
1171
1172   QCryptoBlockLUKSKeyslotState (Enum)
1173       Defines state of keyslots that are affected by the update
1174
1175   Values
1176       active The slots contain the given password and marked as active
1177
1178       inactive
1179              The slots are erased (contain garbage) and marked as inactive
1180
1181   Since
1182       5.1
1183
1184   QCryptoBlockAmendOptionsLUKS (Object)
1185       This struct defines the update parameters that activate/de-activate set
1186       of keyslots
1187
1188   Members
1189       state: QCryptoBlockLUKSKeyslotState
1190              the desired state of the keyslots
1191
1192       new-secret: string (optional)
1193              The ID of a QCryptoSecret object providing the  password  to  be
1194              written into added active keyslots
1195
1196       old-secret: string (optional)
1197              Optional  (for  deactivation  only) If given will deactivate all
1198              keyslots that match password located in QCryptoSecret with  this
1199              ID
1200
1201       iter-time: int (optional)
1202              Optional  (for  activation only) Number of milliseconds to spend
1203              in PBKDF passphrase processing for the newly activated  keyslot.
1204              Currently defaults to 2000.
1205
1206       keyslot: int (optional)
1207              Optional. ID of the keyslot to activate/deactivate.  For keyslot
1208              activation, keyslot should not be active already (this is unsafe
1209              to  update an active keyslot), but possible if 'force' parameter
1210              is given.  If keyslot is not given, first free keyslot  will  be
1211              written.
1212
1213              For  keyslot  deactivation,  this  parameter specifies the exact
1214              keyslot to deactivate
1215
1216       secret: string (optional)
1217              Optional. The ID of a QCryptoSecret object providing  the  pass‐
1218              word  to  use  to  retrieve current master key.  Defaults to the
1219              same secret that was used to open the image
1220       Since 5.1
1221
1222   QCryptoBlockAmendOptions (Object)
1223       The options that are available for all encryption formats when amending
1224       encryption settings
1225
1226   Members
1227       The members of QCryptoBlockOptionsBase
1228
1229       The members of QCryptoBlockAmendOptionsLUKS when format is "luks"
1230
1231   Since
1232       5.1
1233

BLOCK DEVICES

1235   Block core (VM unrelated)
1236   Background jobs
1237   JobType (Enum)
1238       Type of a background job.
1239
1240   Values
1241       commit block commit job type, see "block-commit"
1242
1243       stream block stream job type, see "block-stream"
1244
1245       mirror drive mirror job type, see "drive-mirror"
1246
1247       backup drive backup job type, see "drive-backup"
1248
1249       create image creation job type, see "blockdev-create" (since 3.0)
1250
1251       amend  image options amend job type, see "x-blockdev-amend" (since 5.1)
1252
1253   Since
1254       1.7
1255
1256   JobStatus (Enum)
1257       Indicates the present state of a given job in its lifetime.
1258
1259   Values
1260       undefined
1261              Erroneous, default state. Should not ever be visible.
1262
1263       created
1264              The job has been created, but not yet started.
1265
1266       running
1267              The job is currently running.
1268
1269       paused The  job  is  running, but paused. The pause may be requested by
1270              either the QMP user or by internal processes.
1271
1272       ready  The job is running, but is ready for the user to signal  comple‐
1273              tion.   This  is used for long-running jobs like mirror that are
1274              designed to run indefinitely.
1275
1276       standby
1277              The job is ready,  but  paused.  This  is  nearly  identical  to
1278              paused.  The job may return to ready or otherwise be canceled.
1279
1280       waiting
1281              The job is waiting for other jobs in the transaction to converge
1282              to the waiting state. This status will likely not be visible for
1283              the last job in a transaction.
1284
1285       pending
1286              The  job  has finished its work, but has finalization steps that
1287              it needs to make prior to completing. These changes will require
1288              manual intervention via job-finalize if auto-finalize was set to
1289              false. These pending changes may still fail.
1290
1291       aborting
1292              The job is in the process of being aborted, and will finish with
1293              an  error.  The job will afterwards report that it is concluded.
1294              This status may not be visible to the management process.
1295
1296       concluded
1297              The job has finished all work. If auto-dismiss was set to false,
1298              the  job will remain in the query list until it is dismissed via
1299              job-dismiss.
1300
1301       null   The job is in the process of being dismantled. This state should
1302              not ever be visible externally.
1303
1304   Since
1305       2.12
1306
1307   JobVerb (Enum)
1308       Represents command verbs that can be applied to a job.
1309
1310   Values
1311       cancel see job-cancel
1312
1313       pause  see job-pause
1314
1315       resume see job-resume
1316
1317       set-speed
1318              see block-job-set-speed
1319
1320       complete
1321              see job-complete
1322
1323       dismiss
1324              see job-dismiss
1325
1326       finalize
1327              see job-finalize
1328
1329   Since
1330       2.12
1331
1332   JOB_STATUS_CHANGE (Event)
1333       Emitted when a job transitions to a different status.
1334
1335   Arguments
1336       id: string
1337              The job identifier
1338
1339       status: JobStatus
1340              The new job status
1341
1342   Since
1343       3.0
1344
1345   job-pause (Command)
1346       Pause an active job.
1347
1348       This command returns immediately after marking the active job for paus‐
1349       ing.  Pausing an already paused job is an error.
1350
1351       The job will pause as soon as possible, which means transitioning  into
1352       the  PAUSED  state  if it was RUNNING, or into STANDBY if it was READY.
1353       The corresponding JOB_STATUS_CHANGE event will be emitted.
1354
1355       Cancelling a paused job automatically resumes it.
1356
1357   Arguments
1358       id: string
1359              The job identifier.
1360
1361   Since
1362       3.0
1363
1364   job-resume (Command)
1365       Resume a paused job.
1366
1367       This command returns immediately after resuming a paused job.  Resuming
1368       an already running job is an error.
1369
1370       id : The job identifier.
1371
1372   Arguments
1373       id: string
1374              Not documented
1375
1376   Since
1377       3.0
1378
1379   job-cancel (Command)
1380       Instruct  an  active  background job to cancel at the next opportunity.
1381       This command returns immediately after marking the active job for  can‐
1382       cellation.
1383
1384       The  job  will  cancel  as  soon  as  possible and then emit a JOB_STA‐
1385       TUS_CHANGE event. Usually, the status will change to ABORTING,  but  it
1386       is  possible that a job successfully completes (e.g. because it was al‐
1387       most done and there was no opportunity to cancel earlier than  complet‐
1388       ing the job) and transitions to PENDING instead.
1389
1390   Arguments
1391       id: string
1392              The job identifier.
1393
1394   Since
1395       3.0
1396
1397   job-complete (Command)
1398       Manually trigger completion of an active job in the READY state.
1399
1400   Arguments
1401       id: string
1402              The job identifier.
1403
1404   Since
1405       3.0
1406
1407   job-dismiss (Command)
1408       Deletes  a  job that is in the CONCLUDED state. This command only needs
1409       to be run explicitly for jobs that don't  have  automatic  dismiss  en‐
1410       abled.
1411
1412       This command will refuse to operate on any job that has not yet reached
1413       its terminal state, JOB_STATUS_CONCLUDED. For jobs  that  make  use  of
1414       JOB_READY  event, job-cancel or job-complete will still need to be used
1415       as appropriate.
1416
1417   Arguments
1418       id: string
1419              The job identifier.
1420
1421   Since
1422       3.0
1423
1424   job-finalize (Command)
1425       Instructs all jobs in a transaction (or a single job if it is not  part
1426       of  any transaction) to finalize any graph changes and do any necessary
1427       cleanup. This command requires that all involved jobs are in the  PEND‐
1428       ING state.
1429
1430       For  jobs  in a transaction, instructing one job to finalize will force
1431       ALL jobs in the transaction to finalize, so it is only necessary to in‐
1432       struct a single member job to finalize.
1433
1434   Arguments
1435       id: string
1436              The  identifier  of any job in the transaction, or of a job that
1437              is not part of any transaction.
1438
1439   Since
1440       3.0
1441
1442   JobInfo (Object)
1443       Information about a job.
1444
1445   Members
1446       id: string
1447              The job identifier
1448
1449       type: JobType
1450              The kind of job that is being performed
1451
1452       status: JobStatus
1453              Current job state/status
1454
1455       current-progress: int
1456              Progress made until now. The unit is arbitrary and the value can
1457              only  meaningfully  be used for the ratio of current-progress to
1458              total-progress. The value is monotonically increasing.
1459
1460       total-progress: int
1461              Estimated current-progress value at the completion of  the  job.
1462              This  value  can arbitrarily change while the job is running, in
1463              both directions.
1464
1465       error: string (optional)
1466              If this field is present, the job failed; if it is still missing
1467              in the CONCLUDED state, this indicates successful completion.
1468
1469              The value is a human-readable error message to describe the rea‐
1470              son for the job failure. It should not  be  parsed  by  applica‐
1471              tions.
1472
1473   Since
1474       3.0
1475
1476   query-jobs (Command)
1477       Return information about jobs.
1478
1479   Returns
1480       a list with a JobInfo for each active job
1481
1482   Since
1483       3.0
1484
1485   SnapshotInfo (Object)
1486   Members
1487       id: string
1488              unique snapshot id
1489
1490       name: string
1491              user chosen name
1492
1493       vm-state-size: int
1494              size of the VM state
1495
1496       date-sec: int
1497              UTC date of the snapshot in seconds
1498
1499       date-nsec: int
1500              fractional part in nano seconds to be used with date-sec
1501
1502       vm-clock-sec: int
1503              VM clock relative to boot in seconds
1504
1505       vm-clock-nsec: int
1506              fractional part in nano seconds to be used with vm-clock-sec
1507
1508       icount: int (optional)
1509              Current  instruction count. Appears when execution record/replay
1510              is enabled. Used for "time-traveling" to match the moment in the
1511              recorded  execution  with the snapshots. This counter may be ob‐
1512              tained through query-replay command (since 5.2)
1513
1514   Since
1515       1.3
1516
1517   ImageInfoSpecificQCow2EncryptionBase (Object)
1518   Members
1519       format: BlockdevQcow2EncryptionFormat
1520              The encryption format
1521
1522   Since
1523       2.10
1524
1525   ImageInfoSpecificQCow2Encryption (Object)
1526   Members
1527       The members of ImageInfoSpecificQCow2EncryptionBase
1528
1529       The members of QCryptoBlockInfoLUKS when format is "luks"
1530
1531   Since
1532       2.10
1533
1534   ImageInfoSpecificQCow2 (Object)
1535   Members
1536       compat: string
1537              compatibility level
1538
1539       data-file: string (optional)
1540              the filename of the external data file that is stored in the im‐
1541              age and used as a default for opening the image (since: 4.0)
1542
1543       data-file-raw: boolean (optional)
1544              True  if  the external data file must stay valid as a standalone
1545              (read-only) raw image without looking at qcow2 metadata  (since:
1546              4.0)
1547
1548       extended-l2: boolean (optional)
1549              true if the image has extended L2 entries; only valid for compat
1550              >= 1.1 (since 5.2)
1551
1552       lazy-refcounts: boolean (optional)
1553              on or off; only valid for compat >= 1.1
1554
1555       corrupt: boolean (optional)
1556              true if the image has been marked corrupt; only valid for compat
1557              >= 1.1 (since 2.2)
1558
1559       refcount-bits: int
1560              width of a refcount entry in bits (since 2.3)
1561
1562       encrypt: ImageInfoSpecificQCow2Encryption (optional)
1563              details  about  encryption  parameters; only set if image is en‐
1564              crypted (since 2.10)
1565
1566       bitmaps: array of Qcow2BitmapInfo (optional)
1567              A list of qcow2 bitmap details (since 4.0)
1568
1569       compression-type: Qcow2CompressionType
1570              the image cluster compression method (since 5.1)
1571
1572   Since
1573       1.7
1574
1575   ImageInfoSpecificVmdk (Object)
1576   Members
1577       create-type: string
1578              The create type of VMDK image
1579
1580       cid: int
1581              Content id of image
1582
1583       parent-cid: int
1584              Parent VMDK image's cid
1585
1586       extents: array of ImageInfo
1587              List of extent files
1588
1589   Since
1590       1.7
1591
1592   ImageInfoSpecific (Object)
1593       A discriminated record of image format specific information structures.
1594
1595   Members
1596       type   One of qcow2, vmdk, luks
1597
1598       data: ImageInfoSpecificQCow2 when type is "qcow2"
1599
1600       data: ImageInfoSpecificVmdk when type is "vmdk"
1601
1602       data: QCryptoBlockInfoLUKS when type is "luks"
1603
1604   Since
1605       1.7
1606
1607   ImageInfo (Object)
1608       Information about a QEMU image file
1609
1610   Members
1611       filename: string
1612              name of the image file
1613
1614       format: string
1615              format of the image file
1616
1617       virtual-size: int
1618              maximum capacity in bytes of the image
1619
1620       actual-size: int (optional)
1621              actual size on disk in bytes of the image
1622
1623       dirty-flag: boolean (optional)
1624              true if image is not cleanly closed
1625
1626       cluster-size: int (optional)
1627              size of a cluster in bytes
1628
1629       encrypted: boolean (optional)
1630              true if the image is encrypted
1631
1632       compressed: boolean (optional)
1633              true if the image is compressed (Since 1.7)
1634
1635       backing-filename: string (optional)
1636              name of the backing file
1637
1638       full-backing-filename: string (optional)
1639              full path of the backing file
1640
1641       backing-filename-format: string (optional)
1642              the format of the backing file
1643
1644       snapshots: array of SnapshotInfo (optional)
1645              list of VM snapshots
1646
1647       backing-image: ImageInfo (optional)
1648              info of the backing image (since 1.6)
1649
1650       format-specific: ImageInfoSpecific (optional)
1651              structure  supplying  additional   format-specific   information
1652              (since 1.7)
1653
1654   Since
1655       1.3
1656
1657   ImageCheck (Object)
1658       Information about a QEMU image file check
1659
1660   Members
1661       filename: string
1662              name of the image file checked
1663
1664       format: string
1665              format of the image file checked
1666
1667       check-errors: int
1668              number of unexpected errors occurred during check
1669
1670       image-end-offset: int (optional)
1671              offset (in bytes) where the image ends, this field is present if
1672              the driver for the image format supports it
1673
1674       corruptions: int (optional)
1675              number of corruptions found during the check if any
1676
1677       leaks: int (optional)
1678              number of leaks found during the check if any
1679
1680       corruptions-fixed: int (optional)
1681              number of corruptions fixed during the check if any
1682
1683       leaks-fixed: int (optional)
1684              number of leaks fixed during the check if any
1685
1686       total-clusters: int (optional)
1687              total number of clusters, this field is present  if  the  driver
1688              for the image format supports it
1689
1690       allocated-clusters: int (optional)
1691              total number of allocated clusters, this field is present if the
1692              driver for the image format supports it
1693
1694       fragmented-clusters: int (optional)
1695              total number of fragmented clusters, this field  is  present  if
1696              the driver for the image format supports it
1697
1698       compressed-clusters: int (optional)
1699              total  number  of  compressed clusters, this field is present if
1700              the driver for the image format supports it
1701
1702   Since
1703       1.4
1704
1705   MapEntry (Object)
1706       Mapping information from a virtual block range to a host file range
1707
1708   Members
1709       start: int
1710              virtual (guest) offset of the first byte described by this entry
1711
1712       length: int
1713              the number of bytes of the mapped virtual range
1714
1715       data: boolean
1716              reading the image will actually read data from a file  (in  par‐
1717              ticular,  if  offset  is present this means that the sectors are
1718              not simply preallocated, but contain actual data in raw format)
1719
1720       zero: boolean
1721              whether the virtual blocks read as zeroes
1722
1723       depth: int
1724              number of layers (0 = top image, 1 = top image's  backing  file,
1725              ...,  n  -  1 = bottom image (where n is the number of images in
1726              the chain)) before reaching one for which the range is allocated
1727
1728       offset: int (optional)
1729              if present, the image file stores the data for this range in raw
1730              format at the given (host) offset
1731
1732       filename: string (optional)
1733              filename that is referred to by offset
1734
1735   Since
1736       2.6
1737
1738   BlockdevCacheInfo (Object)
1739       Cache mode information for a block device
1740
1741   Members
1742       writeback: boolean
1743              true if writeback mode is enabled
1744
1745       direct: boolean
1746              true if the host page cache is bypassed (O_DIRECT)
1747
1748       no-flush: boolean
1749              true if flush requests are ignored for the device
1750
1751   Since
1752       2.3
1753
1754   BlockDeviceInfo (Object)
1755       Information about the backing device for a block device.
1756
1757   Members
1758       file: string
1759              the filename of the backing device
1760
1761       node-name: string (optional)
1762              the name of the block driver node (Since 2.0)
1763
1764       ro: boolean
1765              true if the backing device was open read-only
1766
1767       drv: string
1768              the name of the block format used to open the backing device. As
1769              of 0.14.0 this can  be:  'blkdebug',  'bochs',  'cloop',  'cow',
1770              'dmg',  'file',  'file',  'ftp', 'ftps', 'host_cdrom', 'host_de‐
1771              vice', 'http',  'https',  'luks',  'nbd',  'parallels',  'qcow',
1772              'qcow2', 'raw', 'vdi', 'vmdk', 'vpc', 'vvfat' 2.2: 'archipelago'
1773              added,  'cow'  dropped  2.3:   'host_floppy'   deprecated   2.5:
1774              'host_floppy'  dropped  2.6:  'luks'  added  2.8:  'replication'
1775              added, 'tftp' dropped 2.9: 'archipelago' dropped
1776
1777       backing_file: string (optional)
1778              the name of the backing file (for copy-on-write)
1779
1780       backing_file_depth: int
1781              number of files in the backing file chain (since: 1.2)
1782
1783       encrypted: boolean
1784              true if the backing device is encrypted
1785
1786       encryption_key_missing: boolean
1787              always false
1788
1789       detect_zeroes: BlockdevDetectZeroesOptions
1790              detect and optimize zero writes (Since 2.1)
1791
1792       bps: int
1793              total throughput limit in bytes per second is specified
1794
1795       bps_rd: int
1796              read throughput limit in bytes per second is specified
1797
1798       bps_wr: int
1799              write throughput limit in bytes per second is specified
1800
1801       iops: int
1802              total I/O operations per second is specified
1803
1804       iops_rd: int
1805              read I/O operations per second is specified
1806
1807       iops_wr: int
1808              write I/O operations per second is specified
1809
1810       image: ImageInfo
1811              the info of image used (since: 1.6)
1812
1813       bps_max: int (optional)
1814
1815              total throughput limit during bursts,
1816                     in bytes (Since 1.7)
1817
1818       bps_rd_max: int (optional)
1819
1820              read throughput limit during bursts,
1821                     in bytes (Since 1.7)
1822
1823       bps_wr_max: int (optional)
1824
1825              write throughput limit during bursts,
1826                     in bytes (Since 1.7)
1827
1828       iops_max: int (optional)
1829
1830              total I/O operations per second during bursts,
1831                     in bytes (Since 1.7)
1832
1833       iops_rd_max: int (optional)
1834
1835              read I/O operations per second during bursts,
1836                     in bytes (Since 1.7)
1837
1838       iops_wr_max: int (optional)
1839
1840              write I/O operations per second during bursts,
1841                     in bytes (Since 1.7)
1842
1843       bps_max_length: int (optional)
1844
1845              maximum length of the bps_max burst
1846                     period, in seconds. (Since 2.6)
1847
1848       bps_rd_max_length: int (optional)
1849
1850              maximum length of the bps_rd_max
1851                     burst period, in seconds. (Since 2.6)
1852
1853       bps_wr_max_length: int (optional)
1854
1855              maximum length of the bps_wr_max
1856                     burst period, in seconds. (Since 2.6)
1857
1858       iops_max_length: int (optional)
1859
1860              maximum length of the iops burst
1861                     period, in seconds. (Since 2.6)
1862
1863       iops_rd_max_length: int (optional)
1864
1865              maximum length of the iops_rd_max
1866                     burst period, in seconds. (Since 2.6)
1867
1868       iops_wr_max_length: int (optional)
1869
1870              maximum length of the iops_wr_max
1871                     burst period, in seconds. (Since 2.6)
1872
1873       iops_size: int (optional)
1874              an I/O size in bytes (Since 1.7)
1875
1876       group: string (optional)
1877              throttle group name (Since 2.4)
1878
1879       cache: BlockdevCacheInfo
1880              the cache mode used for the block device (since: 2.3)
1881
1882       write_threshold: int
1883              configured write threshold  for  the  device.   0  if  disabled.
1884              (Since 2.3)
1885
1886       dirty-bitmaps: array of BlockDirtyInfo (optional)
1887              dirty  bitmaps information (only present if node has one or more
1888              dirty bitmaps) (Since 4.2)
1889
1890   Features
1891       deprecated
1892              Member  encryption_key_missing  is  deprecated.   It  is  always
1893              false.
1894
1895   Since
1896       0.14.0
1897
1898   BlockDeviceIoStatus (Enum)
1899       An enumeration of block device I/O status.
1900
1901   Values
1902       ok     The last I/O operation has succeeded
1903
1904       failed The last I/O operation has failed
1905
1906       nospace
1907              The last I/O operation has failed due to a no-space condition
1908
1909   Since
1910       1.0
1911
1912   DirtyBitmapStatus (Enum)
1913       An enumeration of possible states that a dirty bitmap can report to the
1914       user.
1915
1916   Values
1917       frozen The bitmap is currently in-use by  some  operation  and  is  im‐
1918              mutable.   If  the bitmap was active prior to the operation, new
1919              writes by the guest are being recorded in  a  temporary  buffer,
1920              and  will  not  be lost.  Generally, bitmaps are cleared on suc‐
1921              cessful use in an operation and the temporary buffer is  commit‐
1922              ted  into the bitmap. On failure, the temporary buffer is merged
1923              back into the bitmap without first clearing it.  Please refer to
1924              the  documentation  for  each  bitmap-using  operation, See also
1925              blockdev-backup, drive-backup.
1926
1927       disabled
1928              The bitmap is not currently recording new writes by  the  guest.
1929              This is requested explicitly via block-dirty-bitmap-disable.  It
1930              can still be cleared, deleted, or used for backup operations.
1931
1932       active The bitmap is actively monitoring for new  writes,  and  can  be
1933              cleared, deleted, or used for backup operations.
1934
1935       locked The  bitmap  is  currently  in-use  by some operation and is im‐
1936              mutable.  If the bitmap was active prior to the operation, it is
1937              still  recording  new  writes. If the bitmap was disabled, it is
1938              not recording new writes. (Since 2.12)
1939
1940       inconsistent
1941              This is a persistent dirty bitmap  that  was  marked  in-use  on
1942              disk,  and  is unusable by QEMU. It can only be deleted.  Please
1943              rely on the inconsistent field in BlockDirtyInfo instead, as the
1944              status field is deprecated. (Since 4.0)
1945
1946   Since
1947       2.4
1948
1949   BlockDirtyInfo (Object)
1950       Block dirty bitmap information.
1951
1952   Members
1953       name: string (optional)
1954              the name of the dirty bitmap (Since 2.4)
1955
1956       count: int
1957              number of dirty bytes according to the dirty bitmap
1958
1959       granularity: int
1960              granularity of the dirty bitmap in bytes (since 1.4)
1961
1962       status: DirtyBitmapStatus
1963              current status of the dirty bitmap (since 2.4)
1964
1965       recording: boolean
1966              true  if the bitmap is recording new writes from the guest.  Re‐
1967              places active and disabled statuses. (since 4.0)
1968
1969       busy: boolean
1970              true if the bitmap is in-use by some operation (NBD or jobs) and
1971              cannot  be  modified  via QMP or used by another operation.  Re‐
1972              places locked and frozen statuses. (since 4.0)
1973
1974       persistent: boolean
1975              true if the bitmap was stored on disk, is scheduled to be stored
1976              on disk, or both. (since 4.0)
1977
1978       inconsistent: boolean (optional)
1979              true  if this is a persistent bitmap that was improperly stored.
1980              Implies persistent to be true; recording and busy to  be  false.
1981              This  bitmap  cannot be used. To remove it, use block-dirty-bit‐
1982              map-remove. (Since 4.0)
1983
1984   Features
1985       deprecated
1986              Member status is deprecated.  Use recording and locked instead.
1987
1988   Since
1989       1.3
1990
1991   Qcow2BitmapInfoFlags (Enum)
1992       An enumeration of flags that a bitmap can report to the user.
1993
1994   Values
1995       in-use This flag is set by any process  actively  modifying  the  qcow2
1996              file,  and  cleared  when  the  updated bitmap is flushed to the
1997              qcow2 image.  The presence of this  flag  in  an  offline  image
1998              means that the bitmap was not saved correctly after its last us‐
1999              age, and may contain inconsistent data.
2000
2001       auto   The bitmap must reflect all changes of the virtual disk  by  any
2002              application that would write to this qcow2 file.
2003
2004   Since
2005       4.0
2006
2007   Qcow2BitmapInfo (Object)
2008       Qcow2 bitmap information.
2009
2010   Members
2011       name: string
2012              the name of the bitmap
2013
2014       granularity: int
2015              granularity of the bitmap in bytes
2016
2017       flags: array of Qcow2BitmapInfoFlags
2018              flags of the bitmap
2019
2020   Since
2021       4.0
2022
2023   BlockLatencyHistogramInfo (Object)
2024       Block latency histogram.
2025
2026   Members
2027       boundaries: array of int
2028              list  of  interval  boundary  values in nanoseconds, all greater
2029              than zero and in ascending order.  For example,  the  list  [10,
2030              50,  100]  produces  the following histogram intervals: [0, 10),
2031              [10, 50), [50, 100), [100, +inf).
2032
2033       bins: array of int
2034              list of io request counts corresponding to histogram  intervals.
2035              len(bins)  = len(boundaries) + 1 For the example above, bins may
2036              be something like [3, 1,  5,  2],  and  corresponding  histogram
2037              looks like:
2038
2039          5|           *
2040          4|           *
2041          3| *         *
2042          2| *         *    *
2043          1| *    *    *    *
2044           +------------------
2045               10   50   100
2046
2047   Since
2048       4.0
2049
2050   BlockInfo (Object)
2051       Block  device  information.   This structure describes a virtual device
2052       and the backing device associated with it.
2053
2054   Members
2055       device: string
2056              The device name associated with the virtual device.
2057
2058       qdev: string (optional)
2059              The qdev ID, or if no ID is assigned, the QOM path of the  block
2060              device. (since 2.10)
2061
2062       type: string
2063              This field is returned only for compatibility reasons, it should
2064              not be used (always returns 'unknown')
2065
2066       removable: boolean
2067              True if the device supports removable media.
2068
2069       locked: boolean
2070              True if the guest has locked this device from having  its  media
2071              removed
2072
2073       tray_open: boolean (optional)
2074              True  if  the  device's  tray  is open (only present if it has a
2075              tray)
2076
2077       dirty-bitmaps: array of BlockDirtyInfo (optional)
2078              dirty bitmaps information (only present if the driver has one or
2079              more dirty bitmaps) (Since 2.0)
2080
2081       io-status: BlockDeviceIoStatus (optional)
2082              BlockDeviceIoStatus.  Only present if the device supports it and
2083              the VM is configured to stop on errors (supported device models:
2084              virtio-blk, IDE, SCSI except scsi-generic)
2085
2086       inserted: BlockDeviceInfo (optional)
2087              BlockDeviceInfo describing the device if media is present
2088
2089   Features
2090       deprecated
2091              Member   dirty-bitmaps   is  deprecated.   Use  inserted  member
2092              dirty-bitmaps instead.
2093
2094   Since
2095       0.14.0
2096
2097   BlockMeasureInfo (Object)
2098       Image file size calculation information.  This structure describes  the
2099       size requirements for creating a new image file.
2100
2101       The  size  requirements depend on the new image file format.  File size
2102       always equals virtual disk size for the 'raw' format, even  for  sparse
2103       POSIX files.  Compact formats such as 'qcow2' represent unallocated and
2104       zero regions efficiently so file size may be smaller than virtual  disk
2105       size.
2106
2107       The  values  are  upper bounds that are guaranteed to fit the new image
2108       file.  Subsequent modification, such as internal  snapshot  or  further
2109       bitmap creation, may require additional space and is not covered here.
2110
2111   Members
2112       required: int
2113              Size  required for a new image file, in bytes, when copying just
2114              allocated guest-visible contents.
2115
2116       fully-allocated: int
2117              Image file size, in bytes, once data has  been  written  to  all
2118              sectors, when copying just guest-visible contents.
2119
2120       bitmaps: int (optional)
2121              Additional size required if all the top-level bitmap metadata in
2122              the source image were to be copied to the  destination,  present
2123              only  when  source  and destination both support persistent bit‐
2124              maps. (since 5.1)
2125
2126   Since
2127       2.10
2128
2129   query-block (Command)
2130       Get a list of BlockInfo for all virtual block devices.
2131
2132   Returns
2133       a list of BlockInfo describing each virtual block device. Filter  nodes
2134       that were created implicitly are skipped over.
2135
2136   Since
2137       0.14.0
2138
2139   Example
2140          -> { "execute": "query-block" }
2141          <- {
2142                "return":[
2143                   {
2144                      "io-status": "ok",
2145                      "device":"ide0-hd0",
2146                      "locked":false,
2147                      "removable":false,
2148                      "inserted":{
2149                         "ro":false,
2150                         "drv":"qcow2",
2151                         "encrypted":false,
2152                         "file":"disks/test.qcow2",
2153                         "backing_file_depth":1,
2154                         "bps":1000000,
2155                         "bps_rd":0,
2156                         "bps_wr":0,
2157                         "iops":1000000,
2158                         "iops_rd":0,
2159                         "iops_wr":0,
2160                         "bps_max": 8000000,
2161                         "bps_rd_max": 0,
2162                         "bps_wr_max": 0,
2163                         "iops_max": 0,
2164                         "iops_rd_max": 0,
2165                         "iops_wr_max": 0,
2166                         "iops_size": 0,
2167                         "detect_zeroes": "on",
2168                         "write_threshold": 0,
2169                         "image":{
2170                            "filename":"disks/test.qcow2",
2171                            "format":"qcow2",
2172                            "virtual-size":2048000,
2173                            "backing_file":"base.qcow2",
2174                            "full-backing-filename":"disks/base.qcow2",
2175                            "backing-filename-format":"qcow2",
2176                            "snapshots":[
2177                               {
2178                                  "id": "1",
2179                                  "name": "snapshot1",
2180                                  "vm-state-size": 0,
2181                                  "date-sec": 10000200,
2182                                  "date-nsec": 12,
2183                                  "vm-clock-sec": 206,
2184                                  "vm-clock-nsec": 30
2185                               }
2186                            ],
2187                            "backing-image":{
2188                                "filename":"disks/base.qcow2",
2189                                "format":"qcow2",
2190                                "virtual-size":2048000
2191                            }
2192                         }
2193                      },
2194                      "qdev": "ide_disk",
2195                      "type":"unknown"
2196                   },
2197                   {
2198                      "io-status": "ok",
2199                      "device":"ide1-cd0",
2200                      "locked":false,
2201                      "removable":true,
2202                      "qdev": "/machine/unattached/device[23]",
2203                      "tray_open": false,
2204                      "type":"unknown"
2205                   },
2206                   {
2207                      "device":"floppy0",
2208                      "locked":false,
2209                      "removable":true,
2210                      "qdev": "/machine/unattached/device[20]",
2211                      "type":"unknown"
2212                   },
2213                   {
2214                      "device":"sd0",
2215                      "locked":false,
2216                      "removable":true,
2217                      "type":"unknown"
2218                   }
2219                ]
2220             }
2221
2222   BlockDeviceTimedStats (Object)
2223       Statistics of a block device during a given interval of time.
2224
2225   Members
2226       interval_length: int
2227              Interval used for calculating the statistics, in seconds.
2228
2229       min_rd_latency_ns: int
2230              Minimum  latency  of read operations in the defined interval, in
2231              nanoseconds.
2232
2233       min_wr_latency_ns: int
2234              Minimum latency of write operations in the defined interval,  in
2235              nanoseconds.
2236
2237       min_flush_latency_ns: int
2238              Minimum  latency of flush operations in the defined interval, in
2239              nanoseconds.
2240
2241       max_rd_latency_ns: int
2242              Maximum latency of read operations in the defined  interval,  in
2243              nanoseconds.
2244
2245       max_wr_latency_ns: int
2246              Maximum  latency of write operations in the defined interval, in
2247              nanoseconds.
2248
2249       max_flush_latency_ns: int
2250              Maximum latency of flush operations in the defined interval,  in
2251              nanoseconds.
2252
2253       avg_rd_latency_ns: int
2254              Average  latency  of read operations in the defined interval, in
2255              nanoseconds.
2256
2257       avg_wr_latency_ns: int
2258              Average latency of write operations in the defined interval,  in
2259              nanoseconds.
2260
2261       avg_flush_latency_ns: int
2262              Average  latency of flush operations in the defined interval, in
2263              nanoseconds.
2264
2265       avg_rd_queue_depth: number
2266              Average number of pending read operations in the defined  inter‐
2267              val.
2268
2269       avg_wr_queue_depth: number
2270              Average number of pending write operations in the defined inter‐
2271              val.
2272
2273   Since
2274       2.5
2275
2276   BlockDeviceStats (Object)
2277       Statistics of a virtual block device or a block backing device.
2278
2279   Members
2280       rd_bytes: int
2281              The number of bytes read by the device.
2282
2283       wr_bytes: int
2284              The number of bytes written by the device.
2285
2286       unmap_bytes: int
2287              The number of bytes unmapped by the device (Since 4.2)
2288
2289       rd_operations: int
2290              The number of read operations performed by the device.
2291
2292       wr_operations: int
2293              The number of write operations performed by the device.
2294
2295       flush_operations: int
2296              The number of cache flush operations  performed  by  the  device
2297              (since 0.15.0)
2298
2299       unmap_operations: int
2300              The  number  of  unmap operations performed by the device (Since
2301              4.2)
2302
2303       rd_total_time_ns: int
2304              Total time spent on reads in nanoseconds (since 0.15.0).
2305
2306       wr_total_time_ns: int
2307              Total time spent on writes in nanoseconds (since 0.15.0).
2308
2309       flush_total_time_ns: int
2310              Total time spent on cache flushes in nanoseconds (since 0.15.0).
2311
2312       unmap_total_time_ns: int
2313              Total time spent on unmap operations in nanoseconds (Since 4.2)
2314
2315       wr_highest_offset: int
2316              The offset after the greatest byte written to the  device.   The
2317              intended  use  of  this information is for growable sparse files
2318              (like qcow2) that are used on top of a physical device.
2319
2320       rd_merged: int
2321              Number of read requests that have been merged into  another  re‐
2322              quest (Since 2.3).
2323
2324       wr_merged: int
2325              Number  of write requests that have been merged into another re‐
2326              quest (Since 2.3).
2327
2328       unmap_merged: int
2329              Number of unmap requests that have been merged into another  re‐
2330              quest (Since 4.2)
2331
2332       idle_time_ns: int (optional)
2333              Time  since the last I/O operation, in nanoseconds. If the field
2334              is absent it means that there haven't been  any  operations  yet
2335              (Since 2.5).
2336
2337       failed_rd_operations: int
2338              The  number  of  failed  read operations performed by the device
2339              (Since 2.5)
2340
2341       failed_wr_operations: int
2342              The number of failed write operations performed  by  the  device
2343              (Since 2.5)
2344
2345       failed_flush_operations: int
2346              The  number  of  failed flush operations performed by the device
2347              (Since 2.5)
2348
2349       failed_unmap_operations: int
2350              The number of failed unmap operations performed  by  the  device
2351              (Since 4.2)
2352
2353       invalid_rd_operations: int
2354
2355              The number of invalid read operations
2356                     performed by the device (Since 2.5)
2357
2358       invalid_wr_operations: int
2359              The  number  of invalid write operations performed by the device
2360              (Since 2.5)
2361
2362       invalid_flush_operations: int
2363              The number of invalid flush operations performed by  the  device
2364              (Since 2.5)
2365
2366       invalid_unmap_operations: int
2367              The  number  of invalid unmap operations performed by the device
2368              (Since 4.2)
2369
2370       account_invalid: boolean
2371              Whether invalid operations are included in the last access  sta‐
2372              tistics (Since 2.5)
2373
2374       account_failed: boolean
2375              Whether  failed  operations are included in the latency and last
2376              access statistics (Since 2.5)
2377
2378       timed_stats: array of BlockDeviceTimedStats
2379              Statistics specific to the set of previously  defined  intervals
2380              of time (Since 2.5)
2381
2382       rd_latency_histogram: BlockLatencyHistogramInfo (optional)
2383              BlockLatencyHistogramInfo. (Since 4.0)
2384
2385       wr_latency_histogram: BlockLatencyHistogramInfo (optional)
2386              BlockLatencyHistogramInfo. (Since 4.0)
2387
2388       flush_latency_histogram: BlockLatencyHistogramInfo (optional)
2389              BlockLatencyHistogramInfo. (Since 4.0)
2390
2391   Since
2392       0.14.0
2393
2394   BlockStatsSpecificFile (Object)
2395       File driver statistics
2396
2397   Members
2398       discard-nb-ok: int
2399              The  number  of  successful  discard operations performed by the
2400              driver.
2401
2402       discard-nb-failed: int
2403              The number of failed discard operations performed by the driver.
2404
2405       discard-bytes-ok: int
2406              The number of bytes discarded by the driver.
2407
2408   Since
2409       4.2
2410
2411   BlockStatsSpecificNvme (Object)
2412       NVMe driver statistics
2413
2414   Members
2415       completion-errors: int
2416              The number of completion errors.
2417
2418       aligned-accesses: int
2419              The number of aligned accesses performed by the driver.
2420
2421       unaligned-accesses: int
2422              The number of unaligned accesses performed by the driver.
2423
2424   Since
2425       5.2
2426
2427   BlockStatsSpecific (Object)
2428       Block driver specific statistics
2429
2430   Members
2431       driver: BlockdevDriver
2432              Not documented
2433
2434       The members of BlockStatsSpecificFile when driver is "file"
2435
2436       The members of BlockStatsSpecificFile when driver is "host_device"
2437
2438       The members of BlockStatsSpecificNvme when driver is "nvme"
2439
2440   Since
2441       4.2
2442
2443   BlockStats (Object)
2444       Statistics of a virtual block device or a block backing device.
2445
2446   Members
2447       device: string (optional)
2448              If the stats are for a virtual block  device,  the  name  corre‐
2449              sponding to the virtual block device.
2450
2451       node-name: string (optional)
2452              The node name of the device. (Since 2.3)
2453
2454       qdev: string (optional)
2455              The  qdev ID, or if no ID is assigned, the QOM path of the block
2456              device. (since 3.0)
2457
2458       stats: BlockDeviceStats
2459              A BlockDeviceStats for the device.
2460
2461       driver-specific: BlockStatsSpecific (optional)
2462              Optional driver-specific stats. (Since 4.2)
2463
2464       parent: BlockStats (optional)
2465              This describes the file block device if it  has  one.   Contains
2466              recursively  the statistics of the underlying protocol (e.g. the
2467              host file for a qcow2 image). If there is no  underlying  proto‐
2468              col, this field is omitted
2469
2470       backing: BlockStats (optional)
2471              This  describes  the backing block device if it has one.  (Since
2472              2.0)
2473
2474   Since
2475       0.14.0
2476
2477   query-blockstats (Command)
2478       Query the BlockStats for all virtual block devices.
2479
2480   Arguments
2481       query-nodes: boolean (optional)
2482              If true, the command will query all the block nodes that have  a
2483              node  name,  in  a list which will include "parent" information,
2484              but not "backing".  If false or omitted, the behavior is as  be‐
2485              fore  -  query  all  the  device backends, recursively including
2486              their "parent" and "backing". Filter nodes that were created im‐
2487              plicitly are skipped over in this mode. (Since 2.3)
2488
2489   Returns
2490       A list of BlockStats for each virtual block devices.
2491
2492   Since
2493       0.14.0
2494
2495   Example
2496          -> { "execute": "query-blockstats" }
2497          <- {
2498                "return":[
2499                   {
2500                      "device":"ide0-hd0",
2501                      "parent":{
2502                         "stats":{
2503                            "wr_highest_offset":3686448128,
2504                            "wr_bytes":9786368,
2505                            "wr_operations":751,
2506                            "rd_bytes":122567168,
2507                            "rd_operations":36772
2508                            "wr_total_times_ns":313253456
2509                            "rd_total_times_ns":3465673657
2510                            "flush_total_times_ns":49653
2511                            "flush_operations":61,
2512                            "rd_merged":0,
2513                            "wr_merged":0,
2514                            "idle_time_ns":2953431879,
2515                            "account_invalid":true,
2516                            "account_failed":false
2517                         }
2518                      },
2519                      "stats":{
2520                         "wr_highest_offset":2821110784,
2521                         "wr_bytes":9786368,
2522                         "wr_operations":692,
2523                         "rd_bytes":122739200,
2524                         "rd_operations":36604
2525                         "flush_operations":51,
2526                         "wr_total_times_ns":313253456
2527                         "rd_total_times_ns":3465673657
2528                         "flush_total_times_ns":49653,
2529                         "rd_merged":0,
2530                         "wr_merged":0,
2531                         "idle_time_ns":2953431879,
2532                         "account_invalid":true,
2533                         "account_failed":false
2534                      },
2535                      "qdev": "/machine/unattached/device[23]"
2536                   },
2537                   {
2538                      "device":"ide1-cd0",
2539                      "stats":{
2540                         "wr_highest_offset":0,
2541                         "wr_bytes":0,
2542                         "wr_operations":0,
2543                         "rd_bytes":0,
2544                         "rd_operations":0
2545                         "flush_operations":0,
2546                         "wr_total_times_ns":0
2547                         "rd_total_times_ns":0
2548                         "flush_total_times_ns":0,
2549                         "rd_merged":0,
2550                         "wr_merged":0,
2551                         "account_invalid":false,
2552                         "account_failed":false
2553                      },
2554                      "qdev": "/machine/unattached/device[24]"
2555                   },
2556                   {
2557                      "device":"floppy0",
2558                      "stats":{
2559                         "wr_highest_offset":0,
2560                         "wr_bytes":0,
2561                         "wr_operations":0,
2562                         "rd_bytes":0,
2563                         "rd_operations":0
2564                         "flush_operations":0,
2565                         "wr_total_times_ns":0
2566                         "rd_total_times_ns":0
2567                         "flush_total_times_ns":0,
2568                         "rd_merged":0,
2569                         "wr_merged":0,
2570                         "account_invalid":false,
2571                         "account_failed":false
2572                      },
2573                      "qdev": "/machine/unattached/device[16]"
2574                   },
2575                   {
2576                      "device":"sd0",
2577                      "stats":{
2578                         "wr_highest_offset":0,
2579                         "wr_bytes":0,
2580                         "wr_operations":0,
2581                         "rd_bytes":0,
2582                         "rd_operations":0
2583                         "flush_operations":0,
2584                         "wr_total_times_ns":0
2585                         "rd_total_times_ns":0
2586                         "flush_total_times_ns":0,
2587                         "rd_merged":0,
2588                         "wr_merged":0,
2589                         "account_invalid":false,
2590                         "account_failed":false
2591                      }
2592                   }
2593                ]
2594             }
2595
2596   BlockdevOnError (Enum)
2597       An enumeration of possible behaviors for errors on I/O operations.  The
2598       exact meaning depends on whether the I/O was initiated by a guest or by
2599       a block job
2600
2601   Values
2602       report for  guest  operations, report the error to the guest; for jobs,
2603              cancel the job
2604
2605       ignore ignore the error, only report a  QMP  event  (BLOCK_IO_ERROR  or
2606              BLOCK_JOB_ERROR). The backup, mirror and commit block jobs retry
2607              the failing request later and may still  complete  successfully.
2608              The  stream block job continues to stream and will complete with
2609              an error.
2610
2611       enospc same as stop on ENOSPC, same as report otherwise.
2612
2613       stop   for guest operations, stop the virtual machine; for jobs,  pause
2614              the job
2615
2616       auto   inherit the error handling policy of the backend (since: 2.7)
2617
2618   Since
2619       1.3
2620
2621   MirrorSyncMode (Enum)
2622       An  enumeration  of  possible behaviors for the initial synchronization
2623       phase of storage mirroring.
2624
2625   Values
2626       top    copies data in the topmost image to the destination
2627
2628       full   copies data from all images to the destination
2629
2630       none   only copy data written from now on
2631
2632       incremental
2633              only copy data described by the dirty bitmap. (since: 2.4)
2634
2635       bitmap only copy data described by the dirty bitmap. (since:  4.2)  Be‐
2636              havior on completion is determined by the BitmapSyncMode.
2637
2638   Since
2639       1.3
2640
2641   BitmapSyncMode (Enum)
2642       An  enumeration of possible behaviors for the synchronization of a bit‐
2643       map when used for data copy operations.
2644
2645   Values
2646       on-success
2647              The bitmap is only synced  when  the  operation  is  successful.
2648              This is the behavior always used for 'INCREMENTAL' backups.
2649
2650       never  The  bitmap  is  never  synchronized  with the operation, and is
2651              treated solely as a read-only manifest of blocks to copy.
2652
2653       always The bitmap is always synchronized with the operation, regardless
2654              of whether or not the operation was successful.
2655
2656   Since
2657       4.2
2658
2659   MirrorCopyMode (Enum)
2660       An  enumeration  whose values tell the mirror block job when to trigger
2661       writes to the target.
2662
2663   Values
2664       background
2665              copy data in background only.
2666
2667       write-blocking
2668              when data is written to the source, write it (synchronously)  to
2669              the  target  as well.  In addition, data is copied in background
2670              just like in background mode.
2671
2672   Since
2673       3.0
2674
2675   BlockJobInfo (Object)
2676       Information about a long-running block device operation.
2677
2678   Members
2679       type: string
2680              the job type ('stream' for image streaming)
2681
2682       device: string
2683              The job identifier. Originally the device name but other  values
2684              are allowed since QEMU 2.7
2685
2686       len: int
2687              Estimated  offset value at the completion of the job. This value
2688              can arbitrarily change while the job is running, in both  direc‐
2689              tions.
2690
2691       offset: int
2692              Progress made until now. The unit is arbitrary and the value can
2693              only meaningfully be used for the ratio of offset  to  len.  The
2694              value is monotonically increasing.
2695
2696       busy: boolean
2697              false  if  the  job is known to be in a quiescent state, with no
2698              pending I/O.  Since 1.3.
2699
2700       paused: boolean
2701              whether the job is paused or, if busy is true, will pause itself
2702              as soon as possible.  Since 1.3.
2703
2704       speed: int
2705              the rate limit, bytes per second
2706
2707       io-status: BlockDeviceIoStatus
2708              the status of the job (since 1.3)
2709
2710       ready: boolean
2711              true if the job may be completed (since 2.2)
2712
2713       status: JobStatus
2714              Current job state/status (since 2.12)
2715
2716       auto-finalize: boolean
2717              Job  will  finalize itself when PENDING, moving to the CONCLUDED
2718              state. (since 2.12)
2719
2720       auto-dismiss: boolean
2721              Job will dismiss itself when CONCLUDED, moving to the NULL state
2722              and disappearing from the query list. (since 2.12)
2723
2724       error: string (optional)
2725              Error information if the job did not complete successfully.  Not
2726              set if the job completed successfully. (since 2.12.1)
2727
2728   Since
2729       1.1
2730
2731   query-block-jobs (Command)
2732       Return information about long-running block device operations.
2733
2734   Returns
2735       a list of BlockJobInfo for each active block job
2736
2737   Since
2738       1.1
2739
2740   block_passwd (Command)
2741       This command sets the password of a block device that has not been open
2742       with a password and requires one.
2743
2744       This command is now obsolete and will always return an error since 2.10
2745
2746   Arguments
2747       device: string (optional)
2748              Not documented
2749
2750       node-name: string (optional)
2751              Not documented
2752
2753       password: string
2754              Not documented
2755
2756   block_resize (Command)
2757       Resize a block image while a guest is running.
2758
2759       Either device or node-name must be set but not both.
2760
2761   Arguments
2762       device: string (optional)
2763              the name of the device to get the image resized
2764
2765       node-name: string (optional)
2766              graph node name to get the image resized (Since 2.0)
2767
2768       size: int
2769              new image size in bytes
2770
2771   Returns
2772       • nothing on success
2773
2774       • If device is not a valid block device, DeviceNotFound
2775
2776   Since
2777       0.14.0
2778
2779   Example
2780          -> { "execute": "block_resize",
2781               "arguments": { "device": "scratch", "size": 1073741824 } }
2782          <- { "return": {} }
2783
2784   NewImageMode (Enum)
2785       An  enumeration  that  tells QEMU how to set the backing file path in a
2786       new image file.
2787
2788   Values
2789       existing
2790              QEMU should look for an existing image file.
2791
2792       absolute-paths
2793              QEMU should create a new image with absolute paths for the back‐
2794              ing  file.  If there is no backing file available, the new image
2795              will not be backed either.
2796
2797   Since
2798       1.1
2799
2800   BlockdevSnapshotSync (Object)
2801       Either device or node-name must be set but not both.
2802
2803   Members
2804       device: string (optional)
2805              the name of the device to take a snapshot of.
2806
2807       node-name: string (optional)
2808              graph node name to generate the snapshot from (Since 2.0)
2809
2810       snapshot-file: string
2811              the target of the new overlay image. If the file exists,  or  if
2812              it  is  a  device,  the  overlay will be created in the existing
2813              file/device. Otherwise, a new file will be created.
2814
2815       snapshot-node-name: string (optional)
2816              the graph node name of the new image (Since 2.0)
2817
2818       format: string (optional)
2819              the format of the overlay image, default is 'qcow2'.
2820
2821       mode: NewImageMode (optional)
2822              whether and how QEMU should create a new image, default is  'ab‐
2823              solute-paths'.
2824
2825   BlockdevSnapshot (Object)
2826   Members
2827       node: string
2828              device or node name that will have a snapshot taken.
2829
2830       overlay: string
2831              reference  to  the  existing  block  device that will become the
2832              overlay of node, as part of taking the snapshot.   It  must  not
2833              have  a  current  backing  file (this can be achieved by passing
2834              "backing": null to blockdev-add).
2835
2836   Since
2837       2.5
2838
2839   BackupCommon (Object)
2840   Members
2841       job-id: string (optional)
2842              identifier for the newly-created block job. If omitted, the  de‐
2843              vice name will be used. (Since 2.7)
2844
2845       device: string
2846              the  device  name  or  node-name  of a root node which should be
2847              copied.
2848
2849       sync: MirrorSyncMode
2850              what parts of the disk image should be copied to the destination
2851              (all  the disk, only the sectors allocated in the topmost image,
2852              from a dirty bitmap, or only new I/O).
2853
2854       speed: int (optional)
2855              the maximum speed, in bytes per second. The default  is  0,  for
2856              unlimited.
2857
2858       bitmap: string (optional)
2859              The  name  of a dirty bitmap to use.  Must be present if sync is
2860              "bitmap" or "incremental".  Can be present if sync is "full"  or
2861              "top".    Must   not   be   present   otherwise.    (Since   2.4
2862              (drive-backup), 3.1 (blockdev-backup))
2863
2864       bitmap-mode: BitmapSyncMode (optional)
2865              Specifies the type of data the bitmap should contain  after  the
2866              operation  concludes.  Must be present if a bitmap was provided,
2867              Must NOT be present otherwise. (Since 4.2)
2868
2869       compress: boolean (optional)
2870              true to compress data, if the target format supports  it.   (de‐
2871              fault: false) (since 2.8)
2872
2873       on-source-error: BlockdevOnError (optional)
2874              the  action to take on an error on the source, default 'report'.
2875              'stop' and 'enospc' can only be used if the  block  device  sup‐
2876              ports io-status (see BlockInfo).
2877
2878       on-target-error: BlockdevOnError (optional)
2879              the  action  to take on an error on the target, default 'report'
2880              (no limitations, since this applies to a different block  device
2881              than device).
2882
2883       auto-finalize: boolean (optional)
2884              When  false,  this job will wait in a PENDING state after it has
2885              finished its work, waiting for block-job-finalize before  making
2886              any block graph changes.  When true, this job will automatically
2887              perform its abort or commit actions.  Defaults to  true.  (Since
2888              2.12)
2889
2890       auto-dismiss: boolean (optional)
2891              When false, this job will wait in a CONCLUDED state after it has
2892              completely ceased all work, and awaits block-job-dismiss.   When
2893              true,  this job will automatically disappear from the query list
2894              without user intervention.  Defaults to true. (Since 2.12)
2895
2896       filter-node-name: string (optional)
2897              the node name that should be assigned to the filter driver  that
2898              the  backup  job  inserts into the graph above node specified by
2899              drive. If this option is not given, a node  name  is  autogener‐
2900              ated. (Since: 4.2)
2901
2902   Note
2903       on-source-error  and on-target-error only affect background I/O.  If an
2904       error occurs during a guest write request, the  device's  rerror/werror
2905       actions will be used.
2906
2907   Since
2908       4.2
2909
2910   DriveBackup (Object)
2911   Members
2912       target: string
2913              the  target  of the new image. If the file exists, or if it is a
2914              device, the existing file/device will be used as the new  desti‐
2915              nation.  If it does not exist, a new file will be created.
2916
2917       format: string (optional)
2918              the  format  of the new destination, default is to probe if mode
2919              is 'existing', else the format of the source
2920
2921       mode: NewImageMode (optional)
2922              whether and how QEMU should create a new image, default is  'ab‐
2923              solute-paths'.
2924
2925       The members of BackupCommon
2926
2927   Since
2928       1.6
2929
2930   BlockdevBackup (Object)
2931   Members
2932       target: string
2933              the device name or node-name of the backup target node.
2934
2935       The members of BackupCommon
2936
2937   Since
2938       2.3
2939
2940   blockdev-snapshot-sync (Command)
2941       Takes a synchronous snapshot of a block device.
2942
2943       For the arguments, see the documentation of BlockdevSnapshotSync.
2944
2945   Returns
2946       • nothing on success
2947
2948       • If device is not a valid block device, DeviceNotFound
2949
2950   Since
2951       0.14.0
2952
2953   Example
2954          -> { "execute": "blockdev-snapshot-sync",
2955               "arguments": { "device": "ide-hd0",
2956                              "snapshot-file":
2957                              "/some/place/my-image",
2958                              "format": "qcow2" } }
2959          <- { "return": {} }
2960
2961   blockdev-snapshot (Command)
2962       Takes a snapshot of a block device.
2963
2964       Take  a  snapshot,  by installing 'node' as the backing image of 'over‐
2965       lay'. Additionally, if 'node' is associated with a  block  device,  the
2966       block device changes to using 'overlay' as its new active image.
2967
2968       For the arguments, see the documentation of BlockdevSnapshot.
2969
2970   Features
2971       allow-write-only-overlay
2972              If present, the check whether this operation is safe was relaxed
2973              so that it can be used to change backing file of  a  destination
2974              of a blockdev-mirror.  (since 5.0)
2975
2976   Since
2977       2.5
2978
2979   Example
2980          -> { "execute": "blockdev-add",
2981               "arguments": { "driver": "qcow2",
2982                              "node-name": "node1534",
2983                              "file": { "driver": "file",
2984                                        "filename": "hd1.qcow2" },
2985                              "backing": null } }
2986
2987          <- { "return": {} }
2988
2989          -> { "execute": "blockdev-snapshot",
2990               "arguments": { "node": "ide-hd0",
2991                              "overlay": "node1534" } }
2992          <- { "return": {} }
2993
2994   change-backing-file (Command)
2995       Change  the  backing  file  in  the image file metadata.  This does not
2996       cause QEMU to reopen the image file to reparse the backing filename (it
2997       may, however, perform a reopen to change permissions from r/o -> r/w ->
2998       r/o, if needed). The new backing file string is written into the  image
2999       file metadata, and the QEMU internal strings are updated.
3000
3001   Arguments
3002       image-node-name: string
3003              The  name of the block driver state node of the image to modify.
3004              The "device" argument is used to verify "image-node-name" is  in
3005              the chain described by "device".
3006
3007       device: string
3008              The  device  name  or  node-name  of the root node that owns im‐
3009              age-node-name.
3010
3011       backing-file: string
3012              The string to write as the backing file.   This  string  is  not
3013              validated, so care should be taken when specifying the string or
3014              the image chain may not be able to be reopened again.
3015
3016   Returns
3017       • Nothing on success
3018
3019       • If "device" does not exist or cannot be determined, DeviceNotFound
3020
3021   Since
3022       2.1
3023
3024   block-commit (Command)
3025       Live commit of data from overlay image nodes into backing nodes - i.e.,
3026       writes data between 'top' and 'base' into 'base'.
3027
3028       If top == base, that is an error.  If top has no overlays on top of it,
3029       or if it is in use by a writer, the job will not be  completed  by  it‐
3030       self.   The  user needs to complete the job with the block-job-complete
3031       command after getting the ready event. (Since 2.0)
3032
3033       If the base image is smaller than top, then the base image will be  re‐
3034       sized  to be the same size as top.  If top is smaller than the base im‐
3035       age, the base will not be truncated.  If you want the base  image  size
3036       to  match the size of the smaller top, you can safely truncate it your‐
3037       self once the commit operation successfully completes.
3038
3039   Arguments
3040       job-id: string (optional)
3041              identifier for the newly-created block job. If omitted, the  de‐
3042              vice name will be used. (Since 2.7)
3043
3044       device: string
3045              the device name or node-name of a root node
3046
3047       base-node: string (optional)
3048              The  node  name of the backing image to write data into.  If not
3049              specified, this is the deepest backing image.  (since: 3.1)
3050
3051       base: string (optional)
3052              Same as base-node, except that it is a file name rather  than  a
3053              node  name. This must be the exact filename string that was used
3054              to open the node; other strings, even  if  addressing  the  same
3055              file, are not accepted
3056
3057       top-node: string (optional)
3058              The  node name of the backing image within the image chain which
3059              contains the topmost data to be committed down.  If  not  speci‐
3060              fied, this is the active layer. (since: 3.1)
3061
3062       top: string (optional)
3063              Same  as  top-node,  except that it is a file name rather than a
3064              node name. This must be the exact filename string that was  used
3065              to  open  the  node;  other strings, even if addressing the same
3066              file, are not accepted
3067
3068       backing-file: string (optional)
3069              The backing file string to  write  into  the  overlay  image  of
3070              'top'.   If 'top' does not have an overlay image, or if 'top' is
3071              in use by a writer, specifying a backing file string is  an  er‐
3072              ror.
3073
3074              This  filename  is  not validated.  If a pathname string is such
3075              that it cannot be resolved by QEMU, that means  that  subsequent
3076              QMP  or  HMP commands must use node-names for the image in ques‐
3077              tion, as filename lookup methods will fail.
3078
3079              If not specified, QEMU will automatically determine the  backing
3080              file  string to use, or error out if there is no obvious choice.
3081              Care should be taken when specifying the string,  to  specify  a
3082              valid filename or protocol.  (Since 2.1)
3083
3084       speed: int (optional)
3085              the maximum speed, in bytes per second
3086
3087       on-error: BlockdevOnError (optional)
3088              the  action to take on an error. 'ignore' means that the request
3089              should be retried. (default: report; Since: 5.0)
3090
3091       filter-node-name: string (optional)
3092              the node name that should be assigned to the filter driver  that
3093              the  commit job inserts into the graph above top. If this option
3094              is not given, a node name is autogenerated. (Since: 2.9)
3095
3096       auto-finalize: boolean (optional)
3097              When false, this job will wait in a PENDING state after  it  has
3098              finished  its work, waiting for block-job-finalize before making
3099              any block graph changes.  When true, this job will automatically
3100              perform  its  abort or commit actions.  Defaults to true. (Since
3101              3.1)
3102
3103       auto-dismiss: boolean (optional)
3104              When false, this job will wait in a CONCLUDED state after it has
3105              completely  ceased all work, and awaits block-job-dismiss.  When
3106              true, this job will automatically disappear from the query  list
3107              without user intervention.  Defaults to true. (Since 3.1)
3108
3109   Features
3110       deprecated
3111              Members base and top are deprecated.  Use base-node and top-node
3112              instead.
3113
3114   Returns
3115       • Nothing on success
3116
3117       • If device does not exist, DeviceNotFound
3118
3119       • Any other error returns a GenericError.
3120
3121   Since
3122       1.3
3123
3124   Example
3125          -> { "execute": "block-commit",
3126               "arguments": { "device": "virtio0",
3127                              "top": "/tmp/snap1.qcow2" } }
3128          <- { "return": {} }
3129
3130   drive-backup (Command)
3131       Start a point-in-time copy of a block device to a new destination.  The
3132       status   of   ongoing  drive-backup  operations  can  be  checked  with
3133       query-block-jobs  where  the  BlockJobInfo.type  field  has  the  value
3134       'backup'.   The  operation can be stopped before it has completed using
3135       the block-job-cancel command.
3136
3137   Arguments
3138       The members of DriveBackup
3139
3140   Returns
3141       • nothing on success
3142
3143       • If device is not a valid block device, GenericError
3144
3145   Since
3146       1.6
3147
3148   Example
3149          -> { "execute": "drive-backup",
3150               "arguments": { "device": "drive0",
3151                              "sync": "full",
3152                              "target": "backup.img" } }
3153          <- { "return": {} }
3154
3155   blockdev-backup (Command)
3156       Start a point-in-time copy of a block device to a new destination.  The
3157       status  of  ongoing  blockdev-backup  operations  can  be  checked with
3158       query-block-jobs  where  the  BlockJobInfo.type  field  has  the  value
3159       'backup'.   The  operation can be stopped before it has completed using
3160       the block-job-cancel command.
3161
3162   Arguments
3163       The members of BlockdevBackup
3164
3165   Returns
3166       • nothing on success
3167
3168       • If device is not a valid block device, DeviceNotFound
3169
3170   Since
3171       2.3
3172
3173   Example
3174          -> { "execute": "blockdev-backup",
3175               "arguments": { "device": "src-id",
3176                              "sync": "full",
3177                              "target": "tgt-id" } }
3178          <- { "return": {} }
3179
3180   query-named-block-nodes (Command)
3181       Get the named block driver list
3182
3183   Arguments
3184       flat: boolean (optional)
3185              Omit the nested data about backing image  ("backing-image"  key)
3186              if true.  Default is false (Since 5.0)
3187
3188   Returns
3189       the list of BlockDeviceInfo
3190
3191   Since
3192       2.0
3193
3194   Example
3195          -> { "execute": "query-named-block-nodes" }
3196          <- { "return": [ { "ro":false,
3197                             "drv":"qcow2",
3198                             "encrypted":false,
3199                             "file":"disks/test.qcow2",
3200                             "node-name": "my-node",
3201                             "backing_file_depth":1,
3202                             "bps":1000000,
3203                             "bps_rd":0,
3204                             "bps_wr":0,
3205                             "iops":1000000,
3206                             "iops_rd":0,
3207                             "iops_wr":0,
3208                             "bps_max": 8000000,
3209                             "bps_rd_max": 0,
3210                             "bps_wr_max": 0,
3211                             "iops_max": 0,
3212                             "iops_rd_max": 0,
3213                             "iops_wr_max": 0,
3214                             "iops_size": 0,
3215                             "write_threshold": 0,
3216                             "image":{
3217                                "filename":"disks/test.qcow2",
3218                                "format":"qcow2",
3219                                "virtual-size":2048000,
3220                                "backing_file":"base.qcow2",
3221                                "full-backing-filename":"disks/base.qcow2",
3222                                "backing-filename-format":"qcow2",
3223                                "snapshots":[
3224                                   {
3225                                      "id": "1",
3226                                      "name": "snapshot1",
3227                                      "vm-state-size": 0,
3228                                      "date-sec": 10000200,
3229                                      "date-nsec": 12,
3230                                      "vm-clock-sec": 206,
3231                                      "vm-clock-nsec": 30
3232                                   }
3233                                ],
3234                                "backing-image":{
3235                                    "filename":"disks/base.qcow2",
3236                                    "format":"qcow2",
3237                                    "virtual-size":2048000
3238                                }
3239                             } } ] }
3240
3241   XDbgBlockGraphNodeType (Enum)
3242   Values
3243       block-backend
3244              corresponds to BlockBackend
3245
3246       block-job
3247              corresponds to BlockJob
3248
3249       block-driver
3250              corresponds to BlockDriverState
3251
3252   Since
3253       4.0
3254
3255   XDbgBlockGraphNode (Object)
3256   Members
3257       id: int
3258              Block graph node identifier. This id is generated only for x-de‐
3259              bug-query-block-graph and does not relate to any  other  identi‐
3260              fiers in Qemu.
3261
3262       type: XDbgBlockGraphNodeType
3263              Type  of  graph  node. Can be one of block-backend, block-job or
3264              block-driver-state.
3265
3266       name: string
3267              Human readable name of the node. Corresponds  to  node-name  for
3268              block-driver-state  nodes; is not guaranteed to be unique in the
3269              whole graph (with block-jobs and block-backends).
3270
3271   Since
3272       4.0
3273
3274   BlockPermission (Enum)
3275       Enum of base block permissions.
3276
3277   Values
3278       consistent-read
3279              A user that has the "permission" of consistent reads is  guaran‐
3280              teed that their view of the contents of the block device is com‐
3281              plete and self-consistent, representing the contents of  a  disk
3282              at  a  specific  point.  For most block devices (including their
3283              backing files) this is true, but the property  cannot  be  main‐
3284              tained in a few situations like for intermediate nodes of a com‐
3285              mit block job.
3286
3287       write  This permission is required to change the visible disk contents.
3288
3289       write-unchanged
3290              This permission (which is weaker than  BLK_PERM_WRITE)  is  both
3291              enough and required for writes to the block node when the caller
3292              promises that the visible disk content doesn't change.   As  the
3293              BLK_PERM_WRITE permission is strictly stronger, either is suffi‐
3294              cient to perform an unchanging write.
3295
3296       resize This permission is required to change the size of a block node.
3297
3298       graph-mod
3299              This permission  is  required  to  change  the  node  that  this
3300              BdrvChild points to.
3301
3302   Since
3303       4.0
3304
3305   XDbgBlockGraphEdge (Object)
3306       Block Graph edge description for x-debug-query-block-graph.
3307
3308   Members
3309       parent: int
3310              parent id
3311
3312       child: int
3313              child id
3314
3315       name: string
3316              name of the relation (examples are 'file' and 'backing')
3317
3318       perm: array of BlockPermission
3319              granted permissions for the parent operating on the child
3320
3321       shared-perm: array of BlockPermission
3322              permissions  that  can  still  be  granted to other users of the
3323              child while it is still attached to this parent
3324
3325   Since
3326       4.0
3327
3328   XDbgBlockGraph (Object)
3329       Block Graph - list of nodes and list of edges.
3330
3331   Members
3332       nodes: array of XDbgBlockGraphNode
3333              Not documented
3334
3335       edges: array of XDbgBlockGraphEdge
3336              Not documented
3337
3338   Since
3339       4.0
3340
3341   x-debug-query-block-graph (Command)
3342       Get the block graph.
3343
3344   Since
3345       4.0
3346
3347   drive-mirror (Command)
3348       Start mirroring a block device's writes to a  new  destination.  target
3349       specifies  the target of the new image. If the file exists, or if it is
3350       a device, it will be used as the new destination for writes. If it does
3351       not  exist,  a new file will be created. format specifies the format of
3352       the mirror image, default is to probe if mode='existing', else the for‐
3353       mat of the source.
3354
3355   Arguments
3356       The members of DriveMirror
3357
3358   Returns
3359       • nothing on success
3360
3361       • If device is not a valid block device, GenericError
3362
3363   Since
3364       1.3
3365
3366   Example
3367          -> { "execute": "drive-mirror",
3368               "arguments": { "device": "ide-hd0",
3369                              "target": "/some/place/my-image",
3370                              "sync": "full",
3371                              "format": "qcow2" } }
3372          <- { "return": {} }
3373
3374   DriveMirror (Object)
3375       A set of parameters describing drive mirror setup.
3376
3377   Members
3378       job-id: string (optional)
3379              identifier  for the newly-created block job. If omitted, the de‐
3380              vice name will be used. (Since 2.7)
3381
3382       device: string
3383              the device name or node-name of a root node whose writes  should
3384              be mirrored.
3385
3386       target: string
3387              the  target  of the new image. If the file exists, or if it is a
3388              device, the existing file/device will be used as the new  desti‐
3389              nation.  If it does not exist, a new file will be created.
3390
3391       format: string (optional)
3392              the  format  of the new destination, default is to probe if mode
3393              is 'existing', else the format of the source
3394
3395       node-name: string (optional)
3396              the new block driver state node name in the graph (Since 2.1)
3397
3398       replaces: string (optional)
3399              with sync=full graph node name to be replaced by the  new  image
3400              when a whole image copy is done. This can be used to repair bro‐
3401              ken Quorum files.  By default, device is replaced, although  im‐
3402              plicitly created filters on it are kept. (Since 2.1)
3403
3404       mode: NewImageMode (optional)
3405              whether  and how QEMU should create a new image, default is 'ab‐
3406              solute-paths'.
3407
3408       speed: int (optional)
3409              the maximum speed, in bytes per second
3410
3411       sync: MirrorSyncMode
3412              what parts of the disk image should be copied to the destination
3413              (all  the disk, only the sectors allocated in the topmost image,
3414              or only new I/O).
3415
3416       granularity: int (optional)
3417              granularity of the dirty bitmap, default is  64K  if  the  image
3418              format  doesn't  have  clusters,  4K if the clusters are smaller
3419              than that, else the cluster size.  Must be a power of 2  between
3420              512 and 64M (since 1.4).
3421
3422       buf-size: int (optional)
3423              maximum  amount  of  data in flight from source to target (since
3424              1.4).
3425
3426       on-source-error: BlockdevOnError (optional)
3427              the action to take on an error on the source, default  'report'.
3428              'stop'  and  'enospc'  can only be used if the block device sup‐
3429              ports io-status (see BlockInfo).
3430
3431       on-target-error: BlockdevOnError (optional)
3432              the action to take on an error on the target,  default  'report'
3433              (no  limitations, since this applies to a different block device
3434              than device).
3435
3436       unmap: boolean (optional)
3437              Whether to try to unmap target sectors  where  source  has  only
3438              zero. If true, and target unallocated sectors will read as zero,
3439              target image sectors will be unmapped; otherwise, zeroes will be
3440              written.  Both  will  result  in identical contents.  Default is
3441              true. (Since 2.4)
3442
3443       copy-mode: MirrorCopyMode (optional)
3444              when to copy data to the destination; defaults  to  'background'
3445              (Since: 3.0)
3446
3447       auto-finalize: boolean (optional)
3448              When  false,  this job will wait in a PENDING state after it has
3449              finished its work, waiting for block-job-finalize before  making
3450              any block graph changes.  When true, this job will automatically
3451              perform its abort or commit actions.  Defaults to  true.  (Since
3452              3.1)
3453
3454       auto-dismiss: boolean (optional)
3455              When false, this job will wait in a CONCLUDED state after it has
3456              completely ceased all work, and awaits block-job-dismiss.   When
3457              true,  this job will automatically disappear from the query list
3458              without user intervention.  Defaults to true. (Since 3.1)
3459
3460   Since
3461       1.3
3462
3463   BlockDirtyBitmap (Object)
3464   Members
3465       node: string
3466              name of device/node which the bitmap is tracking
3467
3468       name: string
3469              name of the dirty bitmap
3470
3471   Since
3472       2.4
3473
3474   BlockDirtyBitmapAdd (Object)
3475   Members
3476       node: string
3477              name of device/node which the bitmap is tracking
3478
3479       name: string
3480              name of the dirty bitmap (must be less than 1024 bytes)
3481
3482       granularity: int (optional)
3483              the bitmap granularity,  default  is  64k  for  block-dirty-bit‐
3484              map-add
3485
3486       persistent: boolean (optional)
3487              the  bitmap  is  persistent, i.e. it will be saved to the corre‐
3488              sponding block device image file on  its  close.  For  now  only
3489              Qcow2  disks  support  persistent  bitmaps. Default is false for
3490              block-dirty-bitmap-add. (Since: 2.10)
3491
3492       disabled: boolean (optional)
3493              the bitmap is created in the disabled state, which means that it
3494              will  not  track  drive  changes. The bitmap may be enabled with
3495              block-dirty-bitmap-enable. Default is false. (Since: 4.0)
3496
3497   Since
3498       2.4
3499
3500   BlockDirtyBitmapMergeSource (Alternate)
3501   Members
3502       local: string
3503              name of the bitmap, attached to the same node as target bitmap.
3504
3505       external: BlockDirtyBitmap
3506              bitmap with specified node
3507
3508   Since
3509       4.1
3510
3511   BlockDirtyBitmapMerge (Object)
3512   Members
3513       node: string
3514              name of device/node which the target bitmap is tracking
3515
3516       target: string
3517              name of the destination dirty bitmap
3518
3519       bitmaps: array of BlockDirtyBitmapMergeSource
3520              name(s) of the source dirty bitmap(s) at node and/or fully spec‐
3521              ified  BlockDirtyBitmap elements. The latter are supported since
3522              4.1.
3523
3524   Since
3525       4.0
3526
3527   block-dirty-bitmap-add (Command)
3528       Create a dirty bitmap with a name on the node, and start  tracking  the
3529       writes.
3530
3531   Returns
3532       • nothing on success
3533
3534       • If node is not a valid block device or node, DeviceNotFound
3535
3536       • If name is already taken, GenericError with an explanation
3537
3538   Since
3539       2.4
3540
3541   Example
3542          -> { "execute": "block-dirty-bitmap-add",
3543               "arguments": { "node": "drive0", "name": "bitmap0" } }
3544          <- { "return": {} }
3545
3546   block-dirty-bitmap-remove (Command)
3547       Stop  write  tracking and remove the dirty bitmap that was created with
3548       block-dirty-bitmap-add. If the bitmap is persistent, remove it from its
3549       storage too.
3550
3551   Returns
3552       • nothing on success
3553
3554       • If node is not a valid block device or node, DeviceNotFound
3555
3556       • If name is not found, GenericError with an explanation
3557
3558       • if name is frozen by an operation, GenericError
3559
3560   Since
3561       2.4
3562
3563   Example
3564          -> { "execute": "block-dirty-bitmap-remove",
3565               "arguments": { "node": "drive0", "name": "bitmap0" } }
3566          <- { "return": {} }
3567
3568   block-dirty-bitmap-clear (Command)
3569       Clear  (reset)  a  dirty  bitmap  on the device, so that an incremental
3570       backup from this point in time forward will only backup clusters  modi‐
3571       fied after this clear operation.
3572
3573   Returns
3574       • nothing on success
3575
3576       • If node is not a valid block device, DeviceNotFound
3577
3578       • If name is not found, GenericError with an explanation
3579
3580   Since
3581       2.4
3582
3583   Example
3584          -> { "execute": "block-dirty-bitmap-clear",
3585               "arguments": { "node": "drive0", "name": "bitmap0" } }
3586          <- { "return": {} }
3587
3588   block-dirty-bitmap-enable (Command)
3589       Enables a dirty bitmap so that it will begin tracking disk changes.
3590
3591   Returns
3592       • nothing on success
3593
3594       • If node is not a valid block device, DeviceNotFound
3595
3596       • If name is not found, GenericError with an explanation
3597
3598   Since
3599       4.0
3600
3601   Example
3602          -> { "execute": "block-dirty-bitmap-enable",
3603               "arguments": { "node": "drive0", "name": "bitmap0" } }
3604          <- { "return": {} }
3605
3606   block-dirty-bitmap-disable (Command)
3607       Disables a dirty bitmap so that it will stop tracking disk changes.
3608
3609   Returns
3610       • nothing on success
3611
3612       • If node is not a valid block device, DeviceNotFound
3613
3614       • If name is not found, GenericError with an explanation
3615
3616   Since
3617       4.0
3618
3619   Example
3620          -> { "execute": "block-dirty-bitmap-disable",
3621               "arguments": { "node": "drive0", "name": "bitmap0" } }
3622          <- { "return": {} }
3623
3624   block-dirty-bitmap-merge (Command)
3625       Merge  dirty  bitmaps  listed  in  bitmaps  to the target dirty bitmap.
3626       Dirty bitmaps in bitmaps will be unchanged, except if it  also  appears
3627       as  the target bitmap. Any bits already set in target will still be set
3628       after the merge, i.e., this operation does not clear  the  target.   On
3629       error, target is unchanged.
3630
3631       The  resulting  bitmap will count as dirty any clusters that were dirty
3632       in any of the source bitmaps. This can be used to achieve backup check‐
3633       points, or in simpler usages, to copy bitmaps.
3634
3635   Returns
3636       • nothing on success
3637
3638       • If node is not a valid block device, DeviceNotFound
3639
3640       • If any bitmap in bitmaps or target is not found, GenericError
3641
3642       • If  any  of the bitmaps have different sizes or granularities, Gener‐
3643         icError
3644
3645   Since
3646       4.0
3647
3648   Example
3649          -> { "execute": "block-dirty-bitmap-merge",
3650               "arguments": { "node": "drive0", "target": "bitmap0",
3651                              "bitmaps": ["bitmap1"] } }
3652          <- { "return": {} }
3653
3654   BlockDirtyBitmapSha256 (Object)
3655       SHA256 hash of dirty bitmap data
3656
3657   Members
3658       sha256: string
3659              ASCII representation of SHA256 bitmap hash
3660
3661   Since
3662       2.10
3663
3664   x-debug-block-dirty-bitmap-sha256 (Command)
3665       Get bitmap SHA256.
3666
3667   Returns
3668       • BlockDirtyBitmapSha256 on success
3669
3670       • If node is not a valid block device, DeviceNotFound
3671
3672       • If name is not found or if hashing has failed, GenericError  with  an
3673         explanation
3674
3675   Since
3676       2.10
3677
3678   blockdev-mirror (Command)
3679       Start mirroring a block device's writes to a new destination.
3680
3681   Arguments
3682       job-id: string (optional)
3683              identifier  for the newly-created block job. If omitted, the de‐
3684              vice name will be used. (Since 2.7)
3685
3686       device: string
3687              The device name or node-name of a root node whose writes  should
3688              be mirrored.
3689
3690       target: string
3691              the  id  or  node-name  of  the  block device to mirror to. This
3692              mustn't be attached to guest.
3693
3694       replaces: string (optional)
3695              with sync=full graph node name to be replaced by the  new  image
3696              when a whole image copy is done. This can be used to repair bro‐
3697              ken Quorum files.  By default, device is replaced, although  im‐
3698              plicitly created filters on it are kept.
3699
3700       speed: int (optional)
3701              the maximum speed, in bytes per second
3702
3703       sync: MirrorSyncMode
3704              what parts of the disk image should be copied to the destination
3705              (all the disk, only the sectors allocated in the topmost  image,
3706              or only new I/O).
3707
3708       granularity: int (optional)
3709              granularity  of  the  dirty  bitmap, default is 64K if the image
3710              format doesn't have clusters, 4K if  the  clusters  are  smaller
3711              than  that, else the cluster size.  Must be a power of 2 between
3712              512 and 64M
3713
3714       buf-size: int (optional)
3715              maximum amount of data in flight from source to target
3716
3717       on-source-error: BlockdevOnError (optional)
3718              the action to take on an error on the source, default  'report'.
3719              'stop'  and  'enospc'  can only be used if the block device sup‐
3720              ports io-status (see BlockInfo).
3721
3722       on-target-error: BlockdevOnError (optional)
3723              the action to take on an error on the target,  default  'report'
3724              (no  limitations, since this applies to a different block device
3725              than device).
3726
3727       filter-node-name: string (optional)
3728              the node name that should be assigned to the filter driver  that
3729              the  mirror job inserts into the graph above device. If this op‐
3730              tion is not given, a node name is autogenerated. (Since: 2.9)
3731
3732       copy-mode: MirrorCopyMode (optional)
3733              when to copy data to the destination; defaults  to  'background'
3734              (Since: 3.0)
3735
3736       auto-finalize: boolean (optional)
3737              When  false,  this job will wait in a PENDING state after it has
3738              finished its work, waiting for block-job-finalize before  making
3739              any block graph changes.  When true, this job will automatically
3740              perform its abort or commit actions.  Defaults to  true.  (Since
3741              3.1)
3742
3743       auto-dismiss: boolean (optional)
3744              When false, this job will wait in a CONCLUDED state after it has
3745              completely ceased all work, and awaits block-job-dismiss.   When
3746              true,  this job will automatically disappear from the query list
3747              without user intervention.  Defaults to true. (Since 3.1)
3748
3749   Returns
3750       nothing on success.
3751
3752   Since
3753       2.6
3754
3755   Example
3756          -> { "execute": "blockdev-mirror",
3757               "arguments": { "device": "ide-hd0",
3758                              "target": "target0",
3759                              "sync": "full" } }
3760          <- { "return": {} }
3761
3762   BlockIOThrottle (Object)
3763       A set of parameters describing block throttling.
3764
3765   Members
3766       device: string (optional)
3767              Block device name
3768
3769       id: string (optional)
3770              The name or QOM path of the guest device (since: 2.8)
3771
3772       bps: int
3773              total throughput limit in bytes per second
3774
3775       bps_rd: int
3776              read throughput limit in bytes per second
3777
3778       bps_wr: int
3779              write throughput limit in bytes per second
3780
3781       iops: int
3782              total I/O operations per second
3783
3784       iops_rd: int
3785              read I/O operations per second
3786
3787       iops_wr: int
3788              write I/O operations per second
3789
3790       bps_max: int (optional)
3791              total throughput limit during bursts, in bytes (Since 1.7)
3792
3793       bps_rd_max: int (optional)
3794              read throughput limit during bursts, in bytes (Since 1.7)
3795
3796       bps_wr_max: int (optional)
3797              write throughput limit during bursts, in bytes (Since 1.7)
3798
3799       iops_max: int (optional)
3800              total I/O operations per second during bursts, in  bytes  (Since
3801              1.7)
3802
3803       iops_rd_max: int (optional)
3804              read  I/O  operations  per second during bursts, in bytes (Since
3805              1.7)
3806
3807       iops_wr_max: int (optional)
3808              write I/O operations per second during bursts, in  bytes  (Since
3809              1.7)
3810
3811       bps_max_length: int (optional)
3812              maximum  length of the bps_max burst period, in seconds. It must
3813              only be set if bps_max is set as well.  Defaults  to  1.  (Since
3814              2.6)
3815
3816       bps_rd_max_length: int (optional)
3817              maximum  length  of  the bps_rd_max burst period, in seconds. It
3818              must only be set if bps_rd_max is set as well.  Defaults  to  1.
3819              (Since 2.6)
3820
3821       bps_wr_max_length: int (optional)
3822              maximum  length  of  the bps_wr_max burst period, in seconds. It
3823              must only be set if bps_wr_max is set as well.  Defaults  to  1.
3824              (Since 2.6)
3825
3826       iops_max_length: int (optional)
3827              maximum  length  of  the  iops burst period, in seconds. It must
3828              only be set if iops_max is set as well.  Defaults to  1.  (Since
3829              2.6)
3830
3831       iops_rd_max_length: int (optional)
3832              maximum  length  of the iops_rd_max burst period, in seconds. It
3833              must only be set if iops_rd_max is set as well.  Defaults to  1.
3834              (Since 2.6)
3835
3836       iops_wr_max_length: int (optional)
3837              maximum  length  of the iops_wr_max burst period, in seconds. It
3838              must only be set if iops_wr_max is set as well.  Defaults to  1.
3839              (Since 2.6)
3840
3841       iops_size: int (optional)
3842              an I/O size in bytes (Since 1.7)
3843
3844       group: string (optional)
3845              throttle group name (Since 2.4)
3846
3847   Features
3848       deprecated
3849              Member device is deprecated.  Use id instead.
3850
3851   Since
3852       1.1
3853
3854   ThrottleLimits (Object)
3855       Limit parameters for throttling.  Since some limit combinations are il‐
3856       legal, limits should always be set in one transaction. All  fields  are
3857       optional.  When setting limits, if a field is missing the current value
3858       is not changed.
3859
3860   Members
3861       iops-total: int (optional)
3862              limit total I/O operations per second
3863
3864       iops-total-max: int (optional)
3865              I/O operations burst
3866
3867       iops-total-max-length: int (optional)
3868              length of the iops-total-max burst period, in  seconds  It  must
3869              only be set if iops-total-max is set as well.
3870
3871       iops-read: int (optional)
3872              limit read operations per second
3873
3874       iops-read-max: int (optional)
3875              I/O operations read burst
3876
3877       iops-read-max-length: int (optional)
3878              length  of  the  iops-read-max  burst period, in seconds It must
3879              only be set if iops-read-max is set as well.
3880
3881       iops-write: int (optional)
3882              limit write operations per second
3883
3884       iops-write-max: int (optional)
3885              I/O operations write burst
3886
3887       iops-write-max-length: int (optional)
3888              length of the iops-write-max burst period, in  seconds  It  must
3889              only be set if iops-write-max is set as well.
3890
3891       bps-total: int (optional)
3892              limit total bytes per second
3893
3894       bps-total-max: int (optional)
3895              total bytes burst
3896
3897       bps-total-max-length: int (optional)
3898              length  of  the bps-total-max burst period, in seconds.  It must
3899              only be set if bps-total-max is set as well.
3900
3901       bps-read: int (optional)
3902              limit read bytes per second
3903
3904       bps-read-max: int (optional)
3905              total bytes read burst
3906
3907       bps-read-max-length: int (optional)
3908              length of the bps-read-max burst period, in seconds It must only
3909              be set if bps-read-max is set as well.
3910
3911       bps-write: int (optional)
3912              limit write bytes per second
3913
3914       bps-write-max: int (optional)
3915              total bytes write burst
3916
3917       bps-write-max-length: int (optional)
3918              length  of  the  bps-write-max  burst period, in seconds It must
3919              only be set if bps-write-max is set as well.
3920
3921       iops-size: int (optional)
3922              when limiting by iops max size of an I/O in bytes
3923
3924   Since
3925       2.11
3926
3927   block-stream (Command)
3928       Copy data from a backing file into a block device.
3929
3930       The block streaming operation is performed in the background until  the
3931       entire  backing file has been copied.  This command returns immediately
3932       once streaming has started.  The status of ongoing block streaming  op‐
3933       erations  can  be  checked with query-block-jobs.  The operation can be
3934       stopped before it has completed using the block-job-cancel command.
3935
3936       The node that receives the data is called the top image, can be located
3937       in  any  part of the chain (but always above the base image; see below)
3938       and can be specified using its device or node name. Earlier  qemu  ver‐
3939       sions only allowed 'device' to name the top level node; presence of the
3940       'base-node' parameter during introspection can be used as a witness  of
3941       the enhanced semantics of 'device'.
3942
3943       If  a base file is specified then sectors are not copied from that base
3944       file and its backing chain.  This can be used to stream a subset of the
3945       backing  file  chain  instead  of  flattening  the  entire image.  When
3946       streaming completes the image file will have the base file as its back‐
3947       ing  file,  unless that node was changed while the job was running.  In
3948       that case, base's parent's  backing  (or  filtered,  whichever  exists)
3949       child  (i.e., base at the beginning of the job) will be the new backing
3950       file.
3951
3952       On successful completion the image file is updated to drop the  backing
3953       file and the BLOCK_JOB_COMPLETED event is emitted.
3954
3955       In  case  device  is  a  filter  node,  block-stream modifies the first
3956       non-filter overlay node below it to point to the new backing  node  in‐
3957       stead of modifying device itself.
3958
3959   Arguments
3960       job-id: string (optional)
3961              identifier  for the newly-created block job. If omitted, the de‐
3962              vice name will be used. (Since 2.7)
3963
3964       device: string
3965              the device or node name of the top image
3966
3967       base: string (optional)
3968              the common backing file name.  It cannot be set if base-node  is
3969              also set.
3970
3971       base-node: string (optional)
3972              the  node name of the backing file.  It cannot be set if base is
3973              also set. (Since 2.8)
3974
3975       backing-file: string (optional)
3976              The backing file string to write into the top image. This  file‐
3977              name is not validated.
3978
3979              If a pathname string is such that it cannot be resolved by QEMU,
3980              that  means  that  subsequent  QMP  or  HMP  commands  must  use
3981              node-names for the image in question, as filename lookup methods
3982              will fail.
3983
3984              If not specified, QEMU will automatically determine the  backing
3985              file  string to use, or error out if there is no obvious choice.
3986              Care should be taken when specifying the string,  to  specify  a
3987              valid filename or protocol.  (Since 2.1)
3988
3989       speed: int (optional)
3990              the maximum speed, in bytes per second
3991
3992       on-error: BlockdevOnError (optional)
3993              the  action  to  take  on an error (default report).  'stop' and
3994              'enospc' can only be used if the block device supports io-status
3995              (see BlockInfo).  Since 1.3.
3996
3997       auto-finalize: boolean (optional)
3998              When  false,  this job will wait in a PENDING state after it has
3999              finished its work, waiting for block-job-finalize before  making
4000              any block graph changes.  When true, this job will automatically
4001              perform its abort or commit actions.  Defaults to  true.  (Since
4002              3.1)
4003
4004       auto-dismiss: boolean (optional)
4005              When false, this job will wait in a CONCLUDED state after it has
4006              completely ceased all work, and awaits block-job-dismiss.   When
4007              true,  this job will automatically disappear from the query list
4008              without user intervention.  Defaults to true. (Since 3.1)
4009
4010   Returns
4011       • Nothing on success.
4012
4013       • If device does not exist, DeviceNotFound.
4014
4015   Since
4016       1.1
4017
4018   Example
4019          -> { "execute": "block-stream",
4020               "arguments": { "device": "virtio0",
4021                              "base": "/tmp/master.qcow2" } }
4022          <- { "return": {} }
4023
4024   block-job-set-speed (Command)
4025       Set maximum speed for a background block operation.
4026
4027       This command can only be issued when there is an active block job.
4028
4029       Throttling can be disabled by setting the speed to 0.
4030
4031   Arguments
4032       device: string
4033              The job identifier. This used to be a  device  name  (hence  the
4034              name  of  the  parameter),  but since QEMU 2.7 it can have other
4035              values.
4036
4037       speed: int
4038              the maximum speed, in bytes per second, or 0 for unlimited.  De‐
4039              faults to 0.
4040
4041   Returns
4042       • Nothing on success
4043
4044       • If no background operation is active on this device, DeviceNotActive
4045
4046   Since
4047       1.1
4048
4049   block-job-cancel (Command)
4050       Stop an active background block operation.
4051
4052       This  command  returns  immediately after marking the active background
4053       block operation for cancellation.  It is an error to call this  command
4054       if no operation is in progress.
4055
4056       The  operation  will  cancel  as  soon  as  possible  and then emit the
4057       BLOCK_JOB_CANCELLED event.  Before that happens the job is still  visi‐
4058       ble when enumerated using query-block-jobs.
4059
4060       Note  that if you issue 'block-job-cancel' after 'drive-mirror' has in‐
4061       dicated (via the event BLOCK_JOB_READY) that the source and destination
4062       are  synchronized,  then the event triggered by this command changes to
4063       BLOCK_JOB_COMPLETED, to indicate that the mirroring has ended  and  the
4064       destination  now  has a point-in-time copy tied to the time of the can‐
4065       cellation.
4066
4067       For streaming, the image file  retains  its  backing  file  unless  the
4068       streaming  operation happens to complete just as it is being cancelled.
4069       A new streaming operation can be started at  a  later  time  to  finish
4070       copying all data from the backing file.
4071
4072   Arguments
4073       device: string
4074              The  job  identifier.  This  used to be a device name (hence the
4075              name of the parameter), but since QEMU 2.7  it  can  have  other
4076              values.
4077
4078       force: boolean (optional)
4079              If   true,   and   the   job   has  already  emitted  the  event
4080              BLOCK_JOB_READY, abandon the job  immediately  (even  if  it  is
4081              paused)  instead  of waiting for the destination to complete its
4082              final synchronization (since 1.3)
4083
4084   Returns
4085       • Nothing on success
4086
4087       • If no background operation is active on this device, DeviceNotActive
4088
4089   Since
4090       1.1
4091
4092   block-job-pause (Command)
4093       Pause an active background block operation.
4094
4095       This command returns immediately after marking  the  active  background
4096       block operation for pausing.  It is an error to call this command if no
4097       operation is in progress or if the job is already paused.
4098
4099       The operation will pause as soon as possible.  No event is emitted when
4100       the  operation  is  actually paused.  Cancelling a paused job automati‐
4101       cally resumes it.
4102
4103   Arguments
4104       device: string
4105              The job identifier. This used to be a  device  name  (hence  the
4106              name  of  the  parameter),  but since QEMU 2.7 it can have other
4107              values.
4108
4109   Returns
4110       • Nothing on success
4111
4112       • If no background operation is active on this device, DeviceNotActive
4113
4114   Since
4115       1.3
4116
4117   block-job-resume (Command)
4118       Resume an active background block operation.
4119
4120       This command returns immediately after  resuming  a  paused  background
4121       block  operation.   It is an error to call this command if no operation
4122       is in progress or if the job is not paused.
4123
4124       This command also clears the error status of the job.
4125
4126   Arguments
4127       device: string
4128              The job identifier. This used to be a  device  name  (hence  the
4129              name  of  the  parameter),  but since QEMU 2.7 it can have other
4130              values.
4131
4132   Returns
4133       • Nothing on success
4134
4135       • If no background operation is active on this device, DeviceNotActive
4136
4137   Since
4138       1.3
4139
4140   block-job-complete (Command)
4141       Manually trigger completion of an active  background  block  operation.
4142       This  is  supported for drive mirroring, where it also switches the de‐
4143       vice to write to the target path only.  The ability to complete is sig‐
4144       naled with a BLOCK_JOB_READY event.
4145
4146       This  command  completes  an  active  background  block  operation syn‐
4147       chronously.   The  ordering  of  this   command's   return   with   the
4148       BLOCK_JOB_COMPLETED  event  is  not defined.  Note that if an I/O error
4149       occurs during the processing of this command:  1)  the  command  itself
4150       will  fail; 2) the error will be processed according to the rerror/wer‐
4151       ror arguments that were specified when starting the operation.
4152
4153       A cancelled or paused job cannot be completed.
4154
4155   Arguments
4156       device: string
4157              The job identifier. This used to be a  device  name  (hence  the
4158              name  of  the  parameter),  but since QEMU 2.7 it can have other
4159              values.
4160
4161   Returns
4162       • Nothing on success
4163
4164       • If no background operation is active on this device, DeviceNotActive
4165
4166   Since
4167       1.3
4168
4169   block-job-dismiss (Command)
4170       For  jobs  that  have  already  concluded,   remove   them   from   the
4171       block-job-query  list. This command only needs to be run for jobs which
4172       were started with QEMU 2.12+ job lifetime management semantics.
4173
4174       This command will refuse to operate on any job that has not yet reached
4175       its terminal state, JOB_STATUS_CONCLUDED. For jobs that make use of the
4176       BLOCK_JOB_READY  event,  block-job-cancel  or  block-job-complete  will
4177       still need to be used as appropriate.
4178
4179   Arguments
4180       id: string
4181              The job identifier.
4182
4183   Returns
4184       Nothing on success
4185
4186   Since
4187       2.12
4188
4189   block-job-finalize (Command)
4190       Once  a  job  that has manual=true reaches the pending state, it can be
4191       instructed to finalize any graph changes and do any  necessary  cleanup
4192       via  this  command.   For jobs in a transaction, instructing one job to
4193       finalize will force ALL jobs in the transaction to finalize, so  it  is
4194       only necessary to instruct a single member job to finalize.
4195
4196   Arguments
4197       id: string
4198              The job identifier.
4199
4200   Returns
4201       Nothing on success
4202
4203   Since
4204       2.12
4205
4206   BlockdevDiscardOptions (Enum)
4207       Determines how to handle discard requests.
4208
4209   Values
4210       ignore Ignore the request
4211
4212       unmap  Forward as an unmap request
4213
4214   Since
4215       2.9
4216
4217   BlockdevDetectZeroesOptions (Enum)
4218       Describes the operation mode for the automatic conversion of plain zero
4219       writes by the OS to driver specific optimized zero write commands.
4220
4221   Values
4222       off    Disabled (default)
4223
4224       on     Enabled
4225
4226       unmap  Enabled and even try to unmap blocks if possible. This  requires
4227              also  that  BlockdevDiscardOptions  is set to unmap for this de‐
4228              vice.
4229
4230   Since
4231       2.1
4232
4233   BlockdevAioOptions (Enum)
4234       Selects the AIO backend to handle I/O requests
4235
4236   Values
4237       threads
4238              Use qemu's thread pool
4239
4240       native Use native AIO backend (only Linux and Windows)
4241
4242       io_uring (If: defined(CONFIG_LINUX_IO_URING))
4243              Use linux io_uring (since 5.0)
4244
4245   Since
4246       2.9
4247
4248   BlockdevCacheOptions (Object)
4249       Includes cache-related options for block devices
4250
4251   Members
4252       direct: boolean (optional)
4253              enables use of O_DIRECT (bypass the host  page  cache;  default:
4254              false)
4255
4256       no-flush: boolean (optional)
4257              ignore any flush requests for the device (default: false)
4258
4259   Since
4260       2.9
4261
4262   BlockdevDriver (Enum)
4263       Drivers that are supported in block device operations.
4264
4265   Values
4266       throttle
4267              Since 2.11
4268
4269       nvme   Since 2.12
4270
4271       copy-on-read
4272              Since 3.0
4273
4274       blklogwrites
4275              Since 3.0
4276
4277       blkreplay
4278              Since 4.2
4279
4280       compress
4281              Since 5.0
4282
4283       blkdebug
4284              Not documented
4285
4286       blkverify
4287              Not documented
4288
4289       bochs  Not documented
4290
4291       cloop  Not documented
4292
4293       dmg    Not documented
4294
4295       file   Not documented
4296
4297       ftp    Not documented
4298
4299       ftps   Not documented
4300
4301       gluster
4302              Not documented
4303
4304       host_cdrom
4305              Not documented
4306
4307       host_device
4308              Not documented
4309
4310       http   Not documented
4311
4312       https  Not documented
4313
4314       iscsi  Not documented
4315
4316       luks   Not documented
4317
4318       nbd    Not documented
4319
4320       nfs    Not documented
4321
4322       null-aio
4323              Not documented
4324
4325       null-co
4326              Not documented
4327
4328       parallels
4329              Not documented
4330
4331       qcow   Not documented
4332
4333       qcow2  Not documented
4334
4335       qed    Not documented
4336
4337       quorum Not documented
4338
4339       raw    Not documented
4340
4341       rbd    Not documented
4342
4343       replication (If: defined(CONFIG_REPLICATION))
4344              Not documented
4345
4346       sheepdog
4347              Not documented
4348
4349       ssh    Not documented
4350
4351       vdi    Not documented
4352
4353       vhdx   Not documented
4354
4355       vmdk   Not documented
4356
4357       vpc    Not documented
4358
4359       vvfat  Not documented
4360
4361   Since
4362       2.9
4363
4364   BlockdevOptionsFile (Object)
4365       Driver specific block device options for the file backend.
4366
4367   Members
4368       filename: string
4369              path to the image file
4370
4371       pr-manager: string (optional)
4372              the  id  for the object that will handle persistent reservations
4373              for this device (default: none, forward the commands via  SG_IO;
4374              since 2.11)
4375
4376       aio: BlockdevAioOptions (optional)
4377              AIO backend (default: threads) (since: 2.8)
4378
4379       locking: OnOffAuto (optional)
4380              whether  to  enable  file locking. If set to 'auto', only enable
4381              when Open File Descriptor (OFD) locking API  is  available  (de‐
4382              fault: auto, since 2.10)
4383
4384       drop-cache: boolean (optional) (If: defined(CONFIG_LINUX))
4385              invalidate  page  cache  during  live  migration.  This prevents
4386              stale data on the migration destination  with  cache.direct=off.
4387              Currently  only  supported on Linux hosts.  (default: on, since:
4388              4.0)
4389
4390       x-check-cache-dropped: boolean (optional)
4391              whether to check that page cache was dropped on live  migration.
4392              May  cause  noticeable delays if the image file is large, do not
4393              use in production.  (default: off) (since: 3.0)
4394
4395   Features
4396       dynamic-auto-read-only
4397              If present, enabled auto-read-only means that  the  driver  will
4398              open  the image read-only at first, dynamically reopen the image
4399              file read-write when the first writer is attached  to  the  node
4400              and  reopen read-only when the last writer is detached. This al‐
4401              lows giving QEMU write permissions only on demand when an opera‐
4402              tion actually needs write access.
4403
4404   Since
4405       2.9
4406
4407   BlockdevOptionsNull (Object)
4408       Driver specific block device options for the null backend.
4409
4410   Members
4411       size: int (optional)
4412              size of the device in bytes.
4413
4414       latency-ns: int (optional)
4415              emulated  latency  (in  nanoseconds) in processing requests. De‐
4416              fault to zero which completes requests immediately.  (Since 2.4)
4417
4418       read-zeroes: boolean (optional)
4419              if true, reads from the device produce  zeroes;  if  false,  the
4420              buffer is left unchanged. (default: false; since: 4.1)
4421
4422   Since
4423       2.9
4424
4425   BlockdevOptionsNVMe (Object)
4426       Driver specific block device options for the NVMe backend.
4427
4428   Members
4429       device: string
4430              PCI controller address of the NVMe device in format hhhh:bb:ss.f
4431              (host:bus:slot.function)
4432
4433       namespace: int
4434              namespace number of the device, starting from 1.
4435       Note that the PCI device must have been unbound from  any  host  kernel
4436       driver before instructing QEMU to add the blockdev.
4437
4438   Since
4439       2.12
4440
4441   BlockdevOptionsVVFAT (Object)
4442       Driver specific block device options for the vvfat protocol.
4443
4444   Members
4445       dir: string
4446              directory to be exported as FAT image
4447
4448       fat-type: int (optional)
4449              FAT type: 12, 16 or 32
4450
4451       floppy: boolean (optional)
4452              whether to export a floppy image (true) or partitioned hard disk
4453              (false; default)
4454
4455       label: string (optional)
4456              set the volume label, limited to 11 bytes. FAT16 and FAT32  tra‐
4457              ditionally  have  some restrictions on labels, which are ignored
4458              by most operating systems. Defaults  to  "QEMU  VVFAT".   (since
4459              2.4)
4460
4461       rw: boolean (optional)
4462              whether to allow write operations (default: false)
4463
4464   Since
4465       2.9
4466
4467   BlockdevOptionsGenericFormat (Object)
4468       Driver  specific block device options for image format that have no op‐
4469       tion besides their data source.
4470
4471   Members
4472       file: BlockdevRef
4473              reference to or definition of the data source block device
4474
4475   Since
4476       2.9
4477
4478   BlockdevOptionsLUKS (Object)
4479       Driver specific block device options for LUKS.
4480
4481   Members
4482       key-secret: string (optional)
4483              the ID of a QCryptoSecret object providing  the  decryption  key
4484              (since  2.6).  Mandatory except when doing a metadata-only probe
4485              of the image.
4486
4487       The members of BlockdevOptionsGenericFormat
4488
4489   Since
4490       2.9
4491
4492   BlockdevOptionsGenericCOWFormat (Object)
4493       Driver specific block device options for image format that have no  op‐
4494       tion besides their data source and an optional backing file.
4495
4496   Members
4497       backing: BlockdevRefOrNull (optional)
4498              reference  to  or  definition  of the backing file block device,
4499              null disables the backing file entirely.  Defaults to the  back‐
4500              ing file stored the image file.
4501
4502       The members of BlockdevOptionsGenericFormat
4503
4504   Since
4505       2.9
4506
4507   Qcow2OverlapCheckMode (Enum)
4508       General overlap check modes.
4509
4510   Values
4511       none   Do not perform any checks
4512
4513       constant
4514              Perform only checks which can be done in constant time and with‐
4515              out reading anything from disk
4516
4517       cached Perform only checks which can be done without  reading  anything
4518              from disk
4519
4520       all    Perform all available overlap checks
4521
4522   Since
4523       2.9
4524
4525   Qcow2OverlapCheckFlags (Object)
4526       Structure  of  flags  for  each  metadata structure. Setting a field to
4527       'true' makes qemu guard that structure against unintended  overwriting.
4528       The default value is chosen according to the template given.
4529
4530   Members
4531       template: Qcow2OverlapCheckMode (optional)
4532              Specifies  a template mode which can be adjusted using the other
4533              flags, defaults to 'cached'
4534
4535       bitmap-directory: boolean (optional)
4536              since 3.0
4537
4538       main-header: boolean (optional)
4539              Not documented
4540
4541       active-l1: boolean (optional)
4542              Not documented
4543
4544       active-l2: boolean (optional)
4545              Not documented
4546
4547       refcount-table: boolean (optional)
4548              Not documented
4549
4550       refcount-block: boolean (optional)
4551              Not documented
4552
4553       snapshot-table: boolean (optional)
4554              Not documented
4555
4556       inactive-l1: boolean (optional)
4557              Not documented
4558
4559       inactive-l2: boolean (optional)
4560              Not documented
4561
4562   Since
4563       2.9
4564
4565   Qcow2OverlapChecks (Alternate)
4566       Specifies which metadata structures should  be  guarded  against  unin‐
4567       tended overwriting.
4568
4569   Members
4570       flags: Qcow2OverlapCheckFlags
4571              set  of flags for separate specification of each metadata struc‐
4572              ture type
4573
4574       mode: Qcow2OverlapCheckMode
4575              named mode which chooses a specific set of flags
4576
4577   Since
4578       2.9
4579
4580   BlockdevQcowEncryptionFormat (Enum)
4581   Values
4582       aes    AES-CBC with plain64 initialization vectors
4583
4584   Since
4585       2.10
4586
4587   BlockdevQcowEncryption (Object)
4588   Members
4589       format: BlockdevQcowEncryptionFormat
4590              Not documented
4591
4592       The members of QCryptoBlockOptionsQCow when format is "aes"
4593
4594   Since
4595       2.10
4596
4597   BlockdevOptionsQcow (Object)
4598       Driver specific block device options for qcow.
4599
4600   Members
4601       encrypt: BlockdevQcowEncryption (optional)
4602              Image decryption options. Mandatory for encrypted images, except
4603              when doing a metadata-only probe of the image.
4604
4605       The members of BlockdevOptionsGenericCOWFormat
4606
4607   Since
4608       2.10
4609
4610   BlockdevQcow2EncryptionFormat (Enum)
4611   Values
4612       aes    AES-CBC with plain64 initialization vectors
4613
4614       luks   Not documented
4615
4616   Since
4617       2.10
4618
4619   BlockdevQcow2Encryption (Object)
4620   Members
4621       format: BlockdevQcow2EncryptionFormat
4622              Not documented
4623
4624       The members of QCryptoBlockOptionsQCow when format is "aes"
4625
4626       The members of QCryptoBlockOptionsLUKS when format is "luks"
4627
4628   Since
4629       2.10
4630
4631   BlockdevOptionsQcow2 (Object)
4632       Driver specific block device options for qcow2.
4633
4634   Members
4635       lazy-refcounts: boolean (optional)
4636              whether  to  enable the lazy refcounts feature (default is taken
4637              from the image file)
4638
4639       pass-discard-request: boolean (optional)
4640              whether discard requests to the qcow2 device should be forwarded
4641              to the data source
4642
4643       pass-discard-snapshot: boolean (optional)
4644              whether  discard  requests  for the data source should be issued
4645              when a snapshot operation  (e.g.   deleting  a  snapshot)  frees
4646              clusters in the qcow2 file
4647
4648       pass-discard-other: boolean (optional)
4649              whether discard requests for the data source should be issued on
4650              other occasions where a cluster gets freed
4651
4652       overlap-check: Qcow2OverlapChecks (optional)
4653              which overlap checks to perform for writes  to  the  image,  de‐
4654              faults to 'cached' (since 2.2)
4655
4656       cache-size: int (optional)
4657              the maximum total size of the L2 table and refcount block caches
4658              in bytes (since 2.2)
4659
4660       l2-cache-size: int (optional)
4661              the maximum size of the L2 table cache in bytes (since 2.2)
4662
4663       l2-cache-entry-size: int (optional)
4664              the size of each entry in the L2 cache in bytes. It  must  be  a
4665              power of two between 512 and the cluster size. The default value
4666              is the cluster size (since 2.12)
4667
4668       refcount-cache-size: int (optional)
4669              the maximum size of the refcount block  cache  in  bytes  (since
4670              2.2)
4671
4672       cache-clean-interval: int (optional)
4673              clean unused entries in the L2 and refcount caches. The interval
4674              is in seconds. The default value is 600 on supporting platforms,
4675              and 0 on other platforms. 0 disables this feature. (since 2.5)
4676
4677       encrypt: BlockdevQcow2Encryption (optional)
4678              Image decryption options. Mandatory for encrypted images, except
4679              when doing a metadata-only probe of the image. (since 2.10)
4680
4681       data-file: BlockdevRef (optional)
4682              reference to or definition of the external data file.  This  may
4683              only be specified for images that require an external data file.
4684              If it is not specified for such an image, the data file name  is
4685              loaded from the image file. (since 4.0)
4686
4687       The members of BlockdevOptionsGenericCOWFormat
4688
4689   Since
4690       2.9
4691
4692   SshHostKeyCheckMode (Enum)
4693   Values
4694       none   Don't check the host key at all
4695
4696       hash   Compare the host key with a given hash
4697
4698       known_hosts
4699              Check the host key against the known_hosts file
4700
4701   Since
4702       2.12
4703
4704   SshHostKeyCheckHashType (Enum)
4705   Values
4706       md5    The given hash is an md5 hash
4707
4708       sha1   The given hash is an sha1 hash
4709
4710   Since
4711       2.12
4712
4713   SshHostKeyHash (Object)
4714   Members
4715       type: SshHostKeyCheckHashType
4716              The hash algorithm used for the hash
4717
4718       hash: string
4719              The expected hash value
4720
4721   Since
4722       2.12
4723
4724   SshHostKeyCheck (Object)
4725   Members
4726       mode: SshHostKeyCheckMode
4727              Not documented
4728
4729       The members of SshHostKeyHash when mode is "hash"
4730
4731   Since
4732       2.12
4733
4734   BlockdevOptionsSsh (Object)
4735   Members
4736       server: InetSocketAddress
4737              host address
4738
4739       path: string
4740              path to the image on the host
4741
4742       user: string (optional)
4743              user as which to connect, defaults to current local user name
4744
4745       host-key-check: SshHostKeyCheck (optional)
4746              Defines  how  and  what  to check the host key against (default:
4747              known_hosts)
4748
4749   Since
4750       2.9
4751
4752   BlkdebugEvent (Enum)
4753       Trigger events supported by blkdebug.
4754
4755   Values
4756       l1_shrink_write_table
4757              write zeros to the l1 table to shrink image.  (since 2.11)
4758
4759       l1_shrink_free_l2_clusters
4760              discard the l2 tables. (since 2.11)
4761
4762       cor_write
4763              a write due to copy-on-read (since 2.11)
4764
4765       cluster_alloc_space
4766              an allocation of file space for a cluster (since 4.1)
4767
4768       none   triggers once at creation of the blkdebug node (since 4.1)
4769
4770       l1_update
4771              Not documented
4772
4773       l1_grow_alloc_table
4774              Not documented
4775
4776       l1_grow_write_table
4777              Not documented
4778
4779       l1_grow_activate_table
4780              Not documented
4781
4782       l2_load
4783              Not documented
4784
4785       l2_update
4786              Not documented
4787
4788       l2_update_compressed
4789              Not documented
4790
4791       l2_alloc_cow_read
4792              Not documented
4793
4794       l2_alloc_write
4795              Not documented
4796
4797       read_aio
4798              Not documented
4799
4800       read_backing_aio
4801              Not documented
4802
4803       read_compressed
4804              Not documented
4805
4806       write_aio
4807              Not documented
4808
4809       write_compressed
4810              Not documented
4811
4812       vmstate_load
4813              Not documented
4814
4815       vmstate_save
4816              Not documented
4817
4818       cow_read
4819              Not documented
4820
4821       cow_write
4822              Not documented
4823
4824       reftable_load
4825              Not documented
4826
4827       reftable_grow
4828              Not documented
4829
4830       reftable_update
4831              Not documented
4832
4833       refblock_load
4834              Not documented
4835
4836       refblock_update
4837              Not documented
4838
4839       refblock_update_part
4840              Not documented
4841
4842       refblock_alloc
4843              Not documented
4844
4845       refblock_alloc_hookup
4846              Not documented
4847
4848       refblock_alloc_write
4849              Not documented
4850
4851       refblock_alloc_write_blocks
4852              Not documented
4853
4854       refblock_alloc_write_table
4855              Not documented
4856
4857       refblock_alloc_switch_table
4858              Not documented
4859
4860       cluster_alloc
4861              Not documented
4862
4863       cluster_alloc_bytes
4864              Not documented
4865
4866       cluster_free
4867              Not documented
4868
4869       flush_to_os
4870              Not documented
4871
4872       flush_to_disk
4873              Not documented
4874
4875       pwritev_rmw_head
4876              Not documented
4877
4878       pwritev_rmw_after_head
4879              Not documented
4880
4881       pwritev_rmw_tail
4882              Not documented
4883
4884       pwritev_rmw_after_tail
4885              Not documented
4886
4887       pwritev
4888              Not documented
4889
4890       pwritev_zero
4891              Not documented
4892
4893       pwritev_done
4894              Not documented
4895
4896       empty_image_prepare
4897              Not documented
4898
4899   Since
4900       2.9
4901
4902   BlkdebugIOType (Enum)
4903       Kinds of I/O that blkdebug can inject errors in.
4904
4905   Values
4906       read   .bdrv_co_preadv()
4907
4908       write  .bdrv_co_pwritev()
4909
4910       write-zeroes
4911              .bdrv_co_pwrite_zeroes()
4912
4913       discard
4914              .bdrv_co_pdiscard()
4915
4916       flush  .bdrv_co_flush_to_disk()
4917
4918       block-status
4919              .bdrv_co_block_status()
4920
4921   Since
4922       4.1
4923
4924   BlkdebugInjectErrorOptions (Object)
4925       Describes a single error injection for blkdebug.
4926
4927   Members
4928       event: BlkdebugEvent
4929              trigger event
4930
4931       state: int (optional)
4932              the state identifier blkdebug needs to be in to actually trigger
4933              the event; defaults to "any"
4934
4935       iotype: BlkdebugIOType (optional)
4936              the  type  of  I/O  operations on which this error should be in‐
4937              jected; defaults to "all read, write, write-zeroes, discard, and
4938              flush operations" (since: 4.1)
4939
4940       errno: int (optional)
4941              error identifier (errno) to be returned; defaults to EIO
4942
4943       sector: int (optional)
4944              specifies  the sector index which has to be affected in order to
4945              actually trigger the event; defaults to "any sector"
4946
4947       once: boolean (optional)
4948              disables further events after this one has been  triggered;  de‐
4949              faults to false
4950
4951       immediately: boolean (optional)
4952              fail immediately; defaults to false
4953
4954   Since
4955       2.9
4956
4957   BlkdebugSetStateOptions (Object)
4958       Describes a single state-change event for blkdebug.
4959
4960   Members
4961       event: BlkdebugEvent
4962              trigger event
4963
4964       state: int (optional)
4965              the  current  state identifier blkdebug needs to be in; defaults
4966              to "any"
4967
4968       new_state: int
4969              the state identifier blkdebug is  supposed  to  assume  if  this
4970              event is triggered
4971
4972   Since
4973       2.9
4974
4975   BlockdevOptionsBlkdebug (Object)
4976       Driver specific block device options for blkdebug.
4977
4978   Members
4979       image: BlockdevRef
4980              underlying raw block device (or image file)
4981
4982       config: string (optional)
4983              filename of the configuration file
4984
4985       align: int (optional)
4986              required alignment for requests in bytes, must be positive power
4987              of 2, or 0 for default
4988
4989       max-transfer: int (optional)
4990              maximum size for I/O transfers in bytes, must be positive multi‐
4991              ple of align and of the underlying file's request alignment (but
4992              need not be a power of 2), or 0 for default (since 2.10)
4993
4994       opt-write-zero: int (optional)
4995              preferred alignment for write zero requests in  bytes,  must  be
4996              positive  multiple of align and of the underlying file's request
4997              alignment (but need not be a power  of  2),  or  0  for  default
4998              (since 2.10)
4999
5000       max-write-zero: int (optional)
5001              maximum  size for write zero requests in bytes, must be positive
5002              multiple of align, of  opt-write-zero,  and  of  the  underlying
5003              file's  request  alignment  (but need not be a power of 2), or 0
5004              for default (since 2.10)
5005
5006       opt-discard: int (optional)
5007              preferred alignment for discard requests in bytes, must be posi‐
5008              tive  multiple  of  align  and  of the underlying file's request
5009              alignment (but need not be a power  of  2),  or  0  for  default
5010              (since 2.10)
5011
5012       max-discard: int (optional)
5013              maximum  size  for  discard  requests in bytes, must be positive
5014              multiple of align, of opt-discard, and of the underlying  file's
5015              request  alignment  (but need not be a power of 2), or 0 for de‐
5016              fault (since 2.10)
5017
5018       inject-error: array of BlkdebugInjectErrorOptions (optional)
5019              array of error injection descriptions
5020
5021       set-state: array of BlkdebugSetStateOptions (optional)
5022              array of state-change descriptions
5023
5024       take-child-perms: array of BlockPermission (optional)
5025              Permissions to take on image in addition to  what  is  necessary
5026              anyway  (which  depends  on how the blkdebug node is used).  De‐
5027              faults to none.  (since 5.0)
5028
5029       unshare-child-perms: array of BlockPermission (optional)
5030              Permissions not to share on image in addition to what cannot  be
5031              shared  anyway (which depends on how the blkdebug node is used).
5032              Defaults to none.  (since 5.0)
5033
5034   Since
5035       2.9
5036
5037   BlockdevOptionsBlklogwrites (Object)
5038       Driver specific block device options for blklogwrites.
5039
5040   Members
5041       file: BlockdevRef
5042              block device
5043
5044       log: BlockdevRef
5045              block device used to log writes to file
5046
5047       log-sector-size: int (optional)
5048              sector size used in logging writes to file, determines granular‐
5049              ity of offsets and sizes of writes (default: 512)
5050
5051       log-append: boolean (optional)
5052              append to an existing log (default: false)
5053
5054       log-super-update-interval: int (optional)
5055              interval  of  write  requests after which the log super block is
5056              updated to disk (default: 4096)
5057
5058   Since
5059       3.0
5060
5061   BlockdevOptionsBlkverify (Object)
5062       Driver specific block device options for blkverify.
5063
5064   Members
5065       test: BlockdevRef
5066              block device to be tested
5067
5068       raw: BlockdevRef
5069              raw image used for verification
5070
5071   Since
5072       2.9
5073
5074   BlockdevOptionsBlkreplay (Object)
5075       Driver specific block device options for blkreplay.
5076
5077   Members
5078       image: BlockdevRef
5079              disk image which should be controlled with blkreplay
5080
5081   Since
5082       4.2
5083
5084   QuorumReadPattern (Enum)
5085       An enumeration of quorum read patterns.
5086
5087   Values
5088       quorum read all the children and do a quorum vote on reads
5089
5090       fifo   read only from the first child that has not failed
5091
5092   Since
5093       2.9
5094
5095   BlockdevOptionsQuorum (Object)
5096       Driver specific block device options for Quorum
5097
5098   Members
5099       blkverify: boolean (optional)
5100
5101              true if the driver must print content mismatch
5102                     set to false by default
5103
5104       children: array of BlockdevRef
5105              the children block devices to use
5106
5107       vote-threshold: int
5108              the vote limit under which a read will fail
5109
5110       rewrite-corrupted: boolean (optional)
5111              rewrite corrupted data when quorum is reached (Since 2.1)
5112
5113       read-pattern: QuorumReadPattern (optional)
5114              choose read pattern and set to quorum by default (Since 2.2)
5115
5116   Since
5117       2.9
5118
5119   BlockdevOptionsGluster (Object)
5120       Driver specific block device options for Gluster
5121
5122   Members
5123       volume: string
5124              name of gluster volume where VM image resides
5125
5126       path: string
5127              absolute path to image file in gluster volume
5128
5129       server: array of SocketAddress
5130              gluster servers description
5131
5132       debug: int (optional)
5133              libgfapi log level (default '4' which is Error) (Since 2.8)
5134
5135       logfile: string (optional)
5136              libgfapi log file (default /dev/stderr) (Since 2.8)
5137
5138   Since
5139       2.9
5140
5141   IscsiTransport (Enum)
5142       An enumeration of libiscsi transport types
5143
5144   Values
5145       tcp    Not documented
5146
5147       iser   Not documented
5148
5149   Since
5150       2.9
5151
5152   IscsiHeaderDigest (Enum)
5153       An enumeration of header digests supported by libiscsi
5154
5155   Values
5156       crc32c Not documented
5157
5158       none   Not documented
5159
5160       crc32c-none
5161              Not documented
5162
5163       none-crc32c
5164              Not documented
5165
5166   Since
5167       2.9
5168
5169   BlockdevOptionsIscsi (Object)
5170   Members
5171       transport: IscsiTransport
5172              The iscsi transport type
5173
5174       portal: string
5175              The address of the iscsi portal
5176
5177       target: string
5178              The target iqn name
5179
5180       lun: int (optional)
5181              LUN to connect to. Defaults to 0.
5182
5183       user: string (optional)
5184              User name to log in with. If omitted, no CHAP authentication  is
5185              performed.
5186
5187       password-secret: string (optional)
5188              The  ID of a QCryptoSecret object providing the password for the
5189              login. This option is required if user is specified.
5190
5191       initiator-name: string (optional)
5192              The iqn name we want to identify to the target as. If  this  op‐
5193              tion  is not specified, an initiator name is generated automati‐
5194              cally.
5195
5196       header-digest: IscsiHeaderDigest (optional)
5197              The desired header digest. Defaults to none-crc32c.
5198
5199       timeout: int (optional)
5200              Timeout in seconds after which a request will timeout.  0  means
5201              no timeout and is the default.
5202       Driver specific block device options for iscsi
5203
5204   Since
5205       2.9
5206
5207   RbdAuthMode (Enum)
5208   Values
5209       cephx  Not documented
5210
5211       none   Not documented
5212
5213   Since
5214       3.0
5215
5216   BlockdevOptionsRbd (Object)
5217   Members
5218       pool: string
5219              Ceph pool name.
5220
5221       namespace: string (optional)
5222              Rados namespace name in the Ceph pool. (Since 5.0)
5223
5224       image: string
5225              Image name in the Ceph pool.
5226
5227       conf: string (optional)
5228              path  to  Ceph  configuration file.  Values in the configuration
5229              file will be overridden by options specified via QAPI.
5230
5231       snapshot: string (optional)
5232              Ceph snapshot name.
5233
5234       user: string (optional)
5235              Ceph id name.
5236
5237       auth-client-required: array of RbdAuthMode (optional)
5238              Acceptable authentication modes.  This maps to  Ceph  configura‐
5239              tion option "auth_client_required".  (Since 3.0)
5240
5241       key-secret: string (optional)
5242              ID of a QCryptoSecret object providing a key for cephx authenti‐
5243              cation.  This maps to Ceph configuration option  "key".   (Since
5244              3.0)
5245
5246       server: array of InetSocketAddressBase (optional)
5247              Monitor host address and port.  This maps to the "mon_host" Ceph
5248              option.
5249
5250   Since
5251       2.9
5252
5253   BlockdevOptionsSheepdog (Object)
5254       Driver specific block device options for sheepdog
5255
5256   Members
5257       vdi: string
5258              Virtual disk image name
5259
5260       server: SocketAddress
5261              The Sheepdog server to connect to
5262
5263       snap-id: int (optional)
5264              Snapshot ID
5265
5266       tag: string (optional)
5267              Snapshot tag name
5268       Only one of snap-id and tag may be present.
5269
5270   Since
5271       2.9
5272
5273   ReplicationMode (Enum)
5274       An enumeration of replication modes.
5275
5276   Values
5277       primary
5278              Primary mode, the vm's state will be sent to secondary QEMU.
5279
5280       secondary
5281              Secondary mode, receive the vm's state from primary QEMU.
5282
5283   Since
5284       2.9
5285
5286   If
5287       defined(CONFIG_REPLICATION).SS BlockdevOptionsReplication (Object)
5288
5289       Driver specific block device options for replication
5290
5291   Members
5292       mode: ReplicationMode
5293              the replication mode
5294
5295       top-id: string (optional)
5296              In secondary mode, node name or device ID of the root  node  who
5297              owns  the  replication  node chain. Must not be given in primary
5298              mode.
5299
5300       The members of BlockdevOptionsGenericFormat
5301
5302   Since
5303       2.9
5304
5305   If
5306       defined(CONFIG_REPLICATION).SS NFSTransport (Enum)
5307
5308       An enumeration of NFS transport types
5309
5310   Values
5311       inet   TCP transport
5312
5313   Since
5314       2.9
5315
5316   NFSServer (Object)
5317       Captures the address of the socket
5318
5319   Members
5320       type: NFSTransport
5321              transport type used for NFS (only TCP supported)
5322
5323       host: string
5324              host address for NFS server
5325
5326   Since
5327       2.9
5328
5329   BlockdevOptionsNfs (Object)
5330       Driver specific block device option for NFS
5331
5332   Members
5333       server: NFSServer
5334              host address
5335
5336       path: string
5337              path of the image on the host
5338
5339       user: int (optional)
5340              UID value to use when talking to the server (defaults  to  65534
5341              on Windows and getuid() on unix)
5342
5343       group: int (optional)
5344              GID  value  to use when talking to the server (defaults to 65534
5345              on Windows and getgid() in unix)
5346
5347       tcp-syn-count: int (optional)
5348              number of SYNs during the  session  establishment  (defaults  to
5349              libnfs default)
5350
5351       readahead-size: int (optional)
5352              set the readahead size in bytes (defaults to libnfs default)
5353
5354       page-cache-size: int (optional)
5355              set the pagecache size in bytes (defaults to libnfs default)
5356
5357       debug: int (optional)
5358              set the NFS debug level (max 2) (defaults to libnfs default)
5359
5360   Since
5361       2.9
5362
5363   BlockdevOptionsCurlBase (Object)
5364       Driver  specific block device options shared by all protocols supported
5365       by the curl backend.
5366
5367   Members
5368       url: string
5369              URL of the image file
5370
5371       readahead: int (optional)
5372              Size of the read-ahead cache; must be a  multiple  of  512  (de‐
5373              faults to 256 kB)
5374
5375       timeout: int (optional)
5376              Timeout for connections, in seconds (defaults to 5)
5377
5378       username: string (optional)
5379              Username for authentication (defaults to none)
5380
5381       password-secret: string (optional)
5382              ID  of a QCryptoSecret object providing a password for authenti‐
5383              cation (defaults to no password)
5384
5385       proxy-username: string (optional)
5386              Username for proxy authentication (defaults to none)
5387
5388       proxy-password-secret: string (optional)
5389              ID of a QCryptoSecret object providing a password for proxy  au‐
5390              thentication (defaults to no password)
5391
5392   Since
5393       2.9
5394
5395   BlockdevOptionsCurlHttp (Object)
5396       Driver specific block device options for HTTP connections over the curl
5397       backend.  URLs must start with "http://".
5398
5399   Members
5400       cookie: string (optional)
5401              List of cookies to set; format  is  "name1=content1;  name2=con‐
5402              tent2;"  as explained by CURLOPT_COOKIE(3). Defaults to no cook‐
5403              ies.
5404
5405       cookie-secret: string (optional)
5406              ID of a QCryptoSecret object providing the cookie data in a  se‐
5407              cure way. See cookie for the format. (since 2.10)
5408
5409       The members of BlockdevOptionsCurlBase
5410
5411   Since
5412       2.9
5413
5414   BlockdevOptionsCurlHttps (Object)
5415       Driver  specific  block  device  options for HTTPS connections over the
5416       curl backend.  URLs must start with "https://".
5417
5418   Members
5419       cookie: string (optional)
5420              List of cookies to set; format  is  "name1=content1;  name2=con‐
5421              tent2;"  as explained by CURLOPT_COOKIE(3). Defaults to no cook‐
5422              ies.
5423
5424       sslverify: boolean (optional)
5425              Whether to verify the SSL certificate's  validity  (defaults  to
5426              true)
5427
5428       cookie-secret: string (optional)
5429              ID  of a QCryptoSecret object providing the cookie data in a se‐
5430              cure way. See cookie for the format. (since 2.10)
5431
5432       The members of BlockdevOptionsCurlBase
5433
5434   Since
5435       2.9
5436
5437   BlockdevOptionsCurlFtp (Object)
5438       Driver specific block device options for FTP connections over the  curl
5439       backend.  URLs must start with "ftp://".
5440
5441   Members
5442       The members of BlockdevOptionsCurlBase
5443
5444   Since
5445       2.9
5446
5447   BlockdevOptionsCurlFtps (Object)
5448       Driver specific block device options for FTPS connections over the curl
5449       backend.  URLs must start with "ftps://".
5450
5451   Members
5452       sslverify: boolean (optional)
5453              Whether to verify the SSL certificate's  validity  (defaults  to
5454              true)
5455
5456       The members of BlockdevOptionsCurlBase
5457
5458   Since
5459       2.9
5460
5461   BlockdevOptionsNbd (Object)
5462       Driver specific block device options for NBD.
5463
5464   Members
5465       server: SocketAddress
5466              NBD server address
5467
5468       export: string (optional)
5469              export name
5470
5471       tls-creds: string (optional)
5472              TLS credentials ID
5473
5474       x-dirty-bitmap: string (optional)
5475              A  metadata  context  name  such  as "qemu:dirty-bitmap:NAME" or
5476              "qemu:allocation-depth" to query in  place  of  the  traditional
5477              "base:allocation" block status (see NBD_OPT_LIST_META_CONTEXT in
5478              the NBD protocol; and yes, naming this  option  x-context  would
5479              have made more sense) (since 3.0)
5480
5481       reconnect-delay: int (optional)
5482              On  an  unexpected  disconnect,  the nbd client tries to connect
5483              again until succeeding or encountering a serious error.   During
5484              the  first  reconnect-delay seconds, all requests are paused and
5485              will be rerun on a successful reconnect. After  that  time,  any
5486              delayed requests and all future requests before a successful re‐
5487              connect will immediately fail. Default 0 (Since 4.2)
5488
5489   Since
5490       2.9
5491
5492   BlockdevOptionsRaw (Object)
5493       Driver specific block device options for the raw driver.
5494
5495   Members
5496       offset: int (optional)
5497              position where the block device starts
5498
5499       size: int (optional)
5500              the assumed size of the device
5501
5502       The members of BlockdevOptionsGenericFormat
5503
5504   Since
5505       2.9
5506
5507   BlockdevOptionsThrottle (Object)
5508       Driver specific block device options for the throttle driver
5509
5510   Members
5511       throttle-group: string
5512              the name of the throttle-group object to use.  It  must  already
5513              exist.
5514
5515       file: BlockdevRef
5516              reference to or definition of the data source block device
5517
5518   Since
5519       2.11
5520
5521   BlockdevOptions (Object)
5522       Options  for  creating  a block device.  Many options are available for
5523       all block devices, independent of the block driver:
5524
5525   Members
5526       driver: BlockdevDriver
5527              block driver name
5528
5529       node-name: string (optional)
5530              the node name of the new node (Since 2.0).  This option  is  re‐
5531              quired on the top level of blockdev-add.  Valid node names start
5532              with an alphabetic character and may contain  only  alphanumeric
5533              characters, '-', '.' and '_'. Their maximum length is 31 charac‐
5534              ters.
5535
5536       discard: BlockdevDiscardOptions (optional)
5537              discard-related options (default: ignore)
5538
5539       cache: BlockdevCacheOptions (optional)
5540              cache-related options
5541
5542       read-only: boolean (optional)
5543              whether the block device should be read-only  (default:  false).
5544              Note  that some block drivers support only read-only access, ei‐
5545              ther generally or in certain configurations. In this  case,  the
5546              default value does not work and the option must be specified ex‐
5547              plicitly.
5548
5549       auto-read-only: boolean (optional)
5550              if true and read-only is false, QEMU  may  automatically  decide
5551              not  to open the image read-write as requested, but fall back to
5552              read-only instead (and switch between the modes later), e.g. de‐
5553              pending on whether the image file is writable or whether a writ‐
5554              ing user is attached to the node (default: false, since 3.1)
5555
5556       detect-zeroes: BlockdevDetectZeroesOptions (optional)
5557              detect and optimize zero writes (Since 2.1) (default: off)
5558
5559       force-share: boolean (optional)
5560              force  share  all   permission   on   added   nodes.    Requires
5561              read-only=true. (Since 2.10)
5562
5563       The members of BlockdevOptionsBlkdebug when driver is "blkdebug"
5564
5565       The  members  of  BlockdevOptionsBlklogwrites  when  driver is "blklog‐
5566       writes"
5567
5568       The members of BlockdevOptionsBlkverify when driver is "blkverify"
5569
5570       The members of BlockdevOptionsBlkreplay when driver is "blkreplay"
5571
5572       The members of BlockdevOptionsGenericFormat when driver is "bochs"
5573
5574       The members of BlockdevOptionsGenericFormat when driver is "cloop"
5575
5576       The members of BlockdevOptionsGenericFormat when driver is "compress"
5577
5578       The   members   of   BlockdevOptionsGenericFormat   when   driver    is
5579       "copy-on-read"
5580
5581       The members of BlockdevOptionsGenericFormat when driver is "dmg"
5582
5583       The members of BlockdevOptionsFile when driver is "file"
5584
5585       The members of BlockdevOptionsCurlFtp when driver is "ftp"
5586
5587       The members of BlockdevOptionsCurlFtps when driver is "ftps"
5588
5589       The members of BlockdevOptionsGluster when driver is "gluster"
5590
5591       The members of BlockdevOptionsFile when driver is "host_cdrom"
5592
5593       The members of BlockdevOptionsFile when driver is "host_device"
5594
5595       The members of BlockdevOptionsCurlHttp when driver is "http"
5596
5597       The members of BlockdevOptionsCurlHttps when driver is "https"
5598
5599       The members of BlockdevOptionsIscsi when driver is "iscsi"
5600
5601       The members of BlockdevOptionsLUKS when driver is "luks"
5602
5603       The members of BlockdevOptionsNbd when driver is "nbd"
5604
5605       The members of BlockdevOptionsNfs when driver is "nfs"
5606
5607       The members of BlockdevOptionsNull when driver is "null-aio"
5608
5609       The members of BlockdevOptionsNull when driver is "null-co"
5610
5611       The members of BlockdevOptionsNVMe when driver is "nvme"
5612
5613       The members of BlockdevOptionsGenericFormat when driver is "parallels"
5614
5615       The members of BlockdevOptionsQcow2 when driver is "qcow2"
5616
5617       The members of BlockdevOptionsQcow when driver is "qcow"
5618
5619       The members of BlockdevOptionsGenericCOWFormat when driver is "qed"
5620
5621       The members of BlockdevOptionsQuorum when driver is "quorum"
5622
5623       The members of BlockdevOptionsRaw when driver is "raw"
5624
5625       The members of BlockdevOptionsRbd when driver is "rbd"
5626
5627       The  members of BlockdevOptionsReplication when driver is "replication"
5628       (If: defined(CONFIG_REPLICATION))
5629
5630       The members of BlockdevOptionsSheepdog when driver is "sheepdog"
5631
5632       The members of BlockdevOptionsSsh when driver is "ssh"
5633
5634       The members of BlockdevOptionsThrottle when driver is "throttle"
5635
5636       The members of BlockdevOptionsGenericFormat when driver is "vdi"
5637
5638       The members of BlockdevOptionsGenericFormat when driver is "vhdx"
5639
5640       The members of BlockdevOptionsGenericCOWFormat when driver is "vmdk"
5641
5642       The members of BlockdevOptionsGenericFormat when driver is "vpc"
5643
5644       The members of BlockdevOptionsVVFAT when driver is "vvfat"
5645       Remaining options are determined by the block driver.
5646
5647   Since
5648       2.9
5649
5650   BlockdevRef (Alternate)
5651       Reference to a block device.
5652
5653   Members
5654       definition: BlockdevOptions
5655              defines a new block device inline
5656
5657       reference: string
5658              references the ID of an existing block device
5659
5660   Since
5661       2.9
5662
5663   BlockdevRefOrNull (Alternate)
5664       Reference to a block device.
5665
5666   Members
5667       definition: BlockdevOptions
5668              defines a new block device inline
5669
5670       reference: string
5671              references the ID of an existing block device.  An empty  string
5672              means  that  no  block device should be referenced.  Deprecated;
5673              use null instead.
5674
5675       null: null
5676              No block device should be referenced (since 2.10)
5677
5678   Since
5679       2.9
5680
5681   blockdev-add (Command)
5682       Creates a new block device.
5683
5684   Arguments
5685       The members of BlockdevOptions
5686
5687   Since
5688       2.9
5689
5690   Example
5691          1.
5692          -> { "execute": "blockdev-add",
5693               "arguments": {
5694                    "driver": "qcow2",
5695                    "node-name": "test1",
5696                    "file": {
5697                        "driver": "file",
5698                        "filename": "test.qcow2"
5699                     }
5700                }
5701              }
5702          <- { "return": {} }
5703
5704          2.
5705          -> { "execute": "blockdev-add",
5706               "arguments": {
5707                    "driver": "qcow2",
5708                    "node-name": "node0",
5709                    "discard": "unmap",
5710                    "cache": {
5711                       "direct": true
5712                     },
5713                     "file": {
5714                       "driver": "file",
5715                       "filename": "/tmp/test.qcow2"
5716                     },
5717                     "backing": {
5718                        "driver": "raw",
5719                        "file": {
5720                           "driver": "file",
5721                           "filename": "/dev/fdset/4"
5722                         }
5723                     }
5724                 }
5725               }
5726
5727          <- { "return": {} }
5728
5729   x-blockdev-reopen (Command)
5730       Reopens a block device using the given set of options. Any  option  not
5731       specified will be reset to its default value regardless of its previous
5732       status. If an option cannot be changed or a particular driver does  not
5733       support reopening then the command will return an error.
5734
5735       The top-level node-name option (from BlockdevOptions) must be specified
5736       and is used to select the block device to be reopened.  Other node-name
5737       options must be either omitted or set to the current name of the appro‐
5738       priate node. This command won't change any node name and any attempt to
5739       do it will result in an error.
5740
5741       In  the case of options that refer to child nodes, the behavior of this
5742       command depends on the value:
5743
5744          1. A set of options (BlockdevOptions): the child  is  reopened  with
5745             the specified set of options.
5746
5747          2. A reference to the current child: the child is reopened using its
5748             existing set of options.
5749
5750          3. A reference to a different node: the current  child  is  replaced
5751             with the specified one.
5752
5753          4. NULL: the current child (if any) is detached.
5754
5755       Options  (1) and (2) are supported in all cases, but at the moment only
5756       backing allows replacing or detaching an existing child.
5757
5758       Unlike with blockdev-add, the backing option must always be present un‐
5759       less the node being reopened does not have a backing file and its image
5760       does not have a default backing file name as part of its metadata.
5761
5762   Arguments
5763       The members of BlockdevOptions
5764
5765   Since
5766       4.0
5767
5768   blockdev-del (Command)
5769       Deletes a block device that has been  added  using  blockdev-add.   The
5770       command  will  fail if the node is attached to a device or is otherwise
5771       being used.
5772
5773   Arguments
5774       node-name: string
5775              Name of the graph node to delete.
5776
5777   Since
5778       2.9
5779
5780   Example
5781          -> { "execute": "blockdev-add",
5782               "arguments": {
5783                    "driver": "qcow2",
5784                    "node-name": "node0",
5785                    "file": {
5786                        "driver": "file",
5787                        "filename": "test.qcow2"
5788                    }
5789               }
5790             }
5791          <- { "return": {} }
5792
5793          -> { "execute": "blockdev-del",
5794               "arguments": { "node-name": "node0" }
5795             }
5796          <- { "return": {} }
5797
5798   BlockdevCreateOptionsFile (Object)
5799       Driver specific image creation options for file.
5800
5801   Members
5802       filename: string
5803              Filename for the new image file
5804
5805       size: int
5806              Size of the virtual disk in bytes
5807
5808       preallocation: PreallocMode (optional)
5809              Preallocation mode for the new image (default: off; allowed val‐
5810              ues:  off,  falloc (if defined CONFIG_POSIX_FALLOCATE), full (if
5811              defined CONFIG_POSIX))
5812
5813       nocow: boolean (optional)
5814              Turn off copy-on-write (valid only on btrfs; default: off)
5815
5816       extent-size-hint: int (optional)
5817              Extent size hint to add to the image file; 0 for not  adding  an
5818              extent size hint (default: 1 MB, since 5.1)
5819
5820   Since
5821       2.12
5822
5823   BlockdevCreateOptionsGluster (Object)
5824       Driver specific image creation options for gluster.
5825
5826   Members
5827       location: BlockdevOptionsGluster
5828              Where to store the new image file
5829
5830       size: int
5831              Size of the virtual disk in bytes
5832
5833       preallocation: PreallocMode (optional)
5834              Preallocation mode for the new image (default: off; allowed val‐
5835              ues: off, falloc (if defined  CONFIG_GLUSTERFS_FALLOCATE),  full
5836              (if defined CONFIG_GLUSTERFS_ZEROFILL))
5837
5838   Since
5839       2.12
5840
5841   BlockdevCreateOptionsLUKS (Object)
5842       Driver specific image creation options for LUKS.
5843
5844   Members
5845       file: BlockdevRef
5846              Node to create the image format on
5847
5848       size: int
5849              Size of the virtual disk in bytes
5850
5851       preallocation: PreallocMode (optional)
5852              Preallocation mode for the new image (since: 4.2) (default: off;
5853              allowed values: off, metadata, falloc, full)
5854
5855       The members of QCryptoBlockCreateOptionsLUKS
5856
5857   Since
5858       2.12
5859
5860   BlockdevCreateOptionsNfs (Object)
5861       Driver specific image creation options for NFS.
5862
5863   Members
5864       location: BlockdevOptionsNfs
5865              Where to store the new image file
5866
5867       size: int
5868              Size of the virtual disk in bytes
5869
5870   Since
5871       2.12
5872
5873   BlockdevCreateOptionsParallels (Object)
5874       Driver specific image creation options for parallels.
5875
5876   Members
5877       file: BlockdevRef
5878              Node to create the image format on
5879
5880       size: int
5881              Size of the virtual disk in bytes
5882
5883       cluster-size: int (optional)
5884              Cluster size in bytes (default: 1 MB)
5885
5886   Since
5887       2.12
5888
5889   BlockdevCreateOptionsQcow (Object)
5890       Driver specific image creation options for qcow.
5891
5892   Members
5893       file: BlockdevRef
5894              Node to create the image format on
5895
5896       size: int
5897              Size of the virtual disk in bytes
5898
5899       backing-file: string (optional)
5900              File name of the backing file if a backing file should be used
5901
5902       encrypt: QCryptoBlockCreateOptions (optional)
5903              Encryption options if the image should be encrypted
5904
5905   Since
5906       2.12
5907
5908   BlockdevQcow2Version (Enum)
5909   Values
5910       v2     The original QCOW2 format as introduced in qemu 0.10 (version 2)
5911
5912       v3     The extended QCOW2 format as introduced in qemu 1.1 (version 3)
5913
5914   Since
5915       2.12
5916
5917   Qcow2CompressionType (Enum)
5918       Compression type used in qcow2 image file
5919
5920   Values
5921       zlib   zlib compression, see <http://zlib.net/>
5922
5923       zstd (If: defined(CONFIG_ZSTD))
5924              zstd compression, see <http://github.com/facebook/zstd>
5925
5926   Since
5927       5.1
5928
5929   BlockdevCreateOptionsQcow2 (Object)
5930       Driver specific image creation options for qcow2.
5931
5932   Members
5933       file: BlockdevRef
5934              Node to create the image format on
5935
5936       data-file: BlockdevRef (optional)
5937              Node to use as an external data file in which all guest data  is
5938              stored  so  that only metadata remains in the qcow2 file (since:
5939              4.0)
5940
5941       data-file-raw: boolean (optional)
5942              True if the external data file must stay valid as  a  standalone
5943              (read-only)  raw  image  without  looking at qcow2 metadata (de‐
5944              fault: false; since: 4.0)
5945
5946       extended-l2: boolean (optional)
5947              True to make the image have extended L2 entries (default: false;
5948              since 5.2)
5949
5950       size: int
5951              Size of the virtual disk in bytes
5952
5953       version: BlockdevQcow2Version (optional)
5954              Compatibility level (default: v3)
5955
5956       backing-file: string (optional)
5957              File name of the backing file if a backing file should be used
5958
5959       backing-fmt: BlockdevDriver (optional)
5960              Name of the block driver to use for the backing file
5961
5962       encrypt: QCryptoBlockCreateOptions (optional)
5963              Encryption options if the image should be encrypted
5964
5965       cluster-size: int (optional)
5966              qcow2 cluster size in bytes (default: 65536)
5967
5968       preallocation: PreallocMode (optional)
5969              Preallocation mode for the new image (default: off; allowed val‐
5970              ues: off, falloc, full, metadata)
5971
5972       lazy-refcounts: boolean (optional)
5973              True if refcounts may be updated lazily (default: off)
5974
5975       refcount-bits: int (optional)
5976              Width of reference counts in bits (default: 16)
5977
5978       compression-type: Qcow2CompressionType (optional)
5979              The image cluster compression method (default: zlib, since 5.1)
5980
5981   Since
5982       2.12
5983
5984   BlockdevCreateOptionsQed (Object)
5985       Driver specific image creation options for qed.
5986
5987   Members
5988       file: BlockdevRef
5989              Node to create the image format on
5990
5991       size: int
5992              Size of the virtual disk in bytes
5993
5994       backing-file: string (optional)
5995              File name of the backing file if a backing file should be used
5996
5997       backing-fmt: BlockdevDriver (optional)
5998              Name of the block driver to use for the backing file
5999
6000       cluster-size: int (optional)
6001              Cluster size in bytes (default: 65536)
6002
6003       table-size: int (optional)
6004              L1/L2 table size (in clusters)
6005
6006   Since
6007       2.12
6008
6009   BlockdevCreateOptionsRbd (Object)
6010       Driver specific image creation options for rbd/Ceph.
6011
6012   Members
6013       location: BlockdevOptionsRbd
6014              Where to store the new image file. This location cannot point to
6015              a snapshot.
6016
6017       size: int
6018              Size of the virtual disk in bytes
6019
6020       cluster-size: int (optional)
6021              RBD object size
6022
6023   Since
6024       2.12
6025
6026   BlockdevVmdkSubformat (Enum)
6027       Subformat options for VMDK images
6028
6029   Values
6030       monolithicSparse
6031              Single file image with sparse cluster allocation
6032
6033       monolithicFlat
6034              Single flat data image and a descriptor file
6035
6036       twoGbMaxExtentSparse
6037              Data is split into 2GB (per virtual LBA) sparse extent files, in
6038              addition to a descriptor file
6039
6040       twoGbMaxExtentFlat
6041              Data is split into 2GB (per virtual LBA) flat extent  files,  in
6042              addition to a descriptor file
6043
6044       streamOptimized
6045              Single  file  image  sparse  cluster  allocation,  optimized for
6046              streaming over network.
6047
6048   Since
6049       4.0
6050
6051   BlockdevVmdkAdapterType (Enum)
6052       Adapter type info for VMDK images
6053
6054   Values
6055       ide    Not documented
6056
6057       buslogic
6058              Not documented
6059
6060       lsilogic
6061              Not documented
6062
6063       legacyESX
6064              Not documented
6065
6066   Since
6067       4.0
6068
6069   BlockdevCreateOptionsVmdk (Object)
6070       Driver specific image creation options for VMDK.
6071
6072   Members
6073       file: BlockdevRef
6074              Where to store the new image file. This refers to the image file
6075              for  monolithcSparse and streamOptimized format, or the descrip‐
6076              tor file for other formats.
6077
6078       size: int
6079              Size of the virtual disk in bytes
6080
6081       extents: array of BlockdevRef (optional)
6082              Where to store the data  extents.  Required  for  monolithcFlat,
6083              twoGbMaxExtentSparse  and  twoGbMaxExtentFlat formats. For mono‐
6084              lithicFlat, only one entry is required; for twoGbMaxExtent* for‐
6085              mats,  the  number  of  entries  required  is  calculated as ex‐
6086              tent_number = virtual_size / 2GB. Providing  more  extents  than
6087              will be used is an error.
6088
6089       subformat: BlockdevVmdkSubformat (optional)
6090              The subformat of the VMDK image. Default: "monolithicSparse".
6091
6092       backing-file: string (optional)
6093              The path of backing file. Default: no backing file is used.
6094
6095       adapter-type: BlockdevVmdkAdapterType (optional)
6096              The adapter type used to fill in the descriptor. Default: ide.
6097
6098       hwversion: string (optional)
6099              Hardware  version.  The  meaningful options are "4" or "6".  De‐
6100              fault: "4".
6101
6102       zeroed-grain: boolean (optional)
6103              Whether to enable zeroed-grain feature  for  sparse  subformats.
6104              Default: false.
6105
6106   Since
6107       4.0
6108
6109   SheepdogRedundancyType (Enum)
6110   Values
6111       full   Create a fully replicated vdi with x copies
6112
6113       erasure-coded
6114              Create  an  erasure  coded  vdi  with x data strips and y parity
6115              strips
6116
6117   Since
6118       2.12
6119
6120   SheepdogRedundancyFull (Object)
6121   Members
6122       copies: int
6123              Number of copies to use (between 1 and 31)
6124
6125   Since
6126       2.12
6127
6128   SheepdogRedundancyErasureCoded (Object)
6129   Members
6130       data-strips: int
6131              Number of data strips to use (one of {2,4,8,16})
6132
6133       parity-strips: int
6134              Number of parity strips to use (between 1 and 15)
6135
6136   Since
6137       2.12
6138
6139   SheepdogRedundancy (Object)
6140   Members
6141       type: SheepdogRedundancyType
6142              Not documented
6143
6144       The members of SheepdogRedundancyFull when type is "full"
6145
6146       The  members  of  SheepdogRedundancyErasureCoded  when  type  is  "era‐
6147       sure-coded"
6148
6149   Since
6150       2.12
6151
6152   BlockdevCreateOptionsSheepdog (Object)
6153       Driver specific image creation options for Sheepdog.
6154
6155   Members
6156       location: BlockdevOptionsSheepdog
6157              Where to store the new image file
6158
6159       size: int
6160              Size of the virtual disk in bytes
6161
6162       backing-file: string (optional)
6163              File name of a base image
6164
6165       preallocation: PreallocMode (optional)
6166              Preallocation mode for the new image (default: off; allowed val‐
6167              ues: off, full)
6168
6169       redundancy: SheepdogRedundancy (optional)
6170              Redundancy of the image
6171
6172       object-size: int (optional)
6173              Object size of the image
6174
6175   Since
6176       2.12
6177
6178   BlockdevCreateOptionsSsh (Object)
6179       Driver specific image creation options for SSH.
6180
6181   Members
6182       location: BlockdevOptionsSsh
6183              Where to store the new image file
6184
6185       size: int
6186              Size of the virtual disk in bytes
6187
6188   Since
6189       2.12
6190
6191   BlockdevCreateOptionsVdi (Object)
6192       Driver specific image creation options for VDI.
6193
6194   Members
6195       file: BlockdevRef
6196              Node to create the image format on
6197
6198       size: int
6199              Size of the virtual disk in bytes
6200
6201       preallocation: PreallocMode (optional)
6202              Preallocation mode for the new image (default: off; allowed val‐
6203              ues: off, metadata)
6204
6205   Since
6206       2.12
6207
6208   BlockdevVhdxSubformat (Enum)
6209   Values
6210       dynamic
6211              Growing image file
6212
6213       fixed  Preallocated fixed-size image file
6214
6215   Since
6216       2.12
6217
6218   BlockdevCreateOptionsVhdx (Object)
6219       Driver specific image creation options for vhdx.
6220
6221   Members
6222       file: BlockdevRef
6223              Node to create the image format on
6224
6225       size: int
6226              Size of the virtual disk in bytes
6227
6228       log-size: int (optional)
6229              Log size in bytes, must be a multiple of 1 MB (default: 1 MB)
6230
6231       block-size: int (optional)
6232              Block  size  in bytes, must be a multiple of 1 MB and not larger
6233              than 256 MB (default: automatically choose a block size  depend‐
6234              ing on the image size)
6235
6236       subformat: BlockdevVhdxSubformat (optional)
6237              vhdx subformat (default: dynamic)
6238
6239       block-state-zero: boolean (optional)
6240              Force  use  of  payload blocks of type 'ZERO'. Non-standard, but
6241              default.  Do not set to 'off' when using 'qemu-img convert' with
6242              subformat=dynamic.
6243
6244   Since
6245       2.12
6246
6247   BlockdevVpcSubformat (Enum)
6248   Values
6249       dynamic
6250              Growing image file
6251
6252       fixed  Preallocated fixed-size image file
6253
6254   Since
6255       2.12
6256
6257   BlockdevCreateOptionsVpc (Object)
6258       Driver specific image creation options for vpc (VHD).
6259
6260   Members
6261       file: BlockdevRef
6262              Node to create the image format on
6263
6264       size: int
6265              Size of the virtual disk in bytes
6266
6267       subformat: BlockdevVpcSubformat (optional)
6268              vhdx subformat (default: dynamic)
6269
6270       force-size: boolean (optional)
6271              Force use of the exact byte size instead of rounding to the next
6272              size that can be represented in CHS geometry (default: false)
6273
6274   Since
6275       2.12
6276
6277   BlockdevCreateOptions (Object)
6278       Options for creating an image format on a given node.
6279
6280   Members
6281       driver: BlockdevDriver
6282              block driver to create the image format
6283
6284       The members of BlockdevCreateOptionsFile when driver is "file"
6285
6286       The members of BlockdevCreateOptionsGluster when driver is "gluster"
6287
6288       The members of BlockdevCreateOptionsLUKS when driver is "luks"
6289
6290       The members of BlockdevCreateOptionsNfs when driver is "nfs"
6291
6292       The members of BlockdevCreateOptionsParallels when  driver  is  "paral‐
6293       lels"
6294
6295       The members of BlockdevCreateOptionsQcow when driver is "qcow"
6296
6297       The members of BlockdevCreateOptionsQcow2 when driver is "qcow2"
6298
6299       The members of BlockdevCreateOptionsQed when driver is "qed"
6300
6301       The members of BlockdevCreateOptionsRbd when driver is "rbd"
6302
6303       The members of BlockdevCreateOptionsSheepdog when driver is "sheepdog"
6304
6305       The members of BlockdevCreateOptionsSsh when driver is "ssh"
6306
6307       The members of BlockdevCreateOptionsVdi when driver is "vdi"
6308
6309       The members of BlockdevCreateOptionsVhdx when driver is "vhdx"
6310
6311       The members of BlockdevCreateOptionsVmdk when driver is "vmdk"
6312
6313       The members of BlockdevCreateOptionsVpc when driver is "vpc"
6314
6315   Since
6316       2.12
6317
6318   blockdev-create (Command)
6319       Starts  a job to create an image format on a given node. The job is au‐
6320       tomatically finalized, but a manual job-dismiss is required.
6321
6322   Arguments
6323       job-id: string
6324              Identifier for the newly created job.
6325
6326       options: BlockdevCreateOptions
6327              Options for the image creation.
6328
6329   Since
6330       3.0
6331
6332   BlockdevAmendOptionsLUKS (Object)
6333       Driver specific image amend options for LUKS.
6334
6335   Members
6336       The members of QCryptoBlockAmendOptionsLUKS
6337
6338   Since
6339       5.1
6340
6341   BlockdevAmendOptionsQcow2 (Object)
6342       Driver specific image amend options for qcow2.  For now,  only  encryp‐
6343       tion options can be amended
6344
6345       encrypt          Encryption options to be amended
6346
6347   Members
6348       encrypt: QCryptoBlockAmendOptions (optional)
6349              Not documented
6350
6351   Since
6352       5.1
6353
6354   BlockdevAmendOptions (Object)
6355       Options for amending an image format
6356
6357   Members
6358       driver: BlockdevDriver
6359              Block driver of the node to amend.
6360
6361       The members of BlockdevAmendOptionsLUKS when driver is "luks"
6362
6363       The members of BlockdevAmendOptionsQcow2 when driver is "qcow2"
6364
6365   Since
6366       5.1
6367
6368   x-blockdev-amend (Command)
6369       Starts a job to amend format specific options of an existing open block
6370       device The job is automatically finalized, but a manual job-dismiss  is
6371       required.
6372
6373   Arguments
6374       job-id: string
6375              Identifier for the newly created job.
6376
6377       node-name: string
6378              Name of the block node to work on
6379
6380       options: BlockdevAmendOptions
6381              Options (driver specific)
6382
6383       force: boolean (optional)
6384              Allow  unsafe  operations,  format specific For luks that allows
6385              erase of the last active keyslot (permanent loss of  data),  and
6386              replacement  of  an  active keyslot (possible loss of data if IO
6387              error happens)
6388
6389   Since
6390       5.1
6391
6392   BlockErrorAction (Enum)
6393       An enumeration of action that has been taken when a DISK I/O occurs
6394
6395   Values
6396       ignore error has been ignored
6397
6398       report error has been reported to the device
6399
6400       stop   error caused VM to be stopped
6401
6402   Since
6403       2.1
6404
6405   BLOCK_IMAGE_CORRUPTED (Event)
6406       Emitted when a disk image is being marked corrupt.  The  image  can  be
6407       identified  by  its  device  or node name. The 'device' field is always
6408       present for compatibility reasons, but it can be empty ("") if the  im‐
6409       age does not have a device name associated.
6410
6411   Arguments
6412       device: string
6413              device  name.  This is always present for compatibility reasons,
6414              but it can be empty ("") if the image does  not  have  a  device
6415              name associated.
6416
6417       node-name: string (optional)
6418              node name (Since: 2.4)
6419
6420       msg: string
6421              informative  message  for human consumption, such as the kind of
6422              corruption being detected. It should not be parsed by machine as
6423              it is not guaranteed to be stable
6424
6425       offset: int (optional)
6426              if  the  corruption  resulted  from an image access, this is the
6427              host's access offset into the image
6428
6429       size: int (optional)
6430              if the corruption resulted from an image access, this is the ac‐
6431              cess size
6432
6433       fatal: boolean
6434              if set, the image is marked corrupt and therefore unusable after
6435              this event and  must  be  repaired  (Since  2.2;  before,  every
6436              BLOCK_IMAGE_CORRUPTED event was fatal)
6437
6438   Note
6439       If   action  is  "stop",  a  STOP  event  will  eventually  follow  the
6440       BLOCK_IO_ERROR event.
6441
6442   Example
6443          <- { "event": "BLOCK_IMAGE_CORRUPTED",
6444               "data": { "device": "ide0-hd0", "node-name": "node0",
6445                         "msg": "Prevented active L1 table overwrite", "offset": 196608,
6446                         "size": 65536 },
6447               "timestamp": { "seconds": 1378126126, "microseconds": 966463 } }
6448
6449   Since
6450       1.7
6451
6452   BLOCK_IO_ERROR (Event)
6453       Emitted when a disk I/O error occurs
6454
6455   Arguments
6456       device: string
6457              device name. This is always present for  compatibility  reasons,
6458              but  it  can  be  empty ("") if the image does not have a device
6459              name associated.
6460
6461       node-name: string (optional)
6462              node name. Note that errors may be reported for  the  root  node
6463              that  is directly attached to a guest device rather than for the
6464              node where the error occurred. The node name is not  present  if
6465              the drive is empty. (Since: 2.8)
6466
6467       operation: IoOperationType
6468              I/O operation
6469
6470       action: BlockErrorAction
6471              action that has been taken
6472
6473       nospace: boolean (optional)
6474              true  if  I/O error was caused due to a no-space condition. This
6475              key is only  present  if  query-block's  io-status  is  present,
6476              please   see  query-block  documentation  for  more  information
6477              (since: 2.2)
6478
6479       reason: string
6480              human readable string describing the error cause.   (This  field
6481              is a debugging aid for humans, it should not be parsed by appli‐
6482              cations) (since: 2.2)
6483
6484   Note
6485       If  action  is  "stop",  a  STOP  event  will  eventually  follow   the
6486       BLOCK_IO_ERROR event
6487
6488   Since
6489       0.13.0
6490
6491   Example
6492          <- { "event": "BLOCK_IO_ERROR",
6493               "data": { "device": "ide0-hd1",
6494                         "node-name": "#block212",
6495                         "operation": "write",
6496                         "action": "stop" },
6497               "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
6498
6499   BLOCK_JOB_COMPLETED (Event)
6500       Emitted when a block job has completed
6501
6502   Arguments
6503       type: JobType
6504              job type
6505
6506       device: string
6507              The  job identifier. Originally the device name but other values
6508              are allowed since QEMU 2.7
6509
6510       len: int
6511              maximum progress value
6512
6513       offset: int
6514              current progress value. On success this is  equal  to  len.   On
6515              failure this is less than len
6516
6517       speed: int
6518              rate limit, bytes per second
6519
6520       error: string (optional)
6521              error  message.  Only  present on failure. This field contains a
6522              human-readable error message. There are no semantics other  than
6523              that  streaming  has failed and clients should not try to inter‐
6524              pret the error string
6525
6526   Since
6527       1.1
6528
6529   Example
6530          <- { "event": "BLOCK_JOB_COMPLETED",
6531               "data": { "type": "stream", "device": "virtio-disk0",
6532                         "len": 10737418240, "offset": 10737418240,
6533                         "speed": 0 },
6534               "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
6535
6536   BLOCK_JOB_CANCELLED (Event)
6537       Emitted when a block job has been cancelled
6538
6539   Arguments
6540       type: JobType
6541              job type
6542
6543       device: string
6544              The job identifier. Originally the device name but other  values
6545              are allowed since QEMU 2.7
6546
6547       len: int
6548              maximum progress value
6549
6550       offset: int
6551              current  progress  value.  On  success this is equal to len.  On
6552              failure this is less than len
6553
6554       speed: int
6555              rate limit, bytes per second
6556
6557   Since
6558       1.1
6559
6560   Example
6561          <- { "event": "BLOCK_JOB_CANCELLED",
6562               "data": { "type": "stream", "device": "virtio-disk0",
6563                         "len": 10737418240, "offset": 134217728,
6564                         "speed": 0 },
6565               "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
6566
6567   BLOCK_JOB_ERROR (Event)
6568       Emitted when a block job encounters an error
6569
6570   Arguments
6571       device: string
6572              The job identifier. Originally the device name but other  values
6573              are allowed since QEMU 2.7
6574
6575       operation: IoOperationType
6576              I/O operation
6577
6578       action: BlockErrorAction
6579              action that has been taken
6580
6581   Since
6582       1.3
6583
6584   Example
6585          <- { "event": "BLOCK_JOB_ERROR",
6586               "data": { "device": "ide0-hd1",
6587                         "operation": "write",
6588                         "action": "stop" },
6589               "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
6590
6591   BLOCK_JOB_READY (Event)
6592       Emitted when a block job is ready to complete
6593
6594   Arguments
6595       type: JobType
6596              job type
6597
6598       device: string
6599              The  job identifier. Originally the device name but other values
6600              are allowed since QEMU 2.7
6601
6602       len: int
6603              maximum progress value
6604
6605       offset: int
6606              current progress value. On success this is  equal  to  len.   On
6607              failure this is less than len
6608
6609       speed: int
6610              rate limit, bytes per second
6611
6612   Note
6613       The  "ready  to  complete"  status is always reset by a BLOCK_JOB_ERROR
6614       event
6615
6616   Since
6617       1.3
6618
6619   Example
6620          <- { "event": "BLOCK_JOB_READY",
6621               "data": { "device": "drive0", "type": "mirror", "speed": 0,
6622                         "len": 2097152, "offset": 2097152 }
6623               "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
6624
6625   BLOCK_JOB_PENDING (Event)
6626       Emitted when a block job is awaiting explicit authorization to finalize
6627       graph changes via block-job-finalize. If this job is part of a transac‐
6628       tion, it will not emit this event until the transaction  has  converged
6629       first.
6630
6631   Arguments
6632       type: JobType
6633              job type
6634
6635       id: string
6636              The job identifier.
6637
6638   Since
6639       2.12
6640
6641   Example
6642          <- { "event": "BLOCK_JOB_WAITING",
6643               "data": { "device": "drive0", "type": "mirror" },
6644               "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
6645
6646   PreallocMode (Enum)
6647       Preallocation mode of QEMU image file
6648
6649   Values
6650       off    no preallocation
6651
6652       metadata
6653              preallocate only for metadata
6654
6655       falloc like  full preallocation but allocate disk space by posix_fallo‐
6656              cate() rather than writing data.
6657
6658       full   preallocate all data by writing it to the device to ensure  disk
6659              space is really available. This data may or may not be zero, de‐
6660              pending on the image format  and  storage.   full  preallocation
6661              also sets up metadata correctly.
6662
6663   Since
6664       2.2
6665
6666   BLOCK_WRITE_THRESHOLD (Event)
6667       Emitted  when  writes on block device reaches or exceeds the configured
6668       write threshold. For thin-provisioned devices, this  means  the  device
6669       should  be extended to avoid pausing for disk exhaustion.  The event is
6670       one shot. Once triggered, it needs to  be  re-registered  with  another
6671       block-set-write-threshold command.
6672
6673   Arguments
6674       node-name: string
6675              graph node name on which the threshold was exceeded.
6676
6677       amount-exceeded: int
6678              amount of data which exceeded the threshold, in bytes.
6679
6680       write-threshold: int
6681              last configured threshold, in bytes.
6682
6683   Since
6684       2.3
6685
6686   block-set-write-threshold (Command)
6687       Change  the  write threshold for a block drive. An event will be deliv‐
6688       ered if a write to this block drive crosses the  configured  threshold.
6689       The  threshold  is  an offset, thus must be non-negative. Default is no
6690       write threshold. Setting the threshold to zero disables it.
6691
6692       This is useful to transparently resize thin-provisioned drives  without
6693       the guest OS noticing.
6694
6695   Arguments
6696       node-name: string
6697              graph node name on which the threshold must be set.
6698
6699       write-threshold: int
6700              configured threshold for the block device, bytes.  Use 0 to dis‐
6701              able the threshold.
6702
6703   Since
6704       2.3
6705
6706   Example
6707          -> { "execute": "block-set-write-threshold",
6708               "arguments": { "node-name": "mydev",
6709                              "write-threshold": 17179869184 } }
6710          <- { "return": {} }
6711
6712   x-blockdev-change (Command)
6713       Dynamically reconfigure the block driver state graph. It can be used to
6714       add,  remove, insert or replace a graph node. Currently only the Quorum
6715       driver implements this feature to add or remove its child. This is use‐
6716       ful to fix a broken quorum child.
6717
6718       If  node  is specified, it will be inserted under parent. child may not
6719       be specified in this case. If both parent and child are  specified  but
6720       node is not, child will be detached from parent.
6721
6722   Arguments
6723       parent: string
6724              the id or name of the parent node.
6725
6726       child: string (optional)
6727              the name of a child under the given parent node.
6728
6729       node: string (optional)
6730              the name of the node that will be added.
6731
6732   Note
6733       this  command  is  experimental, and its API is not stable. It does not
6734       support all kinds of operations, all kinds of children, nor  all  block
6735       drivers.
6736
6737       FIXME  Removing  children  from a quorum node means introducing gaps in
6738       the child indices. This cannot be represented in the 'children' list of
6739       BlockdevOptionsQuorum, as returned by .bdrv_refresh_filename().
6740
6741       Warning: The data in a new quorum child MUST be consistent with that of
6742       the rest of the array.
6743
6744   Since
6745       2.7
6746
6747   Example
6748          1. Add a new node to a quorum
6749          -> { "execute": "blockdev-add",
6750               "arguments": {
6751                   "driver": "raw",
6752                   "node-name": "new_node",
6753                   "file": { "driver": "file",
6754                             "filename": "test.raw" } } }
6755          <- { "return": {} }
6756          -> { "execute": "x-blockdev-change",
6757               "arguments": { "parent": "disk1",
6758                              "node": "new_node" } }
6759          <- { "return": {} }
6760
6761          2. Delete a quorum's node
6762          -> { "execute": "x-blockdev-change",
6763               "arguments": { "parent": "disk1",
6764                              "child": "children.1" } }
6765          <- { "return": {} }
6766
6767   x-blockdev-set-iothread (Command)
6768       Move node and its children into the iothread.  If iothread is null then
6769       move node and its children into the main loop.
6770
6771       The node must not be attached to a BlockBackend.
6772
6773   Arguments
6774       node-name: string
6775              the name of the block driver node
6776
6777       iothread: StrOrNull
6778              the name of the IOThread object or null for the main loop
6779
6780       force: boolean (optional)
6781              true  if the node and its children should be moved when a Block‐
6782              Backend is already attached
6783
6784   Note
6785       this command is experimental and intended for test cases that need con‐
6786       trol over IOThreads only.
6787
6788   Since
6789       2.12
6790
6791   Example
6792          1. Move a node into an IOThread
6793          -> { "execute": "x-blockdev-set-iothread",
6794               "arguments": { "node-name": "disk1",
6795                              "iothread": "iothread0" } }
6796          <- { "return": {} }
6797
6798          2. Move a node into the main loop
6799          -> { "execute": "x-blockdev-set-iothread",
6800               "arguments": { "node-name": "disk1",
6801                              "iothread": null } }
6802          <- { "return": {} }
6803
6804   QuorumOpType (Enum)
6805       An enumeration of the quorum operation types
6806
6807   Values
6808       read   read operation
6809
6810       write  write operation
6811
6812       flush  flush operation
6813
6814   Since
6815       2.6
6816
6817   QUORUM_FAILURE (Event)
6818       Emitted by the Quorum block driver if it fails to establish a quorum
6819
6820   Arguments
6821       reference: string
6822              device name if defined else node name
6823
6824       sector-num: int
6825              number of the first sector of the failed read operation
6826
6827       sectors-count: int
6828              failed read operation sector count
6829
6830   Note
6831       This event is rate-limited.
6832
6833   Since
6834       2.0
6835
6836   Example
6837          <- { "event": "QUORUM_FAILURE",
6838               "data": { "reference": "usr1", "sector-num": 345435, "sectors-count": 5 },
6839               "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
6840
6841   QUORUM_REPORT_BAD (Event)
6842       Emitted to report a corruption of a Quorum file
6843
6844   Arguments
6845       type: QuorumOpType
6846              quorum operation type (Since 2.6)
6847
6848       error: string (optional)
6849              error  message.  Only  present on failure. This field contains a
6850              human-readable error message. There are no semantics other  than
6851              that  the  block  layer reported an error and clients should not
6852              try to interpret the error string.
6853
6854       node-name: string
6855              the graph node name of the block driver state
6856
6857       sector-num: int
6858              number of the first sector of the failed read operation
6859
6860       sectors-count: int
6861              failed read operation sector count
6862
6863   Note
6864       This event is rate-limited.
6865
6866   Since
6867       2.0
6868
6869   Example
6870          1. Read operation
6871
6872          { "event": "QUORUM_REPORT_BAD",
6873               "data": { "node-name": "node0", "sector-num": 345435, "sectors-count": 5,
6874                         "type": "read" },
6875               "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
6876
6877          2. Flush operation
6878
6879          { "event": "QUORUM_REPORT_BAD",
6880               "data": { "node-name": "node0", "sector-num": 0, "sectors-count": 2097120,
6881                         "type": "flush", "error": "Broken pipe" },
6882               "timestamp": { "seconds": 1456406829, "microseconds": 291763 } }
6883
6884   BlockdevSnapshotInternal (Object)
6885   Members
6886       device: string
6887              the device name or node-name of a  root  node  to  generate  the
6888              snapshot from
6889
6890       name: string
6891              the name of the internal snapshot to be created
6892
6893   Notes
6894       In transaction, if name is empty, or any snapshot matching name exists,
6895       the operation will fail. Only some image formats support it, for  exam‐
6896       ple, qcow2, rbd, and sheepdog.
6897
6898   Since
6899       1.7
6900
6901   blockdev-snapshot-internal-sync (Command)
6902       Synchronously  take  an  internal  snapshot of a block device, when the
6903       format of the image used supports it. If the name is an  empty  string,
6904       or a snapshot with name already exists, the operation will fail.
6905
6906       For the arguments, see the documentation of BlockdevSnapshotInternal.
6907
6908   Returns
6909       • nothing on success
6910
6911       • If device is not a valid block device, GenericError
6912
6913       • If any snapshot matching name exists, or name is empty, GenericError
6914
6915       • If  the format of the image used does not support it, BlockFormatFea‐
6916         tureNotSupported
6917
6918   Since
6919       1.7
6920
6921   Example
6922          -> { "execute": "blockdev-snapshot-internal-sync",
6923               "arguments": { "device": "ide-hd0",
6924                              "name": "snapshot0" }
6925             }
6926          <- { "return": {} }
6927
6928   blockdev-snapshot-delete-internal-sync (Command)
6929       Synchronously delete an internal snapshot of a block device,  when  the
6930       format of the image used support it. The snapshot is identified by name
6931       or id or both. One of the name or id is required.  Return  SnapshotInfo
6932       for the successfully deleted snapshot.
6933
6934   Arguments
6935       device: string
6936              the  device name or node-name of a root node to delete the snap‐
6937              shot from
6938
6939       id: string (optional)
6940              optional the snapshot's ID to be deleted
6941
6942       name: string (optional)
6943              optional the snapshot's name to be deleted
6944
6945   Returns
6946       • SnapshotInfo on success
6947
6948       • If device is not a valid block device, GenericError
6949
6950       • If snapshot not found, GenericError
6951
6952       • If the format of the image used does not support it,  BlockFormatFea‐
6953         tureNotSupported
6954
6955       • If id and name are both not specified, GenericError
6956
6957   Since
6958       1.7
6959
6960   Example
6961          -> { "execute": "blockdev-snapshot-delete-internal-sync",
6962               "arguments": { "device": "ide-hd0",
6963                              "name": "snapshot0" }
6964             }
6965          <- { "return": {
6966                             "id": "1",
6967                             "name": "snapshot0",
6968                             "vm-state-size": 0,
6969                             "date-sec": 1000012,
6970                             "date-nsec": 10,
6971                             "vm-clock-sec": 100,
6972                             "vm-clock-nsec": 20,
6973                             "icount": 220414
6974               }
6975             }
6976
6977   Additional block stuff (VM related)
6978   BiosAtaTranslation (Enum)
6979       Policy  that  BIOS  should  use  to  interpret cylinder/head/sector ad‐
6980       dresses.  Note that Bochs BIOS and SeaBIOS will not actually  translate
6981       logical  CHS to physical; instead, they will use logical block address‐
6982       ing.
6983
6984   Values
6985       auto   If cylinder/heads/sizes are passed, choose between none and  LBA
6986              depending  on  the  size  of  the disk.  If they are not passed,
6987              choose none if QEMU can guess that the  disk  had  16  or  fewer
6988              heads, large if QEMU can guess that the disk had 131072 or fewer
6989              tracks across all heads (i.e. cylinders*heads<131072), otherwise
6990              LBA.
6991
6992       none   The physical disk geometry is equal to the logical geometry.
6993
6994       lba    Assume  63  sectors  per track and one of 16, 32, 64, 128 or 255
6995              heads (if fewer than 255 are enough to cover the whole disk with
6996              1024 cylinders/head).  The number of cylinders/head is then com‐
6997              puted based on the number of sectors and heads.
6998
6999       large  The number of cylinders per head is scaled down to 1024 by  cor‐
7000              respondingly scaling up the number of heads.
7001
7002       rechs  Same  as large, but first convert a 16-head geometry to 15-head,
7003              by proportionally scaling up the number of cylinders/head.
7004
7005   Since
7006       2.0
7007
7008   FloppyDriveType (Enum)
7009       Type of Floppy drive to be emulated by the Floppy Disk Controller.
7010
7011   Values
7012       144    1.44MB 3.5" drive
7013
7014       288    2.88MB 3.5" drive
7015
7016       120    1.2MB 5.25" drive
7017
7018       none   No drive connected
7019
7020       auto   Automatically determined by inserted media at boot
7021
7022   Since
7023       2.6
7024
7025   PRManagerInfo (Object)
7026       Information about a persistent reservation manager
7027
7028   Members
7029       id: string
7030              the identifier of the persistent reservation manager
7031
7032       connected: boolean
7033              true if the persistent reservation manager is connected  to  the
7034              underlying storage or helper
7035
7036   Since
7037       3.0
7038
7039   query-pr-managers (Command)
7040       Returns  a  list  of information about each persistent reservation man‐
7041       ager.
7042
7043   Returns
7044       a list of PRManagerInfo for each persistent reservation manager
7045
7046   Since
7047       3.0
7048
7049   eject (Command)
7050       Ejects the medium from a removable drive.
7051
7052   Arguments
7053       device: string (optional)
7054              Block device name
7055
7056       id: string (optional)
7057              The name or QOM path of the guest device (since: 2.8)
7058
7059       force: boolean (optional)
7060              If true, eject regardless of whether the drive  is  locked.   If
7061              not specified, the default value is false.
7062
7063   Features
7064       deprecated
7065              Member device is deprecated.  Use id instead.
7066
7067   Returns
7068       • Nothing on success
7069
7070       • If device is not a valid block device, DeviceNotFound
7071
7072   Notes
7073       Ejecting a device with no media results in success
7074
7075   Since
7076       0.14.0
7077
7078   Example
7079          -> { "execute": "eject", "arguments": { "id": "ide1-0-1" } }
7080          <- { "return": {} }
7081
7082   blockdev-open-tray (Command)
7083       Opens  a block device's tray. If there is a block driver state tree in‐
7084       serted as a medium, it will become inaccessible to the  guest  (but  it
7085       will  remain  associated  to the block device, so closing the tray will
7086       make it accessible again).
7087
7088       If the tray was already open before, this will be a no-op.
7089
7090       Once the tray opens, a DEVICE_TRAY_MOVED event is  emitted.  There  are
7091       cases in which no such event will be generated, these include:
7092
7093       • if  the  guest has locked the tray, force is false and the guest does
7094         not respond to the eject request
7095
7096       • if the BlockBackend denoted by device does not have  a  guest  device
7097         attached to it
7098
7099       • if the guest device does not have an actual tray
7100
7101   Arguments
7102       device: string (optional)
7103              Block device name
7104
7105       id: string (optional)
7106              The name or QOM path of the guest device (since: 2.8)
7107
7108       force: boolean (optional)
7109              if  false  (the  default),  an eject request will be sent to the
7110              guest if it has locked the tray (and the tray will not be opened
7111              immediately);  if  true,  the  tray will be opened regardless of
7112              whether it is locked
7113
7114   Features
7115       deprecated
7116              Member device is deprecated.  Use id instead.
7117
7118   Since
7119       2.5
7120
7121   Example
7122          -> { "execute": "blockdev-open-tray",
7123               "arguments": { "id": "ide0-1-0" } }
7124
7125          <- { "timestamp": { "seconds": 1418751016,
7126                              "microseconds": 716996 },
7127               "event": "DEVICE_TRAY_MOVED",
7128               "data": { "device": "ide1-cd0",
7129                         "id": "ide0-1-0",
7130                         "tray-open": true } }
7131
7132          <- { "return": {} }
7133
7134   blockdev-close-tray (Command)
7135       Closes a block device's tray. If there is a block driver state tree as‐
7136       sociated  with the block device (which is currently ejected), that tree
7137       will be loaded as the medium.
7138
7139       If the tray was already closed before, this will be a no-op.
7140
7141   Arguments
7142       device: string (optional)
7143              Block device name
7144
7145       id: string (optional)
7146              The name or QOM path of the guest device (since: 2.8)
7147
7148   Features
7149       deprecated
7150              Member device is deprecated.  Use id instead.
7151
7152   Since
7153       2.5
7154
7155   Example
7156          -> { "execute": "blockdev-close-tray",
7157               "arguments": { "id": "ide0-1-0" } }
7158
7159          <- { "timestamp": { "seconds": 1418751345,
7160                              "microseconds": 272147 },
7161               "event": "DEVICE_TRAY_MOVED",
7162               "data": { "device": "ide1-cd0",
7163                         "id": "ide0-1-0",
7164                         "tray-open": false } }
7165
7166          <- { "return": {} }
7167
7168   blockdev-remove-medium (Command)
7169       Removes a medium (a block driver state tree) from a block device.  That
7170       block device's tray must currently be open (unless there is no attached
7171       guest device).
7172
7173       If the tray is open and there is no medium inserted,  this  will  be  a
7174       no-op.
7175
7176   Arguments
7177       id: string
7178              The name or QOM path of the guest device
7179
7180   Since
7181       2.12
7182
7183   Example
7184          -> { "execute": "blockdev-remove-medium",
7185               "arguments": { "id": "ide0-1-0" } }
7186
7187          <- { "error": { "class": "GenericError",
7188                          "desc": "Tray of device 'ide0-1-0' is not open" } }
7189
7190          -> { "execute": "blockdev-open-tray",
7191               "arguments": { "id": "ide0-1-0" } }
7192
7193          <- { "timestamp": { "seconds": 1418751627,
7194                              "microseconds": 549958 },
7195               "event": "DEVICE_TRAY_MOVED",
7196               "data": { "device": "ide1-cd0",
7197                         "id": "ide0-1-0",
7198                         "tray-open": true } }
7199
7200          <- { "return": {} }
7201
7202          -> { "execute": "blockdev-remove-medium",
7203               "arguments": { "id": "ide0-1-0" } }
7204
7205          <- { "return": {} }
7206
7207   blockdev-insert-medium (Command)
7208       Inserts  a medium (a block driver state tree) into a block device. That
7209       block device's tray must currently be open (unless there is no attached
7210       guest device) and there must be no medium inserted already.
7211
7212   Arguments
7213       id: string
7214              The name or QOM path of the guest device
7215
7216       node-name: string
7217              name of a node in the block driver state graph
7218
7219   Since
7220       2.12
7221
7222   Example
7223          -> { "execute": "blockdev-add",
7224               "arguments": {
7225                   "node-name": "node0",
7226                   "driver": "raw",
7227                   "file": { "driver": "file",
7228                             "filename": "fedora.iso" } } }
7229          <- { "return": {} }
7230
7231          -> { "execute": "blockdev-insert-medium",
7232               "arguments": { "id": "ide0-1-0",
7233                              "node-name": "node0" } }
7234
7235          <- { "return": {} }
7236
7237   BlockdevChangeReadOnlyMode (Enum)
7238       Specifies  the  new  read-only  mode  of  a block device subject to the
7239       blockdev-change-medium command.
7240
7241   Values
7242       retain Retains the current read-only mode
7243
7244       read-only
7245              Makes the device read-only
7246
7247       read-write
7248              Makes the device writable
7249
7250   Since
7251       2.3
7252
7253   blockdev-change-medium (Command)
7254       Changes the medium inserted into a block device by ejecting the current
7255       medium and loading a new image file which is inserted as the new medium
7256       (this  command  combines  blockdev-open-tray,   blockdev-remove-medium,
7257       blockdev-insert-medium and blockdev-close-tray).
7258
7259   Arguments
7260       device: string (optional)
7261              Block device name
7262
7263       id: string (optional)
7264              The name or QOM path of the guest device (since: 2.8)
7265
7266       filename: string
7267              filename of the new image to be loaded
7268
7269       format: string (optional)
7270              format  to  open the new image with (defaults to the probed for‐
7271              mat)
7272
7273       read-only-mode: BlockdevChangeReadOnlyMode (optional)
7274              change the read-only mode of the device; defaults to 'retain'
7275
7276   Features
7277       deprecated
7278              Member device is deprecated.  Use id instead.
7279
7280   Since
7281       2.5
7282
7283   Examples
7284          1. Change a removable medium
7285
7286          -> { "execute": "blockdev-change-medium",
7287               "arguments": { "id": "ide0-1-0",
7288                              "filename": "/srv/images/Fedora-12-x86_64-DVD.iso",
7289                              "format": "raw" } }
7290          <- { "return": {} }
7291
7292          2. Load a read-only medium into a writable drive
7293
7294          -> { "execute": "blockdev-change-medium",
7295               "arguments": { "id": "floppyA",
7296                              "filename": "/srv/images/ro.img",
7297                              "format": "raw",
7298                              "read-only-mode": "retain" } }
7299
7300          <- { "error":
7301               { "class": "GenericError",
7302                 "desc": "Could not open '/srv/images/ro.img': Permission denied" } }
7303
7304          -> { "execute": "blockdev-change-medium",
7305               "arguments": { "id": "floppyA",
7306                              "filename": "/srv/images/ro.img",
7307                              "format": "raw",
7308                              "read-only-mode": "read-only" } }
7309
7310          <- { "return": {} }
7311
7312   DEVICE_TRAY_MOVED (Event)
7313       Emitted whenever the tray of a removable device is moved by  the  guest
7314       or by HMP/QMP commands
7315
7316   Arguments
7317       device: string
7318              Block device name. This is always present for compatibility rea‐
7319              sons, but it can be empty ("") if the image does not have a  de‐
7320              vice name associated.
7321
7322       id: string
7323              The name or QOM path of the guest device (since 2.8)
7324
7325       tray-open: boolean
7326              true if the tray has been opened or false if it has been closed
7327
7328   Since
7329       1.1
7330
7331   Example
7332          <- { "event": "DEVICE_TRAY_MOVED",
7333               "data": { "device": "ide1-cd0",
7334                         "id": "/machine/unattached/device[22]",
7335                         "tray-open": true
7336               },
7337               "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
7338
7339   PR_MANAGER_STATUS_CHANGED (Event)
7340       Emitted  whenever the connected status of a persistent reservation man‐
7341       ager changes.
7342
7343   Arguments
7344       id: string
7345              The id of the PR manager object
7346
7347       connected: boolean
7348              true if the PR manager is connected to a backend
7349
7350   Since
7351       3.0
7352
7353   Example
7354          <- { "event": "PR_MANAGER_STATUS_CHANGED",
7355               "data": { "id": "pr-helper0",
7356                         "connected": true
7357               },
7358               "timestamp": { "seconds": 1519840375, "microseconds": 450486 } }
7359
7360   block_set_io_throttle (Command)
7361       Change I/O throttle limits for a block drive.
7362
7363       Since QEMU 2.4, each device with I/O limits is  member  of  a  throttle
7364       group.
7365
7366       If  two  or more devices are members of the same group, the limits will
7367       apply to the combined I/O of the whole group in a round-robin  fashion.
7368       Therefore,  setting  new  I/O  limits to a device will affect the whole
7369       group.
7370
7371       The name of the group can be specified using the 'group' parameter.  If
7372       the  parameter  is unset, it is assumed to be the current group of that
7373       device. If it's not in any group yet, the name of the  device  will  be
7374       used as the name for its group.
7375
7376       The  'group' parameter can also be used to move a device to a different
7377       group. In this case the limits specified in the parameters will be  ap‐
7378       plied to the new group only.
7379
7380       I/O  limits  can  be disabled by setting all of them to 0. In this case
7381       the device will be removed from its group and the rest of  its  members
7382       will not be affected. The 'group' parameter is ignored.
7383
7384   Arguments
7385       The members of BlockIOThrottle
7386
7387   Returns
7388       • Nothing on success
7389
7390       • If device is not a valid block device, DeviceNotFound
7391
7392   Since
7393       1.1
7394
7395   Example
7396          -> { "execute": "block_set_io_throttle",
7397               "arguments": { "id": "virtio-blk-pci0/virtio-backend",
7398                              "bps": 0,
7399                              "bps_rd": 0,
7400                              "bps_wr": 0,
7401                              "iops": 512,
7402                              "iops_rd": 0,
7403                              "iops_wr": 0,
7404                              "bps_max": 0,
7405                              "bps_rd_max": 0,
7406                              "bps_wr_max": 0,
7407                              "iops_max": 0,
7408                              "iops_rd_max": 0,
7409                              "iops_wr_max": 0,
7410                              "bps_max_length": 0,
7411                              "iops_size": 0 } }
7412          <- { "return": {} }
7413
7414          -> { "execute": "block_set_io_throttle",
7415               "arguments": { "id": "ide0-1-0",
7416                              "bps": 1000000,
7417                              "bps_rd": 0,
7418                              "bps_wr": 0,
7419                              "iops": 0,
7420                              "iops_rd": 0,
7421                              "iops_wr": 0,
7422                              "bps_max": 8000000,
7423                              "bps_rd_max": 0,
7424                              "bps_wr_max": 0,
7425                              "iops_max": 0,
7426                              "iops_rd_max": 0,
7427                              "iops_wr_max": 0,
7428                              "bps_max_length": 60,
7429                              "iops_size": 0 } }
7430          <- { "return": {} }
7431
7432   block-latency-histogram-set (Command)
7433       Manage read, write and flush latency histograms for the device.
7434
7435       If  only  id  parameter  is  specified, remove all present latency his‐
7436       tograms for the device. Otherwise, add/reset some of (or  all)  latency
7437       histograms.
7438
7439   Arguments
7440       id: string
7441              The name or QOM path of the guest device.
7442
7443       boundaries: array of int (optional)
7444              list of interval boundary values (see description in BlockLaten‐
7445              cyHistogramInfo definition).  If  specified,  all  latency  his‐
7446              tograms  are  removed,  and  empty ones created for all io types
7447              with intervals corresponding to boundaries (except for io types,
7448              for  which specific boundaries are set through the following pa‐
7449              rameters).
7450
7451       boundaries-read: array of int (optional)
7452              list of interval boundary values for read latency histogram.  If
7453              specified,  old read latency histogram is removed, and empty one
7454              created with intervals corresponding to boundaries-read. The pa‐
7455              rameter has higher priority then boundaries.
7456
7457       boundaries-write: array of int (optional)
7458              list of interval boundary values for write latency histogram.
7459
7460       boundaries-flush: array of int (optional)
7461              list of interval boundary values for flush latency histogram.
7462
7463   Returns
7464       error if device is not found or any boundary arrays are invalid.
7465
7466   Since
7467       4.0
7468
7469   Example
7470          set new histograms for all io types with intervals
7471          [0, 10), [10, 50), [50, 100), [100, +inf):
7472
7473          -> { "execute": "block-latency-histogram-set",
7474               "arguments": { "id": "drive0",
7475                              "boundaries": [10, 50, 100] } }
7476          <- { "return": {} }
7477
7478   Example
7479          set new histogram only for write, other histograms will remain
7480          not changed (or not created):
7481
7482          -> { "execute": "block-latency-histogram-set",
7483               "arguments": { "id": "drive0",
7484                              "boundaries-write": [10, 50, 100] } }
7485          <- { "return": {} }
7486
7487   Example
7488          set new histograms with the following intervals:
7489            read, flush: [0, 10), [10, 50), [50, 100), [100, +inf)
7490            write: [0, 1000), [1000, 5000), [5000, +inf)
7491
7492          -> { "execute": "block-latency-histogram-set",
7493               "arguments": { "id": "drive0",
7494                              "boundaries": [10, 50, 100],
7495                              "boundaries-write": [1000, 5000] } }
7496          <- { "return": {} }
7497
7498   Example
7499          remove all latency histograms:
7500
7501          -> { "execute": "block-latency-histogram-set",
7502               "arguments": { "id": "drive0" } }
7503          <- { "return": {} }
7504
7505   Block device exports
7506   NbdServerOptions (Object)
7507       Keep this type consistent with the nbd-server-start arguments. The only
7508       intended difference is using SocketAddress instead of  SocketAddressLe‐
7509       gacy.
7510
7511   Members
7512       addr: SocketAddress
7513              Address on which to listen.
7514
7515       tls-creds: string (optional)
7516              ID of the TLS credentials object (since 2.6).
7517
7518       tls-authz: string (optional)
7519              ID  of  the  QAuthZ  authorization  object  used to validate the
7520              client's x509 distinguished name. This object  is  is  only  re‐
7521              solved  at  time  of use, so can be deleted and recreated on the
7522              fly while the NBD server is active.  If missing, it will default
7523              to denying access (since 4.0).
7524
7525       max-connections: int (optional)
7526              The  maximum  number of connections to allow at the same time, 0
7527              for unlimited. (since 5.2; default: 0)
7528
7529   Since
7530       4.2
7531
7532   nbd-server-start (Command)
7533       Start an NBD server listening on the given host and  port.   Block  de‐
7534       vices  can  then be exported using nbd-server-add.  The NBD server will
7535       present them as named exports; for example, another QEMU instance could
7536       refer to them as "nbd:HOST:PORT:exportname=NAME".
7537
7538       Keep  this type consistent with the NbdServerOptions type. The only in‐
7539       tended difference is using  SocketAddressLegacy  instead  of  SocketAd‐
7540       dress.
7541
7542   Arguments
7543       addr: SocketAddressLegacy
7544              Address on which to listen.
7545
7546       tls-creds: string (optional)
7547              ID of the TLS credentials object (since 2.6).
7548
7549       tls-authz: string (optional)
7550              ID  of  the  QAuthZ  authorization  object  used to validate the
7551              client's x509 distinguished name. This object  is  is  only  re‐
7552              solved  at  time  of use, so can be deleted and recreated on the
7553              fly while the NBD server is active.  If missing, it will default
7554              to denying access (since 4.0).
7555
7556       max-connections: int (optional)
7557              The  maximum  number of connections to allow at the same time, 0
7558              for unlimited. (since 5.2; default: 0)
7559
7560   Returns
7561       error if the server is already running.
7562
7563   Since
7564       1.3.0
7565
7566   BlockExportOptionsNbdBase (Object)
7567       An NBD block export (common options shared between  nbd-server-add  and
7568       the NBD branch of block-export-add).
7569
7570   Members
7571       name: string (optional)
7572              Export name. If unspecified, the device parameter is used as the
7573              export name. (Since 2.12)
7574
7575       description: string (optional)
7576              Free-form description of the export, up to 4096  bytes.   (Since
7577              5.0)
7578
7579   Since
7580       5.0
7581
7582   BlockExportOptionsNbd (Object)
7583       An  NBD  block  export  (distinct  options  used  in  the NBD branch of
7584       block-export-add).
7585
7586   Members
7587       bitmaps: array of string (optional)
7588              Also export each of the named dirty bitmaps reachable  from  de‐
7589              vice,  so  the  NBD client can use NBD_OPT_SET_META_CONTEXT with
7590              the metadata context name "qemu:dirty-bitmap:BITMAP" to  inspect
7591              each bitmap.
7592
7593       allocation-depth: boolean (optional)
7594              Also  export  the  allocation  depth  map for device, so the NBD
7595              client can use NBD_OPT_SET_META_CONTEXT with the  metadata  con‐
7596              text name "qemu:allocation-depth" to inspect allocation details.
7597              (since 5.2)
7598
7599       The members of BlockExportOptionsNbdBase
7600
7601   Since
7602       5.2
7603
7604   BlockExportOptionsVhostUserBlk (Object)
7605       A vhost-user-blk block export.
7606
7607   Members
7608       addr: SocketAddress
7609              The vhost-user socket on which to listen. Both 'unix'  and  'fd'
7610              SocketAddress  types  are supported. Passed fds must be UNIX do‐
7611              main sockets.
7612
7613       logical-block-size: int (optional)
7614              Logical block size in bytes. Defaults to 512 bytes.
7615
7616       num-queues: int (optional)
7617              Number of request virtqueues. Must be greater than  0.  Defaults
7618              to 1.
7619
7620   Since
7621       5.2
7622
7623   NbdServerAddOptions (Object)
7624       An NBD block export, per legacy nbd-server-add command.
7625
7626   Members
7627       device: string
7628              The device name or node name of the node to be exported
7629
7630       writable: boolean (optional)
7631              Whether  clients  should  be able to write to the device via the
7632              NBD connection (default false).
7633
7634       bitmap: string (optional)
7635              Also export a single dirty bitmap reachable from device, so  the
7636              NBD  client  can  use NBD_OPT_SET_META_CONTEXT with the metadata
7637              context name "qemu:dirty-bitmap:BITMAP" to  inspect  the  bitmap
7638              (since 4.0).
7639
7640       The members of BlockExportOptionsNbdBase
7641
7642   Since
7643       5.0
7644
7645   nbd-server-add (Command)
7646       Export a block node to QEMU's embedded NBD server.
7647
7648       The export name will be used as the id for the resulting block export.
7649
7650   Arguments
7651       The members of NbdServerAddOptions
7652
7653   Features
7654       deprecated
7655              This command is deprecated. Use block-export-add instead.
7656
7657   Returns
7658       error  if  the  server is not running, or export with the same name al‐
7659       ready exists.
7660
7661   Since
7662       1.3.0
7663
7664   BlockExportRemoveMode (Enum)
7665       Mode for removing a block export.
7666
7667   Values
7668       safe   Remove export if there are no existing connections, fail  other‐
7669              wise.
7670
7671       hard   Drop all connections immediately and remove export.
7672       Potential additional modes to be added in the future:
7673
7674       hide:  Just hide export from new clients, leave existing connections as
7675       is.  Remove export after all clients are disconnected.
7676
7677       soft: Hide export from new clients, answer with ESHUTDOWN for all  fur‐
7678       ther requests from existing clients.
7679
7680   Since
7681       2.12
7682
7683   nbd-server-remove (Command)
7684       Remove NBD export by name.
7685
7686   Arguments
7687       name: string
7688              Block export id.
7689
7690       mode: BlockExportRemoveMode (optional)
7691              Mode  of  command  operation. See BlockExportRemoveMode descrip‐
7692              tion.  Default is 'safe'.
7693
7694   Features
7695       deprecated
7696              This command is deprecated. Use block-export-del instead.
7697
7698   Returns
7699       error if
7700
7701              • the server is not running
7702
7703              • export is not found
7704
7705              • mode is 'safe' and there are existing connections
7706
7707   Since
7708       2.12
7709
7710   nbd-server-stop (Command)
7711       Stop QEMU's embedded NBD server, and unregister all devices  previously
7712       added via nbd-server-add.
7713
7714   Since
7715       1.3.0
7716
7717   BlockExportType (Enum)
7718       An enumeration of block export types
7719
7720   Values
7721       nbd    NBD export
7722
7723       vhost-user-blk
7724              vhost-user-blk export (since 5.2)
7725
7726   Since
7727       4.2
7728
7729   BlockExportOptions (Object)
7730       Describes a block export, i.e. how single node should be exported on an
7731       external interface.
7732
7733   Members
7734       id: string
7735              A unique identifier for the  block  export  (across  all  export
7736              types)
7737
7738       node-name: string
7739              The node name of the block node to be exported (since: 5.2)
7740
7741       writable: boolean (optional)
7742              True  if  clients should be able to write to the export (default
7743              false)
7744
7745       writethrough: boolean (optional)
7746              If true, caches are flushed after every write request to the ex‐
7747              port  before  completion  is  signalled.  (since:  5.2; default:
7748              false)
7749
7750       iothread: string (optional)
7751              The name of the iothread object where the export will  run.  The
7752              default is to use the thread currently associated with the block
7753              node. (since: 5.2)
7754
7755       fixed-iothread: boolean (optional)
7756              True prevents the block node from being moved to another  thread
7757              while  the  export is active. If true and iothread is given, ex‐
7758              port creation fails if the block node cannot be moved to the io‐
7759              thread. The default is false. (since: 5.2)
7760
7761       type: BlockExportType
7762              Not documented
7763
7764       The members of BlockExportOptionsNbd when type is "nbd"
7765
7766       The    members   of   BlockExportOptionsVhostUserBlk   when   type   is
7767       "vhost-user-blk"
7768
7769   Since
7770       4.2
7771
7772   block-export-add (Command)
7773       Creates a new block export.
7774
7775   Arguments
7776       The members of BlockExportOptions
7777
7778   Since
7779       5.2
7780
7781   block-export-del (Command)
7782       Request to remove a block export. This drops the  user's  reference  to
7783       the export, but the export may still stay around after this command re‐
7784       turns until the shutdown of the export has completed.
7785
7786   Arguments
7787       id: string
7788              Block export id.
7789
7790       mode: BlockExportRemoveMode (optional)
7791              Mode of command operation.  See  BlockExportRemoveMode  descrip‐
7792              tion.  Default is 'safe'.
7793
7794   Returns
7795       Error  if  the  export is not found or mode is 'safe' and the export is
7796       still in use (e.g. by existing client connections)
7797
7798   Since
7799       5.2
7800
7801   BLOCK_EXPORT_DELETED (Event)
7802       Emitted when a block export is removed and its id can be reused.
7803
7804   Arguments
7805       id: string
7806              Block export id.
7807
7808   Since
7809       5.2
7810
7811   BlockExportInfo (Object)
7812       Information about a single block export.
7813
7814   Members
7815       id: string
7816              The unique identifier for the block export
7817
7818       type: BlockExportType
7819              The block export type
7820
7821       node-name: string
7822              The node name of the block node that is exported
7823
7824       shutting-down: boolean
7825              True if the export is shutting  down  (e.g.  after  a  block-ex‐
7826              port-del command, but before the shutdown has completed)
7827
7828   Since
7829       5.2
7830
7831   query-block-exports (Command)
7832   Returns
7833       A list of BlockExportInfo describing all block exports
7834
7835   Since
7836       5.2
7837

CHARACTER DEVICES

7839   ChardevInfo (Object)
7840       Information about a character device.
7841
7842   Members
7843       label: string
7844              the label of the character device
7845
7846       filename: string
7847              the filename of the character device
7848
7849       frontend-open: boolean
7850              shows  whether the frontend device attached to this backend (eg.
7851              with the chardev=... option) is in open or closed  state  (since
7852              2.1)
7853
7854   Notes
7855       filename is encoded using the QEMU command line character device encod‐
7856       ing.  See the QEMU man page for details.
7857
7858   Since
7859       0.14.0
7860
7861   query-chardev (Command)
7862       Returns information about current character devices.
7863
7864   Returns
7865       a list of ChardevInfo
7866
7867   Since
7868       0.14.0
7869
7870   Example
7871          -> { "execute": "query-chardev" }
7872          <- {
7873                "return": [
7874                   {
7875                      "label": "charchannel0",
7876                      "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.agent,server",
7877                      "frontend-open": false
7878                   },
7879                   {
7880                      "label": "charmonitor",
7881                      "filename": "unix:/var/lib/libvirt/qemu/seabios.rhel6.monitor,server",
7882                      "frontend-open": true
7883                   },
7884                   {
7885                      "label": "charserial0",
7886                      "filename": "pty:/dev/pts/2",
7887                      "frontend-open": true
7888                   }
7889                ]
7890             }
7891
7892   ChardevBackendInfo (Object)
7893       Information about a character device backend
7894
7895   Members
7896       name: string
7897              The backend name
7898
7899   Since
7900       2.0
7901
7902   query-chardev-backends (Command)
7903       Returns information about character device backends.
7904
7905   Returns
7906       a list of ChardevBackendInfo
7907
7908   Since
7909       2.0
7910
7911   Example
7912          -> { "execute": "query-chardev-backends" }
7913          <- {
7914                "return":[
7915                   {
7916                      "name":"udp"
7917                   },
7918                   {
7919                      "name":"tcp"
7920                   },
7921                   {
7922                      "name":"unix"
7923                   },
7924                   {
7925                      "name":"spiceport"
7926                   }
7927                ]
7928             }
7929
7930   DataFormat (Enum)
7931       An enumeration of data format.
7932
7933   Values
7934       utf8   Data is a UTF-8 string (RFC 3629)
7935
7936       base64 Data is Base64 encoded binary (RFC 3548)
7937
7938   Since
7939       1.4
7940
7941   ringbuf-write (Command)
7942       Write to a ring buffer character device.
7943
7944   Arguments
7945       device: string
7946              the ring buffer character device name
7947
7948       data: string
7949              data to write
7950
7951       format: DataFormat (optional)
7952              data encoding (default 'utf8').
7953
7954              • base64: data must be base64 encoded text.  Its binary decoding
7955                gets written.
7956
7957              • utf8: data's UTF-8 encoding is written
7958
7959              • data  itself  is always Unicode regardless of format, like any
7960                other string.
7961
7962   Returns
7963       Nothing on success
7964
7965   Since
7966       1.4
7967
7968   Example
7969          -> { "execute": "ringbuf-write",
7970               "arguments": { "device": "foo",
7971                              "data": "abcdefgh",
7972                              "format": "utf8" } }
7973          <- { "return": {} }
7974
7975   ringbuf-read (Command)
7976       Read from a ring buffer character device.
7977
7978   Arguments
7979       device: string
7980              the ring buffer character device name
7981
7982       size: int
7983              how many bytes to read at most
7984
7985       format: DataFormat (optional)
7986              data encoding (default 'utf8').
7987
7988              • base64: the data read is returned in base64 encoding.
7989
7990              • utf8: the data read is interpreted as UTF-8.  Bug:  can  screw
7991                up when the buffer contains invalid UTF-8 sequences, NUL char‐
7992                acters, after the ring buffer  lost  data,  and  when  reading
7993                stops because the size limit is reached.
7994
7995              • The  return value is always Unicode regardless of format, like
7996                any other string.
7997
7998   Returns
7999       data read from the device
8000
8001   Since
8002       1.4
8003
8004   Example
8005          -> { "execute": "ringbuf-read",
8006               "arguments": { "device": "foo",
8007                              "size": 1000,
8008                              "format": "utf8" } }
8009          <- { "return": "abcdefgh" }
8010
8011   ChardevCommon (Object)
8012       Configuration shared across all chardev backends
8013
8014   Members
8015       logfile: string (optional)
8016              The name of a logfile to save output
8017
8018       logappend: boolean (optional)
8019              true to append instead of truncate (default to  false  to  trun‐
8020              cate)
8021
8022   Since
8023       2.6
8024
8025   ChardevFile (Object)
8026       Configuration info for file chardevs.
8027
8028   Members
8029       in: string (optional)
8030              The name of the input file
8031
8032       out: string
8033              The name of the output file
8034
8035       append: boolean (optional)
8036              Open  the file in append mode (default false to truncate) (Since
8037              2.6)
8038
8039       The members of ChardevCommon
8040
8041   Since
8042       1.4
8043
8044   ChardevHostdev (Object)
8045       Configuration info for device and pipe chardevs.
8046
8047   Members
8048       device: string
8049              The name of the special file for the device, i.e. /dev/ttyS0  on
8050              Unix or COM1: on Windows
8051
8052       The members of ChardevCommon
8053
8054   Since
8055       1.4
8056
8057   ChardevSocket (Object)
8058       Configuration info for (stream) socket chardevs.
8059
8060   Members
8061       addr: SocketAddressLegacy
8062              socket   address  to  listen  on  (server=true)  or  connect  to
8063              (server=false)
8064
8065       tls-creds: string (optional)
8066              the ID of the TLS credentials object (since 2.6)
8067
8068       tls-authz: string (optional)
8069              the ID of the QAuthZ  authorization  object  against  which  the
8070              client's  x509 distinguished name will be validated. This object
8071              is only resolved at time of use, so can be deleted and recreated
8072              on  the  fly while the chardev server is active.  If missing, it
8073              will default to denying access (since 4.0)
8074
8075       server: boolean (optional)
8076              create server socket (default: true)
8077
8078       wait: boolean (optional)
8079              wait for incoming connection on server sockets (default: false).
8080              Silently ignored with server: false.  This use is deprecated.
8081
8082       nodelay: boolean (optional)
8083              set TCP_NODELAY socket option (default: false)
8084
8085       telnet: boolean (optional)
8086              enable telnet protocol on server sockets (default: false)
8087
8088       tn3270: boolean (optional)
8089              enable  tn3270  protocol  on  server  sockets  (default:  false)
8090              (Since: 2.10)
8091
8092       websocket: boolean (optional)
8093              enable websocket protocol on  server  sockets  (default:  false)
8094              (Since: 3.1)
8095
8096       reconnect: int (optional)
8097              For a client socket, if a socket is disconnected, then attempt a
8098              reconnect after the given number of seconds.   Setting  this  to
8099              zero disables this function. (default: 0) (Since: 2.2)
8100
8101       The members of ChardevCommon
8102
8103   Since
8104       1.4
8105
8106   ChardevUdp (Object)
8107       Configuration info for datagram socket chardevs.
8108
8109   Members
8110       remote: SocketAddressLegacy
8111              remote address
8112
8113       local: SocketAddressLegacy (optional)
8114              local address
8115
8116       The members of ChardevCommon
8117
8118   Since
8119       1.5
8120
8121   ChardevMux (Object)
8122       Configuration info for mux chardevs.
8123
8124   Members
8125       chardev: string
8126              name of the base chardev.
8127
8128       The members of ChardevCommon
8129
8130   Since
8131       1.5
8132
8133   ChardevStdio (Object)
8134       Configuration info for stdio chardevs.
8135
8136   Members
8137       signal: boolean (optional)
8138              Allow  signals  (such as SIGINT triggered by ^C) be delivered to
8139              qemu.  Default: true.
8140
8141       The members of ChardevCommon
8142
8143   Since
8144       1.5
8145
8146   ChardevSpiceChannel (Object)
8147       Configuration info for spice vm channel chardevs.
8148
8149   Members
8150       type: string
8151              kind of channel (for example vdagent).
8152
8153       The members of ChardevCommon
8154
8155   Since
8156       1.5
8157
8158   If
8159       defined(CONFIG_SPICE).SS ChardevSpicePort (Object)
8160
8161       Configuration info for spice port chardevs.
8162
8163   Members
8164       fqdn: string
8165              name of the channel (see docs/spice-port-fqdn.txt)
8166
8167       The members of ChardevCommon
8168
8169   Since
8170       1.5
8171
8172   If
8173       defined(CONFIG_SPICE).SS ChardevVC (Object)
8174
8175       Configuration info for virtual console chardevs.
8176
8177   Members
8178       width: int (optional)
8179              console width,  in pixels
8180
8181       height: int (optional)
8182              console height, in pixels
8183
8184       cols: int (optional)
8185              console width,  in chars
8186
8187       rows: int (optional)
8188              console height, in chars
8189
8190       The members of ChardevCommon
8191
8192   Since
8193       1.5
8194
8195   ChardevRingbuf (Object)
8196       Configuration info for ring buffer chardevs.
8197
8198   Members
8199       size: int (optional)
8200              ring buffer size, must be power of two, default is 65536
8201
8202       The members of ChardevCommon
8203
8204   Since
8205       1.5
8206
8207   ChardevBackend (Object)
8208       Configuration info for the new chardev backend.
8209
8210   Members
8211       type   One of file, serial, parallel, pipe,  socket,  udp,  pty,  null,
8212              mux,   msmouse,  wctablet,  braille,  testdev,  stdio,  console,
8213              spicevmc, spiceport, vc, ringbuf, memory
8214
8215       data: ChardevFile when type is "file"
8216
8217       data: ChardevHostdev when type is "serial"
8218
8219       data: ChardevHostdev when type is "parallel"
8220
8221       data: ChardevHostdev when type is "pipe"
8222
8223       data: ChardevSocket when type is "socket"
8224
8225       data: ChardevUdp when type is "udp"
8226
8227       data: ChardevCommon when type is "pty"
8228
8229       data: ChardevCommon when type is "null"
8230
8231       data: ChardevMux when type is "mux"
8232
8233       data: ChardevCommon when type is "msmouse"
8234
8235       data: ChardevCommon when type is "wctablet"
8236
8237       data: ChardevCommon when type is "braille"
8238
8239       data: ChardevCommon when type is "testdev"
8240
8241       data: ChardevStdio when type is "stdio"
8242
8243       data: ChardevCommon when type is "console"
8244
8245       data: ChardevSpiceChannel when type  is  "spicevmc"  (If:  defined(CON‐
8246       FIG_SPICE))
8247
8248       data:  ChardevSpicePort  when  type  is  "spiceport"  (If: defined(CON‐
8249       FIG_SPICE))
8250
8251       data: ChardevVC when type is "vc"
8252
8253       data: ChardevRingbuf when type is "ringbuf"
8254
8255       data: ChardevRingbuf when type is "memory"
8256
8257   Since
8258       1.4 (testdev since 2.2, wctablet since 2.9)
8259
8260   ChardevReturn (Object)
8261       Return info about the chardev backend just created.
8262
8263   Members
8264       pty: string (optional)
8265              name of the slave pseudoterminal device, present if and only  if
8266              a chardev of type 'pty' was created
8267
8268   Since
8269       1.4
8270
8271   chardev-add (Command)
8272       Add a character device backend
8273
8274   Arguments
8275       id: string
8276              the chardev's ID, must be unique
8277
8278       backend: ChardevBackend
8279              backend type and parameters
8280
8281   Returns
8282       ChardevReturn.
8283
8284   Since
8285       1.4
8286
8287   Example
8288          -> { "execute" : "chardev-add",
8289               "arguments" : { "id" : "foo",
8290                               "backend" : { "type" : "null", "data" : {} } } }
8291          <- { "return": {} }
8292
8293          -> { "execute" : "chardev-add",
8294               "arguments" : { "id" : "bar",
8295                               "backend" : { "type" : "file",
8296                                             "data" : { "out" : "/tmp/bar.log" } } } }
8297          <- { "return": {} }
8298
8299          -> { "execute" : "chardev-add",
8300               "arguments" : { "id" : "baz",
8301                               "backend" : { "type" : "pty", "data" : {} } } }
8302          <- { "return": { "pty" : "/dev/pty/42" } }
8303
8304   chardev-change (Command)
8305       Change a character device backend
8306
8307   Arguments
8308       id: string
8309              the chardev's ID, must exist
8310
8311       backend: ChardevBackend
8312              new backend type and parameters
8313
8314   Returns
8315       ChardevReturn.
8316
8317   Since
8318       2.10
8319
8320   Example
8321          -> { "execute" : "chardev-change",
8322               "arguments" : { "id" : "baz",
8323                               "backend" : { "type" : "pty", "data" : {} } } }
8324          <- { "return": { "pty" : "/dev/pty/42" } }
8325
8326          -> {"execute" : "chardev-change",
8327              "arguments" : {
8328                  "id" : "charchannel2",
8329                  "backend" : {
8330                      "type" : "socket",
8331                      "data" : {
8332                          "addr" : {
8333                              "type" : "unix" ,
8334                              "data" : {
8335                                  "path" : "/tmp/charchannel2.socket"
8336                              }
8337                           },
8338                           "server" : true,
8339                           "wait" : false }}}}
8340          <- {"return": {}}
8341
8342   chardev-remove (Command)
8343       Remove a character device backend
8344
8345   Arguments
8346       id: string
8347              the chardev's ID, must exist and not be in use
8348
8349   Returns
8350       Nothing on success
8351
8352   Since
8353       1.4
8354
8355   Example
8356          -> { "execute": "chardev-remove", "arguments": { "id" : "foo" } }
8357          <- { "return": {} }
8358
8359   chardev-send-break (Command)
8360       Send a break to a character device
8361
8362   Arguments
8363       id: string
8364              the chardev's ID, must exist
8365
8366   Returns
8367       Nothing on success
8368
8369   Since
8370       2.10
8371
8372   Example
8373          -> { "execute": "chardev-send-break", "arguments": { "id" : "foo" } }
8374          <- { "return": {} }
8375
8376   VSERPORT_CHANGE (Event)
8377       Emitted when the guest opens or closes a virtio-serial port.
8378
8379   Arguments
8380       id: string
8381              device identifier of the virtio-serial port
8382
8383       open: boolean
8384              true if the guest has opened the virtio-serial port
8385
8386   Note
8387       This event is rate-limited.
8388
8389   Since
8390       2.1
8391
8392   Example
8393          <- { "event": "VSERPORT_CHANGE",
8394               "data": { "id": "channel0", "open": true },
8395               "timestamp": { "seconds": 1401385907, "microseconds": 422329 } }
8396

DUMP GUEST MEMORY

8398   DumpGuestMemoryFormat (Enum)
8399       An enumeration of guest-memory-dump's format.
8400
8401   Values
8402       elf    elf format
8403
8404       kdump-zlib
8405              kdump-compressed format with zlib-compressed
8406
8407       kdump-lzo
8408              kdump-compressed format with lzo-compressed
8409
8410       kdump-snappy
8411              kdump-compressed format with snappy-compressed
8412
8413       win-dmp
8414              Windows  full  crashdump format, can be used instead of ELF con‐
8415              verting (since 2.13)
8416
8417   Since
8418       2.0
8419
8420   dump-guest-memory (Command)
8421       Dump guest's memory to vmcore. It is a synchronous operation  that  can
8422       take very long depending on the amount of guest memory.
8423
8424   Arguments
8425       paging: boolean
8426              if  true,  do  paging to get guest's memory mapping. This allows
8427              using gdb to process the core file.
8428
8429              IMPORTANT: this option can make QEMU allocate several  gigabytes
8430              of  RAM. This can happen for a large guest, or a malicious guest
8431              pretending to be large.
8432
8433              Also, paging=true has the following limitations:
8434
8435                 1. The guest may be in a catastrophic state or can have  cor‐
8436                    rupted memory, which cannot be trusted
8437
8438                 2. The  guest  can be in real-mode even if paging is enabled.
8439                    For example, the guest uses ACPI to sleep, and ACPI  sleep
8440                    state goes in real-mode
8441
8442                 3. Currently only supported on i386 and x86_64.
8443
8444       protocol: string
8445              the  filename  or  file  descriptor of the vmcore. The supported
8446              protocols are:
8447
8448              1. file: the protocol starts with  "file:",  and  the  following
8449                 string is the file's path.
8450
8451              2. fd:  the protocol starts with "fd:", and the following string
8452                 is the fd's name.
8453
8454       detach: boolean (optional)
8455              if true, QMP will return immediately rather than waiting for the
8456              dump  to finish. The user can track progress using "query-dump".
8457              (since 2.6).
8458
8459       begin: int (optional)
8460              if specified, the starting physical address.
8461
8462       length: int (optional)
8463              if specified, the memory size, in bytes. If you  don't  want  to
8464              dump  all  guest's  memory,  please  specify the start begin and
8465              length
8466
8467       format: DumpGuestMemoryFormat (optional)
8468              if specified, the format of guest memory dump. But non-elf  for‐
8469              mat  is  conflict  with paging and filter, ie. paging, begin and
8470              length is not allowed to be specified with non-elf format at the
8471              same time (since 2.0)
8472
8473   Note
8474       All boolean arguments default to false
8475
8476   Returns
8477       nothing on success
8478
8479   Since
8480       1.2
8481
8482   Example
8483          -> { "execute": "dump-guest-memory",
8484               "arguments": { "protocol": "fd:dump" } }
8485          <- { "return": {} }
8486
8487   DumpStatus (Enum)
8488       Describe the status of a long-running background guest memory dump.
8489
8490   Values
8491       none   no dump-guest-memory has started yet.
8492
8493       active there is one dump running in background.
8494
8495       completed
8496              the last dump has finished successfully.
8497
8498       failed the last dump has failed.
8499
8500   Since
8501       2.6
8502
8503   DumpQueryResult (Object)
8504       The result format for 'query-dump'.
8505
8506   Members
8507       status: DumpStatus
8508              enum of DumpStatus, which shows current dump status
8509
8510       completed: int
8511              bytes written in latest dump (uncompressed)
8512
8513       total: int
8514              total bytes to be written in latest dump (uncompressed)
8515
8516   Since
8517       2.6
8518
8519   query-dump (Command)
8520       Query latest dump status.
8521
8522   Returns
8523       A DumpStatus object showing the dump status.
8524
8525   Since
8526       2.6
8527
8528   Example
8529          -> { "execute": "query-dump" }
8530          <- { "return": { "status": "active", "completed": 1024000,
8531                           "total": 2048000 } }
8532
8533   DUMP_COMPLETED (Event)
8534       Emitted when background dump has completed
8535
8536   Arguments
8537       result: DumpQueryResult
8538              final dump status
8539
8540       error: string (optional)
8541              human-readable  error  string  that  provides  hint  on why dump
8542              failed. Only presents on failure. The user should not try to in‐
8543              terpret the error string.
8544
8545   Since
8546       2.6
8547
8548   Example
8549          { "event": "DUMP_COMPLETED",
8550            "data": {"result": {"total": 1090650112, "status": "completed",
8551                                "completed": 1090650112} } }
8552
8553   DumpGuestMemoryCapability (Object)
8554       A list of the available formats for dump-guest-memory
8555
8556   Members
8557       formats: array of DumpGuestMemoryFormat
8558              Not documented
8559
8560   Since
8561       2.0
8562
8563   query-dump-guest-memory-capability (Command)
8564       Returns the available formats for dump-guest-memory
8565
8566   Returns
8567       A   DumpGuestMemoryCapability  object  listing  available  formats  for
8568       dump-guest-memory
8569
8570   Since
8571       2.0
8572
8573   Example
8574          -> { "execute": "query-dump-guest-memory-capability" }
8575          <- { "return": { "formats":
8576                           ["elf", "kdump-zlib", "kdump-lzo", "kdump-snappy"] }
8577

NET DEVICES

8579   set_link (Command)
8580       Sets the link status of a virtual network adapter.
8581
8582   Arguments
8583       name: string
8584              the device name of the virtual network adapter
8585
8586       up: boolean
8587              true to set the link status to be up
8588
8589   Returns
8590       Nothing on success If name is not a valid  network  device,  DeviceNot‐
8591       Found
8592
8593   Since
8594       0.14.0
8595
8596   Notes
8597       Not  all  network  adapters  support setting link status.  This command
8598       will succeed even if the network adapter does not support  link  status
8599       notification.
8600
8601   Example
8602          -> { "execute": "set_link",
8603               "arguments": { "name": "e1000.0", "up": false } }
8604          <- { "return": {} }
8605
8606   netdev_add (Command)
8607       Add a network backend.
8608
8609       Additional arguments depend on the type.
8610
8611   Arguments
8612       The members of Netdev
8613
8614   Since
8615       0.14.0
8616
8617   Returns
8618       Nothing  on  success If type is not a valid network backend, DeviceNot‐
8619       Found
8620
8621   Example
8622          -> { "execute": "netdev_add",
8623               "arguments": { "type": "user", "id": "netdev1",
8624                              "dnssearch": "example.org" } }
8625          <- { "return": {} }
8626
8627   netdev_del (Command)
8628       Remove a network backend.
8629
8630   Arguments
8631       id: string
8632              the name of the network backend to remove
8633
8634   Returns
8635       Nothing on success If id is not a valid network backend, DeviceNotFound
8636
8637   Since
8638       0.14.0
8639
8640   Example
8641          -> { "execute": "netdev_del", "arguments": { "id": "netdev1" } }
8642          <- { "return": {} }
8643
8644   NetLegacyNicOptions (Object)
8645       Create a new Network Interface Card.
8646
8647   Members
8648       netdev: string (optional)
8649              id of -netdev to connect to
8650
8651       macaddr: string (optional)
8652              MAC address
8653
8654       model: string (optional)
8655              device model (e1000, rtl8139, virtio etc.)
8656
8657       addr: string (optional)
8658              PCI device address
8659
8660       vectors: int (optional)
8661              number of MSI-x vectors, 0 to disable MSI-X
8662
8663   Since
8664       1.2
8665
8666   NetdevUserOptions (Object)
8667       Use the user mode network stack which requires no administrator  privi‐
8668       lege to run.
8669
8670   Members
8671       hostname: string (optional)
8672              client hostname reported by the builtin DHCP server
8673
8674       restrict: boolean (optional)
8675              isolate the guest from the host
8676
8677       ipv4: boolean (optional)
8678              whether to support IPv4, default true for enabled (since 2.6)
8679
8680       ipv6: boolean (optional)
8681              whether to support IPv6, default true for enabled (since 2.6)
8682
8683       ip: string (optional)
8684              legacy parameter, use net= instead
8685
8686       net: string (optional)
8687              IP  network  address  that  the  guest  will  see,  in  the form
8688              addr[/netmask] The netmask is optional, and can be either in the
8689              form  a.b.c.d  or as a number of valid top-most bits. Default is
8690              10.0.2.0/24.
8691
8692       host: string (optional)
8693              guest-visible address of the host
8694
8695       tftp: string (optional)
8696              root directory of the built-in TFTP server
8697
8698       bootfile: string (optional)
8699              BOOTP filename, for use with tftp=
8700
8701       dhcpstart: string (optional)
8702              the first of the 16 IPs the built-in DHCP server can assign
8703
8704       dns: string (optional)
8705              guest-visible address of the virtual nameserver
8706
8707       dnssearch: array of String (optional)
8708              list of DNS suffixes to search, passed as  DHCP  option  to  the
8709              guest
8710
8711       domainname: string (optional)
8712              guest-visible domain name of the virtual nameserver (since 3.0)
8713
8714       ipv6-prefix: string (optional)
8715              IPv6 network prefix (default is fec0::) (since 2.6). The network
8716              prefix is given in the usual hexadecimal IPv6 address notation.
8717
8718       ipv6-prefixlen: int (optional)
8719              IPv6 network prefix length (default is 64) (since 2.6)
8720
8721       ipv6-host: string (optional)
8722              guest-visible IPv6 address of the host (since 2.6)
8723
8724       ipv6-dns: string (optional)
8725              guest-visible IPv6 address of the virtual nameserver (since 2.6)
8726
8727       smb: string (optional)
8728              root directory of the built-in SMB server
8729
8730       smbserver: string (optional)
8731              IP address of the built-in SMB server
8732
8733       hostfwd: array of String (optional)
8734              redirect incoming TCP or UDP host connections to guest endpoints
8735
8736       guestfwd: array of String (optional)
8737              forward guest TCP connections
8738
8739       tftp-server-name: string (optional)
8740              RFC2132 "TFTP server name" string (Since 3.1)
8741
8742   Since
8743       1.2
8744
8745   NetdevTapOptions (Object)
8746       Used to configure a host TAP network interface backend.
8747
8748   Members
8749       ifname: string (optional)
8750              interface name
8751
8752       fd: string (optional)
8753              file descriptor of an already opened tap
8754
8755       fds: string (optional)
8756              multiple file descriptors of already opened  multiqueue  capable
8757              tap
8758
8759       script: string (optional)
8760              script to initialize the interface
8761
8762       downscript: string (optional)
8763              script to shut down the interface
8764
8765       br: string (optional)
8766              bridge name (since 2.8)
8767
8768       helper: string (optional)
8769              command to execute to configure bridge
8770
8771       sndbuf: int (optional)
8772              send buffer limit. Understands [TGMKkb] suffixes.
8773
8774       vnet_hdr: boolean (optional)
8775              enable the IFF_VNET_HDR flag on the tap interface
8776
8777       vhost: boolean (optional)
8778              enable vhost-net network accelerator
8779
8780       vhostfd: string (optional)
8781              file descriptor of an already opened vhost net device
8782
8783       vhostfds: string (optional)
8784              file descriptors of multiple already opened vhost net devices
8785
8786       vhostforce: boolean (optional)
8787              vhost on for non-MSIX virtio guests
8788
8789       queues: int (optional)
8790              number of queues to be created for multiqueue capable tap
8791
8792       poll-us: int (optional)
8793              maximum  number  of  microseconds  that  could  be spent on busy
8794              polling for tap (since 2.7)
8795
8796   Since
8797       1.2
8798
8799   NetdevSocketOptions (Object)
8800       Socket netdevs are used to establish a network  connection  to  another
8801       QEMU virtual machine via a TCP socket.
8802
8803   Members
8804       fd: string (optional)
8805              file descriptor of an already opened socket
8806
8807       listen: string (optional)
8808              port number, and optional hostname, to listen on
8809
8810       connect: string (optional)
8811              port number, and optional hostname, to connect to
8812
8813       mcast: string (optional)
8814              UDP multicast address and port number
8815
8816       localaddr: string (optional)
8817              source address and port for multicast and udp packets
8818
8819       udp: string (optional)
8820              UDP unicast address and port number
8821
8822   Since
8823       1.2
8824
8825   NetdevL2TPv3Options (Object)
8826       Configure an Ethernet over L2TPv3 tunnel.
8827
8828   Members
8829       src: string
8830              source address
8831
8832       dst: string
8833              destination address
8834
8835       srcport: string (optional)
8836              source port - mandatory for udp, optional for ip
8837
8838       dstport: string (optional)
8839              destination port - mandatory for udp, optional for ip
8840
8841       ipv6: boolean (optional)
8842              force the use of ipv6
8843
8844       udp: boolean (optional)
8845              use the udp version of l2tpv3 encapsulation
8846
8847       cookie64: boolean (optional)
8848              use 64 bit coookies
8849
8850       counter: boolean (optional)
8851              have sequence counter
8852
8853       pincounter: boolean (optional)
8854              pin  sequence counter to zero - workaround for buggy implementa‐
8855              tions or networks with packet reorder
8856
8857       txcookie: int (optional)
8858              32 or 64 bit transmit cookie
8859
8860       rxcookie: int (optional)
8861              32 or 64 bit receive cookie
8862
8863       txsession: int
8864              32 bit transmit session
8865
8866       rxsession: int (optional)
8867              32 bit receive session - if not specified set to the same  value
8868              as transmit
8869
8870       offset: int (optional)
8871              additional  offset - allows the insertion of additional applica‐
8872              tion-specific data before the packet payload
8873
8874   Since
8875       2.1
8876
8877   NetdevVdeOptions (Object)
8878       Connect to a vde switch running on the host.
8879
8880   Members
8881       sock: string (optional)
8882              socket path
8883
8884       port: int (optional)
8885              port number
8886
8887       group: string (optional)
8888              group owner of socket
8889
8890       mode: int (optional)
8891              permissions for socket
8892
8893   Since
8894       1.2
8895
8896   NetdevBridgeOptions (Object)
8897       Connect a host TAP network interface to a host bridge device.
8898
8899   Members
8900       br: string (optional)
8901              bridge name
8902
8903       helper: string (optional)
8904              command to execute to configure bridge
8905
8906   Since
8907       1.2
8908
8909   NetdevHubPortOptions (Object)
8910       Connect two or more net clients through a software hub.
8911
8912   Members
8913       hubid: int
8914              hub identifier number
8915
8916       netdev: string (optional)
8917              used to connect hub to a netdev instead of a device (since 2.12)
8918
8919   Since
8920       1.2
8921
8922   NetdevNetmapOptions (Object)
8923       Connect a client to a netmap-enabled NIC or to a VALE switch port
8924
8925   Members
8926       ifname: string
8927              Either the name of an existing network  interface  supported  by
8928              netmap, or the name of a VALE port (created on the fly).  A VALE
8929              port name is in the form 'valeXXX:YYY', where XXX  and  YYY  are
8930              non-negative  integers.  XXX identifies a switch and YYY identi‐
8931              fies a port of the switch. VALE ports having the  same  XXX  are
8932              therefore connected to the same switch.
8933
8934       devname: string (optional)
8935              path of the netmap device (default: '/dev/netmap').
8936
8937   Since
8938       2.0
8939
8940   NetdevVhostUserOptions (Object)
8941       Vhost-user network backend
8942
8943   Members
8944       chardev: string
8945              name of a unix socket chardev
8946
8947       vhostforce: boolean (optional)
8948              vhost on for non-MSIX virtio guests (default: false).
8949
8950       queues: int (optional)
8951              number  of  queues  to be created for multiqueue vhost-user (de‐
8952              fault: 1) (Since 2.5)
8953
8954   Since
8955       2.1
8956
8957   NetdevVhostVDPAOptions (Object)
8958       Vhost-vdpa network backend
8959
8960       vDPA device is a device that uses a datapath which  complies  with  the
8961       virtio specifications with a vendor specific control path.
8962
8963   Members
8964       vhostdev: string (optional)
8965              path of vhost-vdpa device (default:'/dev/vhost-vdpa-0')
8966
8967       queues: int (optional)
8968              number  of  queues  to be created for multiqueue vhost-vdpa (de‐
8969              fault: 1)
8970
8971   Since
8972       5.1
8973
8974   NetClientDriver (Enum)
8975       Available netdev drivers.
8976
8977   Values
8978       none   Not documented
8979
8980       nic    Not documented
8981
8982       user   Not documented
8983
8984       tap    Not documented
8985
8986       l2tpv3 Not documented
8987
8988       socket Not documented
8989
8990       vde    Not documented
8991
8992       bridge Not documented
8993
8994       hubport
8995              Not documented
8996
8997       netmap Not documented
8998
8999       vhost-user
9000              Not documented
9001
9002       vhost-vdpa
9003              Not documented
9004
9005   Since
9006       2.7
9007
9008       vhost-vdpa since 5.1
9009
9010   Netdev (Object)
9011       Captures the configuration of a network device.
9012
9013   Members
9014       id: string
9015              identifier for monitor commands.
9016
9017       type: NetClientDriver
9018              Specify the driver used for interpreting remaining arguments.
9019
9020       The members of NetLegacyNicOptions when type is "nic"
9021
9022       The members of NetdevUserOptions when type is "user"
9023
9024       The members of NetdevTapOptions when type is "tap"
9025
9026       The members of NetdevL2TPv3Options when type is "l2tpv3"
9027
9028       The members of NetdevSocketOptions when type is "socket"
9029
9030       The members of NetdevVdeOptions when type is "vde"
9031
9032       The members of NetdevBridgeOptions when type is "bridge"
9033
9034       The members of NetdevHubPortOptions when type is "hubport"
9035
9036       The members of NetdevNetmapOptions when type is "netmap"
9037
9038       The members of NetdevVhostUserOptions when type is "vhost-user"
9039
9040       The members of NetdevVhostVDPAOptions when type is "vhost-vdpa"
9041
9042   Since
9043       1.2
9044
9045       'l2tpv3' - since 2.1
9046
9047   NetFilterDirection (Enum)
9048       Indicates whether a netfilter is attached to a netdev's transmit  queue
9049       or receive queue or both.
9050
9051   Values
9052       all    the  filter  is  attached  both  to the receive and the transmit
9053              queue of the netdev (default).
9054
9055       rx     the filter is attached to the receive queue of the netdev, where
9056              it will receive packets sent to the netdev.
9057
9058       tx     the  filter  is  attached  to  the transmit queue of the netdev,
9059              where it will receive packets sent by the netdev.
9060
9061   Since
9062       2.5
9063
9064   RxState (Enum)
9065       Packets receiving state
9066
9067   Values
9068       normal filter assigned packets according to the mac-table
9069
9070       none   don't receive any assigned packet
9071
9072       all    receive all assigned packets
9073
9074   Since
9075       1.6
9076
9077   RxFilterInfo (Object)
9078       Rx-filter information for a NIC.
9079
9080   Members
9081       name: string
9082              net client name
9083
9084       promiscuous: boolean
9085              whether promiscuous mode is enabled
9086
9087       multicast: RxState
9088              multicast receive state
9089
9090       unicast: RxState
9091              unicast receive state
9092
9093       vlan: RxState
9094              vlan receive state (Since 2.0)
9095
9096       broadcast-allowed: boolean
9097              whether to receive broadcast
9098
9099       multicast-overflow: boolean
9100              multicast table is overflowed or not
9101
9102       unicast-overflow: boolean
9103              unicast table is overflowed or not
9104
9105       main-mac: string
9106              the main macaddr string
9107
9108       vlan-table: array of int
9109              a list of active vlan id
9110
9111       unicast-table: array of string
9112              a list of unicast macaddr string
9113
9114       multicast-table: array of string
9115              a list of multicast macaddr string
9116
9117   Since
9118       1.6
9119
9120   query-rx-filter (Command)
9121       Return rx-filter information for all NICs (or for the given NIC).
9122
9123   Arguments
9124       name: string (optional)
9125              net client name
9126
9127   Returns
9128       list of RxFilterInfo for all NICs (or for the given NIC).   Returns  an
9129       error  if  the  given  name doesn't exist, or given NIC doesn't support
9130       rx-filter querying, or given net client isn't a NIC.
9131
9132   Since
9133       1.6
9134
9135   Example
9136          -> { "execute": "query-rx-filter", "arguments": { "name": "vnet0" } }
9137          <- { "return": [
9138                  {
9139                      "promiscuous": true,
9140                      "name": "vnet0",
9141                      "main-mac": "52:54:00:12:34:56",
9142                      "unicast": "normal",
9143                      "vlan": "normal",
9144                      "vlan-table": [
9145                          4,
9146                          0
9147                      ],
9148                      "unicast-table": [
9149                      ],
9150                      "multicast": "normal",
9151                      "multicast-overflow": false,
9152                      "unicast-overflow": false,
9153                      "multicast-table": [
9154                          "01:00:5e:00:00:01",
9155                          "33:33:00:00:00:01",
9156                          "33:33:ff:12:34:56"
9157                      ],
9158                      "broadcast-allowed": false
9159                  }
9160                ]
9161             }
9162
9163   NIC_RX_FILTER_CHANGED (Event)
9164       Emitted once until the 'query-rx-filter' command is executed, the first
9165       event will always be emitted
9166
9167   Arguments
9168       name: string (optional)
9169              net client name
9170
9171       path: string
9172              device path
9173
9174   Since
9175       1.6
9176
9177   Example
9178          <- { "event": "NIC_RX_FILTER_CHANGED",
9179               "data": { "name": "vnet0",
9180                         "path": "/machine/peripheral/vnet0/virtio-backend" },
9181               "timestamp": { "seconds": 1368697518, "microseconds": 326866 } }
9182             }
9183
9184   AnnounceParameters (Object)
9185       Parameters for self-announce timers
9186
9187   Members
9188       initial: int
9189              Initial  delay  (in  ms)  before sending the first GARP/RARP an‐
9190              nouncement
9191
9192       max: int
9193              Maximum delay (in ms) between GARP/RARP announcement packets
9194
9195       rounds: int
9196              Number of self-announcement attempts
9197
9198       step: int
9199              Delay increase (in ms) after each self-announcement attempt
9200
9201       interfaces: array of string (optional)
9202              An optional list of interface names,  which  restricts  the  an‐
9203              nouncement to the listed interfaces. (Since 4.1)
9204
9205       id: string (optional)
9206              A name to be used to identify an instance of announce-timers and
9207              to allow it to modified later.  Not for use as part of  the  mi‐
9208              gration parameters. (Since 4.1)
9209
9210   Since
9211       4.0
9212
9213   announce-self (Command)
9214       Trigger generation of broadcast RARP frames to update network switches.
9215       This can be useful when network bonds fail-over the active slave.
9216
9217   Arguments
9218       The members of AnnounceParameters
9219
9220   Example
9221          -> { "execute": "announce-self",
9222               "arguments": {
9223                   "initial": 50, "max": 550, "rounds": 10, "step": 50,
9224                   "interfaces": ["vn2", "vn3"], "id": "bob" } }
9225          <- { "return": {} }
9226
9227   Since
9228       4.0
9229
9230   FAILOVER_NEGOTIATED (Event)
9231       Emitted when VIRTIO_NET_F_STANDBY was enabled during  feature  negotia‐
9232       tion.   Failover primary devices which were hidden (not hotplugged when
9233       requested) before will now be hotplugged by the virtio-net standby  de‐
9234       vice.
9235
9236       device-id: QEMU device id of the unplugged device
9237
9238   Arguments
9239       device-id: string
9240              Not documented
9241
9242   Since
9243       4.2
9244
9245   Example
9246          <- { "event": "FAILOVER_NEGOTIATED",
9247               "data": "net1" }
9248

RDMA DEVICE

9250   RDMA_GID_STATUS_CHANGED (Event)
9251       Emitted when guest driver adds/deletes GID to/from device
9252
9253   Arguments
9254       netdev: string
9255              RoCE Network Device name
9256
9257       gid-status: boolean
9258              Add or delete indication
9259
9260       subnet-prefix: int
9261              Subnet Prefix
9262
9263       interface-id: int
9264              Not documented
9265       interface-id : Interface ID
9266
9267   Since
9268       4.0
9269
9270   Example
9271          <- {"timestamp": {"seconds": 1541579657, "microseconds": 986760},
9272              "event": "RDMA_GID_STATUS_CHANGED",
9273              "data":
9274                  {"netdev": "bridge0",
9275                  "interface-id": 15880512517475447892,
9276                  "gid-status": true,
9277                  "subnet-prefix": 33022}}
9278

ROCKER SWITCH DEVICE

9280   RockerSwitch (Object)
9281       Rocker switch information.
9282
9283   Members
9284       name: string
9285              switch name
9286
9287       id: int
9288              switch ID
9289
9290       ports: int
9291              number of front-panel ports
9292
9293   Since
9294       2.4
9295
9296   query-rocker (Command)
9297       Return rocker switch information.
9298
9299   Arguments
9300       name: string
9301              Not documented
9302
9303   Returns
9304       Rocker information
9305
9306   Since
9307       2.4
9308
9309   Example
9310          -> { "execute": "query-rocker", "arguments": { "name": "sw1" } }
9311          <- { "return": {"name": "sw1", "ports": 2, "id": 1327446905938}}
9312
9313   RockerPortDuplex (Enum)
9314       An eumeration of port duplex states.
9315
9316   Values
9317       half   half duplex
9318
9319       full   full duplex
9320
9321   Since
9322       2.4
9323
9324   RockerPortAutoneg (Enum)
9325       An eumeration of port autoneg states.
9326
9327   Values
9328       off    autoneg is off
9329
9330       on     autoneg is on
9331
9332   Since
9333       2.4
9334
9335   RockerPort (Object)
9336       Rocker switch port information.
9337
9338   Members
9339       name: string
9340              port name
9341
9342       enabled: boolean
9343              port is enabled for I/O
9344
9345       link-up: boolean
9346              physical link is UP on port
9347
9348       speed: int
9349              port link speed in Mbps
9350
9351       duplex: RockerPortDuplex
9352              port link duplex
9353
9354       autoneg: RockerPortAutoneg
9355              port link autoneg
9356
9357   Since
9358       2.4
9359
9360   query-rocker-ports (Command)
9361       Return rocker switch port information.
9362
9363   Arguments
9364       name: string
9365              Not documented
9366
9367   Returns
9368       a list of RockerPort information
9369
9370   Since
9371       2.4
9372
9373   Example
9374          -> { "execute": "query-rocker-ports", "arguments": { "name": "sw1" } }
9375          <- { "return": [ {"duplex": "full", "enabled": true, "name": "sw1.1",
9376                            "autoneg": "off", "link-up": true, "speed": 10000},
9377                           {"duplex": "full", "enabled": true, "name": "sw1.2",
9378                            "autoneg": "off", "link-up": true, "speed": 10000}
9379             ]}
9380
9381   RockerOfDpaFlowKey (Object)
9382       Rocker switch OF-DPA flow key
9383
9384   Members
9385       priority: int
9386              key priority, 0 being lowest priority
9387
9388       tbl-id: int
9389              flow table ID
9390
9391       in-pport: int (optional)
9392              physical input port
9393
9394       tunnel-id: int (optional)
9395              tunnel ID
9396
9397       vlan-id: int (optional)
9398              VLAN ID
9399
9400       eth-type: int (optional)
9401              Ethernet header type
9402
9403       eth-src: string (optional)
9404              Ethernet header source MAC address
9405
9406       eth-dst: string (optional)
9407              Ethernet header destination MAC address
9408
9409       ip-proto: int (optional)
9410              IP Header protocol field
9411
9412       ip-tos: int (optional)
9413              IP header TOS field
9414
9415       ip-dst: string (optional)
9416              IP header destination address
9417
9418   Note
9419       optional  members  may  or  may not appear in the flow key depending if
9420       they're relevant to the flow key.
9421
9422   Since
9423       2.4
9424
9425   RockerOfDpaFlowMask (Object)
9426       Rocker switch OF-DPA flow mask
9427
9428   Members
9429       in-pport: int (optional)
9430              physical input port
9431
9432       tunnel-id: int (optional)
9433              tunnel ID
9434
9435       vlan-id: int (optional)
9436              VLAN ID
9437
9438       eth-src: string (optional)
9439              Ethernet header source MAC address
9440
9441       eth-dst: string (optional)
9442              Ethernet header destination MAC address
9443
9444       ip-proto: int (optional)
9445              IP Header protocol field
9446
9447       ip-tos: int (optional)
9448              IP header TOS field
9449
9450   Note
9451       optional members may or may not appear in the flow  mask  depending  if
9452       they're relevant to the flow mask.
9453
9454   Since
9455       2.4
9456
9457   RockerOfDpaFlowAction (Object)
9458       Rocker switch OF-DPA flow action
9459
9460   Members
9461       goto-tbl: int (optional)
9462              next table ID
9463
9464       group-id: int (optional)
9465              group ID
9466
9467       tunnel-lport: int (optional)
9468              tunnel logical port ID
9469
9470       vlan-id: int (optional)
9471              VLAN ID
9472
9473       new-vlan-id: int (optional)
9474              new VLAN ID
9475
9476       out-pport: int (optional)
9477              physical output port
9478
9479   Note
9480       optional  members may or may not appear in the flow action depending if
9481       they're relevant to the flow action.
9482
9483   Since
9484       2.4
9485
9486   RockerOfDpaFlow (Object)
9487       Rocker switch OF-DPA flow
9488
9489   Members
9490       cookie: int
9491              flow unique cookie ID
9492
9493       hits: int
9494              count of matches (hits) on flow
9495
9496       key: RockerOfDpaFlowKey
9497              flow key
9498
9499       mask: RockerOfDpaFlowMask
9500              flow mask
9501
9502       action: RockerOfDpaFlowAction
9503              flow action
9504
9505   Since
9506       2.4
9507
9508   query-rocker-of-dpa-flows (Command)
9509       Return rocker OF-DPA flow information.
9510
9511   Arguments
9512       name: string
9513              switch name
9514
9515       tbl-id: int (optional)
9516              flow table ID.  If tbl-id is not specified, returns flow  infor‐
9517              mation for all tables.
9518
9519   Returns
9520       rocker OF-DPA flow information
9521
9522   Since
9523       2.4
9524
9525   Example
9526          -> { "execute": "query-rocker-of-dpa-flows",
9527               "arguments": { "name": "sw1" } }
9528          <- { "return": [ {"key": {"in-pport": 0, "priority": 1, "tbl-id": 0},
9529                            "hits": 138,
9530                            "cookie": 0,
9531                            "action": {"goto-tbl": 10},
9532                            "mask": {"in-pport": 4294901760}
9533                           },
9534                           {...more...},
9535             ]}
9536
9537   RockerOfDpaGroup (Object)
9538       Rocker switch OF-DPA group
9539
9540   Members
9541       id: int
9542              group unique ID
9543
9544       type: int
9545              group type
9546
9547       vlan-id: int (optional)
9548              VLAN ID
9549
9550       pport: int (optional)
9551              physical port number
9552
9553       index: int (optional)
9554              group index, unique with group type
9555
9556       out-pport: int (optional)
9557              output physical port number
9558
9559       group-id: int (optional)
9560              next group ID
9561
9562       set-vlan-id: int (optional)
9563              VLAN ID to set
9564
9565       pop-vlan: int (optional)
9566              pop VLAN headr from packet
9567
9568       group-ids: array of int (optional)
9569              list of next group IDs
9570
9571       set-eth-src: string (optional)
9572              set source MAC address in Ethernet header
9573
9574       set-eth-dst: string (optional)
9575              set destination MAC address in Ethernet header
9576
9577       ttl-check: int (optional)
9578              perform TTL check
9579
9580   Note
9581       optional  members  may  or  may  not  appear  in the group depending if
9582       they're relevant to the group type.
9583
9584   Since
9585       2.4
9586
9587   query-rocker-of-dpa-groups (Command)
9588       Return rocker OF-DPA group information.
9589
9590   Arguments
9591       name: string
9592              switch name
9593
9594       type: int (optional)
9595              group type.  If type is not specified, returns group information
9596              for all group types.
9597
9598   Returns
9599       rocker OF-DPA group information
9600
9601   Since
9602       2.4
9603
9604   Example
9605          -> { "execute": "query-rocker-of-dpa-groups",
9606               "arguments": { "name": "sw1" } }
9607          <- { "return": [ {"type": 0, "out-pport": 2,
9608                            "pport": 2, "vlan-id": 3841,
9609                            "pop-vlan": 1, "id": 251723778},
9610                           {"type": 0, "out-pport": 0,
9611                            "pport": 0, "vlan-id": 3841,
9612                            "pop-vlan": 1, "id": 251723776},
9613                           {"type": 0, "out-pport": 1,
9614                            "pport": 1, "vlan-id": 3840,
9615                            "pop-vlan": 1, "id": 251658241},
9616                           {"type": 0, "out-pport": 0,
9617                            "pport": 0, "vlan-id": 3840,
9618                            "pop-vlan": 1, "id": 251658240}
9619             ]}
9620

TPM (TRUSTED PLATFORM MODULE) DEVICES

9622   TpmModel (Enum)
9623       An enumeration of TPM models
9624
9625   Values
9626       tpm-tis
9627              TPM TIS model
9628
9629       tpm-crb
9630              TPM CRB model (since 2.12)
9631
9632       tpm-spapr
9633              TPM SPAPR model (since 5.0)
9634
9635   Since
9636       1.5
9637
9638   query-tpm-models (Command)
9639       Return a list of supported TPM models
9640
9641   Returns
9642       a list of TpmModel
9643
9644   Since
9645       1.5
9646
9647   Example
9648          -> { "execute": "query-tpm-models" }
9649          <- { "return": [ "tpm-tis", "tpm-crb", "tpm-spapr" ] }
9650
9651   TpmType (Enum)
9652       An enumeration of TPM types
9653
9654   Values
9655       passthrough
9656              TPM passthrough type
9657
9658       emulator
9659              Software Emulator TPM type Since: 2.11
9660
9661   Since
9662       1.5
9663
9664   query-tpm-types (Command)
9665       Return a list of supported TPM types
9666
9667   Returns
9668       a list of TpmType
9669
9670   Since
9671       1.5
9672
9673   Example
9674          -> { "execute": "query-tpm-types" }
9675          <- { "return": [ "passthrough", "emulator" ] }
9676
9677   TPMPassthroughOptions (Object)
9678       Information about the TPM passthrough type
9679
9680   Members
9681       path: string (optional)
9682              string describing the path used for accessing the TPM device
9683
9684       cancel-path: string (optional)
9685              string  showing  the TPM's sysfs cancel file for cancellation of
9686              TPM commands while they are executing
9687
9688   Since
9689       1.5
9690
9691   TPMEmulatorOptions (Object)
9692       Information about the TPM emulator type
9693
9694   Members
9695       chardev: string
9696              Name of a unix socket chardev
9697
9698   Since
9699       2.11
9700
9701   TpmTypeOptions (Object)
9702       A union referencing different TPM backend types' configuration options
9703
9704   Members
9705       type
9706
9707              • 'passthrough'  The   configuration   options   for   the   TPM
9708                passthrough type
9709
9710              • 'emulator'  The configuration options for TPM emulator backend
9711                type
9712
9713       data: TPMPassthroughOptions when type is "passthrough"
9714
9715       data: TPMEmulatorOptions when type is "emulator"
9716
9717   Since
9718       1.5
9719
9720   TPMInfo (Object)
9721       Information about the TPM
9722
9723   Members
9724       id: string
9725              The Id of the TPM
9726
9727       model: TpmModel
9728              The TPM frontend model
9729
9730       options: TpmTypeOptions
9731              The TPM (backend) type configuration options
9732
9733   Since
9734       1.5
9735
9736   query-tpm (Command)
9737       Return information about the TPM device
9738
9739   Returns
9740       TPMInfo on success
9741
9742   Since
9743       1.5
9744
9745   Example
9746          -> { "execute": "query-tpm" }
9747          <- { "return":
9748               [
9749                 { "model": "tpm-tis",
9750                   "options":
9751                     { "type": "passthrough",
9752                       "data":
9753                         { "cancel-path": "/sys/class/misc/tpm0/device/cancel",
9754                           "path": "/dev/tpm0"
9755                         }
9756                     },
9757                   "id": "tpm0"
9758                 }
9759               ]
9760             }
9761

REMOTE DESKTOP

9763   set_password (Command)
9764       Sets the password of a remote display session.
9765
9766   Arguments
9767       protocol: string
9768
9769              • 'vnc' to modify the VNC server password
9770
9771              • 'spice' to modify the Spice server password
9772
9773       password: string
9774              the new password
9775
9776       connected: string (optional)
9777              how to handle existing clients when changing the  password.   If
9778              nothing is specified, defaults to 'keep' 'fail' to fail the com‐
9779              mand if clients are connected 'disconnect' to disconnect  exist‐
9780              ing clients 'keep' to maintain existing clients
9781
9782   Returns
9783       • Nothing on success
9784
9785       • If Spice is not enabled, DeviceNotFound
9786
9787   Since
9788       0.14.0
9789
9790   Example
9791          -> { "execute": "set_password", "arguments": { "protocol": "vnc",
9792                                                         "password": "secret" } }
9793          <- { "return": {} }
9794
9795   expire_password (Command)
9796       Expire the password of a remote display server.
9797
9798   Arguments
9799       protocol: string
9800              the name of the remote display protocol 'vnc' or 'spice'
9801
9802       time: string
9803              when to expire the password.
9804
9805              • 'now' to expire the password immediately
9806
9807              • 'never' to cancel password expiration
9808
9809              • '+INT' where INT is the number of seconds from now (integer)
9810
9811              • 'INT' where INT is the absolute time in seconds
9812
9813   Returns
9814       • Nothing on success
9815
9816       • If protocol is 'spice' and Spice is not active, DeviceNotFound
9817
9818   Since
9819       0.14.0
9820
9821   Notes
9822       Time is relative to the server and currently there is no way to coordi‐
9823       nate server time with client time.  It is not recommended  to  use  the
9824       absolute  time version of the time parameter unless you're sure you are
9825       on the same machine as the QEMU instance.
9826
9827   Example
9828          -> { "execute": "expire_password", "arguments": { "protocol": "vnc",
9829                                                            "time": "+60" } }
9830          <- { "return": {} }
9831
9832   screendump (Command)
9833       Write a PPM of the VGA screen to a file.
9834
9835   Arguments
9836       filename: string
9837              the path of a new PPM file to store the image
9838
9839       device: string (optional)
9840              ID of the display device that should be dumped. If this  parame‐
9841              ter is missing, the primary display will be used. (Since 2.12)
9842
9843       head: int (optional)
9844              head  to use in case the device supports multiple heads. If this
9845              parameter is missing, head #0 will be used. Also note  that  the
9846              head  can  only  be specified in conjunction with the device ID.
9847              (Since 2.12)
9848
9849   Returns
9850       Nothing on success
9851
9852   Since
9853       0.14.0
9854
9855   Example
9856          -> { "execute": "screendump",
9857               "arguments": { "filename": "/tmp/image" } }
9858          <- { "return": {} }
9859
9860   Spice
9861   SpiceBasicInfo (Object)
9862       The basic information for SPICE network connection
9863
9864   Members
9865       host: string
9866              IP address
9867
9868       port: string
9869              port number
9870
9871       family: NetworkAddressFamily
9872              address family
9873
9874   Since
9875       2.1
9876
9877   If
9878       defined(CONFIG_SPICE).SS SpiceServerInfo (Object)
9879
9880       Information about a SPICE server
9881
9882   Members
9883       auth: string (optional)
9884              authentication method
9885
9886       The members of SpiceBasicInfo
9887
9888   Since
9889       2.1
9890
9891   If
9892       defined(CONFIG_SPICE).SS SpiceChannel (Object)
9893
9894       Information about a SPICE client channel.
9895
9896   Members
9897       connection-id: int
9898              SPICE connection id number.  All channels with the same  id  be‐
9899              long to the same SPICE session.
9900
9901       channel-type: int
9902              SPICE  channel  type  number.   "1" is the main control channel,
9903              filter for this one if you want to track spice sessions only
9904
9905       channel-id: int
9906              SPICE channel ID number.  Usually "0", might be  different  when
9907              multiple  channels of the same type exist, such as multiple dis‐
9908              play channels in a multihead setup
9909
9910       tls: boolean
9911              true if the channel is encrypted, false otherwise.
9912
9913       The members of SpiceBasicInfo
9914
9915   Since
9916       0.14.0
9917
9918   If
9919       defined(CONFIG_SPICE).SS SpiceQueryMouseMode (Enum)
9920
9921       An enumeration of Spice mouse states.
9922
9923   Values
9924       client Mouse cursor position is determined by the client.
9925
9926       server Mouse cursor position is determined by the server.
9927
9928       unknown
9929              No information is available about mouse mode used by  the  spice
9930              server.
9931
9932   Note
9933       spice/enums.h has a SpiceMouseMode already, hence the name.
9934
9935   Since
9936       1.1
9937
9938   If
9939       defined(CONFIG_SPICE).SS SpiceInfo (Object)
9940
9941       Information about the SPICE session.
9942
9943   Members
9944       enabled: boolean
9945              true if the SPICE server is enabled, false otherwise
9946
9947       migrated: boolean
9948              true  if  the last guest migration completed and spice migration
9949              had completed as well. false otherwise. (since 1.4)
9950
9951       host: string (optional)
9952              The hostname the SPICE server is bound to.  This depends on  the
9953              name resolution on the host and may be an IP address.
9954
9955       port: int (optional)
9956              The SPICE server's port number.
9957
9958       compiled-version: string (optional)
9959              SPICE server version.
9960
9961       tls-port: int (optional)
9962              The SPICE server's TLS port number.
9963
9964       auth: string (optional)
9965              the current authentication type used by the server
9966
9967              • 'none'  if no authentication is being used
9968
9969              • 'spice'  uses  SASL or direct TLS authentication, depending on
9970                command line options
9971
9972       mouse-mode: SpiceQueryMouseMode
9973              The mode in which the mouse cursor is displayed  currently.  Can
9974              be  determined  by the client or the server, or unknown if spice
9975              server doesn't provide this information. (since: 1.1)
9976
9977       channels: array of SpiceChannel (optional)
9978              a list of SpiceChannel for each active spice channel
9979
9980   Since
9981       0.14.0
9982
9983   If
9984       defined(CONFIG_SPICE).SS query-spice (Command)
9985
9986       Returns information about the current SPICE server
9987
9988   Returns
9989       SpiceInfo
9990
9991   Since
9992       0.14.0
9993
9994   Example
9995          -> { "execute": "query-spice" }
9996          <- { "return": {
9997                   "enabled": true,
9998                   "auth": "spice",
9999                   "port": 5920,
10000                   "tls-port": 5921,
10001                   "host": "0.0.0.0",
10002                   "channels": [
10003                      {
10004                         "port": "54924",
10005                         "family": "ipv4",
10006                         "channel-type": 1,
10007                         "connection-id": 1804289383,
10008                         "host": "127.0.0.1",
10009                         "channel-id": 0,
10010                         "tls": true
10011                      },
10012                      {
10013                         "port": "36710",
10014                         "family": "ipv4",
10015                         "channel-type": 4,
10016                         "connection-id": 1804289383,
10017                         "host": "127.0.0.1",
10018                         "channel-id": 0,
10019                         "tls": false
10020                      },
10021                      [ ... more channels follow ... ]
10022                   ]
10023                }
10024             }
10025
10026   If
10027       defined(CONFIG_SPICE).SS SPICE_CONNECTED (Event)
10028
10029       Emitted when a SPICE client establishes a connection
10030
10031   Arguments
10032       server: SpiceBasicInfo
10033              server information
10034
10035       client: SpiceBasicInfo
10036              client information
10037
10038   Since
10039       0.14.0
10040
10041   Example
10042          <- { "timestamp": {"seconds": 1290688046, "microseconds": 388707},
10043               "event": "SPICE_CONNECTED",
10044               "data": {
10045                 "server": { "port": "5920", "family": "ipv4", "host": "127.0.0.1"},
10046                 "client": {"port": "52873", "family": "ipv4", "host": "127.0.0.1"}
10047             }}
10048
10049   If
10050       defined(CONFIG_SPICE).SS SPICE_INITIALIZED (Event)
10051
10052       Emitted after initial handshake and authentication takes place (if any)
10053       and the SPICE channel is up and running
10054
10055   Arguments
10056       server: SpiceServerInfo
10057              server information
10058
10059       client: SpiceChannel
10060              client information
10061
10062   Since
10063       0.14.0
10064
10065   Example
10066          <- { "timestamp": {"seconds": 1290688046, "microseconds": 417172},
10067               "event": "SPICE_INITIALIZED",
10068               "data": {"server": {"auth": "spice", "port": "5921",
10069                                   "family": "ipv4", "host": "127.0.0.1"},
10070                        "client": {"port": "49004", "family": "ipv4", "channel-type": 3,
10071                                   "connection-id": 1804289383, "host": "127.0.0.1",
10072                                   "channel-id": 0, "tls": true}
10073             }}
10074
10075   If
10076       defined(CONFIG_SPICE).SS SPICE_DISCONNECTED (Event)
10077
10078       Emitted when the SPICE connection is closed
10079
10080   Arguments
10081       server: SpiceBasicInfo
10082              server information
10083
10084       client: SpiceBasicInfo
10085              client information
10086
10087   Since
10088       0.14.0
10089
10090   Example
10091          <- { "timestamp": {"seconds": 1290688046, "microseconds": 388707},
10092               "event": "SPICE_DISCONNECTED",
10093               "data": {
10094                 "server": { "port": "5920", "family": "ipv4", "host": "127.0.0.1"},
10095                 "client": {"port": "52873", "family": "ipv4", "host": "127.0.0.1"}
10096             }}
10097
10098   If
10099       defined(CONFIG_SPICE).SS SPICE_MIGRATE_COMPLETED (Event)
10100
10101       Emitted when SPICE migration has completed
10102
10103   Since
10104       1.3
10105
10106   Example
10107          <- { "timestamp": {"seconds": 1290688046, "microseconds": 417172},
10108               "event": "SPICE_MIGRATE_COMPLETED" }
10109
10110   If
10111       defined(CONFIG_SPICE).SS VNC
10112
10113   VncBasicInfo (Object)
10114       The basic information for vnc network connection
10115
10116   Members
10117       host: string
10118              IP address
10119
10120       service: string
10121              The  service  name  of the vnc port. This may depend on the host
10122              system's service database so symbolic names should not be relied
10123              on.
10124
10125       family: NetworkAddressFamily
10126              address family
10127
10128       websocket: boolean
10129              true in case the socket is a websocket (since 2.3).
10130
10131   Since
10132       2.1
10133
10134   If
10135       defined(CONFIG_VNC).SS VncServerInfo (Object)
10136
10137       The network connection information for server
10138
10139   Members
10140       auth: string (optional)
10141              authentication  method  used  for  the plain (non-websocket) VNC
10142              server
10143
10144       The members of VncBasicInfo
10145
10146   Since
10147       2.1
10148
10149   If
10150       defined(CONFIG_VNC).SS VncClientInfo (Object)
10151
10152       Information about a connected VNC client.
10153
10154   Members
10155       x509_dname: string (optional)
10156              If x509 authentication is in use, the Distinguished Name of  the
10157              client.
10158
10159       sasl_username: string (optional)
10160              If SASL authentication is in use, the SASL username used for au‐
10161              thentication.
10162
10163       The members of VncBasicInfo
10164
10165   Since
10166       0.14.0
10167
10168   If
10169       defined(CONFIG_VNC).SS VncInfo (Object)
10170
10171       Information about the VNC session.
10172
10173   Members
10174       enabled: boolean
10175              true if the VNC server is enabled, false otherwise
10176
10177       host: string (optional)
10178              The hostname the VNC server is bound to.  This  depends  on  the
10179              name resolution on the host and may be an IP address.
10180
10181       family: NetworkAddressFamily (optional)
10182
10183              • 'ipv6' if the host is listening for IPv6 connections
10184
10185              • 'ipv4' if the host is listening for IPv4 connections
10186
10187              • 'unix' if the host is listening on a unix domain socket
10188
10189              • 'unknown' otherwise
10190
10191       service: string (optional)
10192              The  service name of the server's port.  This may depends on the
10193              host system's service database so symbolic names should  not  be
10194              relied on.
10195
10196       auth: string (optional)
10197              the current authentication type used by the server
10198
10199              • 'none' if no authentication is being used
10200
10201              • 'vnc' if VNC authentication is being used
10202
10203              • 'vencrypt+plain' if VEncrypt is used with plain text authenti‐
10204                cation
10205
10206              • 'vencrypt+tls+none' if VEncrypt is used with TLS  and  no  au‐
10207                thentication
10208
10209              • 'vencrypt+tls+vnc'  if  VEncrypt  is used with TLS and VNC au‐
10210                thentication
10211
10212              • 'vencrypt+tls+plain' if VEncrypt is used with  TLS  and  plain
10213                text auth
10214
10215              • 'vencrypt+x509+none' if VEncrypt is used with x509 and no auth
10216
10217              • 'vencrypt+x509+vnc' if VEncrypt is used with x509 and VNC auth
10218
10219              • 'vencrypt+x509+plain'  if VEncrypt is used with x509 and plain
10220                text auth
10221
10222              • 'vencrypt+tls+sasl' if VEncrypt is used with TLS and SASL auth
10223
10224              • 'vencrypt+x509+sasl' if VEncrypt is used with  x509  and  SASL
10225                auth
10226
10227       clients: array of VncClientInfo (optional)
10228              a list of VncClientInfo of all currently connected clients
10229
10230   Since
10231       0.14.0
10232
10233   If
10234       defined(CONFIG_VNC).SS VncPrimaryAuth (Enum)
10235
10236       vnc primary authentication method.
10237
10238   Values
10239       none   Not documented
10240
10241       vnc    Not documented
10242
10243       ra2    Not documented
10244
10245       ra2ne  Not documented
10246
10247       tight  Not documented
10248
10249       ultra  Not documented
10250
10251       tls    Not documented
10252
10253       vencrypt
10254              Not documented
10255
10256       sasl   Not documented
10257
10258   Since
10259       2.3
10260
10261   If
10262       defined(CONFIG_VNC).SS VncVencryptSubAuth (Enum)
10263
10264       vnc sub authentication method with vencrypt.
10265
10266   Values
10267       plain  Not documented
10268
10269       tls-none
10270              Not documented
10271
10272       x509-none
10273              Not documented
10274
10275       tls-vnc
10276              Not documented
10277
10278       x509-vnc
10279              Not documented
10280
10281       tls-plain
10282              Not documented
10283
10284       x509-plain
10285              Not documented
10286
10287       tls-sasl
10288              Not documented
10289
10290       x509-sasl
10291              Not documented
10292
10293   Since
10294       2.3
10295
10296   If
10297       defined(CONFIG_VNC).SS VncServerInfo2 (Object)
10298
10299       The network connection information for server
10300
10301   Members
10302       auth: VncPrimaryAuth
10303              The current authentication type used by the servers
10304
10305       vencrypt: VncVencryptSubAuth (optional)
10306              The  vencrypt  sub authentication type used by the servers, only
10307              specified in case auth == vencrypt.
10308
10309       The members of VncBasicInfo
10310
10311   Since
10312       2.9
10313
10314   If
10315       defined(CONFIG_VNC).SS VncInfo2 (Object)
10316
10317       Information about a vnc server
10318
10319   Members
10320       id: string
10321              vnc server name.
10322
10323       server: array of VncServerInfo2
10324              A list of VncBasincInfo describing all listening  sockets.   The
10325              list can be empty (in case the vnc server is disabled).  It also
10326              may have multiple entries: normal  +  websocket,  possibly  also
10327              ipv4 + ipv6 in the future.
10328
10329       clients: array of VncClientInfo
10330              A list of VncClientInfo of all currently connected clients.  The
10331              list can be empty, for obvious reasons.
10332
10333       auth: VncPrimaryAuth
10334              The current  authentication  type  used  by  the  non-websockets
10335              servers
10336
10337       vencrypt: VncVencryptSubAuth (optional)
10338              The vencrypt authentication type used by the servers, only spec‐
10339              ified in case auth == vencrypt.
10340
10341       display: string (optional)
10342              The display device the vnc server is linked to.
10343
10344   Since
10345       2.3
10346
10347   If
10348       defined(CONFIG_VNC).SS query-vnc (Command)
10349
10350       Returns information about the current VNC server
10351
10352   Returns
10353       VncInfo
10354
10355   Since
10356       0.14.0
10357
10358   Example
10359          -> { "execute": "query-vnc" }
10360          <- { "return": {
10361                   "enabled":true,
10362                   "host":"0.0.0.0",
10363                   "service":"50402",
10364                   "auth":"vnc",
10365                   "family":"ipv4",
10366                   "clients":[
10367                      {
10368                         "host":"127.0.0.1",
10369                         "service":"50401",
10370                         "family":"ipv4"
10371                      }
10372                   ]
10373                }
10374             }
10375
10376   If
10377       defined(CONFIG_VNC).SS query-vnc-servers (Command)
10378
10379       Returns a list of vnc servers.  The list can be empty.
10380
10381   Returns
10382       a list of VncInfo2
10383
10384   Since
10385       2.3
10386
10387   If
10388       defined(CONFIG_VNC).SS change-vnc-password (Command)
10389
10390       Change the VNC server password.
10391
10392   Arguments
10393       password: string
10394              the new password to use with VNC authentication
10395
10396   Since
10397       1.1
10398
10399   Notes
10400       An empty password in this command will set the password  to  the  empty
10401       string.  Existing clients are unaffected by executing this command.
10402
10403   If
10404       defined(CONFIG_VNC).SS VNC_CONNECTED (Event)
10405
10406       Emitted when a VNC client establishes a connection
10407
10408   Arguments
10409       server: VncServerInfo
10410              server information
10411
10412       client: VncBasicInfo
10413              client information
10414
10415   Note
10416       This  event  is emitted before any authentication takes place, thus the
10417       authentication ID is not provided
10418
10419   Since
10420       0.13.0
10421
10422   Example
10423          <- { "event": "VNC_CONNECTED",
10424               "data": {
10425                     "server": { "auth": "sasl", "family": "ipv4",
10426                                 "service": "5901", "host": "0.0.0.0" },
10427                     "client": { "family": "ipv4", "service": "58425",
10428                                 "host": "127.0.0.1" } },
10429               "timestamp": { "seconds": 1262976601, "microseconds": 975795 } }
10430
10431   If
10432       defined(CONFIG_VNC).SS VNC_INITIALIZED (Event)
10433
10434       Emitted after authentication takes place (if any) and the  VNC  session
10435       is made active
10436
10437   Arguments
10438       server: VncServerInfo
10439              server information
10440
10441       client: VncClientInfo
10442              client information
10443
10444   Since
10445       0.13.0
10446
10447   Example
10448          <-  { "event": "VNC_INITIALIZED",
10449                "data": {
10450                     "server": { "auth": "sasl", "family": "ipv4",
10451                                 "service": "5901", "host": "0.0.0.0"},
10452                     "client": { "family": "ipv4", "service": "46089",
10453                                 "host": "127.0.0.1", "sasl_username": "luiz" } },
10454                "timestamp": { "seconds": 1263475302, "microseconds": 150772 } }
10455
10456   If
10457       defined(CONFIG_VNC).SS VNC_DISCONNECTED (Event)
10458
10459       Emitted when the connection is closed
10460
10461   Arguments
10462       server: VncServerInfo
10463              server information
10464
10465       client: VncClientInfo
10466              client information
10467
10468   Since
10469       0.13.0
10470
10471   Example
10472          <- { "event": "VNC_DISCONNECTED",
10473               "data": {
10474                     "server": { "auth": "sasl", "family": "ipv4",
10475                                 "service": "5901", "host": "0.0.0.0" },
10476                     "client": { "family": "ipv4", "service": "58425",
10477                                 "host": "127.0.0.1", "sasl_username": "luiz" } },
10478               "timestamp": { "seconds": 1262976601, "microseconds": 975795 } }
10479
10480   If
10481       defined(CONFIG_VNC).SH INPUT
10482
10483   MouseInfo (Object)
10484       Information about a mouse device.
10485
10486   Members
10487       name: string
10488              the name of the mouse device
10489
10490       index: int
10491              the index of the mouse device
10492
10493       current: boolean
10494              true if this device is currently receiving mouse events
10495
10496       absolute: boolean
10497              true if this device supports absolute coordinates as input
10498
10499   Since
10500       0.14.0
10501
10502   query-mice (Command)
10503       Returns information about each active mouse device
10504
10505   Returns
10506       a list of MouseInfo for each device
10507
10508   Since
10509       0.14.0
10510
10511   Example
10512          -> { "execute": "query-mice" }
10513          <- { "return": [
10514                   {
10515                      "name":"QEMU Microsoft Mouse",
10516                      "index":0,
10517                      "current":false,
10518                      "absolute":false
10519                   },
10520                   {
10521                      "name":"QEMU PS/2 Mouse",
10522                      "index":1,
10523                      "current":true,
10524                      "absolute":true
10525                   }
10526                ]
10527             }
10528
10529   QKeyCode (Enum)
10530       An enumeration of key name.
10531
10532       This is used by the send-key command.
10533
10534   Values
10535       unmapped
10536              since 2.0
10537
10538       pause  since 2.0
10539
10540       ro     since 2.4
10541
10542       kp_comma
10543              since 2.4
10544
10545       kp_equals
10546              since 2.6
10547
10548       power  since 2.6
10549
10550       hiragana
10551              since 2.9
10552
10553       henkan since 2.9
10554
10555       yen    since 2.9
10556
10557       sleep  since 2.10
10558
10559       wake   since 2.10
10560
10561       audionext
10562              since 2.10
10563
10564       audioprev
10565              since 2.10
10566
10567       audiostop
10568              since 2.10
10569
10570       audioplay
10571              since 2.10
10572
10573       audiomute
10574              since 2.10
10575
10576       volumeup
10577              since 2.10
10578
10579       volumedown
10580              since 2.10
10581
10582       mediaselect
10583              since 2.10
10584
10585       mail   since 2.10
10586
10587       calculator
10588              since 2.10
10589
10590       computer
10591              since 2.10
10592
10593       ac_home
10594              since 2.10
10595
10596       ac_back
10597              since 2.10
10598
10599       ac_forward
10600              since 2.10
10601
10602       ac_refresh
10603              since 2.10
10604
10605       ac_bookmarks
10606              since 2.10
10607
10608       muhenkan
10609              since 2.12
10610
10611       katakanahiragana
10612              since 2.12
10613
10614       shift  Not documented
10615
10616       shift_r
10617              Not documented
10618
10619       alt    Not documented
10620
10621       alt_r  Not documented
10622
10623       ctrl   Not documented
10624
10625       ctrl_r Not documented
10626
10627       menu   Not documented
10628
10629       esc    Not documented
10630
10631       1      Not documented
10632
10633       2      Not documented
10634
10635       3      Not documented
10636
10637       4      Not documented
10638
10639       5      Not documented
10640
10641       6      Not documented
10642
10643       7      Not documented
10644
10645       8      Not documented
10646
10647       9      Not documented
10648
10649       0      Not documented
10650
10651       minus  Not documented
10652
10653       equal  Not documented
10654
10655       backspace
10656              Not documented
10657
10658       tab    Not documented
10659
10660       q      Not documented
10661
10662       w      Not documented
10663
10664       e      Not documented
10665
10666       r      Not documented
10667
10668       t      Not documented
10669
10670       y      Not documented
10671
10672       u      Not documented
10673
10674       i      Not documented
10675
10676       o      Not documented
10677
10678       p      Not documented
10679
10680       bracket_left
10681              Not documented
10682
10683       bracket_right
10684              Not documented
10685
10686       ret    Not documented
10687
10688       a      Not documented
10689
10690       s      Not documented
10691
10692       d      Not documented
10693
10694       f      Not documented
10695
10696       g      Not documented
10697
10698       h      Not documented
10699
10700       j      Not documented
10701
10702       k      Not documented
10703
10704       l      Not documented
10705
10706       semicolon
10707              Not documented
10708
10709       apostrophe
10710              Not documented
10711
10712       grave_accent
10713              Not documented
10714
10715       backslash
10716              Not documented
10717
10718       z      Not documented
10719
10720       x      Not documented
10721
10722       c      Not documented
10723
10724       v      Not documented
10725
10726       b      Not documented
10727
10728       n      Not documented
10729
10730       m      Not documented
10731
10732       comma  Not documented
10733
10734       dot    Not documented
10735
10736       slash  Not documented
10737
10738       asterisk
10739              Not documented
10740
10741       spc    Not documented
10742
10743       caps_lock
10744              Not documented
10745
10746       f1     Not documented
10747
10748       f2     Not documented
10749
10750       f3     Not documented
10751
10752       f4     Not documented
10753
10754       f5     Not documented
10755
10756       f6     Not documented
10757
10758       f7     Not documented
10759
10760       f8     Not documented
10761
10762       f9     Not documented
10763
10764       f10    Not documented
10765
10766       num_lock
10767              Not documented
10768
10769       scroll_lock
10770              Not documented
10771
10772       kp_divide
10773              Not documented
10774
10775       kp_multiply
10776              Not documented
10777
10778       kp_subtract
10779              Not documented
10780
10781       kp_add Not documented
10782
10783       kp_enter
10784              Not documented
10785
10786       kp_decimal
10787              Not documented
10788
10789       sysrq  Not documented
10790
10791       kp_0   Not documented
10792
10793       kp_1   Not documented
10794
10795       kp_2   Not documented
10796
10797       kp_3   Not documented
10798
10799       kp_4   Not documented
10800
10801       kp_5   Not documented
10802
10803       kp_6   Not documented
10804
10805       kp_7   Not documented
10806
10807       kp_8   Not documented
10808
10809       kp_9   Not documented
10810
10811       less   Not documented
10812
10813       f11    Not documented
10814
10815       f12    Not documented
10816
10817       print  Not documented
10818
10819       home   Not documented
10820
10821       pgup   Not documented
10822
10823       pgdn   Not documented
10824
10825       end    Not documented
10826
10827       left   Not documented
10828
10829       up     Not documented
10830
10831       down   Not documented
10832
10833       right  Not documented
10834
10835       insert Not documented
10836
10837       delete Not documented
10838
10839       stop   Not documented
10840
10841       again  Not documented
10842
10843       props  Not documented
10844
10845       undo   Not documented
10846
10847       front  Not documented
10848
10849       copy   Not documented
10850
10851       open   Not documented
10852
10853       paste  Not documented
10854
10855       find   Not documented
10856
10857       cut    Not documented
10858
10859       lf     Not documented
10860
10861       help   Not documented
10862
10863       meta_l Not documented
10864
10865       meta_r Not documented
10866
10867       compose
10868              Not documented
10869       'sysrq'  was  mistakenly  added  to  hack  around the fact that the ps2
10870       driver was not generating correct scancodes sequences when  'alt+print'
10871       was  pressed. This flaw is now fixed and the 'sysrq' key serves no fur‐
10872       ther purpose. Any further use of 'sysrq' will be transparently  changed
10873       to 'print', so they are effectively synonyms.
10874
10875   Since
10876       1.3.0
10877
10878   KeyValue (Object)
10879       Represents a keyboard key.
10880
10881   Members
10882       type   One of number, qcode
10883
10884       data: int when type is "number"
10885
10886       data: QKeyCode when type is "qcode"
10887
10888   Since
10889       1.3.0
10890
10891   send-key (Command)
10892       Send keys to guest.
10893
10894   Arguments
10895       keys: array of KeyValue
10896              An  array  of KeyValue elements. All KeyValues in this array are
10897              simultaneously sent to the guest.  A  KeyValue.number  value  is
10898              sent directly to the guest, while KeyValue.qcode must be a valid
10899              QKeyCode value
10900
10901       hold-time: int (optional)
10902              time to delay key up events, milliseconds. Defaults to 100
10903
10904   Returns
10905       • Nothing on success
10906
10907       • If key is unknown or redundant, InvalidParameter
10908
10909   Since
10910       1.3.0
10911
10912   Example
10913          -> { "execute": "send-key",
10914               "arguments": { "keys": [ { "type": "qcode", "data": "ctrl" },
10915                                        { "type": "qcode", "data": "alt" },
10916                                        { "type": "qcode", "data": "delete" } ] } }
10917          <- { "return": {} }
10918
10919   InputButton (Enum)
10920       Button of a pointer input device (mouse, tablet).
10921
10922   Values
10923       side   front side button of a 5-button mouse (since 2.9)
10924
10925       extra  rear side button of a 5-button mouse (since 2.9)
10926
10927       left   Not documented
10928
10929       middle Not documented
10930
10931       right  Not documented
10932
10933       wheel-up
10934              Not documented
10935
10936       wheel-down
10937              Not documented
10938
10939   Since
10940       2.0
10941
10942   InputAxis (Enum)
10943       Position axis of a pointer input device (mouse, tablet).
10944
10945   Values
10946       x      Not documented
10947
10948       y      Not documented
10949
10950   Since
10951       2.0
10952
10953   InputKeyEvent (Object)
10954       Keyboard input event.
10955
10956   Members
10957       key: KeyValue
10958              Which key this event is for.
10959
10960       down: boolean
10961              True for key-down and false for key-up events.
10962
10963   Since
10964       2.0
10965
10966   InputBtnEvent (Object)
10967       Pointer button input event.
10968
10969   Members
10970       button: InputButton
10971              Which button this event is for.
10972
10973       down: boolean
10974              True for key-down and false for key-up events.
10975
10976   Since
10977       2.0
10978
10979   InputMoveEvent (Object)
10980       Pointer motion input event.
10981
10982   Members
10983       axis: InputAxis
10984              Which axis is referenced by value.
10985
10986       value: int
10987              Pointer position.  For absolute coordinates the valid range is 0
10988              -> 0x7ffff
10989
10990   Since
10991       2.0
10992
10993   InputEvent (Object)
10994       Input event union.
10995
10996   Members
10997       type   the input type, one of:
10998
10999              • 'key': Input event of Keyboard
11000
11001              • 'btn': Input event of pointer buttons
11002
11003              • 'rel': Input event of relative pointer motion
11004
11005              • 'abs': Input event of absolute pointer motion
11006
11007       data: InputKeyEvent when type is "key"
11008
11009       data: InputBtnEvent when type is "btn"
11010
11011       data: InputMoveEvent when type is "rel"
11012
11013       data: InputMoveEvent when type is "abs"
11014
11015   Since
11016       2.0
11017
11018   input-send-event (Command)
11019       Send input event(s) to guest.
11020
11021       The  device  and head parameters can be used to send the input event to
11022       specific input devices in case (a) multiple input devices of  the  same
11023       kind are added to the virtual machine and (b) you have configured input
11024       routing (see docs/multiseat.txt) for those input devices.  The  parame‐
11025       ters work exactly like the device and head properties of input devices.
11026       If device is missing, only devices that have no  input  routing  config
11027       are  admissible.   If  device is specified, both input devices with and
11028       without input routing config are admissible,  but  devices  with  input
11029       routing config take precedence.
11030
11031   Arguments
11032       device: string (optional)
11033              display device to send event(s) to.
11034
11035       head: int (optional)
11036              head  to  send  event(s) to, in case the display device supports
11037              multiple scanouts.
11038
11039       events: array of InputEvent
11040              List of InputEvent union.
11041
11042   Returns
11043       Nothing on success.
11044
11045   Since
11046       2.6
11047
11048   Note
11049       The consoles are visible in the qom tree,  under  /backend/console[$in‐
11050       dex].  They  have a device link and head property, so it is possible to
11051       map which console belongs to which device and display.
11052
11053   Example
11054          1. Press left mouse button.
11055
11056          -> { "execute": "input-send-event",
11057              "arguments": { "device": "video0",
11058                             "events": [ { "type": "btn",
11059                             "data" : { "down": true, "button": "left" } } ] } }
11060          <- { "return": {} }
11061
11062          -> { "execute": "input-send-event",
11063              "arguments": { "device": "video0",
11064                             "events": [ { "type": "btn",
11065                             "data" : { "down": false, "button": "left" } } ] } }
11066          <- { "return": {} }
11067
11068          2. Press ctrl-alt-del.
11069
11070          -> { "execute": "input-send-event",
11071               "arguments": { "events": [
11072                  { "type": "key", "data" : { "down": true,
11073                    "key": {"type": "qcode", "data": "ctrl" } } },
11074                  { "type": "key", "data" : { "down": true,
11075                    "key": {"type": "qcode", "data": "alt" } } },
11076                  { "type": "key", "data" : { "down": true,
11077                    "key": {"type": "qcode", "data": "delete" } } } ] } }
11078          <- { "return": {} }
11079
11080          3. Move mouse pointer to absolute coordinates (20000, 400).
11081
11082          -> { "execute": "input-send-event" ,
11083            "arguments": { "events": [
11084                         { "type": "abs", "data" : { "axis": "x", "value" : 20000 } },
11085                         { "type": "abs", "data" : { "axis": "y", "value" : 400 } } ] } }
11086          <- { "return": {} }
11087
11088   GrabToggleKeys (Enum)
11089       Keys to toggle input-linux between host and guest.
11090
11091   Values
11092       ctrl-ctrl
11093              Not documented
11094
11095       alt-alt
11096              Not documented
11097
11098       shift-shift
11099              Not documented
11100
11101       meta-meta
11102              Not documented
11103
11104       scrolllock
11105              Not documented
11106
11107       ctrl-scrolllock
11108              Not documented
11109
11110   Since
11111       4.0
11112
11113   DisplayGTK (Object)
11114       GTK display options.
11115
11116   Members
11117       grab-on-hover: boolean (optional)
11118              Grab keyboard input on mouse hover.
11119
11120       zoom-to-fit: boolean (optional)
11121              Zoom guest display to fit into the host window.  When turned off
11122              the  host  window  will be resized instead.  In case the display
11123              device can notify the guest on window resizes (virtio-gpu)  this
11124              will default to "on", assuming the guest will resize the display
11125              to match the window size then.  Otherwise it defaults to  "off".
11126              Since 3.1
11127
11128   Since
11129       2.12
11130
11131   DisplayEGLHeadless (Object)
11132       EGL headless display options.
11133
11134   Members
11135       rendernode: string (optional)
11136              Which  DRM  render  node  should  be  used. Default is the first
11137              available node on the host.
11138
11139   Since
11140       3.1
11141
11142   DisplayGLMode (Enum)
11143       Display OpenGL mode.
11144
11145   Values
11146       off    Disable OpenGL (default).
11147
11148       on     Use OpenGL, pick context type automatically.   Would  better  be
11149              named  'auto' but is called 'on' for backward compatibility with
11150              bool type.
11151
11152       core   Use OpenGL with Core (desktop) Context.
11153
11154       es     Use OpenGL with ES (embedded systems) Context.
11155
11156   Since
11157       3.0
11158
11159   DisplayCurses (Object)
11160       Curses display options.
11161
11162   Members
11163       charset: string (optional)
11164              Font charset used by guest (default: CP437).
11165
11166   Since
11167       4.0
11168
11169   DisplayType (Enum)
11170       Display (user interface) type.
11171
11172   Values
11173       default
11174              The default user interface, selecting from the  first  available
11175              of gtk, sdl, cocoa, and vnc.
11176
11177       none   No  user interface or video output display. The guest will still
11178              see an emulated graphics card, but its output will not  be  dis‐
11179              played to the QEMU user.
11180
11181       gtk    The GTK user interface.
11182
11183       sdl    The SDL user interface.
11184
11185       egl-headless
11186              No  user interface, offload GL operations to a local DRI device.
11187              Graphical display need to be paired with VNC  or  Spice.  (Since
11188              3.1)
11189
11190       curses Display  video  output  via  curses.  For graphics device models
11191              which support a text mode, QEMU can display this output using  a
11192              curses/ncurses interface. Nothing is displayed when the graphics
11193              device is in graphical mode or if the graphics device  does  not
11194              support  a  text mode. Generally only the VGA device models sup‐
11195              port text mode.
11196
11197       cocoa  The Cocoa user interface.
11198
11199       spice-app
11200              Set up a Spice server and run the default associated application
11201              to  connect  to  it. The server will redirect the serial console
11202              and QEMU monitors. (Since 4.0)
11203
11204   Since
11205       2.12
11206
11207   DisplayOptions (Object)
11208       Display (user interface) options.
11209
11210   Members
11211       type: DisplayType
11212              Which DisplayType qemu should use.
11213
11214       full-screen: boolean (optional)
11215              Start user interface in fullscreen mode (default: off).
11216
11217       window-close: boolean (optional)
11218              Allow to quit qemu with window close button (default: on).
11219
11220       show-cursor: boolean (optional)
11221              Force showing the mouse cursor (default: off).  (since: 5.0)
11222
11223       gl: DisplayGLMode (optional)
11224              Enable OpenGL support (default: off).
11225
11226       The members of DisplayGTK when type is "gtk"
11227
11228       The members of DisplayCurses when type is "curses"
11229
11230       The members of DisplayEGLHeadless when type is "egl-headless"
11231
11232   Since
11233       2.12
11234
11235   query-display-options (Command)
11236       Returns information about display configuration
11237
11238   Returns
11239       DisplayOptions
11240
11241   Since
11242       3.1
11243

USER AUTHORIZATION

11245   QAuthZListPolicy (Enum)
11246       The authorization policy result
11247
11248   Values
11249       deny   deny access
11250
11251       allow  allow access
11252
11253   Since
11254       4.0
11255
11256   QAuthZListFormat (Enum)
11257       The authorization policy match format
11258
11259   Values
11260       exact  an exact string match
11261
11262       glob   string with ? and * shell wildcard support
11263
11264   Since
11265       4.0
11266
11267   QAuthZListRule (Object)
11268       A single authorization rule.
11269
11270   Members
11271       match: string
11272              a string or glob to match against a user identity
11273
11274       policy: QAuthZListPolicy
11275              the result to return if match evaluates to true
11276
11277       format: QAuthZListFormat (optional)
11278              the format of the match rule (default 'exact')
11279
11280   Since
11281       4.0
11282
11283   QAuthZListRuleListHack (Object)
11284       Not exposed via QMP; hack to generate QAuthZListRuleList for use inter‐
11285       nally by the code.
11286
11287   Members
11288       unused: array of QAuthZListRule
11289              Not documented
11290
11291   Since
11292       4.0
11293

MIGRATION

11295   MigrationStats (Object)
11296       Detailed migration status.
11297
11298   Members
11299       transferred: int
11300              amount of bytes already transferred to the target VM
11301
11302       remaining: int
11303              amount of bytes remaining to be transferred to the target VM
11304
11305       total: int
11306              total amount of bytes involved in the migration process
11307
11308       duplicate: int
11309              number of duplicate (zero) pages (since 1.2)
11310
11311       skipped: int
11312              number of skipped zero pages (since 1.5)
11313
11314       normal: int
11315              number of normal pages (since 1.2)
11316
11317       normal-bytes: int
11318              number of normal bytes sent (since 1.2)
11319
11320       dirty-pages-rate: int
11321              number of pages dirtied by second by the guest (since 1.3)
11322
11323       mbps: number
11324              throughput in megabits/sec. (since 1.6)
11325
11326       dirty-sync-count: int
11327              number of times that dirty ram was synchronized (since 2.1)
11328
11329       postcopy-requests: int
11330              The number of page requests received from the destination (since
11331              2.7)
11332
11333       page-size: int
11334              The number of bytes per page for the various page-based  statis‐
11335              tics (since 2.10)
11336
11337       multifd-bytes: int
11338              The number of bytes sent through multifd (since 3.0)
11339
11340       pages-per-second: int
11341              the number of memory pages transferred per second (Since 4.0)
11342
11343   Since
11344       0.14.0
11345
11346   XBZRLECacheStats (Object)
11347       Detailed XBZRLE migration cache statistics
11348
11349   Members
11350       cache-size: int
11351              XBZRLE cache size
11352
11353       bytes: int
11354              amount of bytes already transferred to the target VM
11355
11356       pages: int
11357              amount of pages transferred to the target VM
11358
11359       cache-miss: int
11360              number of cache miss
11361
11362       cache-miss-rate: number
11363              rate of cache miss (since 2.1)
11364
11365       encoding-rate: number
11366              rate of encoded bytes (since 5.1)
11367
11368       overflow: int
11369              number of overflows
11370
11371   Since
11372       1.2
11373
11374   CompressionStats (Object)
11375       Detailed migration compression statistics
11376
11377   Members
11378       pages: int
11379              amount of pages compressed and transferred to the target VM
11380
11381       busy: int
11382              count  of  times  that  no free thread was available to compress
11383              data
11384
11385       busy-rate: number
11386              rate of thread busy
11387
11388       compressed-size: int
11389              amount of bytes after compression
11390
11391       compression-rate: number
11392              rate of compressed size
11393
11394   Since
11395       3.1
11396
11397   MigrationStatus (Enum)
11398       An enumeration of migration status.
11399
11400   Values
11401       none   no migration has ever happened.
11402
11403       setup  migration process has been initiated.
11404
11405       cancelling
11406              in the process of cancelling migration.
11407
11408       cancelled
11409              cancelling migration is finished.
11410
11411       active in the process of doing migration.
11412
11413       postcopy-active
11414              like active, but now in postcopy mode. (since 2.5)
11415
11416       postcopy-paused
11417              during postcopy but paused. (since 3.0)
11418
11419       postcopy-recover
11420              trying to recover from a paused postcopy. (since 3.0)
11421
11422       completed
11423              migration is finished.
11424
11425       failed some error occurred during migration process.
11426
11427       colo   VM is in the process of fault tolerance, VM  can  not  get  into
11428              this  state  unless  colo  capability  is enabled for migration.
11429              (since 2.8)
11430
11431       pre-switchover
11432              Paused before device serialisation. (since 2.11)
11433
11434       device During device serialisation when pause-before-switchover is  en‐
11435              abled (since 2.11)
11436
11437       wait-unplug
11438              wait  for  device  unplug  request  by guest OS to be completed.
11439              (since 4.2)
11440
11441   Since
11442       2.3
11443
11444   VfioStats (Object)
11445       Detailed VFIO devices migration statistics
11446
11447   Members
11448       transferred: int
11449              amount of bytes transferred to the target VM by VFIO devices
11450
11451   Since
11452       5.2
11453
11454   MigrationInfo (Object)
11455       Information about current migration process.
11456
11457   Members
11458       status: MigrationStatus (optional)
11459              MigrationStatus describing the  current  migration  status.   If
11460              this field is not returned, no migration process has been initi‐
11461              ated
11462
11463       ram: MigrationStats (optional)
11464              MigrationStats containing detailed migration  status,  only  re‐
11465              turned if status is 'active' or 'completed'(since 1.2)
11466
11467       disk: MigrationStats (optional)
11468              MigrationStats  containing  detailed disk migration status, only
11469              returned if status is 'active' and it is a block migration
11470
11471       xbzrle-cache: XBZRLECacheStats (optional)
11472              XBZRLECacheStats containing detailed  XBZRLE  migration  statis‐
11473              tics,  only  returned if XBZRLE feature is on and status is 'ac‐
11474              tive' or 'completed' (since 1.2)
11475
11476       total-time: int (optional)
11477              total amount of milliseconds since migration started.  If migra‐
11478              tion has ended, it returns the total migration time. (since 1.2)
11479
11480       downtime: int (optional)
11481              only present when migration finishes correctly total downtime in
11482              milliseconds for the guest.  (since 1.3)
11483
11484       expected-downtime: int (optional)
11485              only present while migration is active expected downtime in mil‐
11486              liseconds for the guest in last walk of the dirty bitmap. (since
11487              1.3)
11488
11489       setup-time: int (optional)
11490              amount of setup time in milliseconds before the iterations begin
11491              but after the QMP command is issued. This is designed to provide
11492              an accounting of any activities (such as RDMA pinning) which may
11493              be expensive, but do not actually occur during the iterative mi‐
11494              gration rounds themselves. (since 1.6)
11495
11496       cpu-throttle-percentage: int (optional)
11497              percentage  of  time  guest  cpus  are  being  throttled  during
11498              auto-converge.  This  is  only  present  when  auto-converge has
11499              started throttling guest cpus. (Since 2.7)
11500
11501       error-desc: string (optional)
11502              the human readable error  description  string,  when  status  is
11503              'failed'. Clients should not attempt to parse the error strings.
11504              (Since 2.7)
11505
11506       postcopy-blocktime: int (optional)
11507              total time when all vCPU were blocked during postcopy  live  mi‐
11508              gration. This is only present when the postcopy-blocktime migra‐
11509              tion capability is enabled. (Since 3.0)
11510
11511       postcopy-vcpu-blocktime: array of int (optional)
11512              list of the postcopy blocktime per vCPU.  This is  only  present
11513              when  the  postcopy-blocktime  migration  capability is enabled.
11514              (Since 3.0)
11515
11516       compression: CompressionStats (optional)
11517              migration compression statistics, only returned  if  compression
11518              feature is on and status is 'active' or 'completed' (Since 3.1)
11519
11520       socket-address: array of SocketAddress (optional)
11521              Only used for tcp, to know what the real port is (Since 4.0)
11522
11523       vfio: VfioStats (optional)
11524              VfioStats containing detailed VFIO devices migration statistics,
11525              only returned if VFIO device is present, migration is  supported
11526              by all VFIO devices and status is 'active' or 'completed' (since
11527              5.2)
11528
11529   Since
11530       0.14.0
11531
11532   query-migrate (Command)
11533       Returns information about current migration process.  If  migration  is
11534       active  there will be another json-object with RAM migration status and
11535       if block migration is active another one with block migration status.
11536
11537   Returns
11538       MigrationInfo
11539
11540   Since
11541       0.14.0
11542
11543   Example
11544          1. Before the first migration
11545
11546          -> { "execute": "query-migrate" }
11547          <- { "return": {} }
11548
11549          2. Migration is done and has succeeded
11550
11551          -> { "execute": "query-migrate" }
11552          <- { "return": {
11553                  "status": "completed",
11554                  "total-time":12345,
11555                  "setup-time":12345,
11556                  "downtime":12345,
11557                  "ram":{
11558                    "transferred":123,
11559                    "remaining":123,
11560                    "total":246,
11561                    "duplicate":123,
11562                    "normal":123,
11563                    "normal-bytes":123456,
11564                    "dirty-sync-count":15
11565                  }
11566               }
11567             }
11568
11569          3. Migration is done and has failed
11570
11571          -> { "execute": "query-migrate" }
11572          <- { "return": { "status": "failed" } }
11573
11574          4. Migration is being performed and is not a block migration:
11575
11576          -> { "execute": "query-migrate" }
11577          <- {
11578                "return":{
11579                   "status":"active",
11580                   "total-time":12345,
11581                   "setup-time":12345,
11582                   "expected-downtime":12345,
11583                   "ram":{
11584                      "transferred":123,
11585                      "remaining":123,
11586                      "total":246,
11587                      "duplicate":123,
11588                      "normal":123,
11589                      "normal-bytes":123456,
11590                      "dirty-sync-count":15
11591                   }
11592                }
11593             }
11594
11595          5. Migration is being performed and is a block migration:
11596
11597          -> { "execute": "query-migrate" }
11598          <- {
11599                "return":{
11600                   "status":"active",
11601                   "total-time":12345,
11602                   "setup-time":12345,
11603                   "expected-downtime":12345,
11604                   "ram":{
11605                      "total":1057024,
11606                      "remaining":1053304,
11607                      "transferred":3720,
11608                      "duplicate":123,
11609                      "normal":123,
11610                      "normal-bytes":123456,
11611                      "dirty-sync-count":15
11612                   },
11613                   "disk":{
11614                      "total":20971520,
11615                      "remaining":20880384,
11616                      "transferred":91136
11617                   }
11618                }
11619             }
11620
11621          6. Migration is being performed and XBZRLE is active:
11622
11623          -> { "execute": "query-migrate" }
11624          <- {
11625                "return":{
11626                   "status":"active",
11627                   "total-time":12345,
11628                   "setup-time":12345,
11629                   "expected-downtime":12345,
11630                   "ram":{
11631                      "total":1057024,
11632                      "remaining":1053304,
11633                      "transferred":3720,
11634                      "duplicate":10,
11635                      "normal":3333,
11636                      "normal-bytes":3412992,
11637                      "dirty-sync-count":15
11638                   },
11639                   "xbzrle-cache":{
11640                      "cache-size":67108864,
11641                      "bytes":20971520,
11642                      "pages":2444343,
11643                      "cache-miss":2244,
11644                      "cache-miss-rate":0.123,
11645                      "encoding-rate":80.1,
11646                      "overflow":34434
11647                   }
11648                }
11649             }
11650
11651   MigrationCapability (Enum)
11652       Migration capabilities enumeration
11653
11654   Values
11655       xbzrle Migration supports xbzrle (Xor Based Zero Run Length  Encoding).
11656              This feature allows us to minimize migration traffic for certain
11657              work loads, by sending compressed difference of the pages
11658
11659       rdma-pin-all
11660              Controls whether or  not  the  entire  VM  memory  footprint  is
11661              mlock()'d  on  demand or all at once. Refer to docs/rdma.txt for
11662              usage.  Disabled by default. (since 2.0)
11663
11664       zero-blocks
11665              During storage migration encode blocks  of  zeroes  efficiently.
11666              This  essentially saves 1MB of zeroes per block on the wire. En‐
11667              abling requires source and target VM to support this feature. To
11668              enable  it  is sufficient to enable the capability on the source
11669              VM. The feature is disabled by default. (since 1.6)
11670
11671       compress
11672              Use multiple compression threads to accelerate  live  migration.
11673              This  feature can help to reduce the migration traffic, by send‐
11674              ing compressed pages. Please note that if  compress  and  xbzrle
11675              are  both  on, compress only takes effect in the ram bulk stage,
11676              after that, it will be disabled and only  xbzrle  takes  effect,
11677              this can help to minimize migration traffic. The feature is dis‐
11678              abled by default.  (since 2.4 )
11679
11680       events generate events for each migration state change (since 2.4 )
11681
11682       auto-converge
11683              If enabled, QEMU will automatically throttle down the  guest  to
11684              speed up convergence of RAM migration. (since 1.6)
11685
11686       postcopy-ram
11687              Start  executing  on  the migration target before all of RAM has
11688              been migrated, pulling the remaining pages along as needed.  The
11689              capacity must have the same setting on both source and target or
11690              migration will not even start. NOTE: If the migration fails dur‐
11691              ing postcopy the VM will fail.  (since 2.6)
11692
11693       x-colo If enabled, migration will never end, and the state of the VM on
11694              the primary side will be migrated continuously to the VM on sec‐
11695              ondary  side,  this process is called COarse-Grain LOck Stepping
11696              (COLO) for Non-stop Service. (since 2.8)
11697
11698       release-ram
11699              if enabled, qemu will free the migrated ram pages on the  source
11700              during postcopy-ram migration. (since 2.9)
11701
11702       block  If enabled, QEMU will also migrate the contents of all block de‐
11703              vices.  Default is disabled.  A possible alternative uses mirror
11704              jobs  to  a  builtin NBD server on the destination, which offers
11705              more flexibility.  (Since 2.10)
11706
11707       return-path
11708              If enabled, migration will use the return path even for precopy.
11709              (since 2.10)
11710
11711       pause-before-switchover
11712              Pause outgoing migration before serialising device state and be‐
11713              fore disabling block IO (since 2.11)
11714
11715       multifd
11716              Use more than one fd for migration (since 4.0)
11717
11718       dirty-bitmaps
11719              If enabled, QEMU will migrate named dirty bitmaps.  (since 2.12)
11720
11721       postcopy-blocktime
11722              Calculate downtime for postcopy live migration (since 3.0)
11723
11724       late-block-activate
11725              If enabled, the destination will not activate block devices (and
11726              thus  take  locks)  immediately at the end of migration.  (since
11727              3.0)
11728
11729       x-ignore-shared
11730              If enabled, QEMU will not migrate shared memory (since 4.0)
11731
11732       validate-uuid
11733              Send the UUID of the source to allow the destination  to  ensure
11734              it is the same. (since 4.2)
11735
11736   Since
11737       1.2
11738
11739   MigrationCapabilityStatus (Object)
11740       Migration capability information
11741
11742   Members
11743       capability: MigrationCapability
11744              capability enum
11745
11746       state: boolean
11747              capability state bool
11748
11749   Since
11750       1.2
11751
11752   migrate-set-capabilities (Command)
11753       Enable/Disable the following migration capabilities (like xbzrle)
11754
11755   Arguments
11756       capabilities: array of MigrationCapabilityStatus
11757              json array of capability modifications to make
11758
11759   Since
11760       1.2
11761
11762   Example
11763          -> { "execute": "migrate-set-capabilities" , "arguments":
11764               { "capabilities": [ { "capability": "xbzrle", "state": true } ] } }
11765
11766   query-migrate-capabilities (Command)
11767       Returns information about the current migration capabilities status
11768
11769   Returns
11770       MigrationCapabilitiesStatus
11771
11772   Since
11773       1.2
11774
11775   Example
11776          -> { "execute": "query-migrate-capabilities" }
11777          <- { "return": [
11778                {"state": false, "capability": "xbzrle"},
11779                {"state": false, "capability": "rdma-pin-all"},
11780                {"state": false, "capability": "auto-converge"},
11781                {"state": false, "capability": "zero-blocks"},
11782                {"state": false, "capability": "compress"},
11783                {"state": true, "capability": "events"},
11784                {"state": false, "capability": "postcopy-ram"},
11785                {"state": false, "capability": "x-colo"}
11786             ]}
11787
11788   MultiFDCompression (Enum)
11789       An enumeration of multifd compression methods.
11790
11791   Values
11792       none   no compression.
11793
11794       zlib   use zlib compression method.
11795
11796       zstd (If: defined(CONFIG_ZSTD))
11797              use zstd compression method.
11798
11799   Since
11800       5.0
11801
11802   BitmapMigrationBitmapAlias (Object)
11803   Members
11804       name: string
11805              The name of the bitmap.
11806
11807       alias: string
11808              An  alias name for migration (for example the bitmap name on the
11809              opposite site).
11810
11811   Since
11812       5.2
11813
11814   BitmapMigrationNodeAlias (Object)
11815       Maps a block node name and the bitmaps it has to aliases for dirty bit‐
11816       map migration.
11817
11818   Members
11819       node-name: string
11820              A block node name.
11821
11822       alias: string
11823              An  alias  block  node  name for migration (for example the node
11824              name on the opposite site).
11825
11826       bitmaps: array of BitmapMigrationBitmapAlias
11827              Mappings for the bitmaps on this node.
11828
11829   Since
11830       5.2
11831
11832   MigrationParameter (Enum)
11833       Migration parameters enumeration
11834
11835   Values
11836       announce-initial
11837              Initial delay (in milliseconds) before  sending  the  first  an‐
11838              nounce (Since 4.0)
11839
11840       announce-max
11841              Maximum delay (in milliseconds) between packets in the announce‐
11842              ment (Since 4.0)
11843
11844       announce-rounds
11845              Number of self-announce packets sent after migration (Since 4.0)
11846
11847       announce-step
11848              Increase in delay (in milliseconds) between  subsequent  packets
11849              in the announcement (Since 4.0)
11850
11851       compress-level
11852              Set the compression level to be used in live migration, the com‐
11853              pression level is an integer between 0 and 9, where 0  means  no
11854              compression,  1  means  the  best compression speed, and 9 means
11855              best compression ratio which will consume more CPU.
11856
11857       compress-threads
11858              Set compression thread count to be used in live  migration,  the
11859              compression thread count is an integer between 1 and 255.
11860
11861       compress-wait-thread
11862              Controls  behavior  when  all  compression threads are currently
11863              busy. If true (default), wait for a free compression  thread  to
11864              become  available; otherwise, send the page uncompressed. (Since
11865              3.1)
11866
11867       decompress-threads
11868              Set decompression thread count to be used in live migration, the
11869              decompression thread count is an integer between 1 and 255. Usu‐
11870              ally, decompression is at least 4 times as fast as  compression,
11871              so  set  the  decompress-threads to the number about 1/4 of com‐
11872              press-threads is adequate.
11873
11874       throttle-trigger-threshold
11875              The ratio of bytes_dirty_period and bytes_xfer_period to trigger
11876              throttling. It is expressed as percentage.  The default value is
11877              50. (Since 5.0)
11878
11879       cpu-throttle-initial
11880              Initial percentage of time guest cpus are throttled when  migra‐
11881              tion auto-converge is activated. The default value is 20. (Since
11882              2.7)
11883
11884       cpu-throttle-increment
11885              throttle percentage increase  each  time  auto-converge  detects
11886              that  migration is not making progress. The default value is 10.
11887              (Since 2.7)
11888
11889       cpu-throttle-tailslow
11890              Make CPU throttling slower at tail stage At the  tail  stage  of
11891              throttling,  the Guest is very sensitive to CPU percentage while
11892              the cpu-throttle -increment is excessive usually at tail  stage.
11893              If  this  parameter  is true, we will compute the ideal CPU per‐
11894              centage used by the Guest, which may exactly make the dirty rate
11895              match  the  dirty  rate threshold. Then we will choose a smaller
11896              throttle increment between the one specified by cpu-throttle-in‐
11897              crement  and  the one generated by ideal CPU percentage.  There‐
11898              fore, it is compatible to traditional throttling, meanwhile  the
11899              throttle  increment  won't  be excessive at tail stage.  The de‐
11900              fault value is false. (Since 5.1)
11901
11902       tls-creds
11903              ID of the 'tls-creds' object that provides credentials  for  es‐
11904              tablishing a TLS connection over the migration data channel.  On
11905              the outgoing side of the migration, the credentials must be  for
11906              a 'client' endpoint, while for the incoming side the credentials
11907              must be for a 'server' endpoint. Setting this  will  enable  TLS
11908              for all migrations. The default is unset, resulting in unsecured
11909              migration at the QEMU level. (Since 2.7)
11910
11911       tls-hostname
11912              hostname of the target host for the migration. This is  required
11913              when using x509 based TLS credentials and the migration URI does
11914              not already include a hostname. For  example  if  using  fd:  or
11915              exec: based migration, the hostname must be provided so that the
11916              server's x509 certificate identity can be validated. (Since 2.7)
11917
11918       tls-authz
11919              ID of the 'authz' object subclass that provides  access  control
11920              checking  of  the TLS x509 certificate distinguished name.  This
11921              object is only resolved at time of use, so can  be  deleted  and
11922              recreated  on  the fly while the migration server is active.  If
11923              missing, it will default to denying access (Since 4.0)
11924
11925       max-bandwidth
11926              to set maximum speed for migration. maximum speed in  bytes  per
11927              second. (Since 2.8)
11928
11929       downtime-limit
11930              set  maximum  tolerated downtime for migration. maximum downtime
11931              in milliseconds (Since 2.8)
11932
11933       x-checkpoint-delay
11934              The delay time (in ms) between two COLO checkpoints in  periodic
11935              mode. (Since 2.8)
11936
11937       block-incremental
11938              Affects  how  much  storage is migrated when the block migration
11939              capability is enabled.  When false, the entire  storage  backing
11940              chain  is  migrated  into  a flattened image at the destination;
11941              when true, only the active qcow2 layer is migrated and the  des‐
11942              tination  must  already have access to the same backing chain as
11943              was used on the source.  (since 2.10)
11944
11945       multifd-channels
11946              Number of channels used to migrate data in parallel. This is the
11947              same  number that the number of sockets used for migration.  The
11948              default value is 2 (since 4.0)
11949
11950       xbzrle-cache-size
11951              cache size to be used by XBZRLE migration.  It  needs  to  be  a
11952              multiple of the target page size and a power of 2 (Since 2.11)
11953
11954       max-postcopy-bandwidth
11955              Background  transfer  bandwidth  during postcopy.  Defaults to 0
11956              (unlimited).  In bytes per second.  (Since 3.0)
11957
11958       max-cpu-throttle
11959              maximum cpu throttle percentage.  Defaults to 99. (Since 3.1)
11960
11961       multifd-compression
11962              Which compression method to use.  Defaults to none. (Since 5.0)
11963
11964       multifd-zlib-level
11965              Set the compression level to be used in live migration, the com‐
11966              pression  level  is an integer between 0 and 9, where 0 means no
11967              compression, 1 means the best compression  speed,  and  9  means
11968              best compression ratio which will consume more CPU.  Defaults to
11969              1. (Since 5.0)
11970
11971       multifd-zstd-level
11972              Set the compression level to be used in live migration, the com‐
11973              pression  level is an integer between 0 and 20, where 0 means no
11974              compression, 1 means the best compression speed,  and  20  means
11975              best compression ratio which will consume more CPU.  Defaults to
11976              1. (Since 5.0)
11977
11978       block-bitmap-mapping
11979              Maps block nodes and bitmaps on them to aliases for the  purpose
11980              of  dirty bitmap migration.  Such aliases may for example be the
11981              corresponding names on the opposite site.  The mapping  must  be
11982              one-to-one,  but  not  necessarily  complete: On the source, un‐
11983              mapped bitmaps and all bitmaps on unmapped  nodes  will  be  ig‐
11984              nored.   On  the  destination, encountering an unmapped alias in
11985              the incoming migration stream will result in a report,  and  all
11986              further bitmap migration data will then be discarded.  Note that
11987              the destination does not know about bitmaps it does not receive,
11988              so there is no limitation or requirement regarding the number of
11989              bitmaps received, or how they are named, or on which nodes  they
11990              are  placed.   By  default  (when  this parameter has never been
11991              set), bitmap names are mapped to themselves.  Nodes  are  mapped
11992              to  their  block  device name if there is one, and to their node
11993              name otherwise. (Since 5.2)
11994
11995   Since
11996       2.4
11997
11998   MigrateSetParameters (Object)
11999   Members
12000       announce-initial: int (optional)
12001              Initial delay (in milliseconds) before  sending  the  first  an‐
12002              nounce (Since 4.0)
12003
12004       announce-max: int (optional)
12005              Maximum delay (in milliseconds) between packets in the announce‐
12006              ment (Since 4.0)
12007
12008       announce-rounds: int (optional)
12009              Number of self-announce packets sent after migration (Since 4.0)
12010
12011       announce-step: int (optional)
12012              Increase in delay (in milliseconds) between  subsequent  packets
12013              in the announcement (Since 4.0)
12014
12015       compress-level: int (optional)
12016              compression level
12017
12018       compress-threads: int (optional)
12019              compression thread count
12020
12021       compress-wait-thread: boolean (optional)
12022              Controls  behavior  when  all  compression threads are currently
12023              busy. If true (default), wait for a free compression  thread  to
12024              become  available; otherwise, send the page uncompressed. (Since
12025              3.1)
12026
12027       decompress-threads: int (optional)
12028              decompression thread count
12029
12030       throttle-trigger-threshold: int (optional)
12031              The ratio of bytes_dirty_period and bytes_xfer_period to trigger
12032              throttling. It is expressed as percentage.  The default value is
12033              50. (Since 5.0)
12034
12035       cpu-throttle-initial: int (optional)
12036              Initial percentage of time guest cpus are throttled when  migra‐
12037              tion  auto-converge  is  activated.   The  default  value is 20.
12038              (Since 2.7)
12039
12040       cpu-throttle-increment: int (optional)
12041              throttle percentage increase  each  time  auto-converge  detects
12042              that  migration is not making progress. The default value is 10.
12043              (Since 2.7)
12044
12045       cpu-throttle-tailslow: boolean (optional)
12046              Make CPU throttling slower at tail stage At the  tail  stage  of
12047              throttling,  the Guest is very sensitive to CPU percentage while
12048              the cpu-throttle -increment is excessive usually at tail  stage.
12049              If  this  parameter  is true, we will compute the ideal CPU per‐
12050              centage used by the Guest, which may exactly make the dirty rate
12051              match  the  dirty  rate threshold. Then we will choose a smaller
12052              throttle increment between the one specified by cpu-throttle-in‐
12053              crement  and  the one generated by ideal CPU percentage.  There‐
12054              fore, it is compatible to traditional throttling, meanwhile  the
12055              throttle  increment  won't  be excessive at tail stage.  The de‐
12056              fault value is false. (Since 5.1)
12057
12058       tls-creds: StrOrNull (optional)
12059              ID of the 'tls-creds' object that provides credentials  for  es‐
12060              tablishing  a TLS connection over the migration data channel. On
12061              the outgoing side of the migration, the credentials must be  for
12062              a 'client' endpoint, while for the incoming side the credentials
12063              must be for a 'server' endpoint. Setting  this  to  a  non-empty
12064              string  enables  TLS  for all migrations.  An empty string means
12065              that QEMU will use plain text mode for  migration,  rather  than
12066              TLS  (Since  2.9)  Previously  (since 2.7), this was reported by
12067              omitting tls-creds instead.
12068
12069       tls-hostname: StrOrNull (optional)
12070              hostname of the target host for the migration. This is  required
12071              when using x509 based TLS credentials and the migration URI does
12072              not already include a hostname. For  example  if  using  fd:  or
12073              exec: based migration, the hostname must be provided so that the
12074              server's x509 certificate identity can be validated. (Since 2.7)
12075              An empty string means that QEMU will use the hostname associated
12076              with the migration URI, if any. (Since  2.9)  Previously  (since
12077              2.7), this was reported by omitting tls-hostname instead.
12078
12079       max-bandwidth: int (optional)
12080              to  set  maximum speed for migration. maximum speed in bytes per
12081              second. (Since 2.8)
12082
12083       downtime-limit: int (optional)
12084              set maximum tolerated downtime for migration.  maximum  downtime
12085              in milliseconds (Since 2.8)
12086
12087       x-checkpoint-delay: int (optional)
12088              the delay time between two COLO checkpoints. (Since 2.8)
12089
12090       block-incremental: boolean (optional)
12091              Affects  how  much  storage is migrated when the block migration
12092              capability is enabled.  When false, the entire  storage  backing
12093              chain  is  migrated  into  a flattened image at the destination;
12094              when true, only the active qcow2 layer is migrated and the  des‐
12095              tination  must  already have access to the same backing chain as
12096              was used on the source.  (since 2.10)
12097
12098       multifd-channels: int (optional)
12099              Number of channels used to migrate data in parallel. This is the
12100              same  number that the number of sockets used for migration.  The
12101              default value is 2 (since 4.0)
12102
12103       xbzrle-cache-size: int (optional)
12104              cache size to be used by XBZRLE migration.  It  needs  to  be  a
12105              multiple of the target page size and a power of 2 (Since 2.11)
12106
12107       max-postcopy-bandwidth: int (optional)
12108              Background  transfer  bandwidth  during postcopy.  Defaults to 0
12109              (unlimited).  In bytes per second.  (Since 3.0)
12110
12111       max-cpu-throttle: int (optional)
12112              maximum cpu throttle  percentage.   The  default  value  is  99.
12113              (Since 3.1)
12114
12115       multifd-compression: MultiFDCompression (optional)
12116              Which compression method to use.  Defaults to none. (Since 5.0)
12117
12118       multifd-zlib-level: int (optional)
12119              Set the compression level to be used in live migration, the com‐
12120              pression level is an integer between 0 and 9, where 0  means  no
12121              compression,  1  means  the  best compression speed, and 9 means
12122              best compression ratio which will consume more CPU.  Defaults to
12123              1. (Since 5.0)
12124
12125       multifd-zstd-level: int (optional)
12126              Set the compression level to be used in live migration, the com‐
12127              pression level is an integer between 0 and 20, where 0 means  no
12128              compression,  1  means  the best compression speed, and 20 means
12129              best compression ratio which will consume more CPU.  Defaults to
12130              1. (Since 5.0)
12131
12132       block-bitmap-mapping: array of BitmapMigrationNodeAlias (optional)
12133              Maps  block nodes and bitmaps on them to aliases for the purpose
12134              of dirty bitmap migration.  Such aliases may for example be  the
12135              corresponding  names  on the opposite site.  The mapping must be
12136              one-to-one, but not necessarily complete:  On  the  source,  un‐
12137              mapped  bitmaps  and  all  bitmaps on unmapped nodes will be ig‐
12138              nored.  On the destination, encountering an  unmapped  alias  in
12139              the  incoming  migration stream will result in a report, and all
12140              further bitmap migration data will then be discarded.  Note that
12141              the destination does not know about bitmaps it does not receive,
12142              so there is no limitation or requirement regarding the number of
12143              bitmaps  received, or how they are named, or on which nodes they
12144              are placed.  By default (when  this  parameter  has  never  been
12145              set),  bitmap  names are mapped to themselves.  Nodes are mapped
12146              to their block device name if there is one, and  to  their  node
12147              name otherwise. (Since 5.2)
12148
12149       tls-authz: StrOrNull (optional)
12150              Not documented
12151
12152   Since
12153       2.4
12154
12155   migrate-set-parameters (Command)
12156       Set various migration parameters.
12157
12158   Arguments
12159       The members of MigrateSetParameters
12160
12161   Since
12162       2.4
12163
12164   Example
12165          -> { "execute": "migrate-set-parameters" ,
12166               "arguments": { "compress-level": 1 } }
12167
12168   MigrationParameters (Object)
12169       The optional members aren't actually optional.
12170
12171   Members
12172       announce-initial: int (optional)
12173              Initial  delay  (in  milliseconds)  before sending the first an‐
12174              nounce (Since 4.0)
12175
12176       announce-max: int (optional)
12177              Maximum delay (in milliseconds) between packets in the announce‐
12178              ment (Since 4.0)
12179
12180       announce-rounds: int (optional)
12181              Number of self-announce packets sent after migration (Since 4.0)
12182
12183       announce-step: int (optional)
12184              Increase  in  delay (in milliseconds) between subsequent packets
12185              in the announcement (Since 4.0)
12186
12187       compress-level: int (optional)
12188              compression level
12189
12190       compress-threads: int (optional)
12191              compression thread count
12192
12193       compress-wait-thread: boolean (optional)
12194              Controls behavior when all  compression  threads  are  currently
12195              busy.  If  true (default), wait for a free compression thread to
12196              become available; otherwise, send the page uncompressed.  (Since
12197              3.1)
12198
12199       decompress-threads: int (optional)
12200              decompression thread count
12201
12202       throttle-trigger-threshold: int (optional)
12203              The ratio of bytes_dirty_period and bytes_xfer_period to trigger
12204              throttling. It is expressed as percentage.  The default value is
12205              50. (Since 5.0)
12206
12207       cpu-throttle-initial: int (optional)
12208              Initial  percentage of time guest cpus are throttled when migra‐
12209              tion auto-converge is activated.  (Since 2.7)
12210
12211       cpu-throttle-increment: int (optional)
12212              throttle percentage increase  each  time  auto-converge  detects
12213              that migration is not making progress. (Since 2.7)
12214
12215       cpu-throttle-tailslow: boolean (optional)
12216              Make  CPU  throttling  slower at tail stage At the tail stage of
12217              throttling, the Guest is very sensitive to CPU percentage  while
12218              the  cpu-throttle -increment is excessive usually at tail stage.
12219              If this parameter is true, we will compute the  ideal  CPU  per‐
12220              centage used by the Guest, which may exactly make the dirty rate
12221              match the dirty rate threshold. Then we will  choose  a  smaller
12222              throttle increment between the one specified by cpu-throttle-in‐
12223              crement and the one generated by ideal CPU  percentage.   There‐
12224              fore,  it is compatible to traditional throttling, meanwhile the
12225              throttle increment won't be excessive at tail  stage.   The  de‐
12226              fault value is false. (Since 5.1)
12227
12228       tls-creds: string (optional)
12229              ID  of  the 'tls-creds' object that provides credentials for es‐
12230              tablishing a TLS connection over the migration data channel.  On
12231              the  outgoing side of the migration, the credentials must be for
12232              a 'client' endpoint, while for the incoming side the credentials
12233              must  be  for  a  'server' endpoint.  An empty string means that
12234              QEMU will use plain text mode for  migration,  rather  than  TLS
12235              (Since  2.7)  Note:  2.8  reports this by omitting tls-creds in‐
12236              stead.
12237
12238       tls-hostname: string (optional)
12239              hostname of the target host for the migration. This is  required
12240              when using x509 based TLS credentials and the migration URI does
12241              not already include a hostname. For  example  if  using  fd:  or
12242              exec: based migration, the hostname must be provided so that the
12243              server's x509 certificate identity can be validated. (Since 2.7)
12244              An empty string means that QEMU will use the hostname associated
12245              with the migration URI, if any. (Since 2.9)  Note:  2.8  reports
12246              this by omitting tls-hostname instead.
12247
12248       tls-authz: string (optional)
12249              ID  of  the 'authz' object subclass that provides access control
12250              checking of the TLS x509 certificate distinguished name.  (Since
12251              4.0)
12252
12253       max-bandwidth: int (optional)
12254              to  set  maximum speed for migration. maximum speed in bytes per
12255              second. (Since 2.8)
12256
12257       downtime-limit: int (optional)
12258              set maximum tolerated downtime for migration.  maximum  downtime
12259              in milliseconds (Since 2.8)
12260
12261       x-checkpoint-delay: int (optional)
12262              the delay time between two COLO checkpoints. (Since 2.8)
12263
12264       block-incremental: boolean (optional)
12265              Affects  how  much  storage is migrated when the block migration
12266              capability is enabled.  When false, the entire  storage  backing
12267              chain  is  migrated  into  a flattened image at the destination;
12268              when true, only the active qcow2 layer is migrated and the  des‐
12269              tination  must  already have access to the same backing chain as
12270              was used on the source.  (since 2.10)
12271
12272       multifd-channels: int (optional)
12273              Number of channels used to migrate data in parallel. This is the
12274              same  number that the number of sockets used for migration.  The
12275              default value is 2 (since 4.0)
12276
12277       xbzrle-cache-size: int (optional)
12278              cache size to be used by XBZRLE migration.  It  needs  to  be  a
12279              multiple of the target page size and a power of 2 (Since 2.11)
12280
12281       max-postcopy-bandwidth: int (optional)
12282              Background  transfer  bandwidth  during postcopy.  Defaults to 0
12283              (unlimited).  In bytes per second.  (Since 3.0)
12284
12285       max-cpu-throttle: int (optional)
12286              maximum cpu throttle percentage.  Defaults to 99.  (Since 3.1)
12287
12288       multifd-compression: MultiFDCompression (optional)
12289              Which compression method to use.  Defaults to none. (Since 5.0)
12290
12291       multifd-zlib-level: int (optional)
12292              Set the compression level to be used in live migration, the com‐
12293              pression  level  is an integer between 0 and 9, where 0 means no
12294              compression, 1 means the best compression  speed,  and  9  means
12295              best compression ratio which will consume more CPU.  Defaults to
12296              1. (Since 5.0)
12297
12298       multifd-zstd-level: int (optional)
12299              Set the compression level to be used in live migration, the com‐
12300              pression  level is an integer between 0 and 20, where 0 means no
12301              compression, 1 means the best compression speed,  and  20  means
12302              best compression ratio which will consume more CPU.  Defaults to
12303              1. (Since 5.0)
12304
12305       block-bitmap-mapping: array of BitmapMigrationNodeAlias (optional)
12306              Maps block nodes and bitmaps on them to aliases for the  purpose
12307              of  dirty bitmap migration.  Such aliases may for example be the
12308              corresponding names on the opposite site.  The mapping  must  be
12309              one-to-one,  but  not  necessarily  complete: On the source, un‐
12310              mapped bitmaps and all bitmaps on unmapped  nodes  will  be  ig‐
12311              nored.   On  the  destination, encountering an unmapped alias in
12312              the incoming migration stream will result in a report,  and  all
12313              further bitmap migration data will then be discarded.  Note that
12314              the destination does not know about bitmaps it does not receive,
12315              so there is no limitation or requirement regarding the number of
12316              bitmaps received, or how they are named, or on which nodes  they
12317              are  placed.   By  default  (when  this parameter has never been
12318              set), bitmap names are mapped to themselves.  Nodes  are  mapped
12319              to  their  block  device name if there is one, and to their node
12320              name otherwise. (Since 5.2)
12321
12322   Since
12323       2.4
12324
12325   query-migrate-parameters (Command)
12326       Returns information about the current migration parameters
12327
12328   Returns
12329       MigrationParameters
12330
12331   Since
12332       2.4
12333
12334   Example
12335          -> { "execute": "query-migrate-parameters" }
12336          <- { "return": {
12337                   "decompress-threads": 2,
12338                   "cpu-throttle-increment": 10,
12339                   "compress-threads": 8,
12340                   "compress-level": 1,
12341                   "cpu-throttle-initial": 20,
12342                   "max-bandwidth": 33554432,
12343                   "downtime-limit": 300
12344                }
12345             }
12346
12347   client_migrate_info (Command)
12348       Set migration information for remote display.  This  makes  the  server
12349       ask the client to automatically reconnect using the new parameters once
12350       migration finished successfully.  Only implemented for SPICE.
12351
12352   Arguments
12353       protocol: string
12354              must be "spice"
12355
12356       hostname: string
12357              migration target hostname
12358
12359       port: int (optional)
12360              spice tcp port for plaintext channels
12361
12362       tls-port: int (optional)
12363              spice tcp port for tls-secured channels
12364
12365       cert-subject: string (optional)
12366              server certificate subject
12367
12368   Since
12369       0.14.0
12370
12371   Example
12372          -> { "execute": "client_migrate_info",
12373               "arguments": { "protocol": "spice",
12374                              "hostname": "virt42.lab.kraxel.org",
12375                              "port": 1234 } }
12376          <- { "return": {} }
12377
12378   migrate-start-postcopy (Command)
12379       Followup to a migration command to switch  the  migration  to  postcopy
12380       mode.   The postcopy-ram capability must be set on both source and des‐
12381       tination before the original migration command.
12382
12383   Since
12384       2.5
12385
12386   Example
12387          -> { "execute": "migrate-start-postcopy" }
12388          <- { "return": {} }
12389
12390   MIGRATION (Event)
12391       Emitted when a migration event happens
12392
12393   Arguments
12394       status: MigrationStatus
12395              MigrationStatus describing the current migration status.
12396
12397   Since
12398       2.4
12399
12400   Example
12401          <- {"timestamp": {"seconds": 1432121972, "microseconds": 744001},
12402              "event": "MIGRATION",
12403              "data": {"status": "completed"} }
12404
12405   MIGRATION_PASS (Event)
12406       Emitted from the source side of a migration at the start of  each  pass
12407       (when it syncs the dirty bitmap)
12408
12409   Arguments
12410       pass: int
12411              An incrementing count (starting at 1 on the first pass)
12412
12413   Since
12414       2.6
12415
12416   Example
12417          { "timestamp": {"seconds": 1449669631, "microseconds": 239225},
12418            "event": "MIGRATION_PASS", "data": {"pass": 2} }
12419
12420   COLOMessage (Enum)
12421       The message transmission between Primary side and Secondary side.
12422
12423   Values
12424       checkpoint-ready
12425              Secondary VM (SVM) is ready for checkpointing
12426
12427       checkpoint-request
12428              Primary VM (PVM) tells SVM to prepare for checkpointing
12429
12430       checkpoint-reply
12431              SVM gets PVM's checkpoint request
12432
12433       vmstate-send
12434              VM's state will be sent by PVM.
12435
12436       vmstate-size
12437              The total size of VMstate.
12438
12439       vmstate-received
12440              VM's state has been received by SVM.
12441
12442       vmstate-loaded
12443              VM's state has been loaded by SVM.
12444
12445   Since
12446       2.8
12447
12448   COLOMode (Enum)
12449       The COLO current mode.
12450
12451   Values
12452       none   COLO is disabled.
12453
12454       primary
12455              COLO node in primary side.
12456
12457       secondary
12458              COLO node in slave side.
12459
12460   Since
12461       2.8
12462
12463   FailoverStatus (Enum)
12464       An enumeration of COLO failover status
12465
12466   Values
12467       none   no failover has ever happened
12468
12469       require
12470              got failover requirement but not handled
12471
12472       active in the process of doing failover
12473
12474       completed
12475              finish the process of failover
12476
12477       relaunch
12478              restart  the failover process, from 'none' -> 'completed' (Since
12479              2.9)
12480
12481   Since
12482       2.8
12483
12484   COLO_EXIT (Event)
12485       Emitted when VM finishes COLO mode due to some errors happening  or  at
12486       the request of users.
12487
12488   Arguments
12489       mode: COLOMode
12490              report COLO mode when COLO exited.
12491
12492       reason: COLOExitReason
12493              describes the reason for the COLO exit.
12494
12495   Since
12496       3.1
12497
12498   Example
12499          <- { "timestamp": {"seconds": 2032141960, "microseconds": 417172},
12500               "event": "COLO_EXIT", "data": {"mode": "primary", "reason": "request" } }
12501
12502   COLOExitReason (Enum)
12503       The reason for a COLO exit.
12504
12505   Values
12506       none   failover  has  never  happened. This state does not occur in the
12507              COLO_EXIT  event,  and  is  only  visible  in  the   result   of
12508              query-colo-status.
12509
12510       request
12511              COLO exit is due to an external request.
12512
12513       error  COLO exit is due to an internal error.
12514
12515       processing
12516              COLO is currently handling a failover (since 4.0).
12517
12518   Since
12519       3.1
12520
12521   x-colo-lost-heartbeat (Command)
12522       Tell qemu that heartbeat is lost, request it to do takeover procedures.
12523       If this command is sent to the PVM, the Primary  side  will  exit  COLO
12524       mode.   If  sent to the Secondary, the Secondary side will run failover
12525       work, then takes over server operation to become the service VM.
12526
12527   Since
12528       2.8
12529
12530   Example
12531          -> { "execute": "x-colo-lost-heartbeat" }
12532          <- { "return": {} }
12533
12534   migrate_cancel (Command)
12535       Cancel the current executing migration process.
12536
12537   Returns
12538       nothing on success
12539
12540   Notes
12541       This command succeeds even if there is no migration process running.
12542
12543   Since
12544       0.14.0
12545
12546   Example
12547          -> { "execute": "migrate_cancel" }
12548          <- { "return": {} }
12549
12550   migrate-continue (Command)
12551       Continue migration when it's in a paused state.
12552
12553   Arguments
12554       state: MigrationStatus
12555              The state the migration is currently expected to be in
12556
12557   Returns
12558       nothing on success
12559
12560   Since
12561       2.11
12562
12563   Example
12564          -> { "execute": "migrate-continue" , "arguments":
12565               { "state": "pre-switchover" } }
12566          <- { "return": {} }
12567
12568   migrate_set_downtime (Command)
12569       Set maximum tolerated downtime for migration.
12570
12571   Arguments
12572       value: number
12573              maximum downtime in seconds
12574
12575   Features
12576       deprecated
12577              This command is deprecated.   Use  'migrate-set-parameters'  in‐
12578              stead.
12579
12580   Returns
12581       nothing on success
12582
12583   Since
12584       0.14.0
12585
12586   Example
12587          -> { "execute": "migrate_set_downtime", "arguments": { "value": 0.1 } }
12588          <- { "return": {} }
12589
12590   migrate_set_speed (Command)
12591       Set maximum speed for migration.
12592
12593   Arguments
12594       value: int
12595              maximum speed in bytes per second.
12596
12597   Features
12598       deprecated
12599              This  command  is  deprecated.  Use 'migrate-set-parameters' in‐
12600              stead.
12601
12602   Returns
12603       nothing on success
12604
12605   Since
12606       0.14.0
12607
12608   Example
12609          -> { "execute": "migrate_set_speed", "arguments": { "value": 1024 } }
12610          <- { "return": {} }
12611
12612   migrate-set-cache-size (Command)
12613       Set cache size to be used by XBZRLE migration
12614
12615   Arguments
12616       value: int
12617              cache size in bytes
12618
12619   Features
12620       deprecated
12621              This command is deprecated.   Use  'migrate-set-parameters'  in‐
12622              stead.
12623       The  size  will  be  rounded down to the nearest power of 2.  The cache
12624       size can be modified before and during ongoing migration
12625
12626   Returns
12627       nothing on success
12628
12629   Since
12630       1.2
12631
12632   Example
12633          -> { "execute": "migrate-set-cache-size",
12634               "arguments": { "value": 536870912 } }
12635          <- { "return": {} }
12636
12637   query-migrate-cache-size (Command)
12638       Query migration XBZRLE cache size
12639
12640   Features
12641       deprecated
12642              This command is deprecated.  Use 'query-migrate-parameters'  in‐
12643              stead.
12644
12645   Returns
12646       XBZRLE cache size in bytes
12647
12648   Since
12649       1.2
12650
12651   Example
12652          -> { "execute": "query-migrate-cache-size" }
12653          <- { "return": 67108864 }
12654
12655   migrate (Command)
12656       Migrates the current running guest to another Virtual Machine.
12657
12658   Arguments
12659       uri: string
12660              the Uniform Resource Identifier of the destination VM
12661
12662       blk: boolean (optional)
12663              do block migration (full disk copy)
12664
12665       inc: boolean (optional)
12666              incremental disk copy migration
12667
12668       detach: boolean (optional)
12669              this  argument  exists only for compatibility reasons and is ig‐
12670              nored by QEMU
12671
12672       resume: boolean (optional)
12673              resume one paused migration, default "off". (since 3.0)
12674
12675   Returns
12676       nothing on success
12677
12678   Since
12679       0.14.0
12680
12681   Notes
12682       1. The 'query-migrate' command should  be  used  to  check  migration's
12683          progress and final result (this information is provided by the 'sta‐
12684          tus' member)
12685
12686       2. All boolean arguments default to false
12687
12688       3. The user Monitor's "detach" argument is invalid in  QMP  and  should
12689          not be used
12690
12691   Example
12692          -> { "execute": "migrate", "arguments": { "uri": "tcp:0:4446" } }
12693          <- { "return": {} }
12694
12695   migrate-incoming (Command)
12696       Start  an incoming migration, the qemu must have been started with -in‐
12697       coming defer
12698
12699   Arguments
12700       uri: string
12701              The Uniform Resource Identifier identifying the  source  or  ad‐
12702              dress to listen on
12703
12704   Returns
12705       nothing on success
12706
12707   Since
12708       2.3
12709
12710   Notes
12711       1. It's  a  bad  idea to use a string for the uri, but it needs to stay
12712          compatible with -incoming and the format of the uri is  already  ex‐
12713          posed above libvirt.
12714
12715       2. QEMU  must be started with -incoming defer to allow migrate-incoming
12716          to be used.
12717
12718       3. The uri format is the same as for -incoming
12719
12720   Example
12721          -> { "execute": "migrate-incoming",
12722               "arguments": { "uri": "tcp::4446" } }
12723          <- { "return": {} }
12724
12725   xen-save-devices-state (Command)
12726       Save the state of all devices to file. The RAM and the block devices of
12727       the VM are not saved by this command.
12728
12729   Arguments
12730       filename: string
12731              the file to save the state of the devices to as binary data. See
12732              xen-save-devices-state.txt for a description of the binary  for‐
12733              mat.
12734
12735       live: boolean (optional)
12736              Optional argument to ask QEMU to treat this command as part of a
12737              live migration. Default to true. (since 2.11)
12738
12739   Returns
12740       Nothing on success
12741
12742   Since
12743       1.1
12744
12745   Example
12746          -> { "execute": "xen-save-devices-state",
12747               "arguments": { "filename": "/tmp/save" } }
12748          <- { "return": {} }
12749
12750   xen-set-global-dirty-log (Command)
12751       Enable or disable the global dirty log mode.
12752
12753   Arguments
12754       enable: boolean
12755              true to enable, false to disable.
12756
12757   Returns
12758       nothing
12759
12760   Since
12761       1.3
12762
12763   Example
12764          -> { "execute": "xen-set-global-dirty-log",
12765               "arguments": { "enable": true } }
12766          <- { "return": {} }
12767
12768   xen-load-devices-state (Command)
12769       Load the state of all devices from file. The RAM and the block  devices
12770       of the VM are not loaded by this command.
12771
12772   Arguments
12773       filename: string
12774              the  file  to load the state of the devices from as binary data.
12775              See xen-save-devices-state.txt for a description of  the  binary
12776              format.
12777
12778   Since
12779       2.7
12780
12781   Example
12782          -> { "execute": "xen-load-devices-state",
12783               "arguments": { "filename": "/tmp/resume" } }
12784          <- { "return": {} }
12785
12786   xen-set-replication (Command)
12787       Enable or disable replication.
12788
12789   Arguments
12790       enable: boolean
12791              true to enable, false to disable.
12792
12793       primary: boolean
12794              true for primary or false for secondary.
12795
12796       failover: boolean (optional)
12797              true  to  do failover, false to stop. but cannot be specified if
12798              'enable' is true. default value is false.
12799
12800   Returns
12801       nothing.
12802
12803   Example
12804          -> { "execute": "xen-set-replication",
12805               "arguments": {"enable": true, "primary": false} }
12806          <- { "return": {} }
12807
12808   Since
12809       2.9
12810
12811   If
12812       defined(CONFIG_REPLICATION).SS ReplicationStatus (Object)
12813
12814       The result format for 'query-xen-replication-status'.
12815
12816   Members
12817       error: boolean
12818              true if an error happened, false if replication is normal.
12819
12820       desc: string (optional)
12821              the human readable  error  description  string,  when  error  is
12822              'true'.
12823
12824   Since
12825       2.9
12826
12827   If
12828       defined(CONFIG_REPLICATION).SS query-xen-replication-status (Command)
12829
12830       Query replication status while the vm is running.
12831
12832   Returns
12833       A ReplicationResult object showing the status.
12834
12835   Example
12836          -> { "execute": "query-xen-replication-status" }
12837          <- { "return": { "error": false } }
12838
12839   Since
12840       2.9
12841
12842   If
12843       defined(CONFIG_REPLICATION).SS xen-colo-do-checkpoint (Command)
12844
12845       Xen uses this command to notify replication to trigger a checkpoint.
12846
12847   Returns
12848       nothing.
12849
12850   Example
12851          -> { "execute": "xen-colo-do-checkpoint" }
12852          <- { "return": {} }
12853
12854   Since
12855       2.9
12856
12857   If
12858       defined(CONFIG_REPLICATION).SS COLOStatus (Object)
12859
12860       The result format for 'query-colo-status'.
12861
12862   Members
12863       mode: COLOMode
12864              COLO  running  mode.  If COLO is running, this field will return
12865              'primary' or 'secondary'.
12866
12867       last-mode: COLOMode
12868              COLO last running mode. If COLO is running, this field will  re‐
12869              turn  same like mode field, after failover we can use this field
12870              to get last colo mode. (since 4.0)
12871
12872       reason: COLOExitReason
12873              describes the reason for the COLO exit.
12874
12875   Since
12876       3.1
12877
12878   query-colo-status (Command)
12879       Query COLO status while the vm is running.
12880
12881   Returns
12882       A COLOStatus object showing the status.
12883
12884   Example
12885          -> { "execute": "query-colo-status" }
12886          <- { "return": { "mode": "primary", "reason": "request" } }
12887
12888   Since
12889       3.1
12890
12891   migrate-recover (Command)
12892       Provide a recovery migration stream URI.
12893
12894   Arguments
12895       uri: string
12896              the URI to be used for the recovery of migration stream.
12897
12898   Returns
12899       nothing.
12900
12901   Example
12902          -> { "execute": "migrate-recover",
12903               "arguments": { "uri": "tcp:192.168.1.200:12345" } }
12904          <- { "return": {} }
12905
12906   Since
12907       3.0
12908
12909   migrate-pause (Command)
12910       Pause a migration.  Currently it only supports postcopy.
12911
12912   Returns
12913       nothing.
12914
12915   Example
12916          -> { "execute": "migrate-pause" }
12917          <- { "return": {} }
12918
12919   Since
12920       3.0
12921
12922   UNPLUG_PRIMARY (Event)
12923       Emitted from source  side  of  a  migration  when  migration  state  is
12924       WAIT_UNPLUG.  Device  was  unplugged by guest operating system.  Device
12925       resources in QEMU are kept on standby to be able to re-plug it in  case
12926       of migration failure.
12927
12928   Arguments
12929       device-id: string
12930              QEMU device id of the unplugged device
12931
12932   Since
12933       4.2
12934
12935   Example
12936          {"event": "UNPLUG_PRIMARY", "data": {"device-id": "hostdev0"} }
12937
12938   DirtyRateStatus (Enum)
12939       An enumeration of dirtyrate status.
12940
12941   Values
12942       unstarted
12943              the dirtyrate thread has not been started.
12944
12945       measuring
12946              the dirtyrate thread is measuring.
12947
12948       measured
12949              the dirtyrate thread has measured and results are available.
12950
12951   Since
12952       5.2
12953
12954   DirtyRateInfo (Object)
12955       Information about current dirty page rate of vm.
12956
12957   Members
12958       dirty-rate: int (optional)
12959              an  estimate  of the dirty page rate of the VM in units of MB/s,
12960              present only when estimating the rate has completed.
12961
12962       status: DirtyRateStatus
12963              status containing dirtyrate query status includes 'unstarted' or
12964              'measuring' or 'measured'
12965
12966       start-time: int
12967              start time in units of second for calculation
12968
12969       calc-time: int
12970              time in units of second for sample dirty pages
12971
12972   Since
12973       5.2
12974
12975   calc-dirty-rate (Command)
12976       start calculating dirty page rate for vm
12977
12978   Arguments
12979       calc-time: int
12980              time in units of second for sample dirty pages
12981
12982   Since
12983       5.2
12984
12985   Example
12986          {"command": "calc-dirty-rate", "data": {"calc-time": 1} }
12987
12988   query-dirty-rate (Command)
12989       query dirty page rate in units of MB/s for vm
12990
12991   Since
12992       5.2
12993

TRANSACTIONS

12995   Abort (Object)
12996       This action can be used to test transaction failure.
12997
12998   Since
12999       1.6
13000
13001   ActionCompletionMode (Enum)
13002       An enumeration of Transactional completion modes.
13003
13004   Values
13005       individual
13006              Do  not  attempt to cancel any other Actions if any Actions fail
13007              after the Transaction request succeeds.  All  Actions  that  can
13008              complete  successfully  will  do  so  without waiting on others.
13009              This is the default.
13010
13011       grouped
13012              If any Action fails after the Transaction succeeds,  cancel  all
13013              Actions.  Actions do not complete until all Actions are ready to
13014              complete. May be rejected by Actions that do  not  support  this
13015              completion mode.
13016
13017   Since
13018       2.5
13019
13020   TransactionAction (Object)
13021       A  discriminated record of operations that can be performed with trans‐
13022       action. Action type can be:
13023
13024abort: since 1.6
13025
13026block-dirty-bitmap-add: since 2.5
13027
13028block-dirty-bitmap-remove: since 4.2
13029
13030block-dirty-bitmap-clear: since 2.5
13031
13032block-dirty-bitmap-enable: since 4.0
13033
13034block-dirty-bitmap-disable: since 4.0
13035
13036block-dirty-bitmap-merge: since 4.0
13037
13038blockdev-backup: since 2.3
13039
13040blockdev-snapshot: since 2.5
13041
13042blockdev-snapshot-internal-sync: since 1.7
13043
13044blockdev-snapshot-sync: since 1.1
13045
13046drive-backup: since 1.6
13047
13048   Members
13049       type   One of abort, block-dirty-bitmap-add, block-dirty-bitmap-remove,
13050              block-dirty-bitmap-clear,             block-dirty-bitmap-enable,
13051              block-dirty-bitmap-disable,   block-dirty-bitmap-merge,   block‐
13052              dev-backup,  blockdev-snapshot, blockdev-snapshot-internal-sync,
13053              blockdev-snapshot-sync, drive-backup
13054
13055       data: Abort when type is "abort"
13056
13057       data: BlockDirtyBitmapAdd when type is "block-dirty-bitmap-add"
13058
13059       data: BlockDirtyBitmap when type is "block-dirty-bitmap-remove"
13060
13061       data: BlockDirtyBitmap when type is "block-dirty-bitmap-clear"
13062
13063       data: BlockDirtyBitmap when type is "block-dirty-bitmap-enable"
13064
13065       data: BlockDirtyBitmap when type is "block-dirty-bitmap-disable"
13066
13067       data: BlockDirtyBitmapMerge when type is "block-dirty-bitmap-merge"
13068
13069       data: BlockdevBackup when type is "blockdev-backup"
13070
13071       data: BlockdevSnapshot when type is "blockdev-snapshot"
13072
13073       data: BlockdevSnapshotInternal when type  is  "blockdev-snapshot-inter‐
13074       nal-sync"
13075
13076       data: BlockdevSnapshotSync when type is "blockdev-snapshot-sync"
13077
13078       data: DriveBackup when type is "drive-backup"
13079
13080   Since
13081       1.1
13082
13083   TransactionProperties (Object)
13084       Optional arguments to modify the behavior of a Transaction.
13085
13086   Members
13087       completion-mode: ActionCompletionMode (optional)
13088              Controls  how  jobs launched asynchronously by Actions will com‐
13089              plete or fail as a group.  See ActionCompletionMode for details.
13090
13091   Since
13092       2.5
13093
13094   transaction (Command)
13095       Executes a number of transactionable QMP commands  atomically.  If  any
13096       operation  fails,  then the entire set of actions will be abandoned and
13097       the appropriate error returned.
13098
13099       For external snapshots, the dictionary contains the device, the file to
13100       use  for  the new snapshot, and the format.  The default format, if not
13101       specified, is qcow2.
13102
13103       Each new snapshot defaults to being created by QEMU  (wiping  any  con‐
13104       tents  if the file already exists), but it is also possible to reuse an
13105       externally-created file.  In the latter case, you  should  ensure  that
13106       the  new image file has the same contents as the current one; QEMU can‐
13107       not perform any meaningful check.  Typically this is achieved by  using
13108       the current image file as the backing file for the new image.
13109
13110       On failure, the original disks pre-snapshot attempt will be used.
13111
13112       For  internal  snapshots,  the  dictionary  contains the device and the
13113       snapshot's name.  If an internal snapshot matching name already exists,
13114       the  request will be rejected.  Only some image formats support it, for
13115       example, qcow2, rbd, and sheepdog.
13116
13117       On failure, qemu will try delete the newly created internal snapshot in
13118       the  transaction.   When  an I/O error occurs during deletion, the user
13119       needs to fix it later with qemu-img or other command.
13120
13121   Arguments
13122       actions: array of TransactionAction
13123              List of TransactionAction; information needed for the respective
13124              operations.
13125
13126       properties: TransactionProperties (optional)
13127              structure  of additional options to control the execution of the
13128              transaction. See TransactionProperties for additional detail.
13129
13130   Returns
13131       nothing on success
13132
13133       Errors depend on the operations of the transaction
13134
13135   Note
13136       The transaction aborts on the first failure.  Therefore, there will  be
13137       information  on  only  one failed operation returned in an error condi‐
13138       tion, and subsequent actions will not have been attempted.
13139
13140   Since
13141       1.1
13142
13143   Example
13144          -> { "execute": "transaction",
13145               "arguments": { "actions": [
13146                   { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd0",
13147                                               "snapshot-file": "/some/place/my-image",
13148                                               "format": "qcow2" } },
13149                   { "type": "blockdev-snapshot-sync", "data" : { "node-name": "myfile",
13150                                               "snapshot-file": "/some/place/my-image2",
13151                                               "snapshot-node-name": "node3432",
13152                                               "mode": "existing",
13153                                               "format": "qcow2" } },
13154                   { "type": "blockdev-snapshot-sync", "data" : { "device": "ide-hd1",
13155                                               "snapshot-file": "/some/place/my-image2",
13156                                               "mode": "existing",
13157                                               "format": "qcow2" } },
13158                   { "type": "blockdev-snapshot-internal-sync", "data" : {
13159                                               "device": "ide-hd2",
13160                                               "name": "snapshot0" } } ] } }
13161          <- { "return": {} }
13162

TRACING

13164   TraceEventState (Enum)
13165       State of a tracing event.
13166
13167   Values
13168       unavailable
13169              The event is statically disabled.
13170
13171       disabled
13172              The event is dynamically disabled.
13173
13174       enabled
13175              The event is dynamically enabled.
13176
13177   Since
13178       2.2
13179
13180   TraceEventInfo (Object)
13181       Information of a tracing event.
13182
13183   Members
13184       name: string
13185              Event name.
13186
13187       state: TraceEventState
13188              Tracing state.
13189
13190       vcpu: boolean
13191              Whether this is a per-vCPU event (since 2.7).
13192       An  event  is  per-vCPU  if  it  has  the  "vcpu"   property   in   the
13193       "trace-events" files.
13194
13195   Since
13196       2.2
13197
13198   trace-event-get-state (Command)
13199       Query the state of events.
13200
13201   Arguments
13202       name: string
13203              Event name pattern (case-sensitive glob).
13204
13205       vcpu: int (optional)
13206              The vCPU to query (any by default; since 2.7).
13207
13208   Returns
13209       a list of TraceEventInfo for the matching events
13210
13211       An event is returned if:
13212
13213       • its name matches the name pattern, and
13214
13215       • if vcpu is given, the event has the "vcpu" property.
13216
13217       Therefore,  if  vcpu  is  given, the operation will only match per-vCPU
13218       events, returning their state on the specified vCPU. Special  case:  if
13219       name  is  an exact match, vcpu is given and the event does not have the
13220       "vcpu" property, an error is returned.
13221
13222   Since
13223       2.2
13224
13225   Example
13226          -> { "execute": "trace-event-get-state",
13227               "arguments": { "name": "qemu_memalign" } }
13228          <- { "return": [ { "name": "qemu_memalign", "state": "disabled" } ] }
13229
13230   trace-event-set-state (Command)
13231       Set the dynamic tracing state of events.
13232
13233   Arguments
13234       name: string
13235              Event name pattern (case-sensitive glob).
13236
13237       enable: boolean
13238              Whether to enable tracing.
13239
13240       ignore-unavailable: boolean (optional)
13241              Do not match unavailable events with name.
13242
13243       vcpu: int (optional)
13244              The vCPU to act upon (all by default; since 2.7).
13245       An event's state is modified if: - its name matches the  name  pattern,
13246       and - if vcpu is given, the event has the "vcpu" property.
13247
13248       Therefore,  if  vcpu  is  given, the operation will only match per-vCPU
13249       events, setting their state on the specified  vCPU.  Special  case:  if
13250       name  is  an exact match, vcpu is given and the event does not have the
13251       "vcpu" property, an error is returned.
13252
13253   Since
13254       2.2
13255
13256   Example
13257          -> { "execute": "trace-event-set-state",
13258               "arguments": { "name": "qemu_memalign", "enable": "true" } }
13259          <- { "return": {} }
13260

QMP MONITOR CONTROL

13262   qmp_capabilities (Command)
13263       Enable QMP capabilities.
13264
13265       Arguments:
13266
13267   Arguments
13268       enable: array of QMPCapability (optional)
13269              An optional list of QMPCapability values to enable.  The  client
13270              must  not enable any capability that is not mentioned in the QMP
13271              greeting message.  If the field is not provided, it means no QMP
13272              capabilities will be enabled.  (since 2.12)
13273
13274   Example
13275          -> { "execute": "qmp_capabilities",
13276               "arguments": { "enable": [ "oob" ] } }
13277          <- { "return": {} }
13278
13279   Notes
13280       This  command is valid exactly when first connecting: it must be issued
13281       before any other command will be accepted, and will fail once the moni‐
13282       tor is accepting other commands. (see qemu docs/interop/qmp-spec.txt)
13283
13284       The  QMP  client needs to explicitly enable QMP capabilities, otherwise
13285       all the QMP capabilities will be turned off by default.
13286
13287   Since
13288       0.13
13289
13290   QMPCapability (Enum)
13291       Enumeration of capabilities to be advertised during initial client con‐
13292       nection, used for agreeing on particular QMP extension behaviors.
13293
13294   Values
13295       oob    QMP  ability  to support out-of-band requests.  (Please refer to
13296              qmp-spec.txt for more information on OOB)
13297
13298   Since
13299       2.12
13300
13301   VersionTriple (Object)
13302       A three-part version number.
13303
13304   Members
13305       major: int
13306              The major version number.
13307
13308       minor: int
13309              The minor version number.
13310
13311       micro: int
13312              The micro version number.
13313
13314   Since
13315       2.4
13316
13317   VersionInfo (Object)
13318       A description of QEMU's version.
13319
13320   Members
13321       qemu: VersionTriple
13322              The version of QEMU.  By current convention, a micro version  of
13323              50 signifies a development branch.  A micro version greater than
13324              or equal to 90 signifies a release candidate for the next  minor
13325              version.  A micro version of less than 50 signifies a stable re‐
13326              lease.
13327
13328       package: string
13329              QEMU will always set this field to an empty string.   Downstream
13330              versions of QEMU should set this to a non-empty string.  The ex‐
13331              act format depends on the downstream however  it  highly  recom‐
13332              mended that a unique name is used.
13333
13334   Since
13335       0.14.0
13336
13337   query-version (Command)
13338       Returns the current version of QEMU.
13339
13340   Returns
13341       A VersionInfo object describing the current version of QEMU.
13342
13343   Since
13344       0.14.0
13345
13346   Example
13347          -> { "execute": "query-version" }
13348          <- {
13349                "return":{
13350                   "qemu":{
13351                      "major":0,
13352                      "minor":11,
13353                      "micro":5
13354                   },
13355                   "package":""
13356                }
13357             }
13358
13359   CommandInfo (Object)
13360       Information about a QMP command
13361
13362   Members
13363       name: string
13364              The command name
13365
13366   Since
13367       0.14.0
13368
13369   query-commands (Command)
13370       Return a list of supported QMP commands by this server
13371
13372   Returns
13373       A list of CommandInfo for all supported commands
13374
13375   Since
13376       0.14.0
13377
13378   Example
13379          -> { "execute": "query-commands" }
13380          <- {
13381               "return":[
13382                  {
13383                     "name":"query-balloon"
13384                  },
13385                  {
13386                     "name":"system_powerdown"
13387                  }
13388               ]
13389             }
13390
13391   Note
13392       This example has been shortened as the real response is too long.
13393
13394   EventInfo (Object)
13395       Information about a QMP event
13396
13397   Members
13398       name: string
13399              The event name
13400
13401   Since
13402       1.2.0
13403
13404   query-events (Command)
13405       Return information on QMP events.
13406
13407   Features
13408       deprecated
13409              This  command  is deprecated, because its output doesn't reflect
13410              compile-time configuration.  Use 'query-qmp-schema' instead.
13411
13412   Returns
13413       A list of EventInfo.
13414
13415   Since
13416       1.2.0
13417
13418   Example
13419          -> { "execute": "query-events" }
13420          <- {
13421               "return": [
13422                   {
13423                      "name":"SHUTDOWN"
13424                   },
13425                   {
13426                      "name":"RESET"
13427                   }
13428                ]
13429             }
13430
13431   Note
13432       This example has been shortened as the real response is too long.
13433
13434   quit (Command)
13435       This command will cause the QEMU process to exit gracefully.  While ev‐
13436       ery  attempt  is made to send the QMP response before terminating, this
13437       is not guaranteed.  When using this interface, a  premature  EOF  would
13438       not be unexpected.
13439
13440   Since
13441       0.14.0
13442
13443   Example
13444          -> { "execute": "quit" }
13445          <- { "return": {} }
13446
13447   MonitorMode (Enum)
13448       An enumeration of monitor modes.
13449
13450   Values
13451       readline
13452              HMP monitor (human-oriented command line interface)
13453
13454       control
13455              QMP monitor (JSON-based machine interface)
13456
13457   Since
13458       5.0
13459
13460   MonitorOptions (Object)
13461       Options to be used for adding a new monitor.
13462
13463   Members
13464       id: string (optional)
13465              Name of the monitor
13466
13467       mode: MonitorMode (optional)
13468              Selects the monitor mode (default: readline in the system emula‐
13469              tor, control in qemu-storage-daemon)
13470
13471       pretty: boolean (optional)
13472              Enables pretty printing (QMP only)
13473
13474       chardev: string
13475              Name of a character device to expose the monitor on
13476
13477   Since
13478       5.0
13479

QMP INTROSPECTION

13481   query-qmp-schema (Command)
13482       Command query-qmp-schema exposes the  QMP  wire  ABI  as  an  array  of
13483       SchemaInfo.   This lets QMP clients figure out what commands and events
13484       are available in this QEMU, and their parameters and results.
13485
13486       However, the SchemaInfo can't reflect all the  rules  and  restrictions
13487       that  apply  to QMP.  It's interface introspection (figuring out what's
13488       there), not interface specification.  The specification is in the  QAPI
13489       schema.
13490
13491       Furthermore, while we strive to keep the QMP wire format backwards-com‐
13492       patible across qemu versions, the introspection output is  not  guaran‐
13493       teed  to have the same stability.  For example, one version of qemu may
13494       list an object member as an optional non-variant, while  another  lists
13495       the  same  member  only through the object's variants; or the type of a
13496       member may change from a generic string into a specific  enum  or  from
13497       one  specific  type  into  an alternate that includes the original type
13498       alongside something else.
13499
13500   Returns
13501       array of SchemaInfo, where each element describes an entity in the ABI:
13502       command, event, type, ...
13503
13504       The  order of the various SchemaInfo is unspecified; however, all names
13505       are guaranteed to be unique (no name will be duplicated with  different
13506       meta-types).
13507
13508   Note
13509       the  QAPI  schema  is  also used to help define internal interfaces, by
13510       defining QAPI types.  These are not part  of  the  QMP  wire  ABI,  and
13511       therefore not returned by this command.
13512
13513   Since
13514       2.5
13515
13516   SchemaMetaType (Enum)
13517       This is a SchemaInfo's meta type, i.e. the kind of entity it describes.
13518
13519   Values
13520       builtin
13521              a predefined type such as 'int' or 'bool'.
13522
13523       enum   an enumeration type
13524
13525       array  an array type
13526
13527       object an object type (struct or union)
13528
13529       alternate
13530              an alternate type
13531
13532       command
13533              a QMP command
13534
13535       event  a QMP event
13536
13537   Since
13538       2.5
13539
13540   SchemaInfo (Object)
13541   Members
13542       name: string
13543              the  entity's  name, inherited from base.  The SchemaInfo is al‐
13544              ways referenced by this name.  Commands and events have the name
13545              defined  in  the  QAPI  schema.  Unlike command and event names,
13546              type names are not part of the  wire  ABI.   Consequently,  type
13547              names  are  meaningless  strings  here,  although they are still
13548              guaranteed unique regardless of meta-type.
13549
13550       meta-type: SchemaMetaType
13551              the entity's meta type, inherited from base.
13552
13553       features: array of string (optional)
13554              names of features associated with the entity, in  no  particular
13555              order.   (since  4.1 for object types, 4.2 for commands, 5.0 for
13556              the rest)
13557
13558       The members of SchemaInfoBuiltin when meta-type is "builtin"
13559
13560       The members of SchemaInfoEnum when meta-type is "enum"
13561
13562       The members of SchemaInfoArray when meta-type is "array"
13563
13564       The members of SchemaInfoObject when meta-type is "object"
13565
13566       The members of SchemaInfoAlternate when meta-type is "alternate"
13567
13568       The members of SchemaInfoCommand when meta-type is "command"
13569
13570       The members of SchemaInfoEvent when meta-type is "event"
13571       Additional members depend on the value of meta-type.
13572
13573   Since
13574       2.5
13575
13576   SchemaInfoBuiltin (Object)
13577       Additional SchemaInfo members for meta-type 'builtin'.
13578
13579   Members
13580       json-type: JSONType
13581              the JSON type used for this type on the wire.
13582
13583   Since
13584       2.5
13585
13586   JSONType (Enum)
13587       The four primitive and two structured types according to RFC 8259  sec‐
13588       tion  1,  plus  'int'  (split  off 'number'), plus the obvious top type
13589       'value'.
13590
13591   Values
13592       string Not documented
13593
13594       number Not documented
13595
13596       int    Not documented
13597
13598       boolean
13599              Not documented
13600
13601       null   Not documented
13602
13603       object Not documented
13604
13605       array  Not documented
13606
13607       value  Not documented
13608
13609   Since
13610       2.5
13611
13612   SchemaInfoEnum (Object)
13613       Additional SchemaInfo members for meta-type 'enum'.
13614
13615   Members
13616       values: array of string
13617              the enumeration type's values, in no particular order.
13618       Values of this type are JSON string on the wire.
13619
13620   Since
13621       2.5
13622
13623   SchemaInfoArray (Object)
13624       Additional SchemaInfo members for meta-type 'array'.
13625
13626   Members
13627       element-type: string
13628              the array type's element type.
13629       Values of this type are JSON array on the wire.
13630
13631   Since
13632       2.5
13633
13634   SchemaInfoObject (Object)
13635       Additional SchemaInfo members for meta-type 'object'.
13636
13637   Members
13638       members: array of SchemaInfoObjectMember
13639              the object type's (non-variant) members, in no particular order.
13640
13641       tag: string (optional)
13642              the name of the member serving as type tag.  An element of  mem‐
13643              bers with this name must exist.
13644
13645       variants: array of SchemaInfoObjectVariant (optional)
13646              variant members, i.e. additional members that depend on the type
13647              tag's value.  Present exactly when tag is present.  The variants
13648              are  in  no particular order, and may even differ from the order
13649              of the values of the enum type of the tag.
13650       Values of this type are JSON object on the wire.
13651
13652   Since
13653       2.5
13654
13655   SchemaInfoObjectMember (Object)
13656       An object member.
13657
13658   Members
13659       name: string
13660              the member's name, as defined in the QAPI schema.
13661
13662       type: string
13663              the name of the member's type.
13664
13665       default: value (optional)
13666              default when used as command parameter.  If absent, the  parame‐
13667              ter  is mandatory.  If present, the value must be null.  The pa‐
13668              rameter is optional, and behavior when it's missing is not spec‐
13669              ified  here.  Future extension: if present and non-null, the pa‐
13670              rameter is optional, and defaults to this value.
13671
13672       features: array of string (optional)
13673              names of features associated with the member, in  no  particular
13674              order.  (since 5.0)
13675
13676   Since
13677       2.5
13678
13679   SchemaInfoObjectVariant (Object)
13680       The variant members for a value of the type tag.
13681
13682   Members
13683       case: string
13684              a value of the type tag.
13685
13686       type: string
13687              the  name  of  the object type that provides the variant members
13688              when the type tag has value case.
13689
13690   Since
13691       2.5
13692
13693   SchemaInfoAlternate (Object)
13694       Additional SchemaInfo members for meta-type 'alternate'.
13695
13696   Members
13697       members: array of SchemaInfoAlternateMember
13698              the alternate type's members, in no particular order.  The  mem‐
13699              bers'     wire    encoding    is    distinct,    see    docs/de‐
13700              vel/qapi-code-gen.txt section Alternate types.
13701       On the wire, this can be any of the members.
13702
13703   Since
13704       2.5
13705
13706   SchemaInfoAlternateMember (Object)
13707       An alternate member.
13708
13709   Members
13710       type: string
13711              the name of the member's type.
13712
13713   Since
13714       2.5
13715
13716   SchemaInfoCommand (Object)
13717       Additional SchemaInfo members for meta-type 'command'.
13718
13719   Members
13720       arg-type: string
13721              the name of the object type that provides the command's  parame‐
13722              ters.
13723
13724       ret-type: string
13725              the name of the command's result type.
13726
13727       allow-oob: boolean (optional)
13728              whether  the  command  allows out-of-band execution, defaults to
13729              false (Since: 2.12)
13730
13731   TODO
13732       success-response (currently irrelevant, because it's QGA, not QMP)
13733
13734   Since
13735       2.5
13736
13737   SchemaInfoEvent (Object)
13738       Additional SchemaInfo members for meta-type 'event'.
13739
13740   Members
13741       arg-type: string
13742              the name of the object type that provides  the  event's  parame‐
13743              ters.
13744
13745   Since
13746       2.5
13747

QEMU OBJECT MODEL (QOM)

13749   ObjectPropertyInfo (Object)
13750   Members
13751       name: string
13752              the name of the property
13753
13754       type: string
13755              the  type  of  the property.  This will typically come in one of
13756              four forms:
13757
13758              1. A primitive type such as 'u8', 'u16', 'bool', 'str', or 'dou‐
13759                 ble'.  These types are mapped to the appropriate JSON type.
13760
13761              2. A  child type in the form 'child<subtype>' where subtype is a
13762                 qdev device type name.  Child properties create the  composi‐
13763                 tion tree.
13764
13765              3. A  link  type  in the form 'link<subtype>' where subtype is a
13766                 qdev device type name.  Link properties form the device model
13767                 graph.
13768
13769       description: string (optional)
13770              if specified, the description of the property.
13771
13772       default-value: value (optional)
13773              the default value, if any (since 5.0)
13774
13775   Since
13776       1.2
13777
13778   qom-list (Command)
13779       This  command  will list any properties of a object given a path in the
13780       object model.
13781
13782   Arguments
13783       path: string
13784              the path within the object model.  See qom-get for a description
13785              of this parameter.
13786
13787   Returns
13788       a  list  of  ObjectPropertyInfo that describe the properties of the ob‐
13789       ject.
13790
13791   Since
13792       1.2
13793
13794   Example
13795          -> { "execute": "qom-list",
13796               "arguments": { "path": "/chardevs" } }
13797          <- { "return": [ { "name": "type", "type": "string" },
13798                           { "name": "parallel0", "type": "child<chardev-vc>" },
13799                           { "name": "serial0", "type": "child<chardev-vc>" },
13800                           { "name": "mon0", "type": "child<chardev-stdio>" } ] }
13801
13802   qom-get (Command)
13803       This command will get a property from a object model  path  and  return
13804       the value.
13805
13806   Arguments
13807       path: string
13808              The  path  within the object model.  There are two forms of sup‐
13809              ported paths--absolute and partial paths.
13810
13811              Absolute paths are derived from the root object and  can  follow
13812              child<>  or  link<>  properties.   Since  they can follow link<>
13813              properties, they can be arbitrarily long.  Absolute  paths  look
13814              like absolute filenames and are prefixed  with a leading slash.
13815
13816              Partial  paths  look like relative filenames.  They do not begin
13817              with a prefix.  The matching rules for partial paths are  subtle
13818              but  designed to make specifying objects easy.  At each level of
13819              the composition tree, the partial path is matched as an absolute
13820              path.   The  first  match is not returned.  At least two matches
13821              are searched for.  A successful result is only returned if  only
13822              one  match is found.  If more than one match is found, a flag is
13823              return to indicate that the match was ambiguous.
13824
13825       property: string
13826              The property name to read
13827
13828   Returns
13829       The property value.  The type depends on the property type. child<> and
13830       link<> properties are returned as #str pathnames.  All integer property
13831       types (u8, u16, etc) are returned as #int.
13832
13833   Since
13834       1.2
13835
13836   Example
13837          1. Use absolute path
13838
13839          -> { "execute": "qom-get",
13840               "arguments": { "path": "/machine/unattached/device[0]",
13841                              "property": "hotplugged" } }
13842          <- { "return": false }
13843
13844          2. Use partial path
13845
13846          -> { "execute": "qom-get",
13847               "arguments": { "path": "unattached/sysbus",
13848                              "property": "type" } }
13849          <- { "return": "System" }
13850
13851   qom-set (Command)
13852       This command will set a property from a object model path.
13853
13854   Arguments
13855       path: string
13856              see qom-get for a description of this parameter
13857
13858       property: string
13859              the property name to set
13860
13861       value: value
13862              a value who's type is appropriate for the  property  type.   See
13863              qom-get for a description of type mapping.
13864
13865   Since
13866       1.2
13867
13868   Example
13869          -> { "execute": "qom-set",
13870               "arguments": { "path": "/machine",
13871                              "property": "graphics",
13872                              "value": false } }
13873          <- { "return": {} }
13874
13875   ObjectTypeInfo (Object)
13876       This structure describes a search result from qom-list-types
13877
13878   Members
13879       name: string
13880              the type name found in the search
13881
13882       abstract: boolean (optional)
13883              the  type is abstract and can't be directly instantiated.  Omit‐
13884              ted if false. (since 2.10)
13885
13886       parent: string (optional)
13887              Name of parent type, if any (since 2.10)
13888
13889   Since
13890       1.1
13891
13892   qom-list-types (Command)
13893       This command will return a list of types given search parameters
13894
13895   Arguments
13896       implements: string (optional)
13897              if specified, only return types that implement this type name
13898
13899       abstract: boolean (optional)
13900              if true, include abstract types in the results
13901
13902   Returns
13903       a list of ObjectTypeInfo or an empty list if no results are found
13904
13905   Since
13906       1.1
13907
13908   qom-list-properties (Command)
13909       List properties associated with a QOM object.
13910
13911   Arguments
13912       typename: string
13913              the type name of an object
13914
13915   Note
13916       objects can create properties at runtime, for example to describe links
13917       between  different devices and/or objects. These properties are not in‐
13918       cluded in the output of this command.
13919
13920   Returns
13921       a list of ObjectPropertyInfo describing object properties
13922
13923   Since
13924       2.12
13925
13926   object-add (Command)
13927       Create a QOM object.
13928
13929   Arguments
13930       qom-type: string
13931              the class name for the object to be created
13932
13933       id: string
13934              the name of the new object
13935
13936       props: value (optional)
13937              a dictionary of properties to be passed to the  backend.  Depre‐
13938              cated  since  5.0,  specify  the properties on the top level in‐
13939              stead. It is an error to specify the same option both on the top
13940              level and in props.
13941       Additional  arguments  depend on qom-type and are passed to the backend
13942       unchanged.
13943
13944   Returns
13945       Nothing on success Error if qom-type is not a valid class name
13946
13947   Since
13948       2.0
13949
13950   Example
13951          -> { "execute": "object-add",
13952               "arguments": { "qom-type": "rng-random", "id": "rng1",
13953                              "filename": "/dev/hwrng" } }
13954          <- { "return": {} }
13955
13956   object-del (Command)
13957       Remove a QOM object.
13958
13959   Arguments
13960       id: string
13961              the name of the QOM object to remove
13962
13963   Returns
13964       Nothing on success Error if id is not a valid id for a QOM object
13965
13966   Since
13967       2.0
13968
13969   Example
13970          -> { "execute": "object-del", "arguments": { "id": "rng1" } }
13971          <- { "return": {} }
13972

DEVICE INFRASTRUCTURE (QDEV)

13974   device-list-properties (Command)
13975       List properties associated with a device.
13976
13977   Arguments
13978       typename: string
13979              the type name of a device
13980
13981   Returns
13982       a list of ObjectPropertyInfo describing a devices properties
13983
13984   Note
13985       objects can create properties at runtime, for example to describe links
13986       between  different devices and/or objects. These properties are not in‐
13987       cluded in the output of this command.
13988
13989   Since
13990       1.2
13991
13992   device_add (Command)
13993   Arguments
13994       driver: string
13995              the name of the new device's driver
13996
13997       bus: string (optional)
13998              the device's parent bus (device tree path)
13999
14000       id: string (optional)
14001              the device's ID, must be unique
14002       Additional arguments depend on the type.
14003
14004       Add a device.
14005
14006   Notes
14007       1. For detailed information about this command,  please  refer  to  the
14008          'docs/qdev-device-use.txt' file.
14009
14010       2. It's  possible  to  list  device properties by running QEMU with the
14011          "-device DEVICE,help" command-line argument, where DEVICE is the de‐
14012          vice's name
14013
14014   Example
14015          -> { "execute": "device_add",
14016               "arguments": { "driver": "e1000", "id": "net1",
14017                              "bus": "pci.0",
14018                              "mac": "52:54:00:12:34:56" } }
14019          <- { "return": {} }
14020
14021   TODO
14022       This  command  effectively  bypasses  QAPI completely due to its "addi‐
14023       tional arguments" business.  It shouldn't have been added to the schema
14024       in  this  form.  It should be qapified properly, or replaced by a prop‐
14025       erly qapified command.
14026
14027   Since
14028       0.13
14029
14030   device_del (Command)
14031       Remove a device from a guest
14032
14033   Arguments
14034       id: string
14035              the device's ID or QOM path
14036
14037   Returns
14038       Nothing on success If id is not a valid device, DeviceNotFound
14039
14040   Notes
14041       When this command completes, the device may not  be  removed  from  the
14042       guest.   Hot  removal  is an operation that requires guest cooperation.
14043       This command merely requests that  the  guest  begin  the  hot  removal
14044       process.   Completion  of the device removal process is signaled with a
14045       DEVICE_DELETED event. Guest reset will automatically  complete  removal
14046       for all devices.
14047
14048   Since
14049       0.14.0
14050
14051   Example
14052          -> { "execute": "device_del",
14053               "arguments": { "id": "net1" } }
14054          <- { "return": {} }
14055
14056          -> { "execute": "device_del",
14057               "arguments": { "id": "/machine/peripheral-anon/device[0]" } }
14058          <- { "return": {} }
14059
14060   DEVICE_DELETED (Event)
14061       Emitted  whenever  the device removal completion is acknowledged by the
14062       guest.  At this point, it's safe to reuse the specified device ID.  De‐
14063       vice removal can be initiated by the guest or by HMP/QMP commands.
14064
14065   Arguments
14066       device: string (optional)
14067              device name
14068
14069       path: string
14070              device path
14071
14072   Since
14073       1.5
14074
14075   Example
14076          <- { "event": "DEVICE_DELETED",
14077               "data": { "device": "virtio-net-pci-0",
14078                         "path": "/machine/peripheral/virtio-net-pci-0" },
14079               "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
14080

MACHINES

14082   SysEmuTarget (Enum)
14083       The comprehensive enumeration of QEMU system emulation ("softmmu") tar‐
14084       gets. Run "./configure --help" in the project root directory, and  look
14085       for the *-softmmu targets near the "--target-list" option. The individ‐
14086       ual target constants are not documented here, for the time being.
14087
14088   Values
14089       rx     since 5.0
14090
14091       avr    since 5.1
14092
14093       aarch64
14094              Not documented
14095
14096       alpha  Not documented
14097
14098       arm    Not documented
14099
14100       cris   Not documented
14101
14102       hppa   Not documented
14103
14104       i386   Not documented
14105
14106       lm32   Not documented
14107
14108       m68k   Not documented
14109
14110       microblaze
14111              Not documented
14112
14113       microblazeel
14114              Not documented
14115
14116       mips   Not documented
14117
14118       mips64 Not documented
14119
14120       mips64el
14121              Not documented
14122
14123       mipsel Not documented
14124
14125       moxie  Not documented
14126
14127       nios2  Not documented
14128
14129       or1k   Not documented
14130
14131       ppc    Not documented
14132
14133       ppc64  Not documented
14134
14135       riscv32
14136              Not documented
14137
14138       riscv64
14139              Not documented
14140
14141       s390x  Not documented
14142
14143       sh4    Not documented
14144
14145       sh4eb  Not documented
14146
14147       sparc  Not documented
14148
14149       sparc64
14150              Not documented
14151
14152       tricore
14153              Not documented
14154
14155       unicore32
14156              Not documented
14157
14158       x86_64 Not documented
14159
14160       xtensa Not documented
14161
14162       xtensaeb
14163              Not documented
14164
14165   Notes
14166       The resulting QMP strings can be appended to the "qemu-system-"  prefix
14167       to  produce  the  corresponding QEMU executable name. This is true even
14168       for "qemu-system-x86_64".
14169
14170   Since
14171       3.0
14172
14173   CpuInfoArch (Enum)
14174       An enumeration of cpu types that enable additional  information  during
14175       query-cpus and query-cpus-fast.
14176
14177   Values
14178       s390   since 2.12
14179
14180       riscv  since 2.12
14181
14182       x86    Not documented
14183
14184       sparc  Not documented
14185
14186       ppc    Not documented
14187
14188       mips   Not documented
14189
14190       tricore
14191              Not documented
14192
14193       other  Not documented
14194
14195   Since
14196       2.6
14197
14198   CpuInfo (Object)
14199       Information about a virtual CPU
14200
14201   Members
14202       CPU: int
14203              the index of the virtual CPU
14204
14205       current: boolean
14206              this  only  exists for backwards compatibility and should be ig‐
14207              nored
14208
14209       halted: boolean
14210              true if the virtual CPU is in  the  halt  state.   Halt  usually
14211              refers to a processor specific low power mode.
14212
14213       qom_path: string
14214              path to the CPU object in the QOM tree (since 2.4)
14215
14216       thread_id: int
14217              ID of the underlying host thread
14218
14219       props: CpuInstanceProperties (optional)
14220              properties  describing  to which node/socket/core/thread virtual
14221              CPU belongs to, provided if supported by board (since 2.10)
14222
14223       arch: CpuInfoArch
14224              architecture of  the  cpu,  which  determines  which  additional
14225              fields will be listed (since 2.6)
14226
14227       The members of CpuInfoX86 when arch is "x86"
14228
14229       The members of CpuInfoSPARC when arch is "sparc"
14230
14231       The members of CpuInfoPPC when arch is "ppc"
14232
14233       The members of CpuInfoMIPS when arch is "mips"
14234
14235       The members of CpuInfoTricore when arch is "tricore"
14236
14237       The members of CpuInfoS390 when arch is "s390"
14238
14239       The members of CpuInfoRISCV when arch is "riscv"
14240
14241   Since
14242       0.14.0
14243
14244   Notes
14245       halted  is  a transient state that changes frequently.  By the time the
14246       data is sent to the client, the guest may no longer be halted.
14247
14248   CpuInfoX86 (Object)
14249       Additional information about a virtual i386 or x86_64 CPU
14250
14251   Members
14252       pc: int
14253              the 64-bit instruction pointer
14254
14255   Since
14256       2.6
14257
14258   CpuInfoSPARC (Object)
14259       Additional information about a virtual SPARC CPU
14260
14261   Members
14262       pc: int
14263              the PC component of the instruction pointer
14264
14265       npc: int
14266              the NPC component of the instruction pointer
14267
14268   Since
14269       2.6
14270
14271   CpuInfoPPC (Object)
14272       Additional information about a virtual PPC CPU
14273
14274   Members
14275       nip: int
14276              the instruction pointer
14277
14278   Since
14279       2.6
14280
14281   CpuInfoMIPS (Object)
14282       Additional information about a virtual MIPS CPU
14283
14284   Members
14285       PC: int
14286              the instruction pointer
14287
14288   Since
14289       2.6
14290
14291   CpuInfoTricore (Object)
14292       Additional information about a virtual Tricore CPU
14293
14294   Members
14295       PC: int
14296              the instruction pointer
14297
14298   Since
14299       2.6
14300
14301   CpuInfoRISCV (Object)
14302       Additional information about a virtual RISCV CPU
14303
14304   Members
14305       pc: int
14306              the instruction pointer
14307       Since 2.12
14308
14309   CpuS390State (Enum)
14310       An enumeration of cpu states that can be assumed by a virtual S390 CPU
14311
14312   Values
14313       uninitialized
14314              Not documented
14315
14316       stopped
14317              Not documented
14318
14319       check-stop
14320              Not documented
14321
14322       operating
14323              Not documented
14324
14325       load   Not documented
14326
14327   Since
14328       2.12
14329
14330   CpuInfoS390 (Object)
14331       Additional information about a virtual S390 CPU
14332
14333   Members
14334       cpu-state: CpuS390State
14335              the virtual CPU's state
14336
14337   Since
14338       2.12
14339
14340   query-cpus (Command)
14341       Returns a list of information about each virtual CPU.
14342
14343       This command causes vCPU threads to exit to userspace, which  causes  a
14344       small  interruption  to  guest CPU execution. This will have a negative
14345       impact on realtime guests and other latency sensitive guest workloads.
14346
14347   Features
14348       deprecated
14349              This command is  deprecated,  because  it  interferes  with  the
14350              guest.   Use  'query-cpus-fast' instead to avoid the vCPU inter‐
14351              ruption.
14352
14353   Returns
14354       a list of CpuInfo for each virtual CPU
14355
14356   Since
14357       0.14.0
14358
14359   Example
14360          -> { "execute": "query-cpus" }
14361          <- { "return": [
14362                   {
14363                      "CPU":0,
14364                      "current":true,
14365                      "halted":false,
14366                      "qom_path":"/machine/unattached/device[0]",
14367                      "arch":"x86",
14368                      "pc":3227107138,
14369                      "thread_id":3134
14370                   },
14371                   {
14372                      "CPU":1,
14373                      "current":false,
14374                      "halted":true,
14375                      "qom_path":"/machine/unattached/device[2]",
14376                      "arch":"x86",
14377                      "pc":7108165,
14378                      "thread_id":3135
14379                   }
14380                ]
14381             }
14382
14383   CpuInfoFast (Object)
14384       Information about a virtual CPU
14385
14386   Members
14387       cpu-index: int
14388              index of the virtual CPU
14389
14390       qom-path: string
14391              path to the CPU object in the QOM tree
14392
14393       thread-id: int
14394              ID of the underlying host thread
14395
14396       props: CpuInstanceProperties (optional)
14397              properties describing to which  node/socket/core/thread  virtual
14398              CPU belongs to, provided if supported by board
14399
14400       arch: CpuInfoArch
14401              base architecture of the cpu
14402
14403       target: SysEmuTarget
14404              the  QEMU  system emulation target, which determines which addi‐
14405              tional fields will be listed (since 3.0)
14406
14407       The members of CpuInfoS390 when target is "s390x"
14408
14409   Features
14410       deprecated
14411              Member arch is deprecated.  Use target instead.
14412
14413   Since
14414       2.12
14415
14416   query-cpus-fast (Command)
14417       Returns information about all virtual CPUs. This command does not incur
14418       a  performance  penalty  and  should  be  used in production instead of
14419       query-cpus.
14420
14421   Returns
14422       list of CpuInfoFast
14423
14424   Since
14425       2.12
14426
14427   Example
14428          -> { "execute": "query-cpus-fast" }
14429          <- { "return": [
14430                  {
14431                      "thread-id": 25627,
14432                      "props": {
14433                          "core-id": 0,
14434                          "thread-id": 0,
14435                          "socket-id": 0
14436                      },
14437                      "qom-path": "/machine/unattached/device[0]",
14438                      "arch":"x86",
14439                      "target":"x86_64",
14440                      "cpu-index": 0
14441                  },
14442                  {
14443                      "thread-id": 25628,
14444                      "props": {
14445                          "core-id": 0,
14446                          "thread-id": 0,
14447                          "socket-id": 1
14448                      },
14449                      "qom-path": "/machine/unattached/device[2]",
14450                      "arch":"x86",
14451                      "target":"x86_64",
14452                      "cpu-index": 1
14453                  }
14454              ]
14455          }
14456
14457   MachineInfo (Object)
14458       Information describing a machine.
14459
14460   Members
14461       name: string
14462              the name of the machine
14463
14464       alias: string (optional)
14465              an alias for the machine name
14466
14467       is-default: boolean (optional)
14468              whether the machine is default
14469
14470       cpu-max: int
14471              maximum number of CPUs supported  by  the  machine  type  (since
14472              1.5.0)
14473
14474       hotpluggable-cpus: boolean
14475              cpu hotplug via -device is supported (since 2.7.0)
14476
14477       numa-mem-supported: boolean
14478              true if '-numa node,mem' option is supported by the machine type
14479              and false otherwise (since 4.1)
14480
14481       deprecated: boolean
14482              if true, the machine type is deprecated and may  be  removed  in
14483              future versions of QEMU according to the QEMU deprecation policy
14484              (since 4.1.0)
14485
14486       default-cpu-type: string (optional)
14487              default CPU model typename if none is requested via the -cpu ar‐
14488              gument. (since 4.2)
14489
14490       default-ram-id: string (optional)
14491              the default ID of initial RAM memory backend (since 5.2)
14492
14493   Since
14494       1.2.0
14495
14496   query-machines (Command)
14497       Return a list of supported machines
14498
14499   Returns
14500       a list of MachineInfo
14501
14502   Since
14503       1.2.0
14504
14505   CurrentMachineParams (Object)
14506       Information describing the running machine parameters.
14507
14508   Members
14509       wakeup-suspend-support: boolean
14510              true if the machine supports wake up from suspend
14511
14512   Since
14513       4.0
14514
14515   query-current-machine (Command)
14516       Return information on the current virtual machine.
14517
14518   Returns
14519       CurrentMachineParams
14520
14521   Since
14522       4.0
14523
14524   TargetInfo (Object)
14525       Information describing the QEMU target.
14526
14527   Members
14528       arch: SysEmuTarget
14529              the target architecture
14530
14531   Since
14532       1.2.0
14533
14534   query-target (Command)
14535       Return information about the target for this QEMU
14536
14537   Returns
14538       TargetInfo
14539
14540   Since
14541       1.2.0
14542
14543   UuidInfo (Object)
14544       Guest UUID information (Universally Unique Identifier).
14545
14546   Members
14547       UUID: string
14548              the UUID of the guest
14549
14550   Since
14551       0.14.0
14552
14553   Notes
14554       If no UUID was specified for the guest, a null UUID is returned.
14555
14556   query-uuid (Command)
14557       Query the guest UUID information.
14558
14559   Returns
14560       The UuidInfo for the guest
14561
14562   Since
14563       0.14.0
14564
14565   Example
14566          -> { "execute": "query-uuid" }
14567          <- { "return": { "UUID": "550e8400-e29b-41d4-a716-446655440000" } }
14568
14569   GuidInfo (Object)
14570       GUID information.
14571
14572   Members
14573       guid: string
14574              the globally unique identifier
14575
14576   Since
14577       2.9
14578
14579   query-vm-generation-id (Command)
14580       Show Virtual Machine Generation ID
14581
14582   Since
14583       2.9
14584
14585   system_reset (Command)
14586       Performs a hard reset of a guest.
14587
14588   Since
14589       0.14.0
14590
14591   Example
14592          -> { "execute": "system_reset" }
14593          <- { "return": {} }
14594
14595   system_powerdown (Command)
14596       Requests that a guest perform a powerdown operation.
14597
14598   Since
14599       0.14.0
14600
14601   Notes
14602       A guest may or may not respond to this command.  This command returning
14603       does not indicate that a guest has accepted the request or that it  has
14604       shut  down.   Many guests will respond to this command by prompting the
14605       user in some way.
14606
14607   Example
14608          -> { "execute": "system_powerdown" }
14609          <- { "return": {} }
14610
14611   system_wakeup (Command)
14612       Wake up guest from suspend. If the guest has wake-up from suspend  sup‐
14613       port  enabled (wakeup-suspend-support flag from query-current-machine),
14614       wake-up guest from suspend if the guest is in SUSPENDED  state.  Return
14615       an error otherwise.
14616
14617   Since
14618       1.1
14619
14620   Returns
14621       nothing.
14622
14623   Note
14624       prior  to  4.0,  this command does nothing in case the guest isn't sus‐
14625       pended.
14626
14627   Example
14628          -> { "execute": "system_wakeup" }
14629          <- { "return": {} }
14630
14631   LostTickPolicy (Enum)
14632       Policy for handling lost ticks in timer devices.  Ticks end up  getting
14633       lost when, for example, the guest is paused.
14634
14635   Values
14636       discard
14637              throw  away  the missed ticks and continue with future injection
14638              normally.  The guest OS will see the timer jump ahead by  a  po‐
14639              tentially quite significant amount all at once, as if the inter‐
14640              vening chunk of time had simply not existed;  needless  to  say,
14641              such  a  sudden  jump can easily confuse a guest OS which is not
14642              specifically prepared to deal with it.  Assuming  the  guest  OS
14643              can deal correctly with the time jump, the time in the guest and
14644              in the host should now match.
14645
14646       delay  continue to deliver ticks at the normal rate.  The guest OS will
14647              not  notice  anything  is  amiss, as from its point of view time
14648              will have continued to flow normally.  The  time  in  the  guest
14649              should  now be behind the time in the host by exactly the amount
14650              of time during which ticks have been missed.
14651
14652       slew   deliver ticks at a higher rate  to  catch  up  with  the  missed
14653              ticks.   The guest OS will not notice anything is amiss, as from
14654              its point of view time will have  continued  to  flow  normally.
14655              Once  the  timer  has  managed  to catch up with all the missing
14656              ticks, the time in the guest and in the host should match.
14657
14658   Since
14659       2.0
14660
14661   inject-nmi (Command)
14662       Injects a Non-Maskable Interrupt into the default CPU (x86/s390) or all
14663       CPUs (ppc64).  The command fails when the guest doesn't support inject‐
14664       ing.
14665
14666   Returns
14667       If successful, nothing
14668
14669   Since
14670       0.14.0
14671
14672   Note
14673       prior to 2.1, this command was only supported for x86 and s390 VMs
14674
14675   Example
14676          -> { "execute": "inject-nmi" }
14677          <- { "return": {} }
14678
14679   KvmInfo (Object)
14680       Information about support for KVM acceleration
14681
14682   Members
14683       enabled: boolean
14684              true if KVM acceleration is active
14685
14686       present: boolean
14687              true if KVM acceleration is built into this executable
14688
14689   Since
14690       0.14.0
14691
14692   query-kvm (Command)
14693       Returns information about KVM acceleration
14694
14695   Returns
14696       KvmInfo
14697
14698   Since
14699       0.14.0
14700
14701   Example
14702          -> { "execute": "query-kvm" }
14703          <- { "return": { "enabled": true, "present": true } }
14704
14705   NumaOptionsType (Enum)
14706   Values
14707       node   NUMA nodes configuration
14708
14709       dist   NUMA distance configuration (since 2.10)
14710
14711       cpu    property based CPU(s) to node mapping (Since: 2.10)
14712
14713       hmat-lb
14714              memory latency and bandwidth information (Since: 5.0)
14715
14716       hmat-cache
14717              memory side cache information (Since: 5.0)
14718
14719   Since
14720       2.1
14721
14722   NumaOptions (Object)
14723       A discriminated record of NUMA options. (for OptsVisitor)
14724
14725   Members
14726       type: NumaOptionsType
14727              Not documented
14728
14729       The members of NumaNodeOptions when type is "node"
14730
14731       The members of NumaDistOptions when type is "dist"
14732
14733       The members of NumaCpuOptions when type is "cpu"
14734
14735       The members of NumaHmatLBOptions when type is "hmat-lb"
14736
14737       The members of NumaHmatCacheOptions when type is "hmat-cache"
14738
14739   Since
14740       2.1
14741
14742   NumaNodeOptions (Object)
14743       Create a guest NUMA node. (for OptsVisitor)
14744
14745   Members
14746       nodeid: int (optional)
14747              NUMA node ID (increase by 1 from 0 if omitted)
14748
14749       cpus: array of int (optional)
14750
14751              VCPUs belonging to this node (assign VCPUS round-robin
14752                     if omitted)
14753
14754       mem: int (optional)
14755              memory size  of  this  node;  mutually  exclusive  with  memdev.
14756              Equally  divide  total memory among nodes if both mem and memdev
14757              are omitted.
14758
14759       memdev: string (optional)
14760              memory backend object.  If specified for one node,  it  must  be
14761              specified for all nodes.
14762
14763       initiator: int (optional)
14764              defined  in ACPI 6.3 Chapter 5.2.27.3 Table 5-145, points to the
14765              nodeid which has the memory controller responsible for this NUMA
14766              node.  This field provides additional information as to the ini‐
14767              tiator node that is closest (as in directly  attached)  to  this
14768              node, and therefore has the best performance (since 5.0)
14769
14770   Since
14771       2.1
14772
14773   NumaDistOptions (Object)
14774       Set the distance between 2 NUMA nodes.
14775
14776   Members
14777       src: int
14778              source NUMA node.
14779
14780       dst: int
14781              destination NUMA node.
14782
14783       val: int
14784              NUMA distance from source node to destination node.  When a node
14785              is unreachable from another node, set the distance between  them
14786              to 255.
14787
14788   Since
14789       2.10
14790
14791   X86CPURegister32 (Enum)
14792       A X86 32-bit register
14793
14794   Values
14795       EAX    Not documented
14796
14797       EBX    Not documented
14798
14799       ECX    Not documented
14800
14801       EDX    Not documented
14802
14803       ESP    Not documented
14804
14805       EBP    Not documented
14806
14807       ESI    Not documented
14808
14809       EDI    Not documented
14810
14811   Since
14812       1.5
14813
14814   X86CPUFeatureWordInfo (Object)
14815       Information about a X86 CPU feature word
14816
14817   Members
14818       cpuid-input-eax: int
14819              Input EAX value for CPUID instruction for that feature word
14820
14821       cpuid-input-ecx: int (optional)
14822              Input ECX value for CPUID instruction for that feature word
14823
14824       cpuid-register: X86CPURegister32
14825              Output register containing the feature bits
14826
14827       features: int
14828              value of output register, containing the feature bits
14829
14830   Since
14831       1.5
14832
14833   DummyForceArrays (Object)
14834       Not  used  by  QMP; hack to let us use X86CPUFeatureWordInfoList inter‐
14835       nally
14836
14837   Members
14838       unused: array of X86CPUFeatureWordInfo
14839              Not documented
14840
14841   Since
14842       2.5
14843
14844   NumaCpuOptions (Object)
14845       Option "-numa cpu" overrides default cpu to node mapping.   It  accepts
14846       the   same   set  of  cpu  properties  as  returned  by  query-hotplug‐
14847       gable-cpus[].props, where node-id could be  used  to  override  default
14848       node mapping.
14849
14850   Members
14851       The members of CpuInstanceProperties
14852
14853   Since
14854       2.10
14855
14856   HmatLBMemoryHierarchy (Enum)
14857       The  memory  hierarchy in the System Locality Latency and Bandwidth In‐
14858       formation Structure of HMAT (Heterogeneous Memory Attribute Table)
14859
14860       For more information about HmatLBMemoryHierarchy, see chapter 5.2.27.4:
14861       Table 5-146: Field "Flags" of ACPI 6.3 spec.
14862
14863   Values
14864       memory the structure represents the memory performance
14865
14866       first-level
14867              first level of memory side cache
14868
14869       second-level
14870              second level of memory side cache
14871
14872       third-level
14873              third level of memory side cache
14874
14875   Since
14876       5.0
14877
14878   HmatLBDataType (Enum)
14879       Data  type  in  the  System  Locality Latency and Bandwidth Information
14880       Structure of HMAT (Heterogeneous Memory Attribute Table)
14881
14882       For more information about HmatLBDataType, see chapter 5.2.27.4:  Table
14883       5-146:  Field "Data Type" of ACPI 6.3 spec.
14884
14885   Values
14886       access-latency
14887              access latency (nanoseconds)
14888
14889       read-latency
14890              read latency (nanoseconds)
14891
14892       write-latency
14893              write latency (nanoseconds)
14894
14895       access-bandwidth
14896              access bandwidth (Bytes per second)
14897
14898       read-bandwidth
14899              read bandwidth (Bytes per second)
14900
14901       write-bandwidth
14902              write bandwidth (Bytes per second)
14903
14904   Since
14905       5.0
14906
14907   NumaHmatLBOptions (Object)
14908       Set  the system locality latency and bandwidth information between Ini‐
14909       tiator and Target proximity Domains.
14910
14911       For more information about NumaHmatLBOptions, see chapter 5.2.27.4: Ta‐
14912       ble 5-146 of ACPI 6.3 spec.
14913
14914   Members
14915       initiator: int
14916              the Initiator Proximity Domain.
14917
14918       target: int
14919              the Target Proximity Domain.
14920
14921       hierarchy: HmatLBMemoryHierarchy
14922              the  Memory  Hierarchy.  Indicates  the performance of memory or
14923              side cache.
14924
14925       data-type: HmatLBDataType
14926              presents the type of data, access/read/write latency or hit  la‐
14927              tency.
14928
14929       latency: int (optional)
14930              the  value of latency from initiator to target proximity domain,
14931              the latency unit is "ns(nanosecond)".
14932
14933       bandwidth: int (optional)
14934              the value of bandwidth between initiator  and  target  proximity
14935              domain, the bandwidth unit is "Bytes per second".
14936
14937   Since
14938       5.0
14939
14940   HmatCacheAssociativity (Enum)
14941       Cache  associativity  in the Memory Side Cache Information Structure of
14942       HMAT
14943
14944       For more information of HmatCacheAssociativity, see  chapter  5.2.27.5:
14945       Table 5-147 of ACPI 6.3 spec.
14946
14947   Values
14948       none
14949
14950              None (no memory side cache in this proximity domain,
14951                     or cache associativity unknown)
14952
14953       direct Direct Mapped
14954
14955       complex
14956              Complex Cache Indexing (implementation specific)
14957
14958   Since
14959       5.0
14960
14961   HmatCacheWritePolicy (Enum)
14962       Cache  write  policy  in the Memory Side Cache Information Structure of
14963       HMAT
14964
14965       For more information of HmatCacheWritePolicy, see chapter 5.2.27.5: Ta‐
14966       ble 5-147: Field "Cache Attributes" of ACPI 6.3 spec.
14967
14968   Values
14969       none   None  (no  memory  side cache in this proximity domain, or cache
14970              write policy unknown)
14971
14972       write-back
14973              Write Back (WB)
14974
14975       write-through
14976              Write Through (WT)
14977
14978   Since
14979       5.0
14980
14981   NumaHmatCacheOptions (Object)
14982       Set the memory side cache information for a given memory domain.
14983
14984       For more information of NumaHmatCacheOptions, see chapter 5.2.27.5: Ta‐
14985       ble 5-147: Field "Cache Attributes" of ACPI 6.3 spec.
14986
14987   Members
14988       node-id: int
14989              the memory proximity domain to which the memory belongs.
14990
14991       size: int
14992              the size of memory side cache in bytes.
14993
14994       level: int
14995              the cache level described in this structure.
14996
14997       associativity: HmatCacheAssociativity
14998              the   cache   associativity,  none/direct-mapped/complex(complex
14999              cache indexing).
15000
15001       policy: HmatCacheWritePolicy
15002              the write policy, none/write-back/write-through.
15003
15004       line: int
15005              the cache Line size in bytes.
15006
15007   Since
15008       5.0
15009
15010   HostMemPolicy (Enum)
15011       Host memory policy types
15012
15013   Values
15014       default
15015              restore default policy, remove any nondefault policy
15016
15017       preferred
15018              set the preferred host nodes for allocation
15019
15020       bind   a strict policy that restricts memory  allocation  to  the  host
15021              nodes specified
15022
15023       interleave
15024              memory  allocations are interleaved across the set of host nodes
15025              specified
15026
15027   Since
15028       2.1
15029
15030   memsave (Command)
15031       Save a portion of guest memory to a file.
15032
15033   Arguments
15034       val: int
15035              the virtual address of the guest to start from
15036
15037       size: int
15038              the size of memory region to save
15039
15040       filename: string
15041              the file to save the memory to as binary data
15042
15043       cpu-index: int (optional)
15044              the index of the virtual CPU to use for translating the  virtual
15045              address (defaults to CPU 0)
15046
15047   Returns
15048       Nothing on success
15049
15050   Since
15051       0.14.0
15052
15053   Notes
15054       Errors were not reliably returned until 1.1
15055
15056   Example
15057          -> { "execute": "memsave",
15058               "arguments": { "val": 10,
15059                              "size": 100,
15060                              "filename": "/tmp/virtual-mem-dump" } }
15061          <- { "return": {} }
15062
15063   pmemsave (Command)
15064       Save a portion of guest physical memory to a file.
15065
15066   Arguments
15067       val: int
15068              the physical address of the guest to start from
15069
15070       size: int
15071              the size of memory region to save
15072
15073       filename: string
15074              the file to save the memory to as binary data
15075
15076   Returns
15077       Nothing on success
15078
15079   Since
15080       0.14.0
15081
15082   Notes
15083       Errors were not reliably returned until 1.1
15084
15085   Example
15086          -> { "execute": "pmemsave",
15087               "arguments": { "val": 10,
15088                              "size": 100,
15089                              "filename": "/tmp/physical-mem-dump" } }
15090          <- { "return": {} }
15091
15092   Memdev (Object)
15093       Information about memory backend
15094
15095   Members
15096       id: string (optional)
15097              backend's ID if backend has 'id' property (since 2.9)
15098
15099       size: int
15100              memory backend size
15101
15102       merge: boolean
15103              enables or disables memory merge support
15104
15105       dump: boolean
15106              includes memory backend's memory in a core dump or not
15107
15108       prealloc: boolean
15109              enables or disables memory preallocation
15110
15111       host-nodes: array of int
15112              host nodes for its memory policy
15113
15114       policy: HostMemPolicy
15115              memory policy of memory backend
15116
15117   Since
15118       2.1
15119
15120   query-memdev (Command)
15121       Returns information for all memory backends.
15122
15123   Returns
15124       a list of Memdev.
15125
15126   Since
15127       2.1
15128
15129   Example
15130          -> { "execute": "query-memdev" }
15131          <- { "return": [
15132                 {
15133                   "id": "mem1",
15134                   "size": 536870912,
15135                   "merge": false,
15136                   "dump": true,
15137                   "prealloc": false,
15138                   "host-nodes": [0, 1],
15139                   "policy": "bind"
15140                 },
15141                 {
15142                   "size": 536870912,
15143                   "merge": false,
15144                   "dump": true,
15145                   "prealloc": true,
15146                   "host-nodes": [2, 3],
15147                   "policy": "preferred"
15148                 }
15149               ]
15150             }
15151
15152   CpuInstanceProperties (Object)
15153       List of properties to be used for hotplugging a CPU instance, it should
15154       be passed by management with device_add command when  a  CPU  is  being
15155       hotplugged.
15156
15157   Members
15158       node-id: int (optional)
15159              NUMA node ID the CPU belongs to
15160
15161       socket-id: int (optional)
15162              socket number within node/board the CPU belongs to
15163
15164       die-id: int (optional)
15165              die number within node/board the CPU belongs to (Since 4.1)
15166
15167       core-id: int (optional)
15168              core number within die the CPU belongs to
15169
15170       thread-id: int (optional)
15171              thread number within core the CPU belongs to
15172
15173   Note
15174       currently  there  are 5 properties that could be present but management
15175       should be prepared to pass through  other  properties  with  device_add
15176       command to allow for future interface extension. This also requires the
15177       filed names to be kept in sync  with  the  properties  passed  to  -de‐
15178       vice/device_add.
15179
15180   Since
15181       2.7
15182
15183   HotpluggableCPU (Object)
15184   Members
15185       type: string
15186              CPU object type for usage with device_add command
15187
15188       props: CpuInstanceProperties
15189              list of properties to be used for hotplugging CPU
15190
15191       vcpus-count: int
15192              number of logical VCPU threads HotpluggableCPU provides
15193
15194       qom-path: string (optional)
15195              link  to existing CPU object if CPU is present or omitted if CPU
15196              is not present.
15197
15198   Since
15199       2.7
15200
15201   query-hotpluggable-cpus (Command)
15202   TODO
15203       Better documentation; currently there is none.
15204
15205   Returns
15206       a list of HotpluggableCPU objects.
15207
15208   Since
15209       2.7
15210
15211   Example
15212          For pseries machine type started with -smp 2,cores=2,maxcpus=4 -cpu POWER8:
15213
15214          -> { "execute": "query-hotpluggable-cpus" }
15215          <- {"return": [
15216               { "props": { "core": 8 }, "type": "POWER8-spapr-cpu-core",
15217                 "vcpus-count": 1 },
15218               { "props": { "core": 0 }, "type": "POWER8-spapr-cpu-core",
15219                 "vcpus-count": 1, "qom-path": "/machine/unattached/device[0]"}
15220             ]}'
15221
15222          For pc machine type started with -smp 1,maxcpus=2:
15223
15224          -> { "execute": "query-hotpluggable-cpus" }
15225          <- {"return": [
15226               {
15227                  "type": "qemu64-x86_64-cpu", "vcpus-count": 1,
15228                  "props": {"core-id": 0, "socket-id": 1, "thread-id": 0}
15229               },
15230               {
15231                  "qom-path": "/machine/unattached/device[0]",
15232                  "type": "qemu64-x86_64-cpu", "vcpus-count": 1,
15233                  "props": {"core-id": 0, "socket-id": 0, "thread-id": 0}
15234               }
15235             ]}
15236
15237          For s390x-virtio-ccw machine type started with -smp 1,maxcpus=2 -cpu qemu
15238          (Since: 2.11):
15239
15240          -> { "execute": "query-hotpluggable-cpus" }
15241          <- {"return": [
15242               {
15243                  "type": "qemu-s390x-cpu", "vcpus-count": 1,
15244                  "props": { "core-id": 1 }
15245               },
15246               {
15247                  "qom-path": "/machine/unattached/device[0]",
15248                  "type": "qemu-s390x-cpu", "vcpus-count": 1,
15249                  "props": { "core-id": 0 }
15250               }
15251             ]}
15252
15253   set-numa-node (Command)
15254       Runtime equivalent of '-numa' CLI  option,  available  at  preconfigure
15255       stage to configure numa mapping before initializing machine.
15256
15257       Since 3.0
15258
15259   Arguments
15260       The members of NumaOptions
15261
15262   balloon (Command)
15263       Request the balloon driver to change its balloon size.
15264
15265   Arguments
15266       value: int
15267              the  target  logical size of the VM in bytes.  We can deduce the
15268              size of the balloon using this formula:
15269                 logical_vm_size = vm_ram_size - balloon_size
15270
15271              From it we have: balloon_size = vm_ram_size - value
15272
15273   Returns
15274       • Nothing on success
15275
15276       • If the balloon driver is enabled but not functional because  the  KVM
15277         kernel module cannot support it, KvmMissingCap
15278
15279       • If no balloon device is present, DeviceNotActive
15280
15281   Notes
15282       This  command just issues a request to the guest.  When it returns, the
15283       balloon size may not have changed.  A guest can change the balloon size
15284       independent of this command.
15285
15286   Since
15287       0.14.0
15288
15289   Example
15290          -> { "execute": "balloon", "arguments": { "value": 536870912 } }
15291          <- { "return": {} }
15292
15293          With a 2.5GiB guest this command inflated the ballon to 3GiB.
15294
15295   BalloonInfo (Object)
15296       Information about the guest balloon device.
15297
15298   Members
15299       actual: int
15300              the  logical  size  of  the  VM  in  bytes  Formula  used: logi‐
15301              cal_vm_size = vm_ram_size - balloon_size
15302
15303   Since
15304       0.14.0
15305
15306   query-balloon (Command)
15307       Return information about the balloon device.
15308
15309   Returns
15310BalloonInfo on success
15311
15312       • If the balloon driver is enabled but not functional because  the  KVM
15313         kernel module cannot support it, KvmMissingCap
15314
15315       • If no balloon device is present, DeviceNotActive
15316
15317   Since
15318       0.14.0
15319
15320   Example
15321          -> { "execute": "query-balloon" }
15322          <- { "return": {
15323                   "actual": 1073741824,
15324                }
15325             }
15326
15327   BALLOON_CHANGE (Event)
15328       Emitted  when the guest changes the actual BALLOON level. This value is
15329       equivalent to the actual field return by the 'query-balloon' command
15330
15331   Arguments
15332       actual: int
15333              the logical  size  of  the  VM  in  bytes  Formula  used:  logi‐
15334              cal_vm_size = vm_ram_size - balloon_size
15335
15336   Note
15337       this event is rate-limited.
15338
15339   Since
15340       1.2
15341
15342   Example
15343          <- { "event": "BALLOON_CHANGE",
15344               "data": { "actual": 944766976 },
15345               "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
15346
15347   MemoryInfo (Object)
15348       Actual memory information in bytes.
15349
15350   Members
15351       base-memory: int
15352              size of "base" memory specified with command line option -m.
15353
15354       plugged-memory: int (optional)
15355              size  of memory that can be hot-unplugged. This field is omitted
15356              if target doesn't support memory hotplug (i.e. CONFIG_MEM_DEVICE
15357              not defined at build time).
15358
15359   Since
15360       2.11.0
15361
15362   query-memory-size-summary (Command)
15363       Return  the  amount of initially allocated and present hotpluggable (if
15364       enabled) memory in bytes.
15365
15366   Example
15367          -> { "execute": "query-memory-size-summary" }
15368          <- { "return": { "base-memory": 4294967296, "plugged-memory": 0 } }
15369
15370   Since
15371       2.11.0
15372
15373   PCDIMMDeviceInfo (Object)
15374       PCDIMMDevice state information
15375
15376   Members
15377       id: string (optional)
15378              device's ID
15379
15380       addr: int
15381              physical address, where device is mapped
15382
15383       size: int
15384              size of memory that the device provides
15385
15386       slot: int
15387              slot number at which device is plugged in
15388
15389       node: int
15390              NUMA node number where device is plugged in
15391
15392       memdev: string
15393              memory backend linked with device
15394
15395       hotplugged: boolean
15396              true if device was hotplugged
15397
15398       hotpluggable: boolean
15399              true if device if could be added/removed while machine  is  run‐
15400              ning
15401
15402   Since
15403       2.1
15404
15405   VirtioPMEMDeviceInfo (Object)
15406       VirtioPMEM state information
15407
15408   Members
15409       id: string (optional)
15410              device's ID
15411
15412       memaddr: int
15413              physical address in memory, where device is mapped
15414
15415       size: int
15416              size of memory that the device provides
15417
15418       memdev: string
15419              memory backend linked with device
15420
15421   Since
15422       4.1
15423
15424   VirtioMEMDeviceInfo (Object)
15425       VirtioMEMDevice state information
15426
15427   Members
15428       id: string (optional)
15429              device's ID
15430
15431       memaddr: int
15432              physical address in memory, where device is mapped
15433
15434       requested-size: int
15435              the user requested size of the device
15436
15437       size: int
15438              the (current) size of memory that the device provides
15439
15440       max-size: int
15441              the maximum size of memory that the device can provide
15442
15443       block-size: int
15444              the block size of memory that the device provides
15445
15446       node: int
15447              NUMA node number where device is assigned to
15448
15449       memdev: string
15450              memory backend linked with the region
15451
15452   Since
15453       5.1
15454
15455   MemoryDeviceInfo (Object)
15456       Union containing information about a memory device
15457
15458       nvdimm is included since 2.12. virtio-pmem is included since 4.1.  vir‐
15459       tio-mem is included since 5.1.
15460
15461   Members
15462       type   One of dimm, nvdimm, virtio-pmem, virtio-mem
15463
15464       data: PCDIMMDeviceInfo when type is "dimm"
15465
15466       data: PCDIMMDeviceInfo when type is "nvdimm"
15467
15468       data: VirtioPMEMDeviceInfo when type is "virtio-pmem"
15469
15470       data: VirtioMEMDeviceInfo when type is "virtio-mem"
15471
15472   Since
15473       2.1
15474
15475   query-memory-devices (Command)
15476       Lists available memory devices and their state
15477
15478   Since
15479       2.1
15480
15481   Example
15482          -> { "execute": "query-memory-devices" }
15483          <- { "return": [ { "data":
15484                                { "addr": 5368709120,
15485                                  "hotpluggable": true,
15486                                  "hotplugged": true,
15487                                  "id": "d1",
15488                                  "memdev": "/objects/memX",
15489                                  "node": 0,
15490                                  "size": 1073741824,
15491                                  "slot": 0},
15492                             "type": "dimm"
15493                           } ] }
15494
15495   MEMORY_DEVICE_SIZE_CHANGE (Event)
15496       Emitted when the size of a memory device changes. Only emitted for mem‐
15497       ory  devices that can actually change the size (e.g., virtio-mem due to
15498       guest action).
15499
15500   Arguments
15501       id: string (optional)
15502              device's ID
15503
15504       size: int
15505              the new size of memory that the device provides
15506
15507   Note
15508       this event is rate-limited.
15509
15510   Since
15511       5.1
15512
15513   Example
15514          <- { "event": "MEMORY_DEVICE_SIZE_CHANGE",
15515               "data": { "id": "vm0", "size": 1073741824},
15516               "timestamp": { "seconds": 1588168529, "microseconds": 201316 } }
15517
15518   MEM_UNPLUG_ERROR (Event)
15519       Emitted when memory hot unplug error occurs.
15520
15521   Arguments
15522       device: string
15523              device name
15524
15525       msg: string
15526              Informative message
15527
15528   Since
15529       2.4
15530
15531   Example
15532          <- { "event": "MEM_UNPLUG_ERROR"
15533               "data": { "device": "dimm1",
15534                         "msg": "acpi: device unplug for unsupported device"
15535               },
15536               "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
15537
15538   CpuModelInfo (Object)
15539       Virtual CPU model.
15540
15541       A CPU model consists of the name of a CPU definition,  to  which  delta
15542       changes  are  applied  (e.g. features added/removed). Most magic values
15543       that an architecture might require should be hidden  behind  the  name.
15544       However, if required, architectures can expose relevant properties.
15545
15546   Members
15547       name: string
15548              the name of the CPU definition the model is based on
15549
15550       props: value (optional)
15551              a dictionary of QOM properties to be applied
15552
15553   Since
15554       2.8.0
15555
15556   CpuModelExpansionType (Enum)
15557       An enumeration of CPU model expansion types.
15558
15559   Values
15560       static Expand  to  a  static  CPU model, a combination of a static base
15561              model name and property delta changes. As the static base  model
15562              will  never change, the expanded CPU model will be the same, in‐
15563              dependent of QEMU version, machine type,  machine  options,  and
15564              accelerator options.  Therefore, the resulting model can be used
15565              by tooling without having to specify a compatibility  machine  -
15566              e.g. when displaying the "host" model. The static CPU models are
15567              migration-safe.
15568
15569       full   Expand all properties. The produced model is not  guaranteed  to
15570              be migration-safe, but allows tooling to get an insight and work
15571              with model details.
15572
15573   Note
15574       When a non-migration-safe CPU model is expanded in  static  mode,  some
15575       features enabled by the CPU model may be omitted, because they can't be
15576       implemented  by  a  static  CPU  model  definition  (e.g.  cache   info
15577       passthrough and PMU passthrough in x86). If you need an accurate repre‐
15578       sentation of the features enabled by a  non-migration-safe  CPU  model,
15579       use  full.  If you need a static representation that will keep ABI com‐
15580       patibility even when changing QEMU version or machine-type, use  static
15581       (but keep in mind that some features may be omitted).
15582
15583   Since
15584       2.8.0
15585
15586   CpuModelCompareResult (Enum)
15587       An  enumeration  of CPU model comparison results. The result is usually
15588       calculated using e.g. CPU features or CPU generations.
15589
15590   Values
15591       incompatible
15592              If model A is incompatible to model B, model A is not guaranteed
15593              to run where model B runs and the other way around.
15594
15595       identical
15596              If model A is identical to model B, model A is guaranteed to run
15597              where model B runs and the other way around.
15598
15599       superset
15600              If model A is a superset of model B, model B  is  guaranteed  to
15601              run  where model A runs. There are no guarantees about the other
15602              way.
15603
15604       subset If model A is a subset of model B, model A is guaranteed to  run
15605              where model B runs. There are no guarantees about the other way.
15606
15607   Since
15608       2.8.0
15609
15610   CpuModelBaselineInfo (Object)
15611       The result of a CPU model baseline.
15612
15613   Members
15614       model: CpuModelInfo
15615              the baselined CpuModelInfo.
15616
15617   Since
15618       2.8.0
15619
15620   If
15621       defined(TARGET_S390X).SS CpuModelCompareInfo (Object)
15622
15623       The result of a CPU model comparison.
15624
15625   Members
15626       result: CpuModelCompareResult
15627              The result of the compare operation.
15628
15629       responsible-properties: array of string
15630              List  of  properties that led to the comparison result not being
15631              identical.
15632       responsible-properties is a list of QOM property names that led to both
15633       CPUs  not  being detected as identical. For identical models, this list
15634       is empty.  If a QOM property is read-only, that means there's no  known
15635       way  to  make  the  CPU  models identical. If the special property name
15636       "type" is included, the models are by definition not identical and can‐
15637       not be made identical.
15638
15639   Since
15640       2.8.0
15641
15642   If
15643       defined(TARGET_S390X).SS query-cpu-model-comparison (Command)
15644
15645       Compares  two CPU models, returning how they compare in a specific con‐
15646       figuration. The results indicates how  both  models  compare  regarding
15647       runnability.  This result can be used by tooling to make decisions if a
15648       certain CPU model will run in a certain configuration or if a  compati‐
15649       ble CPU model has to be created by baselining.
15650
15651       Usually, a CPU model is compared against the maximum possible CPU model
15652       of a certain configuration (e.g. the "host" model for KVM). If that CPU
15653       model is identical or a subset, it will run in that configuration.
15654
15655       The result returned by this command may be affected by:
15656
15657       • QEMU  version:  CPU  models  may look different depending on the QEMU
15658         version.   (Except  for  CPU   models   reported   as   "static"   in
15659         query-cpu-definitions.)
15660
15661       • machine-type:  CPU  model  may  look  different  depending on the ma‐
15662         chine-type.   (Except  for  CPU  models  reported  as   "static"   in
15663         query-cpu-definitions.)
15664
15665       • machine  options  (including accelerator): in some architectures, CPU
15666         models may look different depending on machine  and  accelerator  op‐
15667         tions. (Except for CPU models reported as "static" in query-cpu-defi‐
15668         nitions.)
15669
15670       • "-cpu" arguments and global properties: arguments to the -cpu  option
15671         and  global  properties  may  affect  expansion  of CPU models. Using
15672         query-cpu-model-expansion while using these is not advised.
15673
15674       Some architectures may not support comparing CPU models. s390x supports
15675       comparing CPU models.
15676
15677   Arguments
15678       modela: CpuModelInfo
15679              Not documented
15680
15681       modelb: CpuModelInfo
15682              Not documented
15683
15684   Returns
15685       a CpuModelBaselineInfo. Returns an error if comparing CPU models is not
15686       supported, if a model cannot be used, if a model  contains  an  unknown
15687       cpu definition name, unknown properties or properties with wrong types.
15688
15689   Note
15690       this  command  isn't specific to s390x, but is only implemented on this
15691       architecture currently.
15692
15693   Since
15694       2.8.0
15695
15696   If
15697       defined(TARGET_S390X).SS query-cpu-model-baseline (Command)
15698
15699       Baseline two CPU models, creating a compatible third model. The created
15700       model  will  always be a static, migration-safe CPU model (see "static"
15701       CPU model expansion for details).
15702
15703       This interface can be used by tooling to create a compatible CPU  model
15704       out  two  CPU  models.  The created CPU model will be identical to or a
15705       subset of both CPU models when comparing them. Therefore,  the  created
15706       CPU model is guaranteed to run where the given CPU models run.
15707
15708       The result returned by this command may be affected by:
15709
15710       • QEMU  version:  CPU  models  may look different depending on the QEMU
15711         version.   (Except  for  CPU   models   reported   as   "static"   in
15712         query-cpu-definitions.)
15713
15714       • machine-type:  CPU  model  may  look  different  depending on the ma‐
15715         chine-type.   (Except  for  CPU  models  reported  as   "static"   in
15716         query-cpu-definitions.)
15717
15718       • machine  options  (including accelerator): in some architectures, CPU
15719         models may look different depending on machine  and  accelerator  op‐
15720         tions. (Except for CPU models reported as "static" in query-cpu-defi‐
15721         nitions.)
15722
15723       • "-cpu" arguments and global properties: arguments to the -cpu  option
15724         and  global  properties  may  affect  expansion  of CPU models. Using
15725         query-cpu-model-expansion while using these is not advised.
15726
15727       Some architectures may not support baselining CPU  models.  s390x  sup‐
15728       ports baselining CPU models.
15729
15730   Arguments
15731       modela: CpuModelInfo
15732              Not documented
15733
15734       modelb: CpuModelInfo
15735              Not documented
15736
15737   Returns
15738       a  CpuModelBaselineInfo.  Returns  an error if baselining CPU models is
15739       not supported, if a model cannot be used, if a model  contains  an  un‐
15740       known  cpu definition name, unknown properties or properties with wrong
15741       types.
15742
15743   Note
15744       this command isn't specific to s390x, but is only implemented  on  this
15745       architecture currently.
15746
15747   Since
15748       2.8.0
15749
15750   If
15751       defined(TARGET_S390X).SS CpuModelExpansionInfo (Object)
15752
15753       The result of a cpu model expansion.
15754
15755   Members
15756       model: CpuModelInfo
15757              the expanded CpuModelInfo.
15758
15759   Since
15760       2.8.0
15761
15762   If
15763       defined(TARGET_S390X) || defined(TARGET_I386) || defined(TARGET_ARM).SS
15764       query-cpu-model-expansion (Command)
15765
15766       Expands a given CPU model (or a combination of CPU model  +  additional
15767       options)  to different granularities, allowing tooling to get an under‐
15768       standing what a specific CPU model looks like in QEMU under  a  certain
15769       configuration.
15770
15771       This interface can be used to query the "host" CPU model.
15772
15773       The data returned by this command may be affected by:
15774
15775       • QEMU  version:  CPU  models  may look different depending on the QEMU
15776         version.   (Except  for  CPU   models   reported   as   "static"   in
15777         query-cpu-definitions.)
15778
15779       • machine-type:  CPU  model   may  look  different depending on the ma‐
15780         chine-type.   (Except  for  CPU  models  reported  as   "static"   in
15781         query-cpu-definitions.)
15782
15783       • machine  options  (including accelerator): in some architectures, CPU
15784         models may look different depending on machine  and  accelerator  op‐
15785         tions. (Except for CPU models reported as "static" in query-cpu-defi‐
15786         nitions.)
15787
15788       • "-cpu" arguments and global properties: arguments to the -cpu  option
15789         and  global  properties  may  affect  expansion  of CPU models. Using
15790         query-cpu-model-expansion while using these is not advised.
15791
15792       Some architectures may not support all expansion types. s390x  supports
15793       "full" and "static". Arm only supports "full".
15794
15795   Arguments
15796       type: CpuModelExpansionType
15797              Not documented
15798
15799       model: CpuModelInfo
15800              Not documented
15801
15802   Returns
15803       a  CpuModelExpansionInfo.  Returns  an error if expanding CPU models is
15804       not supported, if the model cannot be expanded, if the  model  contains
15805       an unknown CPU definition name, unknown properties or properties with a
15806       wrong type. Also returns an error if an  expansion  type  is  not  sup‐
15807       ported.
15808
15809   Since
15810       2.8.0
15811
15812   If
15813       defined(TARGET_S390X) || defined(TARGET_I386) || defined(TARGET_ARM).SS
15814       CpuDefinitionInfo (Object)
15815
15816       Virtual CPU definition.
15817
15818   Members
15819       name: string
15820              the name of the CPU definition
15821
15822       migration-safe: boolean (optional)
15823              whether a CPU definition can be safely  used  for  migration  in
15824              combination with a QEMU compatibility machine when migrating be‐
15825              tween different QEMU versions and between hosts  with  different
15826              sets  of  (hardware  or software) capabilities. If not provided,
15827              information is not available and callers should not  assume  the
15828              CPU definition to be migration-safe. (since 2.8)
15829
15830       static: boolean
15831              whether a CPU definition is static and will not change depending
15832              on QEMU version, machine type, machine options  and  accelerator
15833              options.  A static model is always migration-safe. (since 2.8)
15834
15835       unavailable-features: array of string (optional)
15836              List  of  properties  that prevent the CPU model from running in
15837              the current host. (since 2.8)
15838
15839       typename: string
15840              Type name that can be used as  argument  to  device-list-proper‐
15841              ties,  to  introspect  properties  configurable  using  -cpu  or
15842              -global.  (since 2.9)
15843
15844       alias-of: string (optional)
15845              Name of CPU model this model is an alias for.  The target of the
15846              CPU  model alias may change depending on the machine type.  Man‐
15847              agement software is supposed to translate CPU model  aliases  in
15848              the  VM  configuration,  because  aliases  may stop being migra‐
15849              tion-safe in the future (since 4.1)
15850
15851       deprecated: boolean
15852              If true, this CPU model is deprecated and may be removed  in  in
15853              some  future  version  of QEMU according to the QEMU deprecation
15854              policy. (since 5.2)
15855       unavailable-features is a list of QOM property names that represent CPU
15856       model  attributes  that prevent the CPU from running.  If the QOM prop‐
15857       erty is read-only, that means there's no known  way  to  make  the  CPU
15858       model  run in the current host. Implementations that choose not to pro‐
15859       vide specific information return the  property  name  "type".   If  the
15860       property is read-write, it means that it MAY be possible to run the CPU
15861       model in the current host if that property is changed. Management soft‐
15862       ware  can  use  it as hints to suggest or choose an alternative for the
15863       user, or just to generate meaningful error messages explaining why  the
15864       CPU model can't be used.  If unavailable-features is an empty list, the
15865       CPU model is runnable using the current host and machine-type.  If  un‐
15866       available-features  is not present, runnability information for the CPU
15867       is not available.
15868
15869   Since
15870       1.2.0
15871
15872   If
15873       defined(TARGET_PPC) || defined(TARGET_ARM) ||  defined(TARGET_I386)  ||
15874       defined(TARGET_S390X)  || defined(TARGET_MIPS).SS query-cpu-definitions
15875       (Command)
15876
15877       Return a list of supported virtual CPU definitions
15878
15879   Returns
15880       a list of CpuDefInfo
15881
15882   Since
15883       1.2.0
15884
15885   If
15886       defined(TARGET_PPC) || defined(TARGET_ARM) ||  defined(TARGET_I386)  ||
15887       defined(TARGET_S390X) || defined(TARGET_MIPS).SH RECORD/REPLAY
15888
15889   ReplayMode (Enum)
15890       Mode of the replay subsystem.
15891
15892   Values
15893       none   normal execution mode. Replay or record are not enabled.
15894
15895       record record  mode. All non-deterministic data is written into the re‐
15896              play log.
15897
15898       play   replay mode. Non-deterministic data required for  system  execu‐
15899              tion is read from the log.
15900
15901   Since
15902       2.5
15903
15904   ReplayInfo (Object)
15905       Record/replay information.
15906
15907   Members
15908       mode: ReplayMode
15909              current mode.
15910
15911       filename: string (optional)
15912              name  of  the  record/replay  log  file.   It is present only in
15913              record or replay modes, when the log is recorded or replayed.
15914
15915       icount: int
15916              current number of executed instructions.
15917
15918   Since
15919       5.2
15920
15921   query-replay (Command)
15922       Retrieve the record/replay information.  It includes  current  instruc‐
15923       tion count which may be used for replay-break and replay-seek commands.
15924
15925   Returns
15926       record/replay information.
15927
15928   Since
15929       5.2
15930
15931   Example
15932          -> { "execute": "query-replay" }
15933          <- { "return": { "mode": "play", "filename": "log.rr", "icount": 220414 } }
15934
15935   replay-break (Command)
15936       Set  replay  breakpoint  at  instruction count icount.  Execution stops
15937       when the specified instruction is reached.  There can be  at  most  one
15938       breakpoint.  When  breakpoint  is  set,  any prior one is removed.  The
15939       breakpoint may be set only in replay mode and  only  "in  the  future",
15940       i.e.  at  instruction counts greater than the current one.  The current
15941       instruction count can be observed with query-replay.
15942
15943   Arguments
15944       icount: int
15945              instruction count to stop at
15946
15947   Since
15948       5.2
15949
15950   Example
15951          -> { "execute": "replay-break", "data": { "icount": 220414 } }
15952
15953   replay-delete-break (Command)
15954       Remove replay breakpoint which was set with replay-break.  The  command
15955       is ignored when there are no replay breakpoints.
15956
15957   Since
15958       5.2
15959
15960   Example
15961          -> { "execute": "replay-delete-break" }
15962
15963   replay-seek (Command)
15964       Automatically  proceed  to the instruction count icount, when replaying
15965       the execution. The command automatically loads nearest snapshot and re‐
15966       plays  the execution to find the desired instruction.  When there is no
15967       preceding snapshot or the execution is not replayed, then  the  command
15968       fails.  icount for the reference may be obtained with query-replay com‐
15969       mand.
15970
15971   Arguments
15972       icount: int
15973              target instruction count
15974
15975   Since
15976       5.2
15977
15978   Example
15979          -> { "execute": "replay-seek", "data": { "icount": 220414 } }
15980

MISCELLANEA

15982   add_client (Command)
15983       Allow client connections for VNC, Spice and socket based character  de‐
15984       vices to be passed in to QEMU via SCM_RIGHTS.
15985
15986   Arguments
15987       protocol: string
15988              protocol  name.  Valid names are "vnc", "spice" or the name of a
15989              character device (eg. from -chardev id=XXXX)
15990
15991       fdname: string
15992              file descriptor name previously passed via 'getfd' command
15993
15994       skipauth: boolean (optional)
15995              whether to  skip  authentication.  Only  applies  to  "vnc"  and
15996              "spice" protocols
15997
15998       tls: boolean (optional)
15999              whether to perform TLS. Only applies to the "spice" protocol
16000
16001   Returns
16002       nothing on success.
16003
16004   Since
16005       0.14.0
16006
16007   Example
16008          -> { "execute": "add_client", "arguments": { "protocol": "vnc",
16009                                                       "fdname": "myclient" } }
16010          <- { "return": {} }
16011
16012   NameInfo (Object)
16013       Guest name information.
16014
16015   Members
16016       name: string (optional)
16017              The name of the guest
16018
16019   Since
16020       0.14.0
16021
16022   query-name (Command)
16023       Return the name information of a guest.
16024
16025   Returns
16026       NameInfo of the guest
16027
16028   Since
16029       0.14.0
16030
16031   Example
16032          -> { "execute": "query-name" }
16033          <- { "return": { "name": "qemu-name" } }
16034
16035   IOThreadInfo (Object)
16036       Information about an iothread
16037
16038   Members
16039       id: string
16040              the identifier of the iothread
16041
16042       thread-id: int
16043              ID of the underlying host thread
16044
16045       poll-max-ns: int
16046              maximum  polling  time in ns, 0 means polling is disabled (since
16047              2.9)
16048
16049       poll-grow: int
16050              how many ns will be added to polling time, 0 means that it's not
16051              configured (since 2.9)
16052
16053       poll-shrink: int
16054              how many ns will be removed from polling time, 0 means that it's
16055              not configured (since 2.9)
16056
16057   Since
16058       2.0
16059
16060   query-iothreads (Command)
16061       Returns a list of information about each iothread.
16062
16063   Note
16064       this list excludes the QEMU main loop thread, which is not declared us‐
16065       ing  the  -object  iothread command-line option.  It is always the main
16066       thread of the process.
16067
16068   Returns
16069       a list of IOThreadInfo for each iothread
16070
16071   Since
16072       2.0
16073
16074   Example
16075          -> { "execute": "query-iothreads" }
16076          <- { "return": [
16077                   {
16078                      "id":"iothread0",
16079                      "thread-id":3134
16080                   },
16081                   {
16082                      "id":"iothread1",
16083                      "thread-id":3135
16084                   }
16085                ]
16086             }
16087
16088   stop (Command)
16089       Stop all guest VCPU execution.
16090
16091   Since
16092       0.14.0
16093
16094   Notes
16095       This function will succeed even if the guest is already in the  stopped
16096       state.   In  "inmigrate"  state,  it will ensure that the guest remains
16097       paused once migration finishes, as if the -S option was passed  on  the
16098       command line.
16099
16100   Example
16101          -> { "execute": "stop" }
16102          <- { "return": {} }
16103
16104   cont (Command)
16105       Resume guest VCPU execution.
16106
16107   Since
16108       0.14.0
16109
16110   Returns
16111       If successful, nothing
16112
16113   Notes
16114       This  command  will succeed if the guest is currently running.  It will
16115       also succeed if the guest is in the "inmigrate" state;  in  this  case,
16116       the  effect of the command is to make sure the guest starts once migra‐
16117       tion finishes, removing the effect of the -S command line option if  it
16118       was passed.
16119
16120   Example
16121          -> { "execute": "cont" }
16122          <- { "return": {} }
16123
16124   x-exit-preconfig (Command)
16125       Exit from "preconfig" state
16126
16127       This  command  makes  QEMU exit the preconfig state and proceed with VM
16128       initialization using configuration data provided on  the  command  line
16129       and via the QMP monitor during the preconfig state. The command is only
16130       available during the preconfig state (i.e. when the --preconfig command
16131       line option was in use).
16132
16133       Since 3.0
16134
16135   Returns
16136       nothing
16137
16138   Example
16139          -> { "execute": "x-exit-preconfig" }
16140          <- { "return": {} }
16141
16142   human-monitor-command (Command)
16143       Execute a command on the human monitor and return the output.
16144
16145   Arguments
16146       command-line: string
16147              the command to execute in the human monitor
16148
16149       cpu-index: int (optional)
16150              The CPU to use for commands that require an implicit CPU
16151
16152   Features
16153       savevm-monitor-nodes
16154              If  present,  HMP  command  savevm  only snapshots monitor-owned
16155              nodes if they have no parents.  This allows the use of  'savevm'
16156              with -blockdev. (since 4.2)
16157
16158   Returns
16159       the output of the command as a string
16160
16161   Since
16162       0.14.0
16163
16164   Notes
16165       This command only exists as a stop-gap.  Its use is highly discouraged.
16166       The semantics of this command are not guaranteed: this means that  com‐
16167       mand  names,  arguments  and  responses can change or be removed at ANY
16168       time.  Applications that rely on long term stability guarantees  should
16169       NOT use this command.
16170
16171       Known limitations:
16172
16173       • This  command  is  stateless, this means that commands that depend on
16174         state information (such as getfd) might not work
16175
16176       • Commands that prompt the user for data don't currently work
16177
16178   Example
16179          -> { "execute": "human-monitor-command",
16180               "arguments": { "command-line": "info kvm" } }
16181          <- { "return": "kvm support: enabled\r\n" }
16182
16183   change (Command)
16184       This command is multiple commands multiplexed together.
16185
16186   Arguments
16187       device: string
16188              This is normally the name of a block device but it may  also  be
16189              'vnc'.  when it's 'vnc', then sub command depends on target
16190
16191       target: string
16192              If  device is a block device, then this is the new filename.  If
16193              device is 'vnc', then if the value 'password'  selects  the  vnc
16194              change  password  command.    Otherwise,  this  specifies  a new
16195              server URI address to listen to for VNC connections.
16196
16197       arg: string (optional)
16198              If device is a block device, then this is an optional format  to
16199              open  the  device with.  If device is 'vnc' and target is 'pass‐
16200              word',  this  is   the   new   VNC   password   to   set.    See
16201              change-vnc-password for additional notes.
16202
16203   Features
16204       deprecated
16205              This  command  is  deprecated.   For changing block devices, use
16206              'blockdev-change-medium' instead; for changing  VNC  parameters,
16207              use 'change-vnc-password' instead.
16208
16209   Returns
16210       • Nothing on success.
16211
16212       • If device is not a valid block device, DeviceNotFound
16213
16214   Since
16215       0.14.0
16216
16217   Example
16218          1. Change a removable medium
16219
16220          -> { "execute": "change",
16221               "arguments": { "device": "ide1-cd0",
16222                              "target": "/srv/images/Fedora-12-x86_64-DVD.iso" } }
16223          <- { "return": {} }
16224
16225          2. Change VNC password
16226
16227          -> { "execute": "change",
16228               "arguments": { "device": "vnc", "target": "password",
16229                              "arg": "foobar1" } }
16230          <- { "return": {} }
16231
16232   getfd (Command)
16233       Receive a file descriptor via SCM rights and assign it a name
16234
16235   Arguments
16236       fdname: string
16237              file descriptor name
16238
16239   Returns
16240       Nothing on success
16241
16242   Since
16243       0.14.0
16244
16245   Notes
16246       If  fdname  already  exists, the file descriptor assigned to it will be
16247       closed and replaced by the received file descriptor.
16248
16249       The 'closefd' command can be used to explicitly close the file descrip‐
16250       tor when it is no longer needed.
16251
16252   Example
16253          -> { "execute": "getfd", "arguments": { "fdname": "fd1" } }
16254          <- { "return": {} }
16255
16256   closefd (Command)
16257       Close a file descriptor previously passed via SCM rights
16258
16259   Arguments
16260       fdname: string
16261              file descriptor name
16262
16263   Returns
16264       Nothing on success
16265
16266   Since
16267       0.14.0
16268
16269   Example
16270          -> { "execute": "closefd", "arguments": { "fdname": "fd1" } }
16271          <- { "return": {} }
16272
16273   AddfdInfo (Object)
16274       Information about a file descriptor that was added to an fd set.
16275
16276   Members
16277       fdset-id: int
16278              The ID of the fd set that fd was added to.
16279
16280       fd: int
16281              The  file  descriptor that was received via SCM rights and added
16282              to the fd set.
16283
16284   Since
16285       1.2.0
16286
16287   add-fd (Command)
16288       Add a file descriptor, that was passed via SCM rights, to an fd set.
16289
16290   Arguments
16291       fdset-id: int (optional)
16292              The ID of the fd set to add the file descriptor to.
16293
16294       opaque: string (optional)
16295              A free-form string that can be used to describe the fd.
16296
16297   Returns
16298AddfdInfo on success
16299
16300       • If file descriptor was not received, FdNotSupplied
16301
16302       • If fdset-id is a negative value, InvalidParameterValue
16303
16304   Notes
16305       The list of fd sets is shared by all monitor connections.
16306
16307       If fdset-id is not specified, a new fd set will be created.
16308
16309   Since
16310       1.2.0
16311
16312   Example
16313          -> { "execute": "add-fd", "arguments": { "fdset-id": 1 } }
16314          <- { "return": { "fdset-id": 1, "fd": 3 } }
16315
16316   remove-fd (Command)
16317       Remove a file descriptor from an fd set.
16318
16319   Arguments
16320       fdset-id: int
16321              The ID of the fd set that the file descriptor belongs to.
16322
16323       fd: int (optional)
16324              The file descriptor that is to be removed.
16325
16326   Returns
16327       • Nothing on success
16328
16329       • If fdset-id or fd is not found, FdNotFound
16330
16331   Since
16332       1.2.0
16333
16334   Notes
16335       The list of fd sets is shared by all monitor connections.
16336
16337       If fd is not specified, all file descriptors in fdset-id  will  be  re‐
16338       moved.
16339
16340   Example
16341          -> { "execute": "remove-fd", "arguments": { "fdset-id": 1, "fd": 3 } }
16342          <- { "return": {} }
16343
16344   FdsetFdInfo (Object)
16345       Information about a file descriptor that belongs to an fd set.
16346
16347   Members
16348       fd: int
16349              The file descriptor value.
16350
16351       opaque: string (optional)
16352              A free-form string that can be used to describe the fd.
16353
16354   Since
16355       1.2.0
16356
16357   FdsetInfo (Object)
16358       Information about an fd set.
16359
16360   Members
16361       fdset-id: int
16362              The ID of the fd set.
16363
16364       fds: array of FdsetFdInfo
16365              A list of file descriptors that belong to this fd set.
16366
16367   Since
16368       1.2.0
16369
16370   query-fdsets (Command)
16371       Return information describing all fd sets.
16372
16373   Returns
16374       A list of FdsetInfo
16375
16376   Since
16377       1.2.0
16378
16379   Note
16380       The list of fd sets is shared by all monitor connections.
16381
16382   Example
16383          -> { "execute": "query-fdsets" }
16384          <- { "return": [
16385                 {
16386                   "fds": [
16387                     {
16388                       "fd": 30,
16389                       "opaque": "rdonly:/path/to/file"
16390                     },
16391                     {
16392                       "fd": 24,
16393                       "opaque": "rdwr:/path/to/file"
16394                     }
16395                   ],
16396                   "fdset-id": 1
16397                 },
16398                 {
16399                   "fds": [
16400                     {
16401                       "fd": 28
16402                     },
16403                     {
16404                       "fd": 29
16405                     }
16406                   ],
16407                   "fdset-id": 0
16408                 }
16409               ]
16410             }
16411
16412   CommandLineParameterType (Enum)
16413       Possible types for an option parameter.
16414
16415   Values
16416       string accepts a character string
16417
16418       boolean
16419              accepts "on" or "off"
16420
16421       number accepts a number
16422
16423       size   accepts  a number followed by an optional suffix (K)ilo, (M)ega,
16424              (G)iga, (T)era
16425
16426   Since
16427       1.5
16428
16429   CommandLineParameterInfo (Object)
16430       Details about a single parameter of a command line option.
16431
16432   Members
16433       name: string
16434              parameter name
16435
16436       type: CommandLineParameterType
16437              parameter CommandLineParameterType
16438
16439       help: string (optional)
16440              human readable text string, not suitable for parsing.
16441
16442       default: string (optional)
16443              default value string (since 2.1)
16444
16445   Since
16446       1.5
16447
16448   CommandLineOptionInfo (Object)
16449       Details about a command line option, including its  list  of  parameter
16450       details
16451
16452   Members
16453       option: string
16454              option name
16455
16456       parameters: array of CommandLineParameterInfo
16457              an array of CommandLineParameterInfo
16458
16459   Since
16460       1.5
16461
16462   query-command-line-options (Command)
16463       Query command line option schema.
16464
16465   Arguments
16466       option: string (optional)
16467              option name
16468
16469   Returns
16470       list  of  CommandLineOptionInfo  for  all options (or for the given op‐
16471       tion).  Returns an error if the given option doesn't exist.
16472
16473   Since
16474       1.5
16475
16476   Example
16477          -> { "execute": "query-command-line-options",
16478               "arguments": { "option": "option-rom" } }
16479          <- { "return": [
16480                  {
16481                      "parameters": [
16482                          {
16483                              "name": "romfile",
16484                              "type": "string"
16485                          },
16486                          {
16487                              "name": "bootindex",
16488                              "type": "number"
16489                          }
16490                      ],
16491                      "option": "option-rom"
16492                  }
16493               ]
16494             }
16495
16496   RTC_CHANGE (Event)
16497       Emitted when the guest changes the RTC time.
16498
16499   Arguments
16500       offset: int
16501              offset between base RTC clock (as specified by -rtc  base),  and
16502              new RTC clock value
16503
16504   Note
16505       This event is rate-limited.
16506
16507   Since
16508       0.13.0
16509
16510   Example
16511          <-   { "event": "RTC_CHANGE",
16512                 "data": { "offset": 78 },
16513                 "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
16514
16515   If
16516       defined(TARGET_ALPHA) || defined(TARGET_ARM) || defined(TARGET_HPPA) ||
16517       defined(TARGET_I386) || defined(TARGET_MIPS) ||  defined(TARGET_MIPS64)
16518       ||   defined(TARGET_MOXIE)   ||   defined(TARGET_PPC)  ||  defined(TAR‐
16519       GET_PPC64)  ||  defined(TARGET_S390X)  ||  defined(TARGET_SH4)  ||  de‐
16520       fined(TARGET_SPARC).SS rtc-reset-reinjection (Command)
16521
16522       This  command will reset the RTC interrupt reinjection backlog.  Can be
16523       used if another mechanism to synchronize guest time is in  effect,  for
16524       example QEMU guest agent's guest-set-time command.
16525
16526   Since
16527       2.1
16528
16529   Example
16530          -> { "execute": "rtc-reset-reinjection" }
16531          <- { "return": {} }
16532
16533   If
16534       defined(TARGET_I386).SS SevState (Enum)
16535
16536       An enumeration of SEV state information used during query-sev.
16537
16538   Values
16539       uninit The guest is uninitialized.
16540
16541       launch-update
16542              The guest is currently being launched; plaintext data and regis‐
16543              ter state is being imported.
16544
16545       launch-secret
16546              The guest is currently being launched; ciphertext data is  being
16547              imported.
16548
16549       running
16550              The guest is fully launched or migrated in.
16551
16552       send-update
16553              The guest is currently being migrated out to another machine.
16554
16555       receive-update
16556              The guest is currently being migrated from another machine.
16557
16558   Since
16559       2.12
16560
16561   If
16562       defined(TARGET_I386).SS SevInfo (Object)
16563
16564       Information about Secure Encrypted Virtualization (SEV) support
16565
16566   Members
16567       enabled: boolean
16568              true if SEV is active
16569
16570       api-major: int
16571              SEV API major version
16572
16573       api-minor: int
16574              SEV API minor version
16575
16576       build-id: int
16577              SEV FW build id
16578
16579       policy: int
16580              SEV policy value
16581
16582       state: SevState
16583              SEV guest state
16584
16585       handle: int
16586              SEV firmware handle
16587
16588   Since
16589       2.12
16590
16591   If
16592       defined(TARGET_I386).SS query-sev (Command)
16593
16594       Returns information about SEV
16595
16596   Returns
16597       SevInfo
16598
16599   Since
16600       2.12
16601
16602   Example
16603          -> { "execute": "query-sev" }
16604          <- { "return": { "enabled": true, "api-major" : 0, "api-minor" : 0,
16605                           "build-id" : 0, "policy" : 0, "state" : "running",
16606                           "handle" : 1 } }
16607
16608   If
16609       defined(TARGET_I386).SS SevLaunchMeasureInfo (Object)
16610
16611       SEV Guest Launch measurement information
16612
16613   Members
16614       data: string
16615              the measurement value encoded in base64
16616
16617   Since
16618       2.12
16619
16620   If
16621       defined(TARGET_I386).SS query-sev-launch-measure (Command)
16622
16623       Query the SEV guest launch information.
16624
16625   Returns
16626       The SevLaunchMeasureInfo for the guest
16627
16628   Since
16629       2.12
16630
16631   Example
16632          -> { "execute": "query-sev-launch-measure" }
16633          <- { "return": { "data": "4l8LXeNlSPUDlXPJG5966/8%YZ" } }
16634
16635   If
16636       defined(TARGET_I386).SS SevCapability (Object)
16637
16638       The  struct  describes capability for a Secure Encrypted Virtualization
16639       feature.
16640
16641   Members
16642       pdh: string
16643              Platform Diffie-Hellman key (base64 encoded)
16644
16645       cert-chain: string
16646              PDH certificate chain (base64 encoded)
16647
16648       cbitpos: int
16649              C-bit location in page table entry
16650
16651       reduced-phys-bits: int
16652              Number of physical Address bit reduction when SEV is enabled
16653
16654   Since
16655       2.12
16656
16657   If
16658       defined(TARGET_I386).SS query-sev-capabilities (Command)
16659
16660       This command is used to get the SEV capabilities, and is  supported  on
16661       AMD X86 platforms only.
16662
16663   Returns
16664       SevCapability objects.
16665
16666   Since
16667       2.12
16668
16669   Example
16670          -> { "execute": "query-sev-capabilities" }
16671          <- { "return": { "pdh": "8CCDD8DDD", "cert-chain": "888CCCDDDEE",
16672                           "cbitpos": 47, "reduced-phys-bits": 5}}
16673
16674   If
16675       defined(TARGET_I386).SS dump-skeys (Command)
16676
16677       Dump guest's storage keys
16678
16679   Arguments
16680       filename: string
16681              the path to the file to dump to
16682       This command is only supported on s390 architecture.
16683
16684   Since
16685       2.5
16686
16687   Example
16688          -> { "execute": "dump-skeys",
16689               "arguments": { "filename": "/tmp/skeys" } }
16690          <- { "return": {} }
16691
16692   If
16693       defined(TARGET_S390X).SS GICCapability (Object)
16694
16695       The  struct  describes capability for a specific GIC (Generic Interrupt
16696       Controller) version. These bits are not only decided by QEMU/KVM  soft‐
16697       ware version, but also decided by the hardware that the program is run‐
16698       ning upon.
16699
16700   Members
16701       version: int
16702              version of GIC to be described. Currently, only 2 and 3 are sup‐
16703              ported.
16704
16705       emulated: boolean
16706              whether  current  QEMU/hardware  supports emulated GIC device in
16707              user space.
16708
16709       kernel: boolean
16710              whether current QEMU/hardware supports hardware accelerated  GIC
16711              device in kernel.
16712
16713   Since
16714       2.6
16715
16716   If
16717       defined(TARGET_ARM).SS query-gic-capabilities (Command)
16718
16719       This  command  is  ARM-only. It will return a list of GICCapability ob‐
16720       jects that describe its capability bits.
16721
16722   Returns
16723       a list of GICCapability objects.
16724
16725   Since
16726       2.6
16727
16728   Example
16729          -> { "execute": "query-gic-capabilities" }
16730          <- { "return": [{ "version": 2, "emulated": true, "kernel": false },
16731                          { "version": 3, "emulated": false, "kernel": true } ] }
16732
16733   If
16734       defined(TARGET_ARM).SH AUDIO
16735
16736   AudiodevPerDirectionOptions (Object)
16737       General audio backend options that  are  used  for  both  playback  and
16738       recording.
16739
16740   Members
16741       mixing-engine: boolean (optional)
16742              use QEMU's mixing engine to mix all streams inside QEMU and con‐
16743              vert audio formats when not supported by the backend.  When  set
16744              to off, fixed-settings must be also off (default on, since 4.2)
16745
16746       fixed-settings: boolean (optional)
16747              use  fixed  settings for host input/output. When off, frequency,
16748              channels and format must not be specified (default true)
16749
16750       frequency: int (optional)
16751              frequency to use when using fixed settings (default 44100)
16752
16753       channels: int (optional)
16754              number of channels when using fixed settings (default 2)
16755
16756       voices: int (optional)
16757              number of voices to use (default 1)
16758
16759       format: AudioFormat (optional)
16760              sample format to use when using fixed settings (default s16)
16761
16762       buffer-length: int (optional)
16763              the buffer length in microseconds
16764
16765   Since
16766       4.0
16767
16768   AudiodevGenericOptions (Object)
16769       Generic driver-specific options.
16770
16771   Members
16772       in: AudiodevPerDirectionOptions (optional)
16773              options of the capture stream
16774
16775       out: AudiodevPerDirectionOptions (optional)
16776              options of the playback stream
16777
16778   Since
16779       4.0
16780
16781   AudiodevAlsaPerDirectionOptions (Object)
16782       Options of the ALSA backend that are used for both playback and record‐
16783       ing.
16784
16785   Members
16786       dev: string (optional)
16787              the name of the ALSA device to use (default 'default')
16788
16789       period-length: int (optional)
16790              the period length in microseconds
16791
16792       try-poll: boolean (optional)
16793              attempt  to use poll mode, falling back to non-polling access on
16794              failure (default true)
16795
16796       The members of AudiodevPerDirectionOptions
16797
16798   Since
16799       4.0
16800
16801   AudiodevAlsaOptions (Object)
16802       Options of the ALSA audio backend.
16803
16804   Members
16805       in: AudiodevAlsaPerDirectionOptions (optional)
16806              options of the capture stream
16807
16808       out: AudiodevAlsaPerDirectionOptions (optional)
16809              options of the playback stream
16810
16811       threshold: int (optional)
16812              set the threshold (in microseconds) when playback starts
16813
16814   Since
16815       4.0
16816
16817   AudiodevCoreaudioPerDirectionOptions (Object)
16818       Options of the Core Audio backend that are used for both  playback  and
16819       recording.
16820
16821   Members
16822       buffer-count: int (optional)
16823              number of buffers
16824
16825       The members of AudiodevPerDirectionOptions
16826
16827   Since
16828       4.0
16829
16830   AudiodevCoreaudioOptions (Object)
16831       Options of the coreaudio audio backend.
16832
16833   Members
16834       in: AudiodevCoreaudioPerDirectionOptions (optional)
16835              options of the capture stream
16836
16837       out: AudiodevCoreaudioPerDirectionOptions (optional)
16838              options of the playback stream
16839
16840   Since
16841       4.0
16842
16843   AudiodevDsoundOptions (Object)
16844       Options of the DirectSound audio backend.
16845
16846   Members
16847       in: AudiodevPerDirectionOptions (optional)
16848              options of the capture stream
16849
16850       out: AudiodevPerDirectionOptions (optional)
16851              options of the playback stream
16852
16853       latency: int (optional)
16854              add extra latency to playback in microseconds (default 10000)
16855
16856   Since
16857       4.0
16858
16859   AudiodevJackPerDirectionOptions (Object)
16860       Options of the JACK backend that are used for both playback and record‐
16861       ing.
16862
16863   Members
16864       server-name: string (optional)
16865              select from among several possible concurrent  server  instances
16866              (default: environment variable $JACK_DEFAULT_SERVER if set, else
16867              "default")
16868
16869       client-name: string (optional)
16870              the client name to use. The server will modify this name to cre‐
16871              ate  a  unique variant, if needed unless exact-name is true (de‐
16872              fault: the guest's name)
16873
16874       connect-ports: string (optional)
16875              if set, a regular expression of JACK client port name(s) to mon‐
16876              itor for and automatically connect to
16877
16878       start-server: boolean (optional)
16879              start  a  jack server process if one is not already present (de‐
16880              fault: false)
16881
16882       exact-name: boolean (optional)
16883              use the exact name requested otherwise JACK automatically gener‐
16884              ates a unique one, if needed (default: false)
16885
16886       The members of AudiodevPerDirectionOptions
16887
16888   Since
16889       5.1
16890
16891   AudiodevJackOptions (Object)
16892       Options of the JACK audio backend.
16893
16894   Members
16895       in: AudiodevJackPerDirectionOptions (optional)
16896              options of the capture stream
16897
16898       out: AudiodevJackPerDirectionOptions (optional)
16899              options of the playback stream
16900
16901   Since
16902       5.1
16903
16904   AudiodevOssPerDirectionOptions (Object)
16905       Options  of the OSS backend that are used for both playback and record‐
16906       ing.
16907
16908   Members
16909       dev: string (optional)
16910              file name of the OSS device (default '/dev/dsp')
16911
16912       buffer-count: int (optional)
16913              number of buffers
16914
16915       try-poll: boolean (optional)
16916              attempt to use poll mode, falling back to non-polling access  on
16917              failure (default true)
16918
16919       The members of AudiodevPerDirectionOptions
16920
16921   Since
16922       4.0
16923
16924   AudiodevOssOptions (Object)
16925       Options of the OSS audio backend.
16926
16927   Members
16928       in: AudiodevOssPerDirectionOptions (optional)
16929              options of the capture stream
16930
16931       out: AudiodevOssPerDirectionOptions (optional)
16932              options of the playback stream
16933
16934       try-mmap: boolean (optional)
16935              try   using  memory-mapped  access,  falling  back  to  non-mem‐
16936              ory-mapped access on failure (default true)
16937
16938       exclusive: boolean (optional)
16939              open device in exclusive mode (vmix won't work) (default false)
16940
16941       dsp-policy: int (optional)
16942              set the timing policy of the device (between  0  and  10,  where
16943              smaller number means smaller latency but higher CPU usage) or -1
16944              to use fragment mode (option ignored on some platforms) (default
16945              5)
16946
16947   Since
16948       4.0
16949
16950   AudiodevPaPerDirectionOptions (Object)
16951       Options  of  the Pulseaudio backend that are used for both playback and
16952       recording.
16953
16954   Members
16955       name: string (optional)
16956              name of the sink/source to use
16957
16958       stream-name: string (optional)
16959              name of the PulseAudio stream created by qemu.  Can be  used  to
16960              identify  the  stream  in  PulseAudio  when  you create multiple
16961              PulseAudio devices or run multiple qemu instances (default:  au‐
16962              diodev's id, since 4.2)
16963
16964       latency: int (optional)
16965              latency  you want PulseAudio to achieve in microseconds (default
16966              15000)
16967
16968       The members of AudiodevPerDirectionOptions
16969
16970   Since
16971       4.0
16972
16973   AudiodevPaOptions (Object)
16974       Options of the PulseAudio audio backend.
16975
16976   Members
16977       in: AudiodevPaPerDirectionOptions (optional)
16978              options of the capture stream
16979
16980       out: AudiodevPaPerDirectionOptions (optional)
16981              options of the playback stream
16982
16983       server: string (optional)
16984              PulseAudio server address (default: let PulseAudio choose)
16985
16986   Since
16987       4.0
16988
16989   AudiodevWavOptions (Object)
16990       Options of the wav audio backend.
16991
16992   Members
16993       in: AudiodevPerDirectionOptions (optional)
16994              options of the capture stream
16995
16996       out: AudiodevPerDirectionOptions (optional)
16997              options of the playback stream
16998
16999       path: string (optional)
17000              name of the wav file to record (default 'qemu.wav')
17001
17002   Since
17003       4.0
17004
17005   AudioFormat (Enum)
17006       An enumeration of possible audio formats.
17007
17008   Values
17009       u8     unsigned 8 bit integer
17010
17011       s8     signed 8 bit integer
17012
17013       u16    unsigned 16 bit integer
17014
17015       s16    signed 16 bit integer
17016
17017       u32    unsigned 32 bit integer
17018
17019       s32    signed 32 bit integer
17020
17021       f32    single precision floating-point (since 5.0)
17022
17023   Since
17024       4.0
17025
17026   AudiodevDriver (Enum)
17027       An enumeration of possible audio backend drivers.
17028
17029   Values
17030       jack   JACK audio backend (since 5.1)
17031
17032       none   Not documented
17033
17034       alsa   Not documented
17035
17036       coreaudio
17037              Not documented
17038
17039       dsound Not documented
17040
17041       oss    Not documented
17042
17043       pa     Not documented
17044
17045       sdl    Not documented
17046
17047       spice  Not documented
17048
17049       wav    Not documented
17050
17051   Since
17052       4.0
17053
17054   Audiodev (Object)
17055       Options of an audio backend.
17056
17057   Members
17058       id: string
17059              identifier of the backend
17060
17061       driver: AudiodevDriver
17062              the backend driver to use
17063
17064       timer-period: int (optional)
17065              timer period (in microseconds, 0: use lowest possible)
17066
17067       The members of AudiodevGenericOptions when driver is "none"
17068
17069       The members of AudiodevAlsaOptions when driver is "alsa"
17070
17071       The members of AudiodevCoreaudioOptions when driver is "coreaudio"
17072
17073       The members of AudiodevDsoundOptions when driver is "dsound"
17074
17075       The members of AudiodevJackOptions when driver is "jack"
17076
17077       The members of AudiodevOssOptions when driver is "oss"
17078
17079       The members of AudiodevPaOptions when driver is "pa"
17080
17081       The members of AudiodevGenericOptions when driver is "sdl"
17082
17083       The members of AudiodevGenericOptions when driver is "spice"
17084
17085       The members of AudiodevWavOptions when driver is "wav"
17086
17087   Since
17088       4.0
17089

ACPI

17091   AcpiTableOptions (Object)
17092       Specify an ACPI table on the command line to load.
17093
17094       At most one of file and data can be specified. The list of files speci‐
17095       fied  by  any  one of them is loaded and concatenated in order. If both
17096       are omitted, data is implied.
17097
17098       Other fields / optargs can be used to override fields  of  the  generic
17099       ACPI  table  header; refer to the ACPI specification 5.0, section 5.2.6
17100       System Description Table Header. If a header field is  not  overridden,
17101       then  the  corresponding  value  from the concatenated blob is used (in
17102       case of file), or it is filled in with a hard-coded value (in  case  of
17103       data).
17104
17105       String  fields are copied into the matching ACPI member from lowest ad‐
17106       dress upwards, and silently truncated / NUL-padded to length.
17107
17108   Members
17109       sig: string (optional)
17110              table signature / identifier (4 bytes)
17111
17112       rev: int (optional)
17113              table revision number (dependent on signature, 1 byte)
17114
17115       oem_id: string (optional)
17116              OEM identifier (6 bytes)
17117
17118       oem_table_id: string (optional)
17119              OEM table identifier (8 bytes)
17120
17121       oem_rev: int (optional)
17122              OEM-supplied revision number (4 bytes)
17123
17124       asl_compiler_id: string (optional)
17125              identifier of the utility that created the table (4 bytes)
17126
17127       asl_compiler_rev: int (optional)
17128              revision number of the utility that created the table (4 bytes)
17129
17130       file: string (optional)
17131              colon (:) separated list of pathnames to load and concatenate as
17132              table  data.  The  resultant  binary blob is expected to have an
17133              ACPI table header. At least one file is required. This field ex‐
17134              cludes data.
17135
17136       data: string (optional)
17137              colon (:) separated list of pathnames to load and concatenate as
17138              table data. The resultant binary blob must not have an ACPI  ta‐
17139              ble  header.  At least one file is required. This field excludes
17140              file.
17141
17142   Since
17143       1.5
17144
17145   ACPISlotType (Enum)
17146   Values
17147       DIMM   memory slot
17148
17149       CPU    logical CPU slot (since 2.7)
17150
17151   ACPIOSTInfo (Object)
17152       OSPM Status Indication for a device For description of possible  values
17153       of source and status fields see "_OST (OSPM Status Indication)" chapter
17154       of ACPI5.0 spec.
17155
17156   Members
17157       device: string (optional)
17158              device ID associated with slot
17159
17160       slot: string
17161              slot ID, unique per slot of a given slot-type
17162
17163       slot-type: ACPISlotType
17164              type of the slot
17165
17166       source: int
17167              an integer containing the source event
17168
17169       status: int
17170              an integer containing the status code
17171
17172   Since
17173       2.1
17174
17175   query-acpi-ospm-status (Command)
17176       Return a list of ACPIOSTInfo for devices that support status  reporting
17177       via ACPI _OST method.
17178
17179   Since
17180       2.1
17181
17182   Example
17183          -> { "execute": "query-acpi-ospm-status" }
17184          <- { "return": [ { "device": "d1", "slot": "0", "slot-type": "DIMM", "source": 1, "status": 0},
17185                           { "slot": "1", "slot-type": "DIMM", "source": 0, "status": 0},
17186                           { "slot": "2", "slot-type": "DIMM", "source": 0, "status": 0},
17187                           { "slot": "3", "slot-type": "DIMM", "source": 0, "status": 0}
17188             ]}
17189
17190   ACPI_DEVICE_OST (Event)
17191       Emitted when guest executes ACPI _OST method.
17192
17193   Arguments
17194       info: ACPIOSTInfo
17195              OSPM Status Indication
17196
17197   Since
17198       2.1
17199
17200   Example
17201          <- { "event": "ACPI_DEVICE_OST",
17202               "data": { "device": "d1", "slot": "0",
17203                         "slot-type": "DIMM", "source": 1, "status": 0 } }
17204

PCI

17206   PciMemoryRange (Object)
17207       A PCI device memory region
17208
17209   Members
17210       base: int
17211              the starting address (guest physical)
17212
17213       limit: int
17214              the ending address (guest physical)
17215
17216   Since
17217       0.14.0
17218
17219   PciMemoryRegion (Object)
17220       Information about a PCI device I/O region.
17221
17222   Members
17223       bar: int
17224              the index of the Base Address Register for this region
17225
17226       type: string
17227
17228              • 'io' if the region is a PIO region
17229
17230              • 'memory' if the region is a MMIO region
17231
17232       size: int
17233              memory size
17234
17235       prefetch: boolean (optional)
17236              if type is 'memory', true if the memory is prefetchable
17237
17238       mem_type_64: boolean (optional)
17239              if type is 'memory', true if the BAR is 64-bit
17240
17241       address: int
17242              Not documented
17243
17244   Since
17245       0.14.0
17246
17247   PciBusInfo (Object)
17248       Information about a bus of a PCI Bridge device
17249
17250   Members
17251       number: int
17252              primary  bus interface number.  This should be the number of the
17253              bus the device resides on.
17254
17255       secondary: int
17256              secondary bus interface number.  This is the number of the  main
17257              bus for the bridge
17258
17259       subordinate: int
17260              This is the highest number bus that resides below the bridge.
17261
17262       io_range: PciMemoryRange
17263              The PIO range for all devices on this bridge
17264
17265       memory_range: PciMemoryRange
17266              The MMIO range for all devices on this bridge
17267
17268       prefetchable_range: PciMemoryRange
17269              The range of prefetchable MMIO for all devices on this bridge
17270
17271   Since
17272       2.4
17273
17274   PciBridgeInfo (Object)
17275       Information about a PCI Bridge device
17276
17277   Members
17278       bus: PciBusInfo
17279              information about the bus the device resides on
17280
17281       devices: array of PciDeviceInfo (optional)
17282              a list of PciDeviceInfo for each device on this bridge
17283
17284   Since
17285       0.14.0
17286
17287   PciDeviceClass (Object)
17288       Information about the Class of a PCI device
17289
17290   Members
17291       desc: string (optional)
17292              a string description of the device's class
17293
17294       class: int
17295              the class code of the device
17296
17297   Since
17298       2.4
17299
17300   PciDeviceId (Object)
17301       Information about the Id of a PCI device
17302
17303   Members
17304       device: int
17305              the PCI device id
17306
17307       vendor: int
17308              the PCI vendor id
17309
17310       subsystem: int (optional)
17311              the PCI subsystem id (since 3.1)
17312
17313       subsystem-vendor: int (optional)
17314              the PCI subsystem vendor id (since 3.1)
17315
17316   Since
17317       2.4
17318
17319   PciDeviceInfo (Object)
17320       Information about a PCI device
17321
17322   Members
17323       bus: int
17324              the bus number of the device
17325
17326       slot: int
17327              the slot the device is located in
17328
17329       function: int
17330              the function of the slot used by the device
17331
17332       class_info: PciDeviceClass
17333              the class of the device
17334
17335       id: PciDeviceId
17336              the PCI device id
17337
17338       irq: int (optional)
17339              if an IRQ is assigned to the device, the IRQ number
17340
17341       irq_pin: int
17342              the IRQ pin, zero means no IRQ (since 5.1)
17343
17344       qdev_id: string
17345              the device name of the PCI device
17346
17347       pci_bridge: PciBridgeInfo (optional)
17348              if the device is a PCI bridge, the bridge information
17349
17350       regions: array of PciMemoryRegion
17351              a list of the PCI I/O regions associated with the device
17352
17353   Notes
17354       the  contents  of  class_info.desc  are  not  stable and should only be
17355       treated as informational.
17356
17357   Since
17358       0.14.0
17359
17360   PciInfo (Object)
17361       Information about a PCI bus
17362
17363   Members
17364       bus: int
17365              the bus index
17366
17367       devices: array of PciDeviceInfo
17368              a list of devices on this bus
17369
17370   Since
17371       0.14.0
17372
17373   query-pci (Command)
17374       Return information about the PCI bus topology of the guest.
17375
17376   Returns
17377       a list of PciInfo for each PCI  bus.  Each  bus  is  represented  by  a
17378       json-object,  which  has a key with a json-array of all PCI devices at‐
17379       tached to it. Each device is represented by a json-object.
17380
17381   Since
17382       0.14.0
17383
17384   Example
17385          -> { "execute": "query-pci" }
17386          <- { "return": [
17387                   {
17388                      "bus": 0,
17389                      "devices": [
17390                         {
17391                            "bus": 0,
17392                            "qdev_id": "",
17393                            "slot": 0,
17394                            "class_info": {
17395                               "class": 1536,
17396                               "desc": "Host bridge"
17397                            },
17398                            "id": {
17399                               "device": 32902,
17400                               "vendor": 4663
17401                            },
17402                            "function": 0,
17403                            "regions": [
17404                            ]
17405                         },
17406                         {
17407                            "bus": 0,
17408                            "qdev_id": "",
17409                            "slot": 1,
17410                            "class_info": {
17411                               "class": 1537,
17412                               "desc": "ISA bridge"
17413                            },
17414                            "id": {
17415                               "device": 32902,
17416                               "vendor": 28672
17417                            },
17418                            "function": 0,
17419                            "regions": [
17420                            ]
17421                         },
17422                         {
17423                            "bus": 0,
17424                            "qdev_id": "",
17425                            "slot": 1,
17426                            "class_info": {
17427                               "class": 257,
17428                               "desc": "IDE controller"
17429                            },
17430                            "id": {
17431                               "device": 32902,
17432                               "vendor": 28688
17433                            },
17434                            "function": 1,
17435                            "regions": [
17436                               {
17437                                  "bar": 4,
17438                                  "size": 16,
17439                                  "address": 49152,
17440                                  "type": "io"
17441                               }
17442                            ]
17443                         },
17444                         {
17445                            "bus": 0,
17446                            "qdev_id": "",
17447                            "slot": 2,
17448                            "class_info": {
17449                               "class": 768,
17450                               "desc": "VGA controller"
17451                            },
17452                            "id": {
17453                               "device": 4115,
17454                               "vendor": 184
17455                            },
17456                            "function": 0,
17457                            "regions": [
17458                               {
17459                                  "prefetch": true,
17460                                  "mem_type_64": false,
17461                                  "bar": 0,
17462                                  "size": 33554432,
17463                                  "address": 4026531840,
17464                                  "type": "memory"
17465                               },
17466                               {
17467                                  "prefetch": false,
17468                                  "mem_type_64": false,
17469                                  "bar": 1,
17470                                  "size": 4096,
17471                                  "address": 4060086272,
17472                                  "type": "memory"
17473                               },
17474                               {
17475                                  "prefetch": false,
17476                                  "mem_type_64": false,
17477                                  "bar": 6,
17478                                  "size": 65536,
17479                                  "address": -1,
17480                                  "type": "memory"
17481                               }
17482                            ]
17483                         },
17484                         {
17485                            "bus": 0,
17486                            "qdev_id": "",
17487                            "irq": 11,
17488                            "slot": 4,
17489                            "class_info": {
17490                               "class": 1280,
17491                               "desc": "RAM controller"
17492                            },
17493                            "id": {
17494                               "device": 6900,
17495                               "vendor": 4098
17496                            },
17497                            "function": 0,
17498                            "regions": [
17499                               {
17500                                  "bar": 0,
17501                                  "size": 32,
17502                                  "address": 49280,
17503                                  "type": "io"
17504                               }
17505                            ]
17506                         }
17507                      ]
17508                   }
17509                ]
17510             }
17511
17512   Note
17513       This example has been shortened as the real response is too long.
17514
17516       2021, The QEMU Project Developers
17517
17518
17519
17520
175215.2.0                            May 19, 2021                  QEMU-QMP-REF(7)
Impressum