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