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