Re: [Qemu-devel] [PATCH 14/17] qapi: Split dump.json off misc.json

[Marc-André Lureau]

On Wed, Jun 19, 2019 at 10:10 PM Markus Armbruster <address@hidden> wrote:
>
> 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 <address@hidden>
> Signed-off-by: Markus Armbruster <address@hidden>

Reviewed-by: Marc-André Lureau <address@hidden>

> ---
>  MAINTAINERS           |   1 +
>  dump.c                |   4 +-
>  include/sysemu/dump.h |   2 +-
>  monitor/hmp-cmds.c    |   1 +
>  qapi/Makefile.objs    |   2 +-
>  qapi/dump.json        | 200 ++++++++++++++++++++++++++++++++++++++++++
>  qapi/misc.json        | 192 ----------------------------------------
>  qapi/qapi-schema.json |   1 +
>  8 files changed, 207 insertions(+), 196 deletions(-)
>  create mode 100644 qapi/dump.json
>
> diff --git a/MAINTAINERS b/MAINTAINERS
> index 89e8c01cf3..ea110e99ca 100644
> --- a/MAINTAINERS
> +++ b/MAINTAINERS
> @@ -1855,6 +1855,7 @@ F: hw/misc/vmcoreinfo.c
>  F: include/hw/misc/vmcoreinfo.h
>  F: include/sysemu/dump-arch.h
>  F: include/sysemu/dump.h
> +F: qapi/dump.json
>  F: scripts/dump-guest-memory.py
>  F: stubs/dump.c
>
> diff --git a/dump.c b/dump.c
> index e99554628c..c7b2301652 100644
> --- a/dump.c
> +++ b/dump.c
> @@ -24,8 +24,8 @@
>  #include "sysemu/memory_mapping.h"
>  #include "sysemu/cpus.h"
>  #include "qapi/error.h"
> -#include "qapi/qapi-commands-misc.h"
> -#include "qapi/qapi-events-misc.h"
> +#include "qapi/qapi-commands-dump.h"
> +#include "qapi/qapi-events-dump.h"
>  #include "qapi/qmp/qerror.h"
>  #include "qemu/error-report.h"
>  #include "hw/misc/vmcoreinfo.h"
> diff --git a/include/sysemu/dump.h b/include/sysemu/dump.h
> index d824bc0941..250143cb5a 100644
> --- a/include/sysemu/dump.h
> +++ b/include/sysemu/dump.h
> @@ -14,7 +14,7 @@
>  #ifndef DUMP_H
>  #define DUMP_H
>
> -#include "qapi/qapi-types-misc.h"
> +#include "qapi/qapi-types-dump.h"
>
>  #define MAKEDUMPFILE_SIGNATURE      "makedumpfile"
>  #define MAX_SIZE_MDF_HEADER         (4096) /* max size of 
> makedumpfile_header */
> diff --git a/monitor/hmp-cmds.c b/monitor/hmp-cmds.c
> index ea8ae2966e..18ffeb7017 100644
> --- a/monitor/hmp-cmds.c
> +++ b/monitor/hmp-cmds.c
> @@ -31,6 +31,7 @@
>  #include "qapi/qapi-builtin-visit.h"
>  #include "qapi/qapi-commands-block.h"
>  #include "qapi/qapi-commands-char.h"
> +#include "qapi/qapi-commands-dump.h"
>  #include "qapi/qapi-commands-migration.h"
>  #include "qapi/qapi-commands-misc.h"
>  #include "qapi/qapi-commands-net.h"
> diff --git a/qapi/Makefile.objs b/qapi/Makefile.objs
> index c0be6fcd3e..c5a29e86e2 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 0000000000..2b35409a7b
> --- /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 d7db863c81..31427d45a6 100644
> --- a/qapi/misc.json
> +++ b/qapi/misc.json
> @@ -1117,198 +1117,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:
>  #
> diff --git a/qapi/qapi-schema.json b/qapi/qapi-schema.json
> index bcfac85074..38af54d6b3 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' }
> --
> 2.21.0
>