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, can be used instead of ELF 25# 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 36# can take very long depending on the amount of guest memory. 37# 38# @paging: if true, do paging to get guest's memory mapping. This 39# allows 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 malicious guest 43# 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 48# corrupted 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 55# supported 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 waiting 63# for the dump to finish. The user can track progress using 64# "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 want 69# to dump all guest's memory, please specify the start @begin and 70# @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 74# and @length is not allowed to be specified with non-elf @format 75# at the 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": { "paging": false, "protocol": "fd:dump" } } 87# <- { "return": {} } 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{ 'command': 'query-dump', 'returns': 'DumpQueryResult' } 146 147## 148# @DUMP_COMPLETED: 149# 150# Emitted when background dump has completed 151# 152# @result: final dump status 153# 154# @error: human-readable error string that provides hint on why dump 155# failed. Only presents on failure. The user should not try to 156# interpret the error string. 157# 158# Since: 2.6 159# 160# Example: 161# 162# <- { "event": "DUMP_COMPLETED", 163# "data": { "result": { "total": 1090650112, "status": "completed", 164# "completed": 1090650112 } }, 165# "timestamp": { "seconds": 1648244171, "microseconds": 950316 } } 166## 167{ 'event': 'DUMP_COMPLETED' , 168 'data': { 'result': 'DumpQueryResult', '*error': 'str' } } 169 170## 171# @DumpGuestMemoryCapability: 172# 173# A list of the available formats for dump-guest-memory 174# 175# Since: 2.0 176## 177{ 'struct': 'DumpGuestMemoryCapability', 178 'data': { 179 'formats': ['DumpGuestMemoryFormat'] } } 180 181## 182# @query-dump-guest-memory-capability: 183# 184# Returns the available formats for dump-guest-memory 185# 186# Returns: A @DumpGuestMemoryCapability object listing available 187# formats for dump-guest-memory 188# 189# Since: 2.0 190# 191# Example: 192# 193# -> { "execute": "query-dump-guest-memory-capability" } 194# <- { "return": { "formats": 195# ["elf", "kdump-zlib", "kdump-lzo", "kdump-snappy"] } } 196## 197{ 'command': 'query-dump-guest-memory-capability', 198 'returns': 'DumpGuestMemoryCapability' } 199