26ec4e53f2
The current doc generation doesn't care much about indentation levels,
but we would like to switch to an rST format, and rST does care about
indentation.
Make the doc comments more strongly consistent about indentation
for multiline constructs like:
@arg: description line 1
description line 2
Returns: line one
line 2
so that there is always exactly one space after the colon, and
subsequent lines align with the first.
This commit is a purely whitespace change, and it does not alter the
generated .texi files (because the texi generation code strips away
all the extra whitespace). This does mean that we end up with some
over-length lines.
Note that when the documentation for an argument fits on a single
line like this:
@arg: one line only
then stray extra spaces after the ':' don't affect the rST output, so
I have not attempted to methodically fix them, though the preference
is a single space here too.
Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
Message-Id: <20200213175647.17628-10-peter.maydell@linaro.org>
Reviewed-by: Markus Armbruster <armbru@redhat.com>
[Commit message tweaked]
Signed-off-by: Markus Armbruster <armbru@redhat.com>
201 lines
5.3 KiB
Python
201 lines
5.3 KiB
Python
# -*- Mode: Python -*-
|
|
#
|
|
# This work is licensed under the terms of the GNU GPL, version 2 or later.
|
|
# See the COPYING file in the top-level directory.
|
|
|
|
##
|
|
# = Dump guest memory
|
|
##
|
|
|
|
##
|
|
# @DumpGuestMemoryFormat:
|
|
#
|
|
# An enumeration of guest-memory-dump's format.
|
|
#
|
|
# @elf: elf format
|
|
#
|
|
# @kdump-zlib: kdump-compressed format with zlib-compressed
|
|
#
|
|
# @kdump-lzo: kdump-compressed format with lzo-compressed
|
|
#
|
|
# @kdump-snappy: kdump-compressed format with snappy-compressed
|
|
#
|
|
# @win-dmp: Windows full crashdump format,
|
|
# can be used instead of ELF converting (since 2.13)
|
|
#
|
|
# Since: 2.0
|
|
##
|
|
{ 'enum': 'DumpGuestMemoryFormat',
|
|
'data': [ 'elf', 'kdump-zlib', 'kdump-lzo', 'kdump-snappy', 'win-dmp' ] }
|
|
|
|
##
|
|
# @dump-guest-memory:
|
|
#
|
|
# Dump guest's memory to vmcore. It is a synchronous operation that can take
|
|
# very long depending on the amount of guest memory.
|
|
#
|
|
# @paging: if true, do paging to get guest's memory mapping. This allows
|
|
# using gdb to process the core file.
|
|
#
|
|
# IMPORTANT: this option can make QEMU allocate several gigabytes
|
|
# of RAM. This can happen for a large guest, or a
|
|
# malicious guest pretending to be large.
|
|
#
|
|
# Also, paging=true has the following limitations:
|
|
#
|
|
# 1. The guest may be in a catastrophic state or can have corrupted
|
|
# memory, which cannot be trusted
|
|
# 2. The guest can be in real-mode even if paging is enabled. For
|
|
# example, the guest uses ACPI to sleep, and ACPI sleep state
|
|
# goes in real-mode
|
|
# 3. Currently only supported on i386 and x86_64.
|
|
#
|
|
# @protocol: the filename or file descriptor of the vmcore. The supported
|
|
# protocols are:
|
|
#
|
|
# 1. file: the protocol starts with "file:", and the following
|
|
# string is the file's path.
|
|
# 2. fd: the protocol starts with "fd:", and the following string
|
|
# is the fd's name.
|
|
#
|
|
# @detach: if true, QMP will return immediately rather than
|
|
# waiting for the dump to finish. The user can track progress
|
|
# using "query-dump". (since 2.6).
|
|
#
|
|
# @begin: if specified, the starting physical address.
|
|
#
|
|
# @length: if specified, the memory size, in bytes. If you don't
|
|
# want to dump all guest's memory, please specify the start @begin
|
|
# and @length
|
|
#
|
|
# @format: if specified, the format of guest memory dump. But non-elf
|
|
# format is conflict with paging and filter, ie. @paging, @begin and
|
|
# @length is not allowed to be specified with non-elf @format at the
|
|
# same time (since 2.0)
|
|
#
|
|
# Note: All boolean arguments default to false
|
|
#
|
|
# Returns: nothing on success
|
|
#
|
|
# Since: 1.2
|
|
#
|
|
# Example:
|
|
#
|
|
# -> { "execute": "dump-guest-memory",
|
|
# "arguments": { "protocol": "fd:dump" } }
|
|
# <- { "return": {} }
|
|
#
|
|
##
|
|
{ 'command': 'dump-guest-memory',
|
|
'data': { 'paging': 'bool', 'protocol': 'str', '*detach': 'bool',
|
|
'*begin': 'int', '*length': 'int',
|
|
'*format': 'DumpGuestMemoryFormat'} }
|
|
|
|
##
|
|
# @DumpStatus:
|
|
#
|
|
# Describe the status of a long-running background guest memory dump.
|
|
#
|
|
# @none: no dump-guest-memory has started yet.
|
|
#
|
|
# @active: there is one dump running in background.
|
|
#
|
|
# @completed: the last dump has finished successfully.
|
|
#
|
|
# @failed: the last dump has failed.
|
|
#
|
|
# Since: 2.6
|
|
##
|
|
{ 'enum': 'DumpStatus',
|
|
'data': [ 'none', 'active', 'completed', 'failed' ] }
|
|
|
|
##
|
|
# @DumpQueryResult:
|
|
#
|
|
# The result format for 'query-dump'.
|
|
#
|
|
# @status: enum of @DumpStatus, which shows current dump status
|
|
#
|
|
# @completed: bytes written in latest dump (uncompressed)
|
|
#
|
|
# @total: total bytes to be written in latest dump (uncompressed)
|
|
#
|
|
# Since: 2.6
|
|
##
|
|
{ 'struct': 'DumpQueryResult',
|
|
'data': { 'status': 'DumpStatus',
|
|
'completed': 'int',
|
|
'total': 'int' } }
|
|
|
|
##
|
|
# @query-dump:
|
|
#
|
|
# Query latest dump status.
|
|
#
|
|
# Returns: A @DumpStatus object showing the dump status.
|
|
#
|
|
# Since: 2.6
|
|
#
|
|
# Example:
|
|
#
|
|
# -> { "execute": "query-dump" }
|
|
# <- { "return": { "status": "active", "completed": 1024000,
|
|
# "total": 2048000 } }
|
|
#
|
|
##
|
|
{ 'command': 'query-dump', 'returns': 'DumpQueryResult' }
|
|
|
|
##
|
|
# @DUMP_COMPLETED:
|
|
#
|
|
# Emitted when background dump has completed
|
|
#
|
|
# @result: final dump status
|
|
#
|
|
# @error: human-readable error string that provides
|
|
# hint on why dump failed. Only presents on failure. The
|
|
# user should not try to interpret the error string.
|
|
#
|
|
# Since: 2.6
|
|
#
|
|
# Example:
|
|
#
|
|
# { "event": "DUMP_COMPLETED",
|
|
# "data": {"result": {"total": 1090650112, "status": "completed",
|
|
# "completed": 1090650112} } }
|
|
#
|
|
##
|
|
{ 'event': 'DUMP_COMPLETED' ,
|
|
'data': { 'result': 'DumpQueryResult', '*error': 'str' } }
|
|
|
|
##
|
|
# @DumpGuestMemoryCapability:
|
|
#
|
|
# A list of the available formats for dump-guest-memory
|
|
#
|
|
# Since: 2.0
|
|
##
|
|
{ 'struct': 'DumpGuestMemoryCapability',
|
|
'data': {
|
|
'formats': ['DumpGuestMemoryFormat'] } }
|
|
|
|
##
|
|
# @query-dump-guest-memory-capability:
|
|
#
|
|
# Returns the available formats for dump-guest-memory
|
|
#
|
|
# Returns: A @DumpGuestMemoryCapability object listing available formats for
|
|
# dump-guest-memory
|
|
#
|
|
# Since: 2.0
|
|
#
|
|
# Example:
|
|
#
|
|
# -> { "execute": "query-dump-guest-memory-capability" }
|
|
# <- { "return": { "formats":
|
|
# ["elf", "kdump-zlib", "kdump-lzo", "kdump-snappy"] }
|
|
#
|
|
##
|
|
{ 'command': 'query-dump-guest-memory-capability',
|
|
'returns': 'DumpGuestMemoryCapability' }
|