qapi/dump.json

   1 # -*- Mode: Python -*-
   2 # vim: filetype=python
   3 #
   4 # This work is licensed under the terms of the GNU GPL, version 2 or later.
   5 # See the COPYING file in the top-level directory.
   6
   7 ##
   8 # = Dump guest memory
   9 ##
  10
  11 ##
  12 # @DumpGuestMemoryFormat:
  13 #
  14 # An enumeration of guest-memory-dump's format.
  15 #
  16 # @elf: elf format
  17 #
  18 # @kdump-zlib: kdump-compressed format with zlib-compressed
  19 #
  20 # @kdump-lzo: kdump-compressed format with lzo-compressed
  21 #
  22 # @kdump-snappy: kdump-compressed format with snappy-compressed
  23 #
  24 # @win-dmp: Windows full crashdump format,
  25 #           can be used instead of ELF converting (since 2.13)
  26 #
  27 # Since: 2.0
  28 ##
  29 { 'enum': 'DumpGuestMemoryFormat',
  30   'data': [ 'elf', 'kdump-zlib', 'kdump-lzo', 'kdump-snappy', 'win-dmp' ] }
  31
  32 ##
  33 # @dump-guest-memory:
  34 #
  35 # Dump guest's memory to vmcore. It is a synchronous operation that can take
  36 # very long depending on the amount of guest memory.
  37 #
  38 # @paging: if true, do paging to get guest's memory mapping. This allows
  39 #          using gdb to process the core file.
  40 #
  41 #          IMPORTANT: this option can make QEMU allocate several gigabytes
  42 #          of RAM. This can happen for a large guest, or a
  43 #          malicious guest pretending to be large.
  44 #
  45 #          Also, paging=true has the following limitations:
  46 #
  47 #             1. The guest may be in a catastrophic state or can have corrupted
  48 #                memory, which cannot be trusted
  49 #             2. The guest can be in real-mode even if paging is enabled. For
  50 #                example, the guest uses ACPI to sleep, and ACPI sleep state
  51 #                goes in real-mode
  52 #             3. Currently only supported on i386 and x86_64.
  53 #
  54 # @protocol: the filename or file descriptor of the vmcore. The supported
  55 #            protocols are:
  56 #
  57 #            1. file: the protocol starts with "file:", and the following
  58 #               string is the file's path.
  59 #            2. fd: the protocol starts with "fd:", and the following string
  60 #               is the fd's name.
  61 #
  62 # @detach: if true, QMP will return immediately rather than
  63 #          waiting for the dump to finish. The user can track progress
  64 #          using "query-dump". (since 2.6).
  65 #
  66 # @begin: if specified, the starting physical address.
  67 #
  68 # @length: if specified, the memory size, in bytes. If you don't
  69 #          want to dump all guest's memory, please specify the start @begin
  70 #          and @length
  71 #
  72 # @format: if specified, the format of guest memory dump. But non-elf
  73 #          format is conflict with paging and filter, ie. @paging, @begin and
  74 #          @length is not allowed to be specified with non-elf @format at the
  75 #          same time (since 2.0)
  76 #
  77 # Note: All boolean arguments default to false
  78 #
  79 # Returns: nothing on success
  80 #
  81 # Since: 1.2
  82 #
  83 # Example:
  84 #
  85 # -> { "execute": "dump-guest-memory",
  86 #      "arguments": { "paging": false, "protocol": "fd:dump" } }
  87 # <- { "return": {} }
  88 #
  89 ##
  90 { 'command': 'dump-guest-memory',
  91   'data': { 'paging': 'bool', 'protocol': 'str', '*detach': 'bool',
  92             '*begin': 'int', '*length': 'int',
  93             '*format': 'DumpGuestMemoryFormat'} }
  94
  95 ##
  96 # @DumpStatus:
  97 #
  98 # Describe the status of a long-running background guest memory dump.
  99 #
 100 # @none: no dump-guest-memory has started yet.
 101 #
 102 # @active: there is one dump running in background.
 103 #
 104 # @completed: the last dump has finished successfully.
 105 #
 106 # @failed: the last dump has failed.
 107 #
 108 # Since: 2.6
 109 ##
 110 { 'enum': 'DumpStatus',
 111   'data': [ 'none', 'active', 'completed', 'failed' ] }
 112
 113 ##
 114 # @DumpQueryResult:
 115 #
 116 # The result format for 'query-dump'.
 117 #
 118 # @status: enum of @DumpStatus, which shows current dump status
 119 #
 120 # @completed: bytes written in latest dump (uncompressed)
 121 #
 122 # @total: total bytes to be written in latest dump (uncompressed)
 123 #
 124 # Since: 2.6
 125 ##
 126 { 'struct': 'DumpQueryResult',
 127   'data': { 'status': 'DumpStatus',
 128             'completed': 'int',
 129             'total': 'int' } }
 130
 131 ##
 132 # @query-dump:
 133 #
 134 # Query latest dump status.
 135 #
 136 # Returns: A @DumpStatus object showing the dump status.
 137 #
 138 # Since: 2.6
 139 #
 140 # Example:
 141 #
 142 # -> { "execute": "query-dump" }
 143 # <- { "return": { "status": "active", "completed": 1024000,
 144 #                  "total": 2048000 } }
 145 #
 146 ##
 147 { 'command': 'query-dump', 'returns': 'DumpQueryResult' }
 148
 149 ##
 150 # @DUMP_COMPLETED:
 151 #
 152 # Emitted when background dump has completed
 153 #
 154 # @result: final dump status
 155 #
 156 # @error: human-readable error string that provides
 157 #         hint on why dump failed. Only presents on failure. The
 158 #         user should not try to interpret the error string.
 159 #
 160 # Since: 2.6
 161 #
 162 # Example:
 163 #
 164 # <- { "event": "DUMP_COMPLETED",
 165 #      "data": { "result": { "total": 1090650112, "status": "completed",
 166 #                            "completed": 1090650112 } },
 167 #      "timestamp": { "seconds": 1648244171, "microseconds": 950316 } }
 168 #
 169 ##
 170 { 'event': 'DUMP_COMPLETED' ,
 171   'data': { 'result': 'DumpQueryResult', '*error': 'str' } }
 172
 173 ##
 174 # @DumpGuestMemoryCapability:
 175 #
 176 # A list of the available formats for dump-guest-memory
 177 #
 178 # Since: 2.0
 179 ##
 180 { 'struct': 'DumpGuestMemoryCapability',
 181   'data': {
 182       'formats': ['DumpGuestMemoryFormat'] } }
 183
 184 ##
 185 # @query-dump-guest-memory-capability:
 186 #
 187 # Returns the available formats for dump-guest-memory
 188 #
 189 # Returns: A @DumpGuestMemoryCapability object listing available formats for
 190 #          dump-guest-memory
 191 #
 192 # Since: 2.0
 193 #
 194 # Example:
 195 #
 196 # -> { "execute": "query-dump-guest-memory-capability" }
 197 # <- { "return": { "formats":
 198 #                  ["elf", "kdump-zlib", "kdump-lzo", "kdump-snappy"] }
 199 #
 200 ##
 201 { 'command': 'query-dump-guest-memory-capability',
 202   'returns': 'DumpGuestMemoryCapability' }