Re: [Qemu-devel] [PATCH 6/6] qapi: add doc for QEvent

[Eric Blake]

On 10/22/2013 04:19 AM, Wenchao Xia wrote:

>>> +#
>>> +# @POWERDOWN: system power down, if it is suppoted
>> s/suppoted/supported/
>>
>> Events aren't issued if they aren't supported, so that phrase is
>> pointless.
>   Ok, I will skip that phrase. The point here is that, many people are
> confused
> about shutdown and powerdown, and it seems POWERDOWN item is not present
> in doc/qmp/qapi-events.txt?

That's a bug in the existing docs, then :)

> I want to add doc tips the difference:
> How about: It will set the system power control unit to notify guest,
> such as
> ACPI chips.(This is where I am not sure, the qemu online doc says,
> shutdown is
> gracefully....).

Based on patch 3/6, the SHUTDOWN event is triggered if
qemu_shutdown_requested() is called, and the POWERDOWN event is issued
if qemu_shutdown_requested() is issued.  I'm fuzzy myself on the
conditions behind those two requests, maybe someone else can chime in.

>>> +#
>>> +# @STOP: stops the emulation
>>> +#
>> Your use of present tense makes it sounds like this is a causal command
>> ("issuing STOP will stop the emulation"), but you really want it to
>> sound like a notification of an effect ("STOP is issued after emulation
>> is stopped).  That is:
>>
>> s/stops the emulation/emulation stopped/
>   Do you mean all tense in the doc should use past tense?

Yes.

> I hesitated before about tense usage, it seems not all event
> is emitted after it happens, for example, powerdown emitted before
> it call notifier to set the states.

Implementation wise, we may issue some events before the action.  But
events are asynchronous by nature, we cannot guarantee that management
reads the event from QMP in any particular order, and in MOST cases,
management won't know about the event until AFTER we have done the
action, even if we queued the event for delivery on the front end of the
action.  It's better to just document ALL events as generically being
past tense.

>   Take another think, I think I may use past tense through the doc,
> but with more carefully meaning, such as:
> the system has enter powerdown state.
>   If you agree with the tense, I'd like sent the reformed doc
> in the following, before respin.
> 

Indeed, which is why separating the docs from the refactoring made sense
in your series, so that we could hammer out good docs.


-- 
Eric Blake   eblake redhat com    +1-919-301-3266
Libvirt virtualization library http://libvirt.org

signature.asc
Description: OpenPGP digital signature