]>
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 | # | |
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 | # | |
a937b6aa MA |
24 | # @win-dmp: Windows full crashdump format, can be used instead of ELF |
25 | # converting (since 2.13) | |
d06b747b MA |
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 | # | |
a937b6aa MA |
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. | |
d06b747b | 37 | # |
a937b6aa MA |
38 | # @paging: if true, do paging to get guest's memory mapping. This |
39 | # allows using gdb to process the core file. | |
d06b747b | 40 | # |
a937b6aa MA |
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. | |
d06b747b | 44 | # |
a937b6aa | 45 | # Also, paging=true has the following limitations: |
d06b747b | 46 | # |
a937b6aa MA |
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. | |
d06b747b | 53 | # |
a937b6aa MA |
54 | # @protocol: the filename or file descriptor of the vmcore. The |
55 | # supported protocols are: | |
d06b747b | 56 | # |
a937b6aa MA |
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. | |
d06b747b | 61 | # |
a937b6aa MA |
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). | |
d06b747b MA |
65 | # |
66 | # @begin: if specified, the starting physical address. | |
67 | # | |
a937b6aa MA |
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 | |
d06b747b | 71 | # |
a937b6aa MA |
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) | |
d06b747b MA |
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", | |
4375cf98 | 86 | # "arguments": { "paging": false, "protocol": "fd:dump" } } |
d06b747b | 87 | # <- { "return": {} } |
d06b747b MA |
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 } } | |
d06b747b MA |
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 | # | |
a937b6aa MA |
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. | |
d06b747b MA |
157 | # |
158 | # Since: 2.6 | |
159 | # | |
160 | # Example: | |
161 | # | |
077a5b1e VT |
162 | # <- { "event": "DUMP_COMPLETED", |
163 | # "data": { "result": { "total": 1090650112, "status": "completed", | |
164 | # "completed": 1090650112 } }, | |
165 | # "timestamp": { "seconds": 1648244171, "microseconds": 950316 } } | |
d06b747b MA |
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 | # | |
a937b6aa MA |
186 | # Returns: A @DumpGuestMemoryCapability object listing available |
187 | # formats for dump-guest-memory | |
d06b747b MA |
188 | # |
189 | # Since: 2.0 | |
190 | # | |
191 | # Example: | |
192 | # | |
193 | # -> { "execute": "query-dump-guest-memory-capability" } | |
194 | # <- { "return": { "formats": | |
612fb7cd | 195 | # ["elf", "kdump-zlib", "kdump-lzo", "kdump-snappy"] } } |
d06b747b MA |
196 | ## |
197 | { 'command': 'query-dump-guest-memory-capability', | |
198 | 'returns': 'DumpGuestMemoryCapability' } |