1# *-*- Mode: Python -*-* 2# vim: filetype=python 3 4## 5# = General note concerning the use of guest agent interfaces 6# 7# "unsupported" is a higher-level error than the errors that 8# individual commands might document. The caller should always be 9# prepared to receive QERR_UNSUPPORTED, even if the given command 10# doesn't specify it, or doesn't document any failure mode at all. 11## 12 13## 14# = QEMU guest agent protocol commands and structs 15## 16 17{ 'pragma': { 'doc-required': true } } 18 19# Lists with items allowed to permit QAPI rule violations; think twice 20# before you add to them! 21{ 'pragma': { 22 # Types whose member names may use '_' 23 'member-name-exceptions': [ 24 'GuestAgentInfo' 25 ], 26 # Commands allowed to return a non-dictionary: 27 'command-returns-exceptions': [ 28 'guest-file-open', 29 'guest-fsfreeze-freeze', 30 'guest-fsfreeze-freeze-list', 31 'guest-fsfreeze-status', 32 'guest-fsfreeze-thaw', 33 'guest-get-time', 34 'guest-set-vcpus', 35 'guest-sync', 36 'guest-sync-delimited' ], 37 # Types and commands with undocumented members: 38 'documentation-exceptions': [ 39 'GuestNVMeSmart' ] } } 40 41## 42# @guest-sync-delimited: 43# 44# Echo back a unique integer value, and prepend to response a leading 45# sentinel byte (0xFF) the client can check scan for. 46# 47# This is used by clients talking to the guest agent over the wire to 48# ensure the stream is in sync and doesn't contain stale data from 49# previous client. It must be issued upon initial connection, and 50# after any client-side timeouts (including timeouts on receiving a 51# response to this command). 52# 53# After issuing this request, all guest agent responses should be 54# ignored until the response containing the unique integer value the 55# client passed in is returned. Receival of the 0xFF sentinel byte 56# must be handled as an indication that the client's 57# lexer/tokenizer/parser state should be flushed/reset in preparation 58# for reliably receiving the subsequent response. As an optimization, 59# clients may opt to ignore all data until a sentinel value is 60# receiving to avoid unnecessary processing of stale data. 61# 62# Similarly, clients should also precede this *request* with a 0xFF 63# byte to make sure the guest agent flushes any partially read JSON 64# data from a previous client connection. 65# 66# @id: randomly generated 64-bit integer 67# 68# Returns: The unique integer id passed in by the client 69# 70# Since: 1.1 71## 72{ 'command': 'guest-sync-delimited', 73 'data': { 'id': 'int' }, 74 'returns': 'int' } 75 76## 77# @guest-sync: 78# 79# Echo back a unique integer value 80# 81# This is used by clients talking to the guest agent over the wire to 82# ensure the stream is in sync and doesn't contain stale data from 83# previous client. All guest agent responses should be ignored until 84# the provided unique integer value is returned, and it is up to the 85# client to handle stale whole or partially-delivered JSON text in 86# such a way that this response can be obtained. 87# 88# In cases where a partial stale response was previously received by 89# the client, this cannot always be done reliably. One particular 90# scenario being if qemu-ga responses are fed character-by-character 91# into a JSON parser. In these situations, using guest-sync-delimited 92# may be optimal. 93# 94# For clients that fetch responses line by line and convert them to 95# JSON objects, guest-sync should be sufficient, but note that in 96# cases where the channel is dirty some attempts at parsing the 97# response may result in a parser error. 98# 99# Such clients should also precede this command with a 0xFF byte to 100# make sure the guest agent flushes any partially read JSON data from 101# a previous session. 102# 103# @id: randomly generated 64-bit integer 104# 105# Returns: The unique integer id passed in by the client 106# 107# Since: 0.15.0 108## 109{ 'command': 'guest-sync', 110 'data': { 'id': 'int' }, 111 'returns': 'int' } 112 113## 114# @guest-ping: 115# 116# Ping the guest agent, a non-error return implies success 117# 118# Since: 0.15.0 119## 120{ 'command': 'guest-ping' } 121 122## 123# @guest-get-time: 124# 125# Get the information about guest's System Time relative to the Epoch 126# of 1970-01-01 in UTC. 127# 128# Returns: Time in nanoseconds. 129# 130# Since: 1.5 131## 132{ 'command': 'guest-get-time', 133 'returns': 'int' } 134 135## 136# @guest-set-time: 137# 138# Set guest time. 139# 140# When a guest is paused or migrated to a file then loaded from that 141# file, the guest OS has no idea that there was a big gap in the time. 142# Depending on how long the gap was, NTP might not be able to 143# resynchronize the guest. 144# 145# This command tries to set guest's System Time to the given value, 146# then sets the Hardware Clock (RTC) to the current System Time. This 147# will make it easier for a guest to resynchronize without waiting for 148# NTP. If no @time is specified, then the time to set is read from 149# RTC. However, this may not be supported on all platforms (i.e. 150# Windows). If that's the case users are advised to always pass a 151# value. 152# 153# @time: time of nanoseconds, relative to the Epoch of 1970-01-01 in 154# UTC. 155# 156# Returns: Nothing on success. 157# 158# Since: 1.5 159## 160{ 'command': 'guest-set-time', 161 'data': { '*time': 'int' } } 162 163## 164# @GuestAgentCommandInfo: 165# 166# Information about guest agent commands. 167# 168# @name: name of the command 169# 170# @enabled: whether command is currently enabled by guest admin 171# 172# @success-response: whether command returns a response on success 173# (since 1.7) 174# 175# Since: 1.1.0 176## 177{ 'struct': 'GuestAgentCommandInfo', 178 'data': { 'name': 'str', 'enabled': 'bool', 'success-response': 'bool' } } 179 180## 181# @GuestAgentInfo: 182# 183# Information about guest agent. 184# 185# @version: guest agent version 186# 187# @supported_commands: Information about guest agent commands 188# 189# Since: 0.15.0 190## 191{ 'struct': 'GuestAgentInfo', 192 'data': { 'version': 'str', 193 'supported_commands': ['GuestAgentCommandInfo'] } } 194## 195# @guest-info: 196# 197# Get some information about the guest agent. 198# 199# Returns: @GuestAgentInfo 200# 201# Since: 0.15.0 202## 203{ 'command': 'guest-info', 204 'returns': 'GuestAgentInfo' } 205 206## 207# @guest-shutdown: 208# 209# Initiate guest-activated shutdown. Note: this is an asynchronous 210# shutdown request, with no guarantee of successful shutdown. 211# 212# @mode: "halt", "powerdown" (default), or "reboot" 213# 214# This command does NOT return a response on success. Success 215# condition is indicated by the VM exiting with a zero exit status or, 216# when running with --no-shutdown, by issuing the query-status QMP 217# command to confirm the VM status is "shutdown". 218# 219# Since: 0.15.0 220## 221{ 'command': 'guest-shutdown', 'data': { '*mode': 'str' }, 222 'success-response': false } 223 224## 225# @guest-file-open: 226# 227# Open a file in the guest and retrieve a file handle for it 228# 229# @path: Full path to the file in the guest to open. 230# 231# @mode: open mode, as per fopen(), "r" is the default. 232# 233# Returns: Guest file handle on success. 234# 235# Since: 0.15.0 236## 237{ 'command': 'guest-file-open', 238 'data': { 'path': 'str', '*mode': 'str' }, 239 'returns': 'int' } 240 241## 242# @guest-file-close: 243# 244# Close an open file in the guest 245# 246# @handle: filehandle returned by guest-file-open 247# 248# Returns: Nothing on success. 249# 250# Since: 0.15.0 251## 252{ 'command': 'guest-file-close', 253 'data': { 'handle': 'int' } } 254 255## 256# @GuestFileRead: 257# 258# Result of guest agent file-read operation 259# 260# @count: number of bytes read (note: count is *before* 261# base64-encoding is applied) 262# 263# @buf-b64: base64-encoded bytes read 264# 265# @eof: whether EOF was encountered during read operation. 266# 267# Since: 0.15.0 268## 269{ 'struct': 'GuestFileRead', 270 'data': { 'count': 'int', 'buf-b64': 'str', 'eof': 'bool' } } 271 272## 273# @guest-file-read: 274# 275# Read from an open file in the guest. Data will be base64-encoded. 276# As this command is just for limited, ad-hoc debugging, such as log 277# file access, the number of bytes to read is limited to 48 MB. 278# 279# @handle: filehandle returned by guest-file-open 280# 281# @count: maximum number of bytes to read (default is 4KB, maximum is 282# 48MB) 283# 284# Returns: @GuestFileRead on success. 285# 286# Since: 0.15.0 287## 288{ 'command': 'guest-file-read', 289 'data': { 'handle': 'int', '*count': 'int' }, 290 'returns': 'GuestFileRead' } 291 292## 293# @GuestFileWrite: 294# 295# Result of guest agent file-write operation 296# 297# @count: number of bytes written (note: count is actual bytes 298# written, after base64-decoding of provided buffer) 299# 300# @eof: whether EOF was encountered during write operation. 301# 302# Since: 0.15.0 303## 304{ 'struct': 'GuestFileWrite', 305 'data': { 'count': 'int', 'eof': 'bool' } } 306 307## 308# @guest-file-write: 309# 310# Write to an open file in the guest. 311# 312# @handle: filehandle returned by guest-file-open 313# 314# @buf-b64: base64-encoded string representing data to be written 315# 316# @count: bytes to write (actual bytes, after base64-decode), default 317# is all content in buf-b64 buffer after base64 decoding 318# 319# Returns: @GuestFileWrite on success. 320# 321# Since: 0.15.0 322## 323{ 'command': 'guest-file-write', 324 'data': { 'handle': 'int', 'buf-b64': 'str', '*count': 'int' }, 325 'returns': 'GuestFileWrite' } 326 327 328## 329# @GuestFileSeek: 330# 331# Result of guest agent file-seek operation 332# 333# @position: current file position 334# 335# @eof: whether EOF was encountered during file seek 336# 337# Since: 0.15.0 338## 339{ 'struct': 'GuestFileSeek', 340 'data': { 'position': 'int', 'eof': 'bool' } } 341 342## 343# @QGASeek: 344# 345# Symbolic names for use in @guest-file-seek 346# 347# @set: Set to the specified offset (same effect as 'whence':0) 348# 349# @cur: Add offset to the current location (same effect as 'whence':1) 350# 351# @end: Add offset to the end of the file (same effect as 'whence':2) 352# 353# Since: 2.6 354## 355{ 'enum': 'QGASeek', 'data': [ 'set', 'cur', 'end' ] } 356 357## 358# @GuestFileWhence: 359# 360# Controls the meaning of offset to @guest-file-seek. 361# 362# @value: Integral value (0 for set, 1 for cur, 2 for end), available 363# for historical reasons, and might differ from the host's or 364# guest's SEEK_* values (since: 0.15) 365# 366# @name: Symbolic name, and preferred interface 367# 368# Since: 2.6 369## 370{ 'alternate': 'GuestFileWhence', 371 'data': { 'value': 'int', 'name': 'QGASeek' } } 372 373## 374# @guest-file-seek: 375# 376# Seek to a position in the file, as with fseek(), and return the 377# current file position afterward. Also encapsulates ftell()'s 378# functionality, with offset=0 and whence=1. 379# 380# @handle: filehandle returned by guest-file-open 381# 382# @offset: bytes to skip over in the file stream 383# 384# @whence: Symbolic or numeric code for interpreting offset 385# 386# Returns: @GuestFileSeek on success. 387# 388# Since: 0.15.0 389## 390{ 'command': 'guest-file-seek', 391 'data': { 'handle': 'int', 'offset': 'int', 392 'whence': 'GuestFileWhence' }, 393 'returns': 'GuestFileSeek' } 394 395## 396# @guest-file-flush: 397# 398# Write file changes buffered in userspace to disk/kernel buffers 399# 400# @handle: filehandle returned by guest-file-open 401# 402# Returns: Nothing on success. 403# 404# Since: 0.15.0 405## 406{ 'command': 'guest-file-flush', 407 'data': { 'handle': 'int' } } 408 409## 410# @GuestFsfreezeStatus: 411# 412# An enumeration of filesystem freeze states 413# 414# @thawed: filesystems thawed/unfrozen 415# 416# @frozen: all non-network guest filesystems frozen 417# 418# Since: 0.15.0 419## 420{ 'enum': 'GuestFsfreezeStatus', 421 'data': [ 'thawed', 'frozen' ] } 422 423## 424# @guest-fsfreeze-status: 425# 426# Get guest fsfreeze state. 427# 428# Returns: GuestFsfreezeStatus ("thawed", "frozen", etc., as defined 429# below) 430# 431# Note: This may fail to properly report the current state as a result 432# of some other guest processes having issued an fs freeze/thaw. 433# 434# Since: 0.15.0 435## 436{ 'command': 'guest-fsfreeze-status', 437 'returns': 'GuestFsfreezeStatus' } 438 439## 440# @guest-fsfreeze-freeze: 441# 442# Sync and freeze all freezable, local guest filesystems. If this 443# command succeeded, you may call @guest-fsfreeze-thaw later to 444# unfreeze. 445# 446# Note: On Windows, the command is implemented with the help of a 447# Volume Shadow-copy Service DLL helper. The frozen state is 448# limited for up to 10 seconds by VSS. 449# 450# Returns: Number of file systems currently frozen. On error, all 451# filesystems will be thawed. If no filesystems are frozen as a 452# result of this call, then @guest-fsfreeze-status will remain 453# "thawed" and calling @guest-fsfreeze-thaw is not necessary. 454# 455# Since: 0.15.0 456## 457{ 'command': 'guest-fsfreeze-freeze', 458 'returns': 'int' } 459 460## 461# @guest-fsfreeze-freeze-list: 462# 463# Sync and freeze specified guest filesystems. See also 464# @guest-fsfreeze-freeze. 465# 466# @mountpoints: an array of mountpoints of filesystems to be frozen. 467# If omitted, every mounted filesystem is frozen. Invalid mount 468# points are ignored. 469# 470# Returns: Number of file systems currently frozen. On error, all 471# filesystems will be thawed. 472# 473# Since: 2.2 474## 475{ 'command': 'guest-fsfreeze-freeze-list', 476 'data': { '*mountpoints': ['str'] }, 477 'returns': 'int' } 478 479## 480# @guest-fsfreeze-thaw: 481# 482# Unfreeze all frozen guest filesystems 483# 484# Returns: Number of file systems thawed by this call 485# 486# Note: if return value does not match the previous call to 487# guest-fsfreeze-freeze, this likely means some freezable 488# filesystems were unfrozen before this call, and that the 489# filesystem state may have changed before issuing this command. 490# 491# Since: 0.15.0 492## 493{ 'command': 'guest-fsfreeze-thaw', 494 'returns': 'int' } 495 496## 497# @GuestFilesystemTrimResult: 498# 499# @path: path that was trimmed 500# 501# @error: an error message when trim failed 502# 503# @trimmed: bytes trimmed for this path 504# 505# @minimum: reported effective minimum for this path 506# 507# Since: 2.4 508## 509{ 'struct': 'GuestFilesystemTrimResult', 510 'data': {'path': 'str', 511 '*trimmed': 'int', '*minimum': 'int', '*error': 'str'} } 512 513## 514# @GuestFilesystemTrimResponse: 515# 516# @paths: list of @GuestFilesystemTrimResult per path that was trimmed 517# 518# Since: 2.4 519## 520{ 'struct': 'GuestFilesystemTrimResponse', 521 'data': {'paths': ['GuestFilesystemTrimResult']} } 522 523## 524# @guest-fstrim: 525# 526# Discard (or "trim") blocks which are not in use by the filesystem. 527# 528# @minimum: Minimum contiguous free range to discard, in bytes. Free 529# ranges smaller than this may be ignored (this is a hint and the 530# guest may not respect it). By increasing this value, the fstrim 531# operation will complete more quickly for filesystems with badly 532# fragmented free space, although not all blocks will be 533# discarded. The default value is zero, meaning "discard every 534# free block". 535# 536# Returns: A @GuestFilesystemTrimResponse which contains the status of 537# all trimmed paths. (since 2.4) 538# 539# Since: 1.2 540## 541{ 'command': 'guest-fstrim', 542 'data': { '*minimum': 'int' }, 543 'returns': 'GuestFilesystemTrimResponse' } 544 545## 546# @guest-suspend-disk: 547# 548# Suspend guest to disk. 549# 550# This command attempts to suspend the guest using three strategies, 551# in this order: 552# 553# - systemd hibernate 554# - pm-utils (via pm-hibernate) 555# - manual write into sysfs 556# 557# This command does NOT return a response on success. There is a high 558# chance the command succeeded if the VM exits with a zero exit status 559# or, when running with --no-shutdown, by issuing the query-status QMP 560# command to to confirm the VM status is "shutdown". However, the VM 561# could also exit (or set its status to "shutdown") due to other 562# reasons. 563# 564# Errors: 565# - If suspend to disk is not supported, Unsupported 566# 567# Notes: It's strongly recommended to issue the guest-sync command 568# before sending commands when the guest resumes 569# 570# Since: 1.1 571## 572{ 'command': 'guest-suspend-disk', 'success-response': false } 573 574## 575# @guest-suspend-ram: 576# 577# Suspend guest to ram. 578# 579# This command attempts to suspend the guest using three strategies, 580# in this order: 581# 582# - systemd hibernate 583# - pm-utils (via pm-hibernate) 584# - manual write into sysfs 585# 586# IMPORTANT: guest-suspend-ram requires working wakeup support in 587# QEMU. You should check QMP command query-current-machine returns 588# wakeup-suspend-support: true before issuing this command. Failure 589# in doing so can result in a suspended guest that QEMU will not be 590# able to awaken, forcing the user to power cycle the guest to bring 591# it back. 592# 593# This command does NOT return a response on success. There are two 594# options to check for success: 595# 596# 1. Wait for the SUSPEND QMP event from QEMU 597# 2. Issue the query-status QMP command to confirm the VM status is 598# "suspended" 599# 600# Errors: 601# - If suspend to ram is not supported, Unsupported 602# 603# Notes: It's strongly recommended to issue the guest-sync command 604# before sending commands when the guest resumes 605# 606# Since: 1.1 607## 608{ 'command': 'guest-suspend-ram', 'success-response': false } 609 610## 611# @guest-suspend-hybrid: 612# 613# Save guest state to disk and suspend to ram. 614# 615# This command attempts to suspend the guest by executing, in this 616# order: 617# 618# - systemd hybrid-sleep 619# - pm-utils (via pm-suspend-hybrid) 620# 621# IMPORTANT: guest-suspend-hybrid requires working wakeup support in 622# QEMU. You should check QMP command query-current-machine returns 623# wakeup-suspend-support: true before issuing this command. Failure 624# in doing so can result in a suspended guest that QEMU will not be 625# able to awaken, forcing the user to power cycle the guest to bring 626# it back. 627# 628# This command does NOT return a response on success. There are two 629# options to check for success: 630# 631# 1. Wait for the SUSPEND QMP event from QEMU 632# 2. Issue the query-status QMP command to confirm the VM status is 633# "suspended" 634# 635# Errors: 636# - If hybrid suspend is not supported, Unsupported 637# 638# Notes: It's strongly recommended to issue the guest-sync command 639# before sending commands when the guest resumes 640# 641# Since: 1.1 642## 643{ 'command': 'guest-suspend-hybrid', 'success-response': false } 644 645## 646# @GuestIpAddressType: 647# 648# An enumeration of supported IP address types 649# 650# @ipv4: IP version 4 651# 652# @ipv6: IP version 6 653# 654# Since: 1.1 655## 656{ 'enum': 'GuestIpAddressType', 657 'data': [ 'ipv4', 'ipv6' ] } 658 659## 660# @GuestIpAddress: 661# 662# @ip-address: IP address 663# 664# @ip-address-type: Type of @ip-address (e.g. ipv4, ipv6) 665# 666# @prefix: Network prefix length of @ip-address 667# 668# Since: 1.1 669## 670{ 'struct': 'GuestIpAddress', 671 'data': {'ip-address': 'str', 672 'ip-address-type': 'GuestIpAddressType', 673 'prefix': 'int'} } 674 675## 676# @GuestNetworkInterfaceStat: 677# 678# @rx-bytes: total bytes received 679# 680# @rx-packets: total packets received 681# 682# @rx-errs: bad packets received 683# 684# @rx-dropped: receiver dropped packets 685# 686# @tx-bytes: total bytes transmitted 687# 688# @tx-packets: total packets transmitted 689# 690# @tx-errs: packet transmit problems 691# 692# @tx-dropped: dropped packets transmitted 693# 694# Since: 2.11 695## 696{ 'struct': 'GuestNetworkInterfaceStat', 697 'data': {'rx-bytes': 'uint64', 698 'rx-packets': 'uint64', 699 'rx-errs': 'uint64', 700 'rx-dropped': 'uint64', 701 'tx-bytes': 'uint64', 702 'tx-packets': 'uint64', 703 'tx-errs': 'uint64', 704 'tx-dropped': 'uint64' 705 } } 706 707## 708# @GuestNetworkInterface: 709# 710# @name: The name of interface for which info are being delivered 711# 712# @hardware-address: Hardware address of @name 713# 714# @ip-addresses: List of addresses assigned to @name 715# 716# @statistics: various statistic counters related to @name (since 717# 2.11) 718# 719# Since: 1.1 720## 721{ 'struct': 'GuestNetworkInterface', 722 'data': {'name': 'str', 723 '*hardware-address': 'str', 724 '*ip-addresses': ['GuestIpAddress'], 725 '*statistics': 'GuestNetworkInterfaceStat' } } 726 727## 728# @guest-network-get-interfaces: 729# 730# Get list of guest IP addresses, MAC addresses and netmasks. 731# 732# Returns: List of GuestNetworkInterface on success. 733# 734# Since: 1.1 735## 736{ 'command': 'guest-network-get-interfaces', 737 'returns': ['GuestNetworkInterface'] } 738 739## 740# @GuestLogicalProcessor: 741# 742# @logical-id: Arbitrary guest-specific unique identifier of the VCPU. 743# 744# @online: Whether the VCPU is enabled. 745# 746# @can-offline: Whether offlining the VCPU is possible. This member 747# is always filled in by the guest agent when the structure is 748# returned, and always ignored on input (hence it can be omitted 749# then). 750# 751# Since: 1.5 752## 753{ 'struct': 'GuestLogicalProcessor', 754 'data': {'logical-id': 'int', 755 'online': 'bool', 756 '*can-offline': 'bool'} } 757 758## 759# @guest-get-vcpus: 760# 761# Retrieve the list of the guest's logical processors. 762# 763# This is a read-only operation. 764# 765# Returns: The list of all VCPUs the guest knows about. Each VCPU is 766# put on the list exactly once, but their order is unspecified. 767# 768# Since: 1.5 769## 770{ 'command': 'guest-get-vcpus', 771 'returns': ['GuestLogicalProcessor'] } 772 773## 774# @guest-set-vcpus: 775# 776# Attempt to reconfigure (currently: enable/disable) logical 777# processors inside the guest. 778# 779# @vcpus: The logical processors to be reconfigured. This list is 780# processed node by node in order. In each node @logical-id is 781# used to look up the guest VCPU, for which @online specifies the 782# requested state. The set of distinct @logical-id's is only 783# required to be a subset of the guest-supported identifiers. 784# There's no restriction on list length or on repeating the same 785# @logical-id (with possibly different @online field). Preferably 786# the input list should describe a modified subset of 787# @guest-get-vcpus' return value. 788# 789# Returns: The length of the initial sublist that has been 790# successfully processed. The guest agent maximizes this value. 791# Possible cases: 792# 793# - 0: 794# if the @vcpus list was empty on input. Guest state has not 795# been changed. Otherwise, 796# - < length(@vcpus): 797# more than zero initial nodes have been processed, but not the 798# entire @vcpus list. Guest state has changed accordingly. To 799# retrieve the error (assuming it persists), repeat the call 800# with the successfully processed initial sublist removed. 801# Otherwise, 802# - length(@vcpus): 803# call successful. 804# 805# Errors: 806# - If the reconfiguration of the first node in @vcpus failed. 807# Guest state has not been changed. 808# 809# Since: 1.5 810## 811{ 'command': 'guest-set-vcpus', 812 'data': {'vcpus': ['GuestLogicalProcessor'] }, 813 'returns': 'int' } 814 815## 816# @GuestDiskBusType: 817# 818# An enumeration of bus type of disks 819# 820# @ide: IDE disks 821# 822# @fdc: floppy disks 823# 824# @scsi: SCSI disks 825# 826# @virtio: virtio disks 827# 828# @xen: Xen disks 829# 830# @usb: USB disks 831# 832# @uml: UML disks 833# 834# @sata: SATA disks 835# 836# @sd: SD cards 837# 838# @unknown: Unknown bus type 839# 840# @ieee1394: Win IEEE 1394 bus type 841# 842# @ssa: Win SSA bus type 843# 844# @fibre: Win fiber channel bus type 845# 846# @raid: Win RAID bus type 847# 848# @iscsi: Win iScsi bus type 849# 850# @sas: Win serial-attaches SCSI bus type 851# 852# @mmc: Win multimedia card (MMC) bus type 853# 854# @virtual: Win virtual bus type 855# 856# @file-backed-virtual: Win file-backed bus type 857# 858# @nvme: NVMe disks (since 7.1) 859# 860# Since: 2.2; 'Unknown' and all entries below since 2.4 861## 862{ 'enum': 'GuestDiskBusType', 863 'data': [ 'ide', 'fdc', 'scsi', 'virtio', 'xen', 'usb', 'uml', 'sata', 864 'sd', 'unknown', 'ieee1394', 'ssa', 'fibre', 'raid', 'iscsi', 865 'sas', 'mmc', 'virtual', 'file-backed-virtual', 'nvme' ] } 866 867 868## 869# @GuestPCIAddress: 870# 871# @domain: domain id 872# 873# @bus: bus id 874# 875# @slot: slot id 876# 877# @function: function id 878# 879# Since: 2.2 880## 881{ 'struct': 'GuestPCIAddress', 882 'data': {'domain': 'int', 'bus': 'int', 883 'slot': 'int', 'function': 'int'} } 884 885## 886# @GuestCCWAddress: 887# 888# @cssid: channel subsystem image id 889# 890# @ssid: subchannel set id 891# 892# @subchno: subchannel number 893# 894# @devno: device number 895# 896# Since: 6.0 897## 898{ 'struct': 'GuestCCWAddress', 899 'data': {'cssid': 'int', 900 'ssid': 'int', 901 'subchno': 'int', 902 'devno': 'int'} } 903 904## 905# @GuestDiskAddress: 906# 907# @pci-controller: controller's PCI address (fields are set to -1 if 908# invalid) 909# 910# @bus-type: bus type 911# 912# @bus: bus id 913# 914# @target: target id 915# 916# @unit: unit id 917# 918# @serial: serial number (since: 3.1) 919# 920# @dev: device node (POSIX) or device UNC (Windows) (since: 3.1) 921# 922# @ccw-address: CCW address on s390x (since: 6.0) 923# 924# Since: 2.2 925## 926{ 'struct': 'GuestDiskAddress', 927 'data': {'pci-controller': 'GuestPCIAddress', 928 'bus-type': 'GuestDiskBusType', 929 'bus': 'int', 'target': 'int', 'unit': 'int', 930 '*serial': 'str', '*dev': 'str', 931 '*ccw-address': 'GuestCCWAddress'} } 932 933## 934# @GuestNVMeSmart: 935# 936# NVMe smart information, based on NVMe specification, section 937# <SMART / Health Information (Log Identifier 02h)> 938# 939# TODO: document members briefly 940# 941# Since: 7.1 942## 943{ 'struct': 'GuestNVMeSmart', 944 'data': {'critical-warning': 'int', 945 'temperature': 'int', 946 'available-spare': 'int', 947 'available-spare-threshold': 'int', 948 'percentage-used': 'int', 949 'data-units-read-lo': 'uint64', 950 'data-units-read-hi': 'uint64', 951 'data-units-written-lo': 'uint64', 952 'data-units-written-hi': 'uint64', 953 'host-read-commands-lo': 'uint64', 954 'host-read-commands-hi': 'uint64', 955 'host-write-commands-lo': 'uint64', 956 'host-write-commands-hi': 'uint64', 957 'controller-busy-time-lo': 'uint64', 958 'controller-busy-time-hi': 'uint64', 959 'power-cycles-lo': 'uint64', 960 'power-cycles-hi': 'uint64', 961 'power-on-hours-lo': 'uint64', 962 'power-on-hours-hi': 'uint64', 963 'unsafe-shutdowns-lo': 'uint64', 964 'unsafe-shutdowns-hi': 'uint64', 965 'media-errors-lo': 'uint64', 966 'media-errors-hi': 'uint64', 967 'number-of-error-log-entries-lo': 'uint64', 968 'number-of-error-log-entries-hi': 'uint64' } } 969 970## 971# @GuestDiskSmart: 972# 973# Disk type related smart information. 974# 975# @type: disk bus type 976# 977# Since: 7.1 978## 979{ 'union': 'GuestDiskSmart', 980 'base': { 'type': 'GuestDiskBusType' }, 981 'discriminator': 'type', 982 'data': { 'nvme': 'GuestNVMeSmart' } } 983 984## 985# @GuestDiskInfo: 986# 987# @name: device node (Linux) or device UNC (Windows) 988# 989# @partition: whether this is a partition or disk 990# 991# @dependencies: list of device dependencies; e.g. for LVs of the LVM 992# this will hold the list of PVs, for LUKS encrypted volume this 993# will contain the disk where the volume is placed. (Linux) 994# 995# @address: disk address information (only for non-virtual devices) 996# 997# @alias: optional alias assigned to the disk, on Linux this is a name 998# assigned by device mapper 999# 1000# @smart: disk smart information (Since 7.1) 1001# 1002# Since: 5.2 1003## 1004{ 'struct': 'GuestDiskInfo', 1005 'data': {'name': 'str', 'partition': 'bool', '*dependencies': ['str'], 1006 '*address': 'GuestDiskAddress', '*alias': 'str', 1007 '*smart': 'GuestDiskSmart'} } 1008 1009## 1010# @guest-get-disks: 1011# 1012# Returns: The list of disks in the guest. For Windows these are only 1013# the physical disks. On Linux these are all root block devices 1014# of non-zero size including e.g. removable devices, loop devices, 1015# NBD, etc. 1016# 1017# Since: 5.2 1018## 1019{ 'command': 'guest-get-disks', 1020 'returns': ['GuestDiskInfo'] } 1021 1022## 1023# @GuestFilesystemInfo: 1024# 1025# @name: disk name 1026# 1027# @mountpoint: mount point path 1028# 1029# @type: file system type string 1030# 1031# @used-bytes: file system used bytes (since 3.0) 1032# 1033# @total-bytes: non-root file system total bytes (since 3.0) 1034# 1035# @disk: an array of disk hardware information that the volume lies 1036# on, which may be empty if the disk type is not supported 1037# 1038# Since: 2.2 1039## 1040{ 'struct': 'GuestFilesystemInfo', 1041 'data': {'name': 'str', 'mountpoint': 'str', 'type': 'str', 1042 '*used-bytes': 'uint64', '*total-bytes': 'uint64', 1043 'disk': ['GuestDiskAddress']} } 1044 1045## 1046# @guest-get-fsinfo: 1047# 1048# Returns: The list of filesystems information mounted in the guest. 1049# The returned mountpoints may be specified to 1050# @guest-fsfreeze-freeze-list. Network filesystems (such as CIFS 1051# and NFS) are not listed. 1052# 1053# Since: 2.2 1054## 1055{ 'command': 'guest-get-fsinfo', 1056 'returns': ['GuestFilesystemInfo'] } 1057 1058## 1059# @guest-set-user-password: 1060# 1061# @username: the user account whose password to change 1062# 1063# @password: the new password entry string, base64 encoded 1064# 1065# @crypted: true if password is already crypt()d, false if raw 1066# 1067# If the @crypted flag is true, it is the caller's responsibility to 1068# ensure the correct crypt() encryption scheme is used. This command 1069# does not attempt to interpret or report on the encryption scheme. 1070# Refer to the documentation of the guest operating system in question 1071# to determine what is supported. 1072# 1073# Not all guest operating systems will support use of the @crypted 1074# flag, as they may require the clear-text password 1075# 1076# The @password parameter must always be base64 encoded before 1077# transmission, even if already crypt()d, to ensure it is 8-bit safe 1078# when passed as JSON. 1079# 1080# Returns: Nothing on success. 1081# 1082# Since: 2.3 1083## 1084{ 'command': 'guest-set-user-password', 1085 'data': { 'username': 'str', 'password': 'str', 'crypted': 'bool' } } 1086 1087## 1088# @GuestMemoryBlock: 1089# 1090# @phys-index: Arbitrary guest-specific unique identifier of the 1091# MEMORY BLOCK. 1092# 1093# @online: Whether the MEMORY BLOCK is enabled in guest. 1094# 1095# @can-offline: Whether offlining the MEMORY BLOCK is possible. This 1096# member is always filled in by the guest agent when the structure 1097# is returned, and always ignored on input (hence it can be 1098# omitted then). 1099# 1100# Since: 2.3 1101## 1102{ 'struct': 'GuestMemoryBlock', 1103 'data': {'phys-index': 'uint64', 1104 'online': 'bool', 1105 '*can-offline': 'bool'} } 1106 1107## 1108# @guest-get-memory-blocks: 1109# 1110# Retrieve the list of the guest's memory blocks. 1111# 1112# This is a read-only operation. 1113# 1114# Returns: The list of all memory blocks the guest knows about. Each 1115# memory block is put on the list exactly once, but their order is 1116# unspecified. 1117# 1118# Since: 2.3 1119## 1120{ 'command': 'guest-get-memory-blocks', 1121 'returns': ['GuestMemoryBlock'] } 1122 1123## 1124# @GuestMemoryBlockResponseType: 1125# 1126# An enumeration of memory block operation result. 1127# 1128# @success: the operation of online/offline memory block is 1129# successful. 1130# 1131# @not-found: can't find the corresponding memoryXXX directory in 1132# sysfs. 1133# 1134# @operation-not-supported: for some old kernels, it does not support 1135# online or offline memory block. 1136# 1137# @operation-failed: the operation of online/offline memory block 1138# fails, because of some errors happen. 1139# 1140# Since: 2.3 1141## 1142{ 'enum': 'GuestMemoryBlockResponseType', 1143 'data': ['success', 'not-found', 'operation-not-supported', 1144 'operation-failed'] } 1145 1146## 1147# @GuestMemoryBlockResponse: 1148# 1149# @phys-index: same with the 'phys-index' member of @GuestMemoryBlock. 1150# 1151# @response: the result of memory block operation. 1152# 1153# @error-code: the error number. When memory block operation fails, 1154# we assign the value of 'errno' to this member, it indicates what 1155# goes wrong. When the operation succeeds, it will be omitted. 1156# 1157# Since: 2.3 1158## 1159{ 'struct': 'GuestMemoryBlockResponse', 1160 'data': { 'phys-index': 'uint64', 1161 'response': 'GuestMemoryBlockResponseType', 1162 '*error-code': 'int' }} 1163 1164## 1165# @guest-set-memory-blocks: 1166# 1167# Attempt to reconfigure (currently: enable/disable) state of memory 1168# blocks inside the guest. 1169# 1170# @mem-blks: The memory blocks to be reconfigured. This list is 1171# processed node by node in order. In each node @phys-index is 1172# used to look up the guest MEMORY BLOCK, for which @online 1173# specifies the requested state. The set of distinct 1174# @phys-index's is only required to be a subset of the 1175# guest-supported identifiers. There's no restriction on list 1176# length or on repeating the same @phys-index (with possibly 1177# different @online field). Preferably the input list should 1178# describe a modified subset of @guest-get-memory-blocks' return 1179# value. 1180# 1181# Returns: The operation results, it is a list of 1182# @GuestMemoryBlockResponse, which is corresponding to the input 1183# list. 1184# 1185# Note: it will return NULL if the @mem-blks list was empty on 1186# input, or there is an error, and in this case, guest state will 1187# not be changed. 1188# 1189# Since: 2.3 1190## 1191{ 'command': 'guest-set-memory-blocks', 1192 'data': {'mem-blks': ['GuestMemoryBlock'] }, 1193 'returns': ['GuestMemoryBlockResponse'] } 1194 1195## 1196# @GuestMemoryBlockInfo: 1197# 1198# @size: the size (in bytes) of the guest memory blocks, which are the 1199# minimal units of memory block online/offline operations (also 1200# called Logical Memory Hotplug). 1201# 1202# Since: 2.3 1203## 1204{ 'struct': 'GuestMemoryBlockInfo', 1205 'data': {'size': 'uint64'} } 1206 1207## 1208# @guest-get-memory-block-info: 1209# 1210# Get information relating to guest memory blocks. 1211# 1212# Returns: @GuestMemoryBlockInfo 1213# 1214# Since: 2.3 1215## 1216{ 'command': 'guest-get-memory-block-info', 1217 'returns': 'GuestMemoryBlockInfo' } 1218 1219## 1220# @GuestExecStatus: 1221# 1222# @exited: true if process has already terminated. 1223# 1224# @exitcode: process exit code if it was normally terminated. 1225# 1226# @signal: signal number (linux) or unhandled exception code (windows) 1227# if the process was abnormally terminated. 1228# 1229# @out-data: base64-encoded stdout of the process. This field will only 1230# be populated after the process exits. 1231# 1232# @err-data: base64-encoded stderr of the process. Note: @out-data and 1233# @err-data are present only if 'capture-output' was specified for 1234# 'guest-exec'. This field will only be populated after the process 1235# exits. 1236# 1237# @out-truncated: true if stdout was not fully captured due to size 1238# limitation. 1239# 1240# @err-truncated: true if stderr was not fully captured due to size 1241# limitation. 1242# 1243# Since: 2.5 1244## 1245{ 'struct': 'GuestExecStatus', 1246 'data': { 'exited': 'bool', '*exitcode': 'int', '*signal': 'int', 1247 '*out-data': 'str', '*err-data': 'str', 1248 '*out-truncated': 'bool', '*err-truncated': 'bool' }} 1249## 1250# @guest-exec-status: 1251# 1252# Check status of process associated with PID retrieved via 1253# guest-exec. Reap the process and associated metadata if it has 1254# exited. 1255# 1256# @pid: pid returned from guest-exec 1257# 1258# Returns: GuestExecStatus on success. 1259# 1260# Since: 2.5 1261## 1262{ 'command': 'guest-exec-status', 1263 'data': { 'pid': 'int' }, 1264 'returns': 'GuestExecStatus' } 1265 1266## 1267# @GuestExec: 1268# 1269# @pid: pid of child process in guest OS 1270# 1271# Since: 2.5 1272## 1273{ 'struct': 'GuestExec', 1274 'data': { 'pid': 'int'} } 1275 1276## 1277# @GuestExecCaptureOutputMode: 1278# 1279# An enumeration of guest-exec capture modes. 1280# 1281# @none: do not capture any output 1282# @stdout: only capture stdout 1283# @stderr: only capture stderr 1284# @separated: capture both stdout and stderr, but separated into 1285# GuestExecStatus out-data and err-data, respectively 1286# @merged: capture both stdout and stderr, but merge together 1287# into out-data. not effective on windows guests. 1288# 1289# Since: 8.0 1290## 1291 { 'enum': 'GuestExecCaptureOutputMode', 1292 'data': [ 'none', 'stdout', 'stderr', 'separated', 1293 { 'name': 'merged', 'if': { 'not': 'CONFIG_WIN32' } } ] } 1294 1295## 1296# @GuestExecCaptureOutput: 1297# 1298# Controls what guest-exec output gets captures. 1299# 1300# @flag: captures both stdout and stderr if true. Equivalent 1301# to GuestExecCaptureOutputMode::all. (since 2.5) 1302# @mode: capture mode; preferred interface 1303# 1304# Since: 8.0 1305## 1306 { 'alternate': 'GuestExecCaptureOutput', 1307 'data': { 'flag': 'bool', 1308 'mode': 'GuestExecCaptureOutputMode'} } 1309 1310## 1311# @guest-exec: 1312# 1313# Execute a command in the guest 1314# 1315# @path: path or executable name to execute 1316# 1317# @arg: argument list to pass to executable 1318# 1319# @env: environment variables to pass to executable 1320# 1321# @input-data: data to be passed to process stdin (base64 encoded) 1322# 1323# @capture-output: bool flag to enable capture of stdout/stderr of 1324# running process. defaults to false. 1325# 1326# Returns: PID on success. 1327# 1328# Since: 2.5 1329## 1330{ 'command': 'guest-exec', 1331 'data': { 'path': 'str', '*arg': ['str'], '*env': ['str'], 1332 '*input-data': 'str', '*capture-output': 'GuestExecCaptureOutput' }, 1333 'returns': 'GuestExec' } 1334 1335 1336## 1337# @GuestHostName: 1338# 1339# @host-name: Fully qualified domain name of the guest OS 1340# 1341# Since: 2.10 1342## 1343{ 'struct': 'GuestHostName', 1344 'data': { 'host-name': 'str' } } 1345 1346## 1347# @guest-get-host-name: 1348# 1349# Return a name for the machine. 1350# 1351# The returned name is not necessarily a fully-qualified domain name, 1352# or even present in DNS or some other name service at all. It need 1353# not even be unique on your local network or site, but usually it is. 1354# 1355# Returns: the host name of the machine on success 1356# 1357# Since: 2.10 1358## 1359{ 'command': 'guest-get-host-name', 1360 'returns': 'GuestHostName' } 1361 1362 1363## 1364# @GuestUser: 1365# 1366# @user: Username 1367# 1368# @domain: Logon domain (windows only) 1369# 1370# @login-time: Time of login of this user on the computer. If 1371# multiple instances of the user are logged in, the earliest login 1372# time is reported. The value is in fractional seconds since 1373# epoch time. 1374# 1375# Since: 2.10 1376## 1377{ 'struct': 'GuestUser', 1378 'data': { 'user': 'str', 'login-time': 'number', '*domain': 'str' } } 1379 1380## 1381# @guest-get-users: 1382# 1383# Retrieves a list of currently active users on the VM. 1384# 1385# Returns: A unique list of users. 1386# 1387# Since: 2.10 1388## 1389{ 'command': 'guest-get-users', 1390 'returns': ['GuestUser'] } 1391 1392## 1393# @GuestTimezone: 1394# 1395# @zone: Timezone name. These values may differ depending on guest/OS 1396# and should only be used for informational purposes. 1397# 1398# @offset: Offset to UTC in seconds, negative numbers for time zones 1399# west of GMT, positive numbers for east 1400# 1401# Since: 2.10 1402## 1403{ 'struct': 'GuestTimezone', 1404 'data': { '*zone': 'str', 'offset': 'int' } } 1405 1406## 1407# @guest-get-timezone: 1408# 1409# Retrieves the timezone information from the guest. 1410# 1411# Returns: A GuestTimezone dictionary. 1412# 1413# Since: 2.10 1414## 1415{ 'command': 'guest-get-timezone', 1416 'returns': 'GuestTimezone' } 1417 1418## 1419# @GuestOSInfo: 1420# 1421# @kernel-release: 1422# * POSIX: release field returned by uname(2) 1423# * Windows: build number of the OS 1424# 1425# @kernel-version: 1426# * POSIX: version field returned by uname(2) 1427# * Windows: version number of the OS 1428# 1429# @machine: 1430# * POSIX: machine field returned by uname(2) 1431# * Windows: one of x86, x86_64, arm, ia64 1432# 1433# @id: 1434# * POSIX: as defined by os-release(5) 1435# * Windows: contains string "mswindows" 1436# 1437# @name: 1438# * POSIX: as defined by os-release(5) 1439# * Windows: contains string "Microsoft Windows" 1440# 1441# @pretty-name: 1442# * POSIX: as defined by os-release(5) 1443# * Windows: product name, e.g. "Microsoft Windows 10 Enterprise" 1444# 1445# @version: 1446# * POSIX: as defined by os-release(5) 1447# * Windows: long version string, e.g. "Microsoft Windows Server 1448# 2008" 1449# 1450# @version-id: 1451# * POSIX: as defined by os-release(5) 1452# * Windows: short version identifier, e.g. "7" or "20012r2" 1453# 1454# @variant: 1455# * POSIX: as defined by os-release(5) 1456# * Windows: contains string "server" or "client" 1457# 1458# @variant-id: 1459# * POSIX: as defined by os-release(5) 1460# * Windows: contains string "server" or "client" 1461# 1462# Notes: On POSIX systems the fields @id, @name, @pretty-name, 1463# @version, @version-id, @variant and @variant-id follow the 1464# definition specified in os-release(5). Refer to the manual page 1465# for exact description of the fields. Their values are taken 1466# from the os-release file. If the file is not present in the 1467# system, or the values are not present in the file, the fields 1468# are not included. 1469# 1470# On Windows the values are filled from information gathered from 1471# the system. 1472# 1473# Since: 2.10 1474## 1475{ 'struct': 'GuestOSInfo', 1476 'data': { 1477 '*kernel-release': 'str', '*kernel-version': 'str', 1478 '*machine': 'str', '*id': 'str', '*name': 'str', 1479 '*pretty-name': 'str', '*version': 'str', '*version-id': 'str', 1480 '*variant': 'str', '*variant-id': 'str' } } 1481 1482## 1483# @guest-get-osinfo: 1484# 1485# Retrieve guest operating system information 1486# 1487# Returns: @GuestOSInfo 1488# 1489# Since: 2.10 1490## 1491{ 'command': 'guest-get-osinfo', 1492 'returns': 'GuestOSInfo' } 1493 1494## 1495# @GuestDeviceType: 1496# 1497# @pci: PCI device 1498## 1499{ 'enum': 'GuestDeviceType', 1500 'data': [ 'pci' ] } 1501 1502## 1503# @GuestDeviceIdPCI: 1504# 1505# @vendor-id: vendor ID 1506# 1507# @device-id: device ID 1508# 1509# Since: 5.2 1510## 1511{ 'struct': 'GuestDeviceIdPCI', 1512 'data': { 'vendor-id': 'uint16', 'device-id': 'uint16' } } 1513 1514## 1515# @GuestDeviceId: 1516# 1517# Id of the device 1518# 1519# @type: device type 1520# 1521# Since: 5.2 1522## 1523{ 'union': 'GuestDeviceId', 1524 'base': { 'type': 'GuestDeviceType' }, 1525 'discriminator': 'type', 1526 'data': { 'pci': 'GuestDeviceIdPCI' } } 1527 1528## 1529# @GuestDeviceInfo: 1530# 1531# @driver-name: name of the associated driver 1532# 1533# @driver-date: driver release date, in nanoseconds since the epoch 1534# 1535# @driver-version: driver version 1536# 1537# @id: device ID 1538# 1539# Since: 5.2 1540## 1541{ 'struct': 'GuestDeviceInfo', 1542 'data': { 1543 'driver-name': 'str', 1544 '*driver-date': 'int', 1545 '*driver-version': 'str', 1546 '*id': 'GuestDeviceId' 1547 } } 1548 1549## 1550# @guest-get-devices: 1551# 1552# Retrieve information about device drivers in Windows guest 1553# 1554# Returns: @GuestDeviceInfo 1555# 1556# Since: 5.2 1557## 1558{ 'command': 'guest-get-devices', 1559 'returns': ['GuestDeviceInfo'] } 1560 1561## 1562# @GuestAuthorizedKeys: 1563# 1564# @keys: public keys (in OpenSSH/sshd(8) authorized_keys format) 1565# 1566# Since: 5.2 1567## 1568{ 'struct': 'GuestAuthorizedKeys', 1569 'data': { 1570 'keys': ['str'] 1571 }, 1572 'if': 'CONFIG_POSIX' } 1573 1574 1575## 1576# @guest-ssh-get-authorized-keys: 1577# 1578# Return the public keys from user .ssh/authorized_keys on Unix 1579# systems (not implemented for other systems). 1580# 1581# @username: the user account to add the authorized keys 1582# 1583# Returns: @GuestAuthorizedKeys 1584# 1585# Since: 5.2 1586## 1587{ 'command': 'guest-ssh-get-authorized-keys', 1588 'data': { 'username': 'str' }, 1589 'returns': 'GuestAuthorizedKeys', 1590 'if': 'CONFIG_POSIX' } 1591 1592## 1593# @guest-ssh-add-authorized-keys: 1594# 1595# Append public keys to user .ssh/authorized_keys on Unix systems (not 1596# implemented for other systems). 1597# 1598# @username: the user account to add the authorized keys 1599# 1600# @keys: the public keys to add (in OpenSSH/sshd(8) authorized_keys 1601# format) 1602# 1603# @reset: ignore the existing content, set it with the given keys only 1604# 1605# Returns: Nothing on success. 1606# 1607# Since: 5.2 1608## 1609{ 'command': 'guest-ssh-add-authorized-keys', 1610 'data': { 'username': 'str', 'keys': ['str'], '*reset': 'bool' }, 1611 'if': 'CONFIG_POSIX' } 1612 1613## 1614# @guest-ssh-remove-authorized-keys: 1615# 1616# Remove public keys from the user .ssh/authorized_keys on Unix 1617# systems (not implemented for other systems). It's not an error if 1618# the key is already missing. 1619# 1620# @username: the user account to remove the authorized keys 1621# 1622# @keys: the public keys to remove (in OpenSSH/sshd(8) authorized_keys 1623# format) 1624# 1625# Returns: Nothing on success. 1626# 1627# Since: 5.2 1628## 1629{ 'command': 'guest-ssh-remove-authorized-keys', 1630 'data': { 'username': 'str', 'keys': ['str'] }, 1631 'if': 'CONFIG_POSIX' } 1632 1633## 1634# @GuestDiskStats: 1635# 1636# @read-sectors: sectors read 1637# 1638# @read-ios: reads completed successfully 1639# 1640# @read-merges: read requests merged 1641# 1642# @write-sectors: sectors written 1643# 1644# @write-ios: writes completed 1645# 1646# @write-merges: write requests merged 1647# 1648# @discard-sectors: sectors discarded 1649# 1650# @discard-ios: discards completed successfully 1651# 1652# @discard-merges: discard requests merged 1653# 1654# @flush-ios: flush requests completed successfully 1655# 1656# @read-ticks: time spent reading(ms) 1657# 1658# @write-ticks: time spent writing(ms) 1659# 1660# @discard-ticks: time spent discarding(ms) 1661# 1662# @flush-ticks: time spent flushing(ms) 1663# 1664# @ios-pgr: number of I/Os currently in flight 1665# 1666# @total-ticks: time spent doing I/Os (ms) 1667# 1668# @weight-ticks: weighted time spent doing I/Os since the last update 1669# of this field(ms) 1670# 1671# Since: 7.1 1672## 1673{ 'struct': 'GuestDiskStats', 1674 'data': {'*read-sectors': 'uint64', 1675 '*read-ios': 'uint64', 1676 '*read-merges': 'uint64', 1677 '*write-sectors': 'uint64', 1678 '*write-ios': 'uint64', 1679 '*write-merges': 'uint64', 1680 '*discard-sectors': 'uint64', 1681 '*discard-ios': 'uint64', 1682 '*discard-merges': 'uint64', 1683 '*flush-ios': 'uint64', 1684 '*read-ticks': 'uint64', 1685 '*write-ticks': 'uint64', 1686 '*discard-ticks': 'uint64', 1687 '*flush-ticks': 'uint64', 1688 '*ios-pgr': 'uint64', 1689 '*total-ticks': 'uint64', 1690 '*weight-ticks': 'uint64' 1691 } } 1692 1693## 1694# @GuestDiskStatsInfo: 1695# 1696# @name: disk name 1697# 1698# @major: major device number of disk 1699# 1700# @minor: minor device number of disk 1701# 1702# @stats: I/O statistics 1703## 1704{ 'struct': 'GuestDiskStatsInfo', 1705 'data': {'name': 'str', 1706 'major': 'uint64', 1707 'minor': 'uint64', 1708 'stats': 'GuestDiskStats' } } 1709 1710## 1711# @guest-get-diskstats: 1712# 1713# Retrieve information about disk stats. 1714# 1715# Returns: List of disk stats of guest. 1716# 1717# Since: 7.1 1718## 1719{ 'command': 'guest-get-diskstats', 1720 'returns': ['GuestDiskStatsInfo'] 1721} 1722 1723## 1724# @GuestCpuStatsType: 1725# 1726# Guest operating systems supporting CPU statistics 1727# 1728# @linux: Linux 1729# 1730# Since: 7.1 1731## 1732{ 'enum': 'GuestCpuStatsType', 1733 'data': [ 'linux' ] } 1734 1735 1736## 1737# @GuestLinuxCpuStats: 1738# 1739# CPU statistics of Linux 1740# 1741# @cpu: CPU index in guest OS 1742# 1743# @user: Time spent in user mode 1744# 1745# @nice: Time spent in user mode with low priority (nice) 1746# 1747# @system: Time spent in system mode 1748# 1749# @idle: Time spent in the idle task 1750# 1751# @iowait: Time waiting for I/O to complete (since Linux 2.5.41) 1752# 1753# @irq: Time servicing interrupts (since Linux 2.6.0-test4) 1754# 1755# @softirq: Time servicing softirqs (since Linux 2.6.0-test4) 1756# 1757# @steal: Stolen time by host (since Linux 2.6.11) 1758# 1759# @guest: ime spent running a virtual CPU for guest operating systems 1760# under the control of the Linux kernel (since Linux 2.6.24) 1761# 1762# @guestnice: Time spent running a niced guest (since Linux 2.6.33) 1763# 1764# Since: 7.1 1765## 1766{ 'struct': 'GuestLinuxCpuStats', 1767 'data': {'cpu': 'int', 1768 'user': 'uint64', 1769 'nice': 'uint64', 1770 'system': 'uint64', 1771 'idle': 'uint64', 1772 '*iowait': 'uint64', 1773 '*irq': 'uint64', 1774 '*softirq': 'uint64', 1775 '*steal': 'uint64', 1776 '*guest': 'uint64', 1777 '*guestnice': 'uint64' 1778 } } 1779 1780## 1781# @GuestCpuStats: 1782# 1783# Get statistics of each CPU in millisecond. 1784# 1785# @type: guest operating system 1786# 1787# Since: 7.1 1788## 1789{ 'union': 'GuestCpuStats', 1790 'base': { 'type': 'GuestCpuStatsType' }, 1791 'discriminator': 'type', 1792 'data': { 'linux': 'GuestLinuxCpuStats' } } 1793 1794## 1795# @guest-get-cpustats: 1796# 1797# Retrieve information about CPU stats. 1798# 1799# Returns: List of CPU stats of guest. 1800# 1801# Since: 7.1 1802## 1803{ 'command': 'guest-get-cpustats', 1804 'returns': ['GuestCpuStats'] 1805} 1806