diff options
author | Markus Armbruster <armbru@redhat.com> | 2019-06-19 22:10:47 +0200 |
---|---|---|
committer | Markus Armbruster <armbru@redhat.com> | 2019-07-02 13:37:00 +0200 |
commit | d06b747bd55059f6e5bde64f105477929f8275fb (patch) | |
tree | 8ff88260415fae027232e779528c2cd9fc55663e /qapi | |
parent | b0227cdb00f8dbb1fb624f5b4f5f0c0817324d2f (diff) | |
download | qemu-d06b747bd55059f6e5bde64f105477929f8275fb.zip qemu-d06b747bd55059f6e5bde64f105477929f8275fb.tar.gz qemu-d06b747bd55059f6e5bde64f105477929f8275fb.tar.bz2 |
qapi: Split dump.json off misc.json
Move commands dump-guest-memory, query-dump,
query-dump-guest-memory-capability with their types from misc.json to
new dump.json. Add dump.json to MAINTAINERS section "Dump".
Cc: Marc-André Lureau <marcandre.lureau@redhat.com>
Signed-off-by: Markus Armbruster <armbru@redhat.com>
Message-Id: <20190619201050.19040-15-armbru@redhat.com>
Reviewed-by: Marc-André Lureau <marcandre.lureau@redhat.com>
Reviewed-by: Daniel P. Berrangé <berrange@redhat.com>
Diffstat (limited to 'qapi')
-rw-r--r-- | qapi/Makefile.objs | 2 | ||||
-rw-r--r-- | qapi/dump.json | 200 | ||||
-rw-r--r-- | qapi/misc.json | 192 | ||||
-rw-r--r-- | qapi/qapi-schema.json | 1 |
4 files changed, 202 insertions, 193 deletions
diff --git a/qapi/Makefile.objs b/qapi/Makefile.objs index c0be6fc..c5a29e8 100644 --- a/qapi/Makefile.objs +++ b/qapi/Makefile.objs @@ -6,7 +6,7 @@ util-obj-y += qmp-event.o util-obj-y += qapi-util.o QAPI_COMMON_MODULES = audio authz block-core block char common crypto -QAPI_COMMON_MODULES += introspect job machine migration misc net +QAPI_COMMON_MODULES += dump introspect job machine migration misc net QAPI_COMMON_MODULES += qdev qom rdma rocker run-state sockets tpm QAPI_COMMON_MODULES += trace transaction ui QAPI_TARGET_MODULES = machine-target misc-target diff --git a/qapi/dump.json b/qapi/dump.json new file mode 100644 index 0000000..2b35409 --- /dev/null +++ b/qapi/dump.json @@ -0,0 +1,200 @@ +# -*- 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' } diff --git a/qapi/misc.json b/qapi/misc.json index d7db863..31427d4 100644 --- a/qapi/misc.json +++ b/qapi/misc.json @@ -1118,198 +1118,6 @@ { 'command': 'xen-set-global-dirty-log', 'data': { 'enable': 'bool' } } ## -# @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' } - -## # @getfd: # # Receive a file descriptor via SCM rights and assign it a name diff --git a/qapi/qapi-schema.json b/qapi/qapi-schema.json index bcfac85..38af54d 100644 --- a/qapi/qapi-schema.json +++ b/qapi/qapi-schema.json @@ -86,6 +86,7 @@ { 'include': 'crypto.json' } { 'include': 'block.json' } { 'include': 'char.json' } +{ 'include': 'dump.json' } { 'include': 'job.json' } { 'include': 'net.json' } { 'include': 'rdma.json' } |