| # -*- 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' } |