qapi/dump.json

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