Markus Armbruster | d06b747 | 2019-06-19 22:10:47 +0200 | [diff] [blame] | 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 |
Peter Maydell | 26ec4e5 | 2020-02-13 17:56:26 +0000 | [diff] [blame] | 41 | # of RAM. This can happen for a large guest, or a |
| 42 | # malicious guest pretending to be large. |
Markus Armbruster | d06b747 | 2019-06-19 22:10:47 +0200 | [diff] [blame] | 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' } |