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