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