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' } 201