Re: [Qemu-devel] [PATCH 12/12 v14] introduce a new monitor command 'dump-guest-memory' to dump guest's memory

[Wen Congyang <wency@cn.fujitsu.com>]

At 04/27/2012 10:43 PM, Luiz Capitulino Wrote:
> On Tue, 24 Apr 2012 12:10:07 +0800
> Wen Congyang <wency@cn.fujitsu.com> wrote:
> 
>> The command's usage:
>>    dump [-p] protocol [begin] [length]
>> The supported protocol can be file or fd:
>> 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.
>>
>> Note:
>>   1. If you want to use gdb to process the core, please specify -p option.
>>      The reason why the -p option is not default is:
>>        a. guest machine in a catastrophic state can have corrupted memory,
>>           which we cannot trust.
>>        b. The guest machine can be in read-mode even if paging is enabled.
>>           For example: the guest machine uses ACPI to sleep, and ACPI sleep
>>           state goes in real-mode.
>>   2. If you don't want to dump all guest's memory, please specify the start
>>      physical address and the length.
>>
>> Signed-off-by: Wen Congyang <wency@cn.fujitsu.com>

<cut>

>> diff --git a/qapi-schema.json b/qapi-schema.json
>> index 6499895..5b4d121 100644
>> --- a/qapi-schema.json
>> +++ b/qapi-schema.json
>> @@ -1722,3 +1722,36 @@
>>  # Since: 0.14.0
>>  ##
>>  { 'command': 'device_del', 'data': {'id': 'str'} }
>> +
>> +##
>> +# @dump-guest-memory
>> +#
>> +# Dump guest's memory to vmcore.
> 
> I think it's a good idea to mention that this is a synchronous operation that
> can take very long depending on the amount of guest memory.

OK

> 
>> +#
>> +# @paging: if true, do paging to get guest's memory mapping. The @paging's
>> +# default value of @paging is false, If you want to use gdb to process the
>> +# core, please set @paging to true. The reason why the @paging's value is
>> +# false:
> 
> paging is an required argument. If you want to make it optional, you have to
> change the args_type field in qmp-commands.hx and change the schema file
> accordingly.

paging is an required argument in qmp-commands.hx while it is an optional argument
in hmp-commnds.hx. I will update qmp-commands.hx.

> 
>> +#   1. guest machine in a catastrophic state can have corrupted memory,
>> +#      which we cannot trust.
>> +#   2. The guest machine can be in read-mode even if paging is enabled.
>> +#      For example: the guest machine uses ACPI to sleep, and ACPI sleep
>> +#      state goes in real-mode
>> +# @protocol: the filename or file descriptor of the vmcore. The supported
>> +# protocol can be file or fd:
>> +#   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.
>> +# @begin: #optional if specified, the starting physical address.
>> +# @length: #optional 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
>> +#
>> +# Returns: nothing on success
> 
> You have to describe the possible errors. You can look in qapi-schema.json
> for examples.

OK

Thanks
Wen Congyang
> 
>> +#
>> +# Since: 1.1
>> +##
>> +{ 'command': 'dump-guest-memory',
>> +  'data': { 'paging': 'bool', 'protocol': 'str', '*begin': 'int',
>> +            '*length': 'int' } }
>> diff --git a/qmp-commands.hx b/qmp-commands.hx
>> index f972332..4c888a9 100644
>> --- a/qmp-commands.hx
>> +++ b/qmp-commands.hx
>> @@ -604,6 +604,42 @@ Example:
>>  EQMP
>>  
>>      {
>> +        .name       = "dump-guest-memory",
>> +        .args_type  = "paging:b,protocol:s,begin:i?,end:i?",
>> +        .params     = "[-p] protocol [begin] [length]",
>> +        .help       = "dump guest memory to file",
>> +        .user_print = monitor_user_noop,
>> +        .mhandler.cmd_new = qmp_marshal_input_dump_guest_memory,
>> +    },
>> +
>> +SQMP
>> +dump
>> +
>> +
>> +Dump guest memory to file. The file can be processed with crash or gdb.
>> +
>> +Arguments:
>> +
>> +- "paging": do paging to get guest's memory mapping (json-bool)
>> +- "protocol": destination file(started with "file:") or destination file
>> +              descriptor (started with "fd:") (json-string)
>> +- "begin": the starting physical address. It's optional, and should be specified
>> +           with length together (json-int)
>> +- "length": the memory size, in bytes. It's optional, and should be specified
>> +            with begin together (json-int)
>> +
>> +Example:
>> +
>> +-> { "execute": "dump-guest-memory", "arguments": { "protocol": "fd:dump" } }
>> +<- { "return": {} }
>> +
>> +Notes:
>> +
>> +(1) All boolean arguments default to false
>> +
>> +EQMP
>> +
>> +    {
>>          .name       = "netdev_add",
>>          .args_type  = "netdev:O",
>>          .params     = "[user|tap|socket],id=str[,prop=value][,...]",
> 
>