capstone: Update to upstream "next" branch
[qemu.git] / qapi / dump.json
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 # = 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 #
24 # @win-dmp: Windows full crashdump format,
25 #           can be used instead of ELF converting (since 2.13)
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 #
35 # Dump guest's memory to vmcore. It is a synchronous operation that can take
36 # very long depending on the amount of guest memory.
37 #
38 # @paging: if true, do paging to get guest's memory mapping. This allows
39 #          using gdb to process the core file.
40 #
41 #          IMPORTANT: this option can make QEMU allocate several gigabytes
42 #          of RAM. This can happen for a large guest, or a
43 #          malicious guest pretending to be large.
44 #
45 #          Also, paging=true has the following limitations:
46 #
47 #             1. The guest may be in a catastrophic state or can have corrupted
48 #                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.
53 #
54 # @protocol: the filename or file descriptor of the vmcore. The supported
55 #            protocols are:
56 #
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.
61 #
62 # @detach: if true, QMP will return immediately rather than
63 #          waiting for the dump to finish. The user can track progress
64 #          using "query-dump". (since 2.6).
65 #
66 # @begin: if specified, the starting physical address.
67 #
68 # @length: if specified, the memory size, in bytes. If you don't
69 #          want to dump all guest's memory, please specify the start @begin
70 #          and @length
71 #
72 # @format: if specified, the format of guest memory dump. But non-elf
73 #          format is conflict with paging and filter, ie. @paging, @begin and
74 #          @length is not allowed to be specified with non-elf @format at the
75 #          same time (since 2.0)
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",
86 #      "arguments": { "protocol": "fd:dump" } }
87 # <- { "return": {} }
88 #
89 ##
90 { 'command': 'dump-guest-memory',
91   'data': { 'paging': 'bool', 'protocol': 'str', '*detach': 'bool',
92             '*begin': 'int', '*length': 'int',
93             '*format': 'DumpGuestMemoryFormat'} }
94
95 ##
96 # @DumpStatus:
97 #
98 # Describe the status of a long-running background guest memory dump.
99 #
100 # @none: no dump-guest-memory has started yet.
101 #
102 # @active: there is one dump running in background.
103 #
104 # @completed: the last dump has finished successfully.
105 #
106 # @failed: the last dump has failed.
107 #
108 # Since: 2.6
109 ##
110 { 'enum': 'DumpStatus',
111   'data': [ 'none', 'active', 'completed', 'failed' ] }
112
113 ##
114 # @DumpQueryResult:
115 #
116 # The result format for 'query-dump'.
117 #
118 # @status: enum of @DumpStatus, which shows current dump status
119 #
120 # @completed: bytes written in latest dump (uncompressed)
121 #
122 # @total: total bytes to be written in latest dump (uncompressed)
123 #
124 # Since: 2.6
125 ##
126 { 'struct': 'DumpQueryResult',
127   'data': { 'status': 'DumpStatus',
128             'completed': 'int',
129             'total': 'int' } }
130
131 ##
132 # @query-dump:
133 #
134 # Query latest dump status.
135 #
136 # Returns: A @DumpStatus object showing the dump status.
137 #
138 # Since: 2.6
139 #
140 # Example:
141 #
142 # -> { "execute": "query-dump" }
143 # <- { "return": { "status": "active", "completed": 1024000,
144 #                  "total": 2048000 } }
145 #
146 ##
147 { 'command': 'query-dump', 'returns': 'DumpQueryResult' }
148
149 ##
150 # @DUMP_COMPLETED:
151 #
152 # Emitted when background dump has completed
153 #
154 # @result: final dump status
155 #
156 # @error: human-readable error string that provides
157 #         hint on why dump failed. Only presents on failure. The
158 #         user should not try to interpret the error string.
159 #
160 # Since: 2.6
161 #
162 # Example:
163 #
164 # { "event": "DUMP_COMPLETED",
165 #   "data": {"result": {"total": 1090650112, "status": "completed",
166 #                       "completed": 1090650112} } }
167 #
168 ##
169 { 'event': 'DUMP_COMPLETED' ,
170   'data': { 'result': 'DumpQueryResult', '*error': 'str' } }
171
172 ##
173 # @DumpGuestMemoryCapability:
174 #
175 # A list of the available formats for dump-guest-memory
176 #
177 # Since: 2.0
178 ##
179 { 'struct': 'DumpGuestMemoryCapability',
180   'data': {
181       'formats': ['DumpGuestMemoryFormat'] } }
182
183 ##
184 # @query-dump-guest-memory-capability:
185 #
186 # Returns the available formats for dump-guest-memory
187 #
188 # Returns:  A @DumpGuestMemoryCapability object listing available formats for
189 #           dump-guest-memory
190 #
191 # Since: 2.0
192 #
193 # Example:
194 #
195 # -> { "execute": "query-dump-guest-memory-capability" }
196 # <- { "return": { "formats":
197 #                  ["elf", "kdump-zlib", "kdump-lzo", "kdump-snappy"] }
198 #
199 ##
200 { 'command': 'query-dump-guest-memory-capability',
201   'returns': 'DumpGuestMemoryCapability' }