target/riscv: vmfirst find-first-set mask bit
[qemu.git] / qapi / dump.json
1 # -*- Mode: Python -*-
2 #
3 # This work is licensed under the terms of the GNU GPL, version 2 or later.
4 # See the COPYING file in the top-level directory.
5
6 ##
7 # = Dump guest memory
8 ##
9
10 ##
11 # @DumpGuestMemoryFormat:
12 #
13 # An enumeration of guest-memory-dump's format.
14 #
15 # @elf: elf format
16 #
17 # @kdump-zlib: kdump-compressed format with zlib-compressed
18 #
19 # @kdump-lzo: kdump-compressed format with lzo-compressed
20 #
21 # @kdump-snappy: kdump-compressed format with snappy-compressed
22 #
23 # @win-dmp: Windows full crashdump format,
24 #           can be used instead of ELF converting (since 2.13)
25 #
26 # Since: 2.0
27 ##
28 { 'enum': 'DumpGuestMemoryFormat',
29   'data': [ 'elf', 'kdump-zlib', 'kdump-lzo', 'kdump-snappy', 'win-dmp' ] }
30
31 ##
32 # @dump-guest-memory:
33 #
34 # Dump guest's memory to vmcore. It is a synchronous operation that can take
35 # very long depending on the amount of guest memory.
36 #
37 # @paging: if true, do paging to get guest's memory mapping. This allows
38 #          using gdb to process the core file.
39 #
40 #          IMPORTANT: this option can make QEMU allocate several gigabytes
41 #          of RAM. This can happen for a large guest, or a
42 #          malicious guest pretending to be large.
43 #
44 #          Also, paging=true has the following limitations:
45 #
46 #             1. The guest may be in a catastrophic state or can have corrupted
47 #                memory, which cannot be trusted
48 #             2. The guest can be in real-mode even if paging is enabled. For
49 #                example, the guest uses ACPI to sleep, and ACPI sleep state
50 #                goes in real-mode
51 #             3. Currently only supported on i386 and x86_64.
52 #
53 # @protocol: the filename or file descriptor of the vmcore. The supported
54 #            protocols are:
55 #
56 #            1. file: the protocol starts with "file:", and the following
57 #               string is the file's path.
58 #            2. fd: the protocol starts with "fd:", and the following string
59 #               is the fd's name.
60 #
61 # @detach: if true, QMP will return immediately rather than
62 #          waiting for the dump to finish. The user can track progress
63 #          using "query-dump". (since 2.6).
64 #
65 # @begin: if specified, the starting physical address.
66 #
67 # @length: if specified, the memory size, in bytes. If you don't
68 #          want to dump all guest's memory, please specify the start @begin
69 #          and @length
70 #
71 # @format: if specified, the format of guest memory dump. But non-elf
72 #          format is conflict with paging and filter, ie. @paging, @begin and
73 #          @length is not allowed to be specified with non-elf @format at the
74 #          same time (since 2.0)
75 #
76 # Note: All boolean arguments default to false
77 #
78 # Returns: nothing on success
79 #
80 # Since: 1.2
81 #
82 # Example:
83 #
84 # -> { "execute": "dump-guest-memory",
85 #      "arguments": { "protocol": "fd:dump" } }
86 # <- { "return": {} }
87 #
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 } }
144 #
145 ##
146 { 'command': 'query-dump', 'returns': 'DumpQueryResult' }
147
148 ##
149 # @DUMP_COMPLETED:
150 #
151 # Emitted when background dump has completed
152 #
153 # @result: final dump status
154 #
155 # @error: human-readable error string that provides
156 #         hint on why dump failed. Only presents on failure. The
157 #         user should not try to interpret the error string.
158 #
159 # Since: 2.6
160 #
161 # Example:
162 #
163 # { "event": "DUMP_COMPLETED",
164 #   "data": {"result": {"total": 1090650112, "status": "completed",
165 #                       "completed": 1090650112} } }
166 #
167 ##
168 { 'event': 'DUMP_COMPLETED' ,
169   'data': { 'result': 'DumpQueryResult', '*error': 'str' } }
170
171 ##
172 # @DumpGuestMemoryCapability:
173 #
174 # A list of the available formats for dump-guest-memory
175 #
176 # Since: 2.0
177 ##
178 { 'struct': 'DumpGuestMemoryCapability',
179   'data': {
180       'formats': ['DumpGuestMemoryFormat'] } }
181
182 ##
183 # @query-dump-guest-memory-capability:
184 #
185 # Returns the available formats for dump-guest-memory
186 #
187 # Returns:  A @DumpGuestMemoryCapability object listing available formats for
188 #           dump-guest-memory
189 #
190 # Since: 2.0
191 #
192 # Example:
193 #
194 # -> { "execute": "query-dump-guest-memory-capability" }
195 # <- { "return": { "formats":
196 #                  ["elf", "kdump-zlib", "kdump-lzo", "kdump-snappy"] }
197 #
198 ##
199 { 'command': 'query-dump-guest-memory-capability',
200   'returns': 'DumpGuestMemoryCapability' }