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# ***************** 9# Dump guest memory 10# ***************** 11## 12 13## 14# @DumpGuestMemoryFormat: 15# 16# An enumeration of guest-memory-dump's format. 17# 18# @elf: elf format 19# 20# @kdump-zlib: makedumpfile flattened, kdump-compressed format with 21# zlib compression 22# 23# @kdump-lzo: makedumpfile flattened, kdump-compressed format with lzo 24# compression 25# 26# @kdump-snappy: makedumpfile flattened, kdump-compressed format with 27# snappy compression 28# 29# @kdump-raw-zlib: raw assembled kdump-compressed format with zlib 30# compression (since 8.2) 31# 32# @kdump-raw-lzo: raw assembled kdump-compressed format with lzo 33# compression (since 8.2) 34# 35# @kdump-raw-snappy: raw assembled kdump-compressed format with snappy 36# compression (since 8.2) 37# 38# @win-dmp: Windows full crashdump format, can be used instead of ELF 39# converting (since 2.13) 40# 41# Since: 2.0 42## 43{ 'enum': 'DumpGuestMemoryFormat', 44 'data': [ 45 'elf', 46 'kdump-zlib', 'kdump-lzo', 'kdump-snappy', 47 'kdump-raw-zlib', 'kdump-raw-lzo', 'kdump-raw-snappy', 48 'win-dmp' ] } 49 50## 51# @dump-guest-memory: 52# 53# Dump guest's memory to vmcore. It is a synchronous operation that 54# can take very long depending on the amount of guest memory. 55# 56# @paging: if true, do paging to get guest's memory mapping. This 57# allows using gdb to process the core file. 58# 59# **Important**: this option can make QEMU allocate several 60# gigabytes of RAM. This can happen for a large guest, or a 61# malicious guest pretending to be large. 62# 63# Also, paging=true has the following limitations: 64# 65# 1. The guest may be in a catastrophic state or can have 66# corrupted memory, which cannot be trusted 67# 2. The guest can be in real-mode even if paging is enabled. For 68# example, the guest uses ACPI to sleep, and ACPI sleep state 69# goes in real-mode 70# 3. Currently only supported on i386 and x86_64. 71# 72# @protocol: the filename or file descriptor of the vmcore. The 73# supported protocols are: 74# 75# 1. file: the protocol starts with "file:", and the following 76# string is the file's path. 77# 2. fd: the protocol starts with "fd:", and the following string 78# is the fd's name. 79# 80# @detach: if true, QMP will return immediately rather than waiting 81# for the dump to finish. The user can track progress using 82# `query-dump`. (since 2.6). 83# 84# @begin: if specified, the starting physical address. 85# 86# @length: if specified, the memory size, in bytes. If you don't want 87# to dump all guest's memory, please specify the start @begin and 88# @length 89# 90# @format: if specified, the format of guest memory dump. But non-elf 91# format is conflict with paging and filter, ie. @paging, @begin 92# and @length is not allowed to be specified with non-elf @format 93# at the same time (since 2.0) 94# 95# .. note:: All boolean arguments default to false. 96# 97# Since: 1.2 98# 99# .. qmp-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: An object showing the dump status. 152# 153# Since: 2.6 154# 155# .. qmp-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# .. qmp-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# Return the available formats for `dump-guest-memory` 201# 202# Returns: An object listing available formats for `dump-guest-memory` 203# 204# Since: 2.0 205# 206# .. qmp-example:: 207# 208# -> { "execute": "query-dump-guest-memory-capability" } 209# <- { "return": { "formats": 210# ["elf", "kdump-zlib", "kdump-lzo", "kdump-snappy"] } } 211## 212{ 'command': 'query-dump-guest-memory-capability', 213 'returns': 'DumpGuestMemoryCapability' } 214