Import QEMU upstream snapshot d2e570c

Upstream: https://gitlab.com/qemu-project/qemu.git

Upstream-Commit: d2e570cc0f97b936902a5b1b86b73c0f5998b475

qapi/dump.json

@@ -0,0 +1,220 @@
+# -*- Mode: Python -*-
+# vim: filetype=python
+#
+# This work is licensed under the terms of the GNU GPL, version 2 or later.
+# See the COPYING file in the top-level directory.
+
+##
+# *****************
+# Dump guest memory
+# *****************
+##
+
+##
+# @DumpGuestMemoryFormat:
+#
+# An enumeration of guest-memory-dump's format.
+#
+# @elf: elf format
+#
+# @kdump-zlib: makedumpfile flattened, kdump-compressed format with
+#     zlib compression
+#
+# @kdump-lzo: makedumpfile flattened, kdump-compressed format with lzo
+#     compression
+#
+# @kdump-snappy: makedumpfile flattened, kdump-compressed format with
+#     snappy compression
+#
+# @kdump-raw-zlib: raw assembled kdump-compressed format with zlib
+#     compression (since 8.2)
+#
+# @kdump-raw-lzo: raw assembled kdump-compressed format with lzo
+#     compression (since 8.2)
+#
+# @kdump-raw-snappy: raw assembled kdump-compressed format with snappy
+#     compression (since 8.2)
+#
+# @win-dmp: Windows full crashdump format, can be used instead of ELF
+#     converting (since 2.13)
+#
+# Features:
+#
+# @allowed-by-guest: If present, @win-dmp is listed by
+#     `query-dump-guest-memory-capability`, and accepted by
+#     `dump-guest-memory`, only when the guest has published a Windows
+#     dump header through the vmcoreinfo device (since 11.1)
+#
+# Since: 2.0
+##
+{ 'enum': 'DumpGuestMemoryFormat',
+  'data': [
+      'elf',
+      'kdump-zlib', 'kdump-lzo', 'kdump-snappy',
+      'kdump-raw-zlib', 'kdump-raw-lzo', 'kdump-raw-snappy',
+      { 'name': 'win-dmp', 'features': ['allowed-by-guest'] } ] }
+
+##
+# @dump-guest-memory:
+#
+# Dump guest's memory to vmcore.  It is a synchronous operation that
+# can take very long depending on the amount of guest memory.
+#
+# @paging: if true, do paging to get guest's memory mapping.  This
+#     allows using gdb to process the core file.
+#
+#     **Important**: this option can make QEMU allocate several
+#     gigabytes of RAM.  This can happen for a large guest, or a
+#     malicious guest pretending to be large.
+#
+#     Also, paging=true has the following limitations:
+#
+#     1. The guest may be in a catastrophic state or can have
+#        corrupted memory, which cannot be trusted
+#     2. The guest can be in real-mode even if paging is enabled.  For
+#        example, the guest uses ACPI to sleep, and ACPI sleep state
+#        goes in real-mode
+#     3. Currently only supported on i386 and x86_64.
+#
+# @protocol: the filename or file descriptor of the vmcore.  The
+#     supported protocols are:
+#
+#     1. file: the protocol starts with "file:", and the following
+#        string is the file's path.
+#     2. fd: the protocol starts with "fd:", and the following string
+#        is the fd's name.
+#
+# @detach: if true, QMP will return immediately rather than waiting
+#     for the dump to finish.  The user can track progress using
+#     `query-dump`.  (since 2.6).
+#
+# @begin: if specified, the starting physical address.
+#
+# @length: if specified, the memory size, in bytes.  If you don't want
+#     to dump all guest's memory, please specify the start @begin and
+#     @length
+#
+# @format: if specified, the format of guest memory dump.  But non-elf
+#     format is conflict with paging and filter, ie.  @paging, @begin
+#     and @length is not allowed to be specified with non-elf @format
+#     at the same time (since 2.0)
+#
+# .. note:: All boolean arguments default to false.
+#
+# Since: 1.2
+#
+# .. qmp-example::
+#
+#     -> { "execute": "dump-guest-memory",
+#          "arguments": { "paging": false, "protocol": "fd:dump" } }
+#     <- { "return": {} }
+##
+{ 'command': 'dump-guest-memory',
+  'data': { 'paging': 'bool', 'protocol': 'str', '*detach': 'bool',
+            '*begin': 'int', '*length': 'int',
+            '*format': 'DumpGuestMemoryFormat'} }
+
+##
+# @DumpStatus:
+#
+# Describe the status of a long-running background guest memory dump.
+#
+# @none: no `dump-guest-memory` has started yet.
+#
+# @active: there is one dump running in background.
+#
+# @completed: the last dump has finished successfully.
+#
+# @failed: the last dump has failed.
+#
+# Since: 2.6
+##
+{ 'enum': 'DumpStatus',
+  'data': [ 'none', 'active', 'completed', 'failed' ] }
+
+##
+# @DumpQueryResult:
+#
+# The result format for `query-dump`.
+#
+# @status: enum of `DumpStatus`, which shows current dump status
+#
+# @completed: bytes written in latest dump (uncompressed)
+#
+# @total: total bytes to be written in latest dump (uncompressed)
+#
+# Since: 2.6
+##
+{ 'struct': 'DumpQueryResult',
+  'data': { 'status': 'DumpStatus',
+            'completed': 'int',
+            'total': 'int' } }
+
+##
+# @query-dump:
+#
+# Query latest dump status.
+#
+# Returns: An object showing the dump status.
+#
+# Since: 2.6
+#
+# .. qmp-example::
+#
+#     -> { "execute": "query-dump" }
+#     <- { "return": { "status": "active", "completed": 1024000,
+#                      "total": 2048000 } }
+##
+{ 'command': 'query-dump', 'returns': 'DumpQueryResult' }
+
+##
+# @DUMP_COMPLETED:
+#
+# Emitted when background dump has completed
+#
+# @result: final dump status
+#
+# @error: human-readable error string that provides hint on why dump
+#     failed.  Only presents on failure.  The user should not try to
+#     interpret the error string.
+#
+# Since: 2.6
+#
+# .. qmp-example::
+#
+#     <- { "event": "DUMP_COMPLETED",
+#          "data": { "result": { "total": 1090650112, "status": "completed",
+#                                "completed": 1090650112 } },
+#          "timestamp": { "seconds": 1648244171, "microseconds": 950316 } }
+##
+{ 'event': 'DUMP_COMPLETED' ,
+  'data': { 'result': 'DumpQueryResult', '*error': 'str' } }
+
+##
+# @DumpGuestMemoryCapability:
+#
+# @formats: the available formats for `dump-guest-memory`
+#
+# Since: 2.0
+##
+{ 'struct': 'DumpGuestMemoryCapability',
+  'data': {
+      'formats': ['DumpGuestMemoryFormat'] } }
+
+##
+# @query-dump-guest-memory-capability:
+#
+# Return the available formats for `dump-guest-memory`
+#
+# Returns: An object listing available formats for `dump-guest-memory`
+#
+# Since: 2.0
+#
+# .. qmp-example::
+#
+#     -> { "execute": "query-dump-guest-memory-capability" }
+#     <- { "return": { "formats":
+#                      ["elf", "kdump-zlib", "kdump-lzo", "kdump-snappy"] } }
+##
+{ 'command': 'query-dump-guest-memory-capability',
+  'returns': 'DumpGuestMemoryCapability' }