From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([2001:4830:134:3::10]:50574) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VYSvJ-0004qB-PK for qemu-devel@nongnu.org; Mon, 21 Oct 2013 23:46:30 -0400 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1VYSvE-0001TJ-TE for qemu-devel@nongnu.org; Mon, 21 Oct 2013 23:46:25 -0400 Received: from mx1.redhat.com ([209.132.183.28]:5869) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1VYSvE-0001T6-Kz for qemu-devel@nongnu.org; Mon, 21 Oct 2013 23:46:20 -0400 Message-ID: <5265F506.7010603@redhat.com> Date: Tue, 22 Oct 2013 04:46:14 +0100 From: Eric Blake MIME-Version: 1.0 References: <1382321765-29052-1-git-send-email-xiawenc@linux.vnet.ibm.com> <1382321765-29052-7-git-send-email-xiawenc@linux.vnet.ibm.com> <526595ED.5090506@redhat.com> <5265EEDC.3080900@linux.vnet.ibm.com> In-Reply-To: <5265EEDC.3080900@linux.vnet.ibm.com> Content-Type: multipart/signed; micalg=pgp-sha256; protocol="application/pgp-signature"; boundary="3B6TSKSsJMc1whEcJudDGreebcotHTlA1" Subject: Re: [Qemu-devel] [PATCH 6/6] qapi: add doc for QEvent List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: Wenchao Xia , qemu-devel@nongnu.org Cc: kwolf@redhat.com, pbonzini@redhat.com, armbru@redhat.com, stefanha@redhat.com, lcapitulino@redhat.com This is an OpenPGP/MIME signed message (RFC 4880 and 3156) --3B6TSKSsJMc1whEcJudDGreebcotHTlA1 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: quoted-printable 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 presen= t > 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 comman= d >> ("issuing STOP will stop the emulation"), but you really want it to >> sound like a notification of an effect ("STOP is issued after emulatio= n >> 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. >=20 Indeed, which is why separating the docs from the refactoring made sense in your series, so that we could hammer out good docs. --=20 Eric Blake eblake redhat com +1-919-301-3266 Libvirt virtualization library http://libvirt.org --3B6TSKSsJMc1whEcJudDGreebcotHTlA1 Content-Type: application/pgp-signature; name="signature.asc" Content-Description: OpenPGP digital signature Content-Disposition: attachment; filename="signature.asc" -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.15 (GNU/Linux) Comment: Public key at http://people.redhat.com/eblake/eblake.gpg Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/ iQEcBAEBCAAGBQJSZfUGAAoJEKeha0olJ0Nq62EIAIBwrPX/IUJVa0bVCBuEfkWu B4Koqe3cTSY6wtRAkmTTmjv9A8dAGB75tVBiIZaUxLlrvC0n707wB+2PMOQWcmN2 hE3Oa0SU7k/zAUsJz71rP2IyZmasyPhgf9/Gvbn/PiS7IvzyGSqNCoBClN8s2Dyv YfPCkCql3h725/HBQSv88nkoqdCy9lpF3u92kdXKfbz/U9wnvOdMFjHzdHy8Mq3u DpXBM4omJY0Fs6FQhroUkj+Nj0CdKiuxLmv7SZDTRzlOyzFYyShzKS+mjz8yIv+e WoABoI4VsR2jhvHsNWRI1zY9GLVpnkW0W/Z2GxZpxirCp84+HptDAHBe7FCfbn0= =4Z4/ -----END PGP SIGNATURE----- --3B6TSKSsJMc1whEcJudDGreebcotHTlA1--