]>
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 | # | |
e6549197 SB |
18 | # @kdump-zlib: makedumpfile flattened, kdump-compressed format with zlib |
19 | # compression | |
d06b747b | 20 | # |
e6549197 SB |
21 | # @kdump-lzo: makedumpfile flattened, kdump-compressed format with lzo |
22 | # compression | |
d06b747b | 23 | # |
e6549197 SB |
24 | # @kdump-snappy: makedumpfile flattened, kdump-compressed format with snappy |
25 | # compression | |
26 | # | |
27 | # @kdump-raw-zlib: raw assembled kdump-compressed format with zlib compression | |
28 | # (since 8.2) | |
29 | # | |
30 | # @kdump-raw-lzo: raw assembled kdump-compressed format with lzo compression | |
31 | # (since 8.2) | |
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 | |
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 | # | |
95 | # Returns: nothing on success | |
96 | # | |
97 | # Since: 1.2 | |
98 | # | |
99 | # Example: | |
100 | # | |
101 | # -> { "execute": "dump-guest-memory", | |
4375cf98 | 102 | # "arguments": { "paging": false, "protocol": "fd:dump" } } |
d06b747b | 103 | # <- { "return": {} } |
d06b747b MA |
104 | ## |
105 | { 'command': 'dump-guest-memory', | |
106 | 'data': { 'paging': 'bool', 'protocol': 'str', '*detach': 'bool', | |
107 | '*begin': 'int', '*length': 'int', | |
108 | '*format': 'DumpGuestMemoryFormat'} } | |
109 | ||
110 | ## | |
111 | # @DumpStatus: | |
112 | # | |
113 | # Describe the status of a long-running background guest memory dump. | |
114 | # | |
115 | # @none: no dump-guest-memory has started yet. | |
116 | # | |
117 | # @active: there is one dump running in background. | |
118 | # | |
119 | # @completed: the last dump has finished successfully. | |
120 | # | |
121 | # @failed: the last dump has failed. | |
122 | # | |
123 | # Since: 2.6 | |
124 | ## | |
125 | { 'enum': 'DumpStatus', | |
126 | 'data': [ 'none', 'active', 'completed', 'failed' ] } | |
127 | ||
128 | ## | |
129 | # @DumpQueryResult: | |
130 | # | |
131 | # The result format for 'query-dump'. | |
132 | # | |
133 | # @status: enum of @DumpStatus, which shows current dump status | |
134 | # | |
135 | # @completed: bytes written in latest dump (uncompressed) | |
136 | # | |
137 | # @total: total bytes to be written in latest dump (uncompressed) | |
138 | # | |
139 | # Since: 2.6 | |
140 | ## | |
141 | { 'struct': 'DumpQueryResult', | |
142 | 'data': { 'status': 'DumpStatus', | |
143 | 'completed': 'int', | |
144 | 'total': 'int' } } | |
145 | ||
146 | ## | |
147 | # @query-dump: | |
148 | # | |
149 | # Query latest dump status. | |
150 | # | |
151 | # Returns: A @DumpStatus object showing the dump status. | |
152 | # | |
153 | # Since: 2.6 | |
154 | # | |
155 | # Example: | |
156 | # | |
157 | # -> { "execute": "query-dump" } | |
158 | # <- { "return": { "status": "active", "completed": 1024000, | |
159 | # "total": 2048000 } } | |
d06b747b MA |
160 | ## |
161 | { 'command': 'query-dump', 'returns': 'DumpQueryResult' } | |
162 | ||
163 | ## | |
164 | # @DUMP_COMPLETED: | |
165 | # | |
166 | # Emitted when background dump has completed | |
167 | # | |
168 | # @result: final dump status | |
169 | # | |
a937b6aa MA |
170 | # @error: human-readable error string that provides hint on why dump |
171 | # failed. Only presents on failure. The user should not try to | |
172 | # interpret the error string. | |
d06b747b MA |
173 | # |
174 | # Since: 2.6 | |
175 | # | |
176 | # Example: | |
177 | # | |
077a5b1e VT |
178 | # <- { "event": "DUMP_COMPLETED", |
179 | # "data": { "result": { "total": 1090650112, "status": "completed", | |
180 | # "completed": 1090650112 } }, | |
181 | # "timestamp": { "seconds": 1648244171, "microseconds": 950316 } } | |
d06b747b MA |
182 | ## |
183 | { 'event': 'DUMP_COMPLETED' , | |
184 | 'data': { 'result': 'DumpQueryResult', '*error': 'str' } } | |
185 | ||
186 | ## | |
187 | # @DumpGuestMemoryCapability: | |
188 | # | |
189 | # A list of the available formats for dump-guest-memory | |
190 | # | |
191 | # Since: 2.0 | |
192 | ## | |
193 | { 'struct': 'DumpGuestMemoryCapability', | |
194 | 'data': { | |
195 | 'formats': ['DumpGuestMemoryFormat'] } } | |
196 | ||
197 | ## | |
198 | # @query-dump-guest-memory-capability: | |
199 | # | |
200 | # Returns the available formats for dump-guest-memory | |
201 | # | |
a937b6aa MA |
202 | # Returns: A @DumpGuestMemoryCapability object listing available |
203 | # formats for dump-guest-memory | |
d06b747b MA |
204 | # |
205 | # Since: 2.0 | |
206 | # | |
207 | # Example: | |
208 | # | |
209 | # -> { "execute": "query-dump-guest-memory-capability" } | |
210 | # <- { "return": { "formats": | |
612fb7cd | 211 | # ["elf", "kdump-zlib", "kdump-lzo", "kdump-snappy"] } } |
d06b747b MA |
212 | ## |
213 | { 'command': 'query-dump-guest-memory-capability', | |
214 | 'returns': 'DumpGuestMemoryCapability' } |