[Qemu-devel] [PATCH] Makefile: Install qmp-events.txt

[Qemu-devel] [PATCH] Makefile: Install qmp-events.txt

[Michal Privoznik]

Since fe069d9d5946 the qmp-events.txt does not exist anymore. This is
unhappy as users still may want to know what events they can await
from qemu.

Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
---
 Makefile | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/Makefile b/Makefile
index 145adb6..b93aa38 100644
--- a/Makefile
+++ b/Makefile
@@ -77,7 +77,7 @@ LIBS+=-lz $(LIBS_TOOLS)
 HELPERS-$(CONFIG_LINUX) = qemu-bridge-helper$(EXESUF)
 
 ifdef BUILD_DOCS
-DOCS=qemu-doc.html qemu-tech.html qemu.1 qemu-img.1 qemu-nbd.8 qmp-commands.txt
+DOCS=qemu-doc.html qemu-tech.html qemu.1 qemu-img.1 qemu-nbd.8 qmp-commands.txt qmp-events.txt
 ifdef CONFIG_VIRTFS
 DOCS+=fsdev/virtfs-proxy-helper.1
 endif
@@ -353,6 +353,7 @@ install-doc: $(DOCS)
 	$(INSTALL_DIR) "$(DESTDIR)$(qemu_docdir)"
 	$(INSTALL_DATA) qemu-doc.html  qemu-tech.html "$(DESTDIR)$(qemu_docdir)"
 	$(INSTALL_DATA) qmp-commands.txt "$(DESTDIR)$(qemu_docdir)"
+	$(INSTALL_DATA) qmp-events.txt "$(DESTDIR)$(qemu_docdir)"
 ifdef CONFIG_POSIX
 	$(INSTALL_DIR) "$(DESTDIR)$(mandir)/man1"
 	$(INSTALL_DATA) qemu.1 "$(DESTDIR)$(mandir)/man1"
@@ -455,6 +456,9 @@ qemu-monitor.texi: $(SRC_PATH)/hmp-commands.hx
 qmp-commands.txt: $(SRC_PATH)/qmp-commands.hx
 	$(call quiet-command,sh $(SRC_PATH)/scripts/hxtool -q < $< > $@,"  GEN   $@")
 
+qmp-events.txt: $(SRC_PATH)/qapi-event.json
+	$(call quiet-command,sh $(SRC_PATH)/scripts/hxtool -h < $< > $@,"  GEN   $@")
+
 qemu-img-cmds.texi: $(SRC_PATH)/qemu-img-cmds.hx
 	$(call quiet-command,sh $(SRC_PATH)/scripts/hxtool -t < $< > $@,"  GEN   $@")
 
-- 
1.8.5.5

Re: [Qemu-devel] [PATCH] Makefile: Install qmp-events.txt

[Paolo Bonzini]

Il 25/06/2014 11:30, Michal Privoznik ha scritto:
> Since fe069d9d5946 the qmp-events.txt does not exist anymore. This is
> unhappy as users still may want to know what events they can await
> from qemu.

hxtool however doesn't understand the json format. :(  I guess for now 
we could just revert the deletion, and aim at automatically-generating 
the documentation in the future.

Paolo

Re: [Qemu-devel] [PATCH] Makefile: Install qmp-events.txt

[Michal Privoznik]

On 25.06.2014 11:34, Paolo Bonzini wrote:
> Il 25/06/2014 11:30, Michal Privoznik ha scritto:
>> Since fe069d9d5946 the qmp-events.txt does not exist anymore. This is
>> unhappy as users still may want to know what events they can await
>> from qemu.
>
> hxtool however doesn't understand the json format. :(  I guess for now
> we could just revert the deletion, and aim at automatically-generating
> the documentation in the future.

Well, the patch is using 'hxtool -h' which effectively is 'cp'. Yes, it 
is hackish.

Michal

Re: [Qemu-devel] [PATCH] Makefile: Install qmp-events.txt

[Eric Blake]

[-- Attachment #1: Type: text/plain, Size: 2456 bytes --]

On 06/25/2014 03:30 AM, Michal Privoznik wrote:
> Since fe069d9d5946 the qmp-events.txt does not exist anymore. This is
> unhappy as users still may want to know what events they can await
> from qemu.

The .json files are a better contract of what is supported, anyways.

> 
> Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
> ---
>  Makefile | 6 +++++-
>  1 file changed, 5 insertions(+), 1 deletion(-)
> 
> diff --git a/Makefile b/Makefile
> index 145adb6..b93aa38 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -77,7 +77,7 @@ LIBS+=-lz $(LIBS_TOOLS)
>  HELPERS-$(CONFIG_LINUX) = qemu-bridge-helper$(EXESUF)
>  
>  ifdef BUILD_DOCS
> -DOCS=qemu-doc.html qemu-tech.html qemu.1 qemu-img.1 qemu-nbd.8 qmp-commands.txt
> +DOCS=qemu-doc.html qemu-tech.html qemu.1 qemu-img.1 qemu-nbd.8 qmp-commands.txt qmp-events.txt

Then again, qmp-commands.txt is generated from qmp-commands.hx, which
duplicates information already in qapi-schema.json (and friends, now).
Would it be better to just install the .json files?  Is it time to
finally bite the bullet and figure out how to get rid of duplication by
dropping qmp-commands.hx, and instead listing example usage directly in
the qapi-schema.json file?  I'm not sure if we have a good plan in place
for user-facing documentation, even if the move to events-as-QAPI was
desirable.

>  ifdef CONFIG_VIRTFS
>  DOCS+=fsdev/virtfs-proxy-helper.1
>  endif
> @@ -353,6 +353,7 @@ install-doc: $(DOCS)
>  	$(INSTALL_DIR) "$(DESTDIR)$(qemu_docdir)"
>  	$(INSTALL_DATA) qemu-doc.html  qemu-tech.html "$(DESTDIR)$(qemu_docdir)"
>  	$(INSTALL_DATA) qmp-commands.txt "$(DESTDIR)$(qemu_docdir)"
> +	$(INSTALL_DATA) qmp-events.txt "$(DESTDIR)$(qemu_docdir)"
>  ifdef CONFIG_POSIX
>  	$(INSTALL_DIR) "$(DESTDIR)$(mandir)/man1"
>  	$(INSTALL_DATA) qemu.1 "$(DESTDIR)$(mandir)/man1"
> @@ -455,6 +456,9 @@ qemu-monitor.texi: $(SRC_PATH)/hmp-commands.hx
>  qmp-commands.txt: $(SRC_PATH)/qmp-commands.hx
>  	$(call quiet-command,sh $(SRC_PATH)/scripts/hxtool -q < $< > $@,"  GEN   $@")
>  
> +qmp-events.txt: $(SRC_PATH)/qapi-event.json
> +	$(call quiet-command,sh $(SRC_PATH)/scripts/hxtool -h < $< > $@,"  GEN   $@")
> +
>  qemu-img-cmds.texi: $(SRC_PATH)/qemu-img-cmds.hx
>  	$(call quiet-command,sh $(SRC_PATH)/scripts/hxtool -t < $< > $@,"  GEN   $@")
>  
> 

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


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 604 bytes --]

Re: [Qemu-devel] [PATCH] Makefile: Install qmp-events.txt

[Markus Armbruster]

Eric Blake <eblake@redhat.com> writes:

> On 06/25/2014 03:30 AM, Michal Privoznik wrote:
>> Since fe069d9d5946 the qmp-events.txt does not exist anymore. This is
>> unhappy as users still may want to know what events they can await
>> from qemu.
>
> The .json files are a better contract of what is supported, anyways.
>
>> 
>> Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
>> ---
>>  Makefile | 6 +++++-
>>  1 file changed, 5 insertions(+), 1 deletion(-)
>> 
>> diff --git a/Makefile b/Makefile
>> index 145adb6..b93aa38 100644
>> --- a/Makefile
>> +++ b/Makefile
>> @@ -77,7 +77,7 @@ LIBS+=-lz $(LIBS_TOOLS)
>>  HELPERS-$(CONFIG_LINUX) = qemu-bridge-helper$(EXESUF)
>>  
>>  ifdef BUILD_DOCS
>> -DOCS=qemu-doc.html qemu-tech.html qemu.1 qemu-img.1 qemu-nbd.8
>> qmp-commands.txt
>> +DOCS=qemu-doc.html qemu-tech.html qemu.1 qemu-img.1 qemu-nbd.8
>> qmp-commands.txt qmp-events.txt
>
> Then again, qmp-commands.txt is generated from qmp-commands.hx, which
> duplicates information already in qapi-schema.json (and friends, now).
> Would it be better to just install the .json files?  Is it time to
> finally bite the bullet and figure out how to get rid of duplication by
> dropping qmp-commands.hx, and instead listing example usage directly in
> the qapi-schema.json file?  I'm not sure if we have a good plan in place
> for user-facing documentation, even if the move to events-as-QAPI was
> desirable.

The plan always was to retire qmp-commands.hx once all commands are
qapified.  Naturally, retiring shouldn't involve loss of useful
documentation.

Re: [Qemu-devel] [PATCH] Makefile: Install qmp-events.txt

[Luiz Capitulino]

On Wed, 25 Jun 2014 07:56:51 -0600
Eric Blake <eblake@redhat.com> wrote:

> On 06/25/2014 03:30 AM, Michal Privoznik wrote:
> > Since fe069d9d5946 the qmp-events.txt does not exist anymore. This is
> > unhappy as users still may want to know what events they can await
> > from qemu.
> 
> The .json files are a better contract of what is supported, anyways.
> 
> > 
> > Signed-off-by: Michal Privoznik <mprivozn@redhat.com>
> > ---
> >  Makefile | 6 +++++-
> >  1 file changed, 5 insertions(+), 1 deletion(-)
> > 
> > diff --git a/Makefile b/Makefile
> > index 145adb6..b93aa38 100644
> > --- a/Makefile
> > +++ b/Makefile
> > @@ -77,7 +77,7 @@ LIBS+=-lz $(LIBS_TOOLS)
> >  HELPERS-$(CONFIG_LINUX) = qemu-bridge-helper$(EXESUF)
> >  
> >  ifdef BUILD_DOCS
> > -DOCS=qemu-doc.html qemu-tech.html qemu.1 qemu-img.1 qemu-nbd.8 qmp-commands.txt
> > +DOCS=qemu-doc.html qemu-tech.html qemu.1 qemu-img.1 qemu-nbd.8 qmp-commands.txt qmp-events.txt
> 
> Then again, qmp-commands.txt is generated from qmp-commands.hx, which
> duplicates information already in qapi-schema.json (and friends, now).
> Would it be better to just install the .json files?  Is it time to
> finally bite the bullet and figure out how to get rid of duplication by
> dropping qmp-commands.hx, and instead listing example usage directly in
> the qapi-schema.json file?  I'm not sure if we have a good plan in place
> for user-facing documentation, even if the move to events-as-QAPI was
> desirable.

My original plan was to generate qmp-commands.txt & qmp-evets.txt from
the schema file(s). I'm not sure if the .json files are consumable to
non-qemu/libvirt developers. If you think they are then I'd be fine with
installing them.

Wrt the examples, my only concern about having them in the schema is
that the examples are in QMP format but in the past we were also planning
on having C support via libqmp. If what we have today is what matters,
then we can just move the examples to the schema files.

> 
> >  ifdef CONFIG_VIRTFS
> >  DOCS+=fsdev/virtfs-proxy-helper.1
> >  endif
> > @@ -353,6 +353,7 @@ install-doc: $(DOCS)
> >  	$(INSTALL_DIR) "$(DESTDIR)$(qemu_docdir)"
> >  	$(INSTALL_DATA) qemu-doc.html  qemu-tech.html "$(DESTDIR)$(qemu_docdir)"
> >  	$(INSTALL_DATA) qmp-commands.txt "$(DESTDIR)$(qemu_docdir)"
> > +	$(INSTALL_DATA) qmp-events.txt "$(DESTDIR)$(qemu_docdir)"
> >  ifdef CONFIG_POSIX
> >  	$(INSTALL_DIR) "$(DESTDIR)$(mandir)/man1"
> >  	$(INSTALL_DATA) qemu.1 "$(DESTDIR)$(mandir)/man1"
> > @@ -455,6 +456,9 @@ qemu-monitor.texi: $(SRC_PATH)/hmp-commands.hx
> >  qmp-commands.txt: $(SRC_PATH)/qmp-commands.hx
> >  	$(call quiet-command,sh $(SRC_PATH)/scripts/hxtool -q < $< > $@,"  GEN   $@")
> >  
> > +qmp-events.txt: $(SRC_PATH)/qapi-event.json
> > +	$(call quiet-command,sh $(SRC_PATH)/scripts/hxtool -h < $< > $@,"  GEN   $@")
> > +
> >  qemu-img-cmds.texi: $(SRC_PATH)/qemu-img-cmds.hx
> >  	$(call quiet-command,sh $(SRC_PATH)/scripts/hxtool -t < $< > $@,"  GEN   $@")
> >  
> > 
> 

Re: [Qemu-devel] [PATCH] Makefile: Install qmp-events.txt

[Eric Blake]

[-- Attachment #1: Type: text/plain, Size: 2360 bytes --]

On 06/25/2014 01:50 PM, Luiz Capitulino wrote:

>> Then again, qmp-commands.txt is generated from qmp-commands.hx, which
>> duplicates information already in qapi-schema.json (and friends, now).
>> Would it be better to just install the .json files?  Is it time to
>> finally bite the bullet and figure out how to get rid of duplication by
>> dropping qmp-commands.hx, and instead listing example usage directly in
>> the qapi-schema.json file?  I'm not sure if we have a good plan in place
>> for user-facing documentation, even if the move to events-as-QAPI was
>> desirable.
> 
> My original plan was to generate qmp-commands.txt & qmp-evets.txt from
> the schema file(s). I'm not sure if the .json files are consumable to
> non-qemu/libvirt developers. If you think they are then I'd be fine with
> installing them.

The .json files are what _I_ refer to (but I'm probably biased, since
I've become a vested partner in the json files in the meantime); for
someone encountering the docs with no prior experience, I'm not sure how
much value-added the qmp-commands.txt was providing.

> 
> Wrt the examples, my only concern about having them in the schema is
> that the examples are in QMP format but in the past we were also planning
> on having C support via libqmp. If what we have today is what matters,
> then we can just move the examples to the schema files.

Putting the examples in the .json files also comes with its own
interesting issues - do you prefix every line with # comment markers (so
the examples are no longer copy-paste, but now copy-paste-modify)? Or do
we do it as top-level JSON elements, perhaps via a new item that the
generators ignore but which a doc conversion tool could consume?  Maybe:
{ 'example': {
  'client':
    {"command": {"foo", "arguments": { "hello": "world" } } },
  'server':
    {"reply": {} }
} }

Michal's hack at least ensures that we have event documentation, even if
the format changed compared to the 2.0 docs, and even if we don't have
time to get something better in place before 2.1 goes out.  So all of
this conversation on ways to do better is nice, but if we don't get
there quickly, I could at least live with Michal's patch in the short term.

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


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 604 bytes --]

Re: [Qemu-devel] [PATCH] Makefile: Install qmp-events.txt

[Luiz Capitulino]

On Wed, 25 Jun 2014 14:13:37 -0600
Eric Blake <eblake@redhat.com> wrote:

> On 06/25/2014 01:50 PM, Luiz Capitulino wrote:
> 
> >> Then again, qmp-commands.txt is generated from qmp-commands.hx, which
> >> duplicates information already in qapi-schema.json (and friends, now).
> >> Would it be better to just install the .json files?  Is it time to
> >> finally bite the bullet and figure out how to get rid of duplication by
> >> dropping qmp-commands.hx, and instead listing example usage directly in
> >> the qapi-schema.json file?  I'm not sure if we have a good plan in place
> >> for user-facing documentation, even if the move to events-as-QAPI was
> >> desirable.
> > 
> > My original plan was to generate qmp-commands.txt & qmp-evets.txt from
> > the schema file(s). I'm not sure if the .json files are consumable to
> > non-qemu/libvirt developers. If you think they are then I'd be fine with
> > installing them.
> 
> The .json files are what _I_ refer to (but I'm probably biased, since
> I've become a vested partner in the json files in the meantime); for
> someone encountering the docs with no prior experience, I'm not sure how
> much value-added the qmp-commands.txt was providing.
> 
> > 
> > Wrt the examples, my only concern about having them in the schema is
> > that the examples are in QMP format but in the past we were also planning
> > on having C support via libqmp. If what we have today is what matters,
> > then we can just move the examples to the schema files.
> 
> Putting the examples in the .json files also comes with its own
> interesting issues - do you prefix every line with # comment markers (so
> the examples are no longer copy-paste, but now copy-paste-modify)? Or do
> we do it as top-level JSON elements, perhaps via a new item that the
> generators ignore but which a doc conversion tool could consume?  Maybe:
> { 'example': {
>   'client':
>     {"command": {"foo", "arguments": { "hello": "world" } } },
>   'server':
>     {"reply": {} }
> } }
> 
> Michal's hack at least ensures that we have event documentation, even if
> the format changed compared to the 2.0 docs, and even if we don't have
> time to get something better in place before 2.1 goes out.  So all of
> this conversation on ways to do better is nice, but if we don't get
> there quickly, I could at least live with Michal's patch in the short term.

I honestly don't know what's the best thing to do here. I can live with
this patch too, although having some introductory comments at the top of
the file saying what it is would be nicer.

Re: [Qemu-devel] [PATCH] Makefile: Install qmp-events.txt

[Paolo Bonzini]

Il 26/06/2014 14:46, Luiz Capitulino ha scritto:
>> >
>> > Michal's hack at least ensures that we have event documentation, even if
>> > the format changed compared to the 2.0 docs, and even if we don't have
>> > time to get something better in place before 2.1 goes out.  So all of
>> > this conversation on ways to do better is nice, but if we don't get
>> > there quickly, I could at least live with Michal's patch in the short term.
> I honestly don't know what's the best thing to do here. I can live with
> this patch too, although having some introductory comments at the top of
> the file saying what it is would be nicer.

Can we just revert to the pre-conversion qmp-events.txt file?  This is 
similar to the situation with qmp-commands.hx.

Paolo

Re: [Qemu-devel] [PATCH] Makefile: Install qmp-events.txt

[Eric Blake]

[-- Attachment #1: Type: text/plain, Size: 1446 bytes --]

On 06/26/2014 07:01 AM, Paolo Bonzini wrote:
> Il 26/06/2014 14:46, Luiz Capitulino ha scritto:
>>> >
>>> > Michal's hack at least ensures that we have event documentation,
>>> even if
>>> > the format changed compared to the 2.0 docs, and even if we don't have
>>> > time to get something better in place before 2.1 goes out.  So all of
>>> > this conversation on ways to do better is nice, but if we don't get
>>> > there quickly, I could at least live with Michal's patch in the
>>> short term.
>> I honestly don't know what's the best thing to do here. I can live with
>> this patch too, although having some introductory comments at the top of
>> the file saying what it is would be nicer.
> 
> Can we just revert to the pre-conversion qmp-events.txt file?  This is
> similar to the situation with qmp-commands.hx.

As in, carrying redundant information between two files?  True that it's
no worse than qmp-commands.hx; it would also ensure we aren't regressing
on quality of user documentation in relation to prior releases.  We
could do the restore of that file, but if we do, we should fix the bugs
in pre-conversion qmp-events.txt (a couple events were undocumented,
there were some grammar errors, all fixed as part of the conversion), as
well as document events that have been added post-conversion.

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


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 604 bytes --]

Re: [Qemu-devel] [PATCH] Makefile: Install qmp-events.txt

[Paolo Bonzini]

Il 26/06/2014 15:11, Eric Blake ha scritto:
>> >
>> > Can we just revert to the pre-conversion qmp-events.txt file?  This is
>> > similar to the situation with qmp-commands.hx.
> As in, carrying redundant information between two files?  True that it's
> no worse than qmp-commands.hx; it would also ensure we aren't regressing
> on quality of user documentation in relation to prior releases.  We
> could do the restore of that file, but if we do, we should fix the bugs
> in pre-conversion qmp-events.txt (a couple events were undocumented,
> there were some grammar errors, all fixed as part of the conversion), as
> well as document events that have been added post-conversion.

No events were added post-conversion, since ACPI_DEVICE_OST first went 
in under the old scheme and Luiz then applied the conversion patch when 
he did the rebase.

We're really close to hard freeze and by extension the release.  Do 
_not_ strive for perfection.  Get something that is mostly okay and is 
an obvious patch.  We'll then have 3 weeks to do documentation patches.

Paolo

Re: [Qemu-devel] [PATCH] Makefile: Install qmp-events.txt

[Luiz Capitulino]

On Thu, 26 Jun 2014 15:14:01 +0200
Paolo Bonzini <pbonzini@redhat.com> wrote:

> Il 26/06/2014 15:11, Eric Blake ha scritto:
> >> >
> >> > Can we just revert to the pre-conversion qmp-events.txt file?  This is
> >> > similar to the situation with qmp-commands.hx.
> > As in, carrying redundant information between two files?  True that it's
> > no worse than qmp-commands.hx; it would also ensure we aren't regressing
> > on quality of user documentation in relation to prior releases.  We
> > could do the restore of that file, but if we do, we should fix the bugs
> > in pre-conversion qmp-events.txt (a couple events were undocumented,
> > there were some grammar errors, all fixed as part of the conversion), as
> > well as document events that have been added post-conversion.
> 
> No events were added post-conversion, since ACPI_DEVICE_OST first went 
> in under the old scheme and Luiz then applied the conversion patch when 
> he did the rebase.
> 
> We're really close to hard freeze and by extension the release.  Do 
> _not_ strive for perfection.  Get something that is mostly okay and is 
> an obvious patch.  We'll then have 3 weeks to do documentation patches.

The hard freeze argument is a strong one, but my understanding was that
we wanted to move away from duplicated information. So reverting is a
step back.

Any strong objections against this patch?

Re: [Qemu-devel] [PATCH] Makefile: Install qmp-events.txt

[Paolo Bonzini]

Il 26/06/2014 15:17, Luiz Capitulino ha scritto:
>> > We're really close to hard freeze and by extension the release.  Do
>> > _not_ strive for perfection.  Get something that is mostly okay and is
>> > an obvious patch.  We'll then have 3 weeks to do documentation patches.
> The hard freeze argument is a strong one, but my understanding was that
> we wanted to move away from duplicated information. So reverting is a
> step back.

We sure want to move away from duplicated information.  However, at this 
point we are actively _dropping_ information compared to qmp-events.txt 
(the examples).

Considering that QEMU releases rarely add more than 1 event(*), the 
amount of duplicated work caused by qmp-events.txt is trivial for the 
foreseeable future.

Of course, the obvious steps to do things "right" are:

- automatically generate HTML/DocBook/Texinfo documentation from .json

- install the automatically-generated documentation

- move examples from qmp-events.txt and qmp-commands.hx to the .json

- when qmp-events.txt and qmp-commands.hx are entirely duplicate, kill them

But this requires manpower, of course.

Paolo

(*)    Version         Events introduced
        0.12.0                5
        0.13.0                5
        0.14.0                3
        0.15.0                0
        1.0                   0
        1.1                   2
        1.2                   2
        1.3                   1
        1.4                   0
        1.5                   1
        1.6                   1
        1.7                   0
        2.0                   1
        2.1                   1

[Qemu-devel] [PATCH] qmp: add qmp-events.txt back

[Luiz Capitulino]

On Thu, 26 Jun 2014 15:25:33 +0200
Paolo Bonzini <pbonzini@redhat.com> wrote:

> Il 26/06/2014 15:17, Luiz Capitulino ha scritto:
> >> > We're really close to hard freeze and by extension the release.  Do
> >> > _not_ strive for perfection.  Get something that is mostly okay and is
> >> > an obvious patch.  We'll then have 3 weeks to do documentation patches.
> > The hard freeze argument is a strong one, but my understanding was that
> > we wanted to move away from duplicated information. So reverting is a
> > step back.
> 
> We sure want to move away from duplicated information.  However, at this 
> point we are actively _dropping_ information compared to qmp-events.txt 
> (the examples).

Fair enough. Here goes the patch. As each commit dropped a section of the
file, it was easier just to re-add it. ACKs wanted.

Subject: [PATCH] qmp: add qmp-events.txt back

The conversion of events to the QAPI, resulted in the removal of the
docs/qmp/qmp-events.txt file. This was done to avoid having duplicated
information between qmp-events.txt and qapi-event.json.

However, qmp-events.txt contains examples and we're still not sure
how to proper install QAPI docs in the host. To avoid harming users,
it's better to re-add qmp-events.txt for now and deal with the
duplication later.

Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
---
 docs/qmp/qmp-events.txt | 551 ++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 551 insertions(+)
 create mode 100644 docs/qmp/qmp-events.txt

diff --git a/docs/qmp/qmp-events.txt b/docs/qmp/qmp-events.txt
new file mode 100644
index 0000000..22fea58
--- /dev/null
+++ b/docs/qmp/qmp-events.txt
@@ -0,0 +1,551 @@
+                   QEMU Machine Protocol Events
+                   ============================
+
+ACPI_DEVICE_OST
+---------------
+
+Emitted when guest executes ACPI _OST method.
+
+ - data: ACPIOSTInfo type as described in qapi-schema.json
+
+{ "event": "ACPI_DEVICE_OST",
+     "data": { "device": "d1", "slot": "0", "slot-type": "DIMM", "source": 1, "status": 0 } }
+
+BALLOON_CHANGE
+--------------
+
+Emitted when the guest changes the actual BALLOON level. This
+value is equivalent to the 'actual' field return by the
+'query-balloon' command
+
+Data:
+
+- "actual": actual level of the guest memory balloon in bytes (json-number)
+
+Example:
+
+{ "event": "BALLOON_CHANGE",
+    "data": { "actual": 944766976 },
+    "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
+
+BLOCK_IMAGE_CORRUPTED
+---------------------
+
+Emitted when a disk image is being marked corrupt.
+
+Data:
+
+- "device": Device name (json-string)
+- "msg":    Informative message (e.g., reason for the corruption) (json-string)
+- "offset": If the corruption resulted from an image access, this is the access
+            offset into the image (json-int)
+- "size":   If the corruption resulted from an image access, this is the access
+            size (json-int)
+
+Example:
+
+{ "event": "BLOCK_IMAGE_CORRUPTED",
+    "data": { "device": "ide0-hd0",
+        "msg": "Prevented active L1 table overwrite", "offset": 196608,
+        "size": 65536 },
+    "timestamp": { "seconds": 1378126126, "microseconds": 966463 } }
+
+BLOCK_IO_ERROR
+--------------
+
+Emitted when a disk I/O error occurs.
+
+Data:
+
+- "device": device name (json-string)
+- "operation": I/O operation (json-string, "read" or "write")
+- "action": action that has been taken, it's one of the following (json-string):
+    "ignore": error has been ignored
+    "report": error has been reported to the device
+    "stop": the VM is going to stop because of the error
+
+Example:
+
+{ "event": "BLOCK_IO_ERROR",
+    "data": { "device": "ide0-hd1",
+              "operation": "write",
+              "action": "stop" },
+    "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
+
+Note: If action is "stop", a STOP event will eventually follow the
+BLOCK_IO_ERROR event.
+
+BLOCK_JOB_CANCELLED
+-------------------
+
+Emitted when a block job has been cancelled.
+
+Data:
+
+- "type":     Job type (json-string; "stream" for image streaming
+                                     "commit" for block commit)
+- "device":   Device name (json-string)
+- "len":      Maximum progress value (json-int)
+- "offset":   Current progress value (json-int)
+              On success this is equal to len.
+              On failure this is less than len.
+- "speed":    Rate limit, bytes per second (json-int)
+
+Example:
+
+{ "event": "BLOCK_JOB_CANCELLED",
+     "data": { "type": "stream", "device": "virtio-disk0",
+               "len": 10737418240, "offset": 134217728,
+               "speed": 0 },
+     "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
+
+BLOCK_JOB_COMPLETED
+-------------------
+
+Emitted when a block job has completed.
+
+Data:
+
+- "type":     Job type (json-string; "stream" for image streaming
+                                     "commit" for block commit)
+- "device":   Device name (json-string)
+- "len":      Maximum progress value (json-int)
+- "offset":   Current progress value (json-int)
+              On success this is equal to len.
+              On failure this is less than len.
+- "speed":    Rate limit, bytes per second (json-int)
+- "error":    Error message (json-string, optional)
+              Only present on failure.  This field contains a human-readable
+              error message.  There are no semantics other than that streaming
+              has failed and clients should not try to interpret the error
+              string.
+
+Example:
+
+{ "event": "BLOCK_JOB_COMPLETED",
+     "data": { "type": "stream", "device": "virtio-disk0",
+               "len": 10737418240, "offset": 10737418240,
+               "speed": 0 },
+     "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
+
+BLOCK_JOB_ERROR
+---------------
+
+Emitted when a block job encounters an error.
+
+Data:
+
+- "device": device name (json-string)
+- "operation": I/O operation (json-string, "read" or "write")
+- "action": action that has been taken, it's one of the following (json-string):
+    "ignore": error has been ignored, the job may fail later
+    "report": error will be reported and the job canceled
+    "stop": error caused job to be paused
+
+Example:
+
+{ "event": "BLOCK_JOB_ERROR",
+    "data": { "device": "ide0-hd1",
+              "operation": "write",
+              "action": "stop" },
+    "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
+
+BLOCK_JOB_READY
+---------------
+
+Emitted when a block job is ready to complete.
+
+Data:
+
+- "device": device name (json-string)
+
+Example:
+
+{ "event": "BLOCK_JOB_READY",
+    "data": { "device": "ide0-hd1" },
+    "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
+
+Note: The "ready to complete" status is always reset by a BLOCK_JOB_ERROR
+event.
+
+DEVICE_DELETED
+--------------
+
+Emitted whenever the device removal completion is acknowledged
+by the guest.
+At this point, it's safe to reuse the specified device ID.
+Device removal can be initiated by the guest or by HMP/QMP commands.
+
+Data:
+
+- "device": device name (json-string, optional)
+- "path": device path (json-string)
+
+{ "event": "DEVICE_DELETED",
+  "data": { "device": "virtio-net-pci-0",
+            "path": "/machine/peripheral/virtio-net-pci-0" },
+  "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
+
+DEVICE_TRAY_MOVED
+-----------------
+
+It's emitted whenever the tray of a removable device is moved by the guest
+or by HMP/QMP commands.
+
+Data:
+
+- "device": device name (json-string)
+- "tray-open": true if the tray has been opened or false if it has been closed
+               (json-bool)
+
+{ "event": "DEVICE_TRAY_MOVED",
+  "data": { "device": "ide1-cd0",
+            "tray-open": true
+  },
+  "timestamp": { "seconds": 1265044230, "microseconds": 450486 } }
+
+GUEST_PANICKED
+--------------
+
+Emitted when guest OS panic is detected.
+
+Data:
+
+- "action": Action that has been taken (json-string, currently always "pause").
+
+Example:
+
+{ "event": "GUEST_PANICKED",
+     "data": { "action": "pause" } }
+
+NIC_RX_FILTER_CHANGED
+---------------------
+
+The event is emitted once until the query command is executed,
+the first event will always be emitted.
+
+Data:
+
+- "name": net client name (json-string)
+- "path": device path (json-string)
+
+{ "event": "NIC_RX_FILTER_CHANGED",
+  "data": { "name": "vnet0",
+            "path": "/machine/peripheral/vnet0/virtio-backend" },
+  "timestamp": { "seconds": 1368697518, "microseconds": 326866 } }
+}
+
+QUORUM_FAILURE
+--------------
+
+Emitted by the Quorum block driver if it fails to establish a quorum.
+
+Data:
+
+- "reference":    device name if defined else node name.
+- "sector-num":   Number of the first sector of the failed read operation.
+- "sector-count": Failed read operation sector count.
+
+Example:
+
+{ "event": "QUORUM_FAILURE",
+     "data": { "reference": "usr1", "sector-num": 345435, "sector-count": 5 },
+     "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
+
+QUORUM_REPORT_BAD
+-----------------
+
+Emitted to report a corruption of a Quorum file.
+
+Data:
+
+- "error":        Error message (json-string, optional)
+                  Only present on failure.  This field contains a human-readable
+                  error message.  There are no semantics other than that the
+                  block layer reported an error and clients should not try to
+                  interpret the error string.
+- "node-name":    The graph node name of the block driver state.
+- "sector-num":   Number of the first sector of the failed read operation.
+- "sector-count": Failed read operation sector count.
+
+Example:
+
+{ "event": "QUORUM_REPORT_BAD",
+     "data": { "node-name": "1.raw", "sector-num": 345435, "sector-count": 5 },
+     "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
+
+RESET
+-----
+
+Emitted when the Virtual Machine is reseted.
+
+Data: None.
+
+Example:
+
+{ "event": "RESET",
+    "timestamp": { "seconds": 1267041653, "microseconds": 9518 } }
+
+RESUME
+------
+
+Emitted when the Virtual Machine resumes execution.
+
+Data: None.
+
+Example:
+
+{ "event": "RESUME",
+    "timestamp": { "seconds": 1271770767, "microseconds": 582542 } }
+
+RTC_CHANGE
+----------
+
+Emitted when the guest changes the RTC time.
+
+Data:
+
+- "offset": Offset between base RTC clock (as specified by -rtc base), and
+new RTC clock value (json-number)
+
+Example:
+
+{ "event": "RTC_CHANGE",
+    "data": { "offset": 78 },
+    "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
+
+SHUTDOWN
+--------
+
+Emitted when the Virtual Machine is powered down.
+
+Data: None.
+
+Example:
+
+{ "event": "SHUTDOWN",
+    "timestamp": { "seconds": 1267040730, "microseconds": 682951 } }
+
+Note: If the command-line option "-no-shutdown" has been specified, a STOP
+event will eventually follow the SHUTDOWN event.
+
+SPICE_CONNECTED, SPICE_DISCONNECTED
+-----------------------------------
+
+Emitted when a SPICE client connects or disconnects.
+
+Data:
+
+- "server": Server information (json-object)
+  - "host": IP address (json-string)
+  - "port": port number (json-string)
+  - "family": address family (json-string, "ipv4" or "ipv6")
+- "client": Client information (json-object)
+  - "host": IP address (json-string)
+  - "port": port number (json-string)
+  - "family": address family (json-string, "ipv4" or "ipv6")
+
+Example:
+
+{ "timestamp": {"seconds": 1290688046, "microseconds": 388707},
+  "event": "SPICE_CONNECTED",
+  "data": {
+    "server": { "port": "5920", "family": "ipv4", "host": "127.0.0.1"},
+    "client": {"port": "52873", "family": "ipv4", "host": "127.0.0.1"}
+}}
+
+SPICE_INITIALIZED
+-----------------
+
+Emitted after initial handshake and authentication takes place (if any)
+and the SPICE channel is up'n'running
+
+Data:
+
+- "server": Server information (json-object)
+  - "host": IP address (json-string)
+  - "port": port number (json-string)
+  - "family": address family (json-string, "ipv4" or "ipv6")
+  - "auth": authentication method (json-string, optional)
+- "client": Client information (json-object)
+  - "host": IP address (json-string)
+  - "port": port number (json-string)
+  - "family": address family (json-string, "ipv4" or "ipv6")
+  - "connection-id": spice connection id.  All channels with the same id
+                     belong to the same spice session (json-int)
+  - "channel-type": channel type.  "1" is the main control channel, filter for
+                    this one if you want track spice sessions only (json-int)
+  - "channel-id": channel id.  Usually "0", might be different needed when
+                  multiple channels of the same type exist, such as multiple
+                  display channels in a multihead setup (json-int)
+  - "tls": whevener the channel is encrypted (json-bool)
+
+Example:
+
+{ "timestamp": {"seconds": 1290688046, "microseconds": 417172},
+  "event": "SPICE_INITIALIZED",
+  "data": {"server": {"auth": "spice", "port": "5921",
+                      "family": "ipv4", "host": "127.0.0.1"},
+           "client": {"port": "49004", "family": "ipv4", "channel-type": 3,
+                      "connection-id": 1804289383, "host": "127.0.0.1",
+                      "channel-id": 0, "tls": true}
+}}
+
+STOP
+----
+
+Emitted when the Virtual Machine is stopped.
+
+Data: None.
+
+Example:
+
+{ "event": "STOP",
+    "timestamp": { "seconds": 1267041730, "microseconds": 281295 } }
+
+SUSPEND
+-------
+
+Emitted when guest enters S3 state.
+
+Data: None.
+
+Example:
+
+{ "event": "SUSPEND",
+     "timestamp": { "seconds": 1344456160, "microseconds": 309119 } }
+
+SUSPEND_DISK
+------------
+
+Emitted when the guest makes a request to enter S4 state.
+
+Data: None.
+
+Example:
+
+{ "event": "SUSPEND_DISK",
+     "timestamp": { "seconds": 1344456160, "microseconds": 309119 } }
+
+Note: QEMU shuts down when entering S4 state.
+
+VNC_CONNECTED
+-------------
+
+Emitted when a VNC client establishes a connection.
+
+Data:
+
+- "server": Server information (json-object)
+  - "host": IP address (json-string)
+  - "service": port number (json-string)
+  - "family": address family (json-string, "ipv4" or "ipv6")
+  - "auth": authentication method (json-string, optional)
+- "client": Client information (json-object)
+  - "host": IP address (json-string)
+  - "service": port number (json-string)
+  - "family": address family (json-string, "ipv4" or "ipv6")
+
+Example:
+
+{ "event": "VNC_CONNECTED",
+    "data": {
+        "server": { "auth": "sasl", "family": "ipv4",
+                    "service": "5901", "host": "0.0.0.0" },
+        "client": { "family": "ipv4", "service": "58425",
+                    "host": "127.0.0.1" } },
+    "timestamp": { "seconds": 1262976601, "microseconds": 975795 } }
+
+
+Note: This event is emitted before any authentication takes place, thus
+the authentication ID is not provided.
+
+VNC_DISCONNECTED
+----------------
+
+Emitted when the connection is closed.
+
+Data:
+
+- "server": Server information (json-object)
+  - "host": IP address (json-string)
+  - "service": port number (json-string)
+  - "family": address family (json-string, "ipv4" or "ipv6")
+  - "auth": authentication method (json-string, optional)
+- "client": Client information (json-object)
+  - "host": IP address (json-string)
+  - "service": port number (json-string)
+  - "family": address family (json-string, "ipv4" or "ipv6")
+  - "x509_dname": TLS dname (json-string, optional)
+  - "sasl_username": SASL username (json-string, optional)
+
+Example:
+
+{ "event": "VNC_DISCONNECTED",
+    "data": {
+        "server": { "auth": "sasl", "family": "ipv4",
+                    "service": "5901", "host": "0.0.0.0" },
+        "client": { "family": "ipv4", "service": "58425",
+                    "host": "127.0.0.1", "sasl_username": "luiz" } },
+    "timestamp": { "seconds": 1262976601, "microseconds": 975795 } }
+
+VNC_INITIALIZED
+---------------
+
+Emitted after authentication takes place (if any) and the VNC session is
+made active.
+
+Data:
+
+- "server": Server information (json-object)
+  - "host": IP address (json-string)
+  - "service": port number (json-string)
+  - "family": address family (json-string, "ipv4" or "ipv6")
+  - "auth": authentication method (json-string, optional)
+- "client": Client information (json-object)
+  - "host": IP address (json-string)
+  - "service": port number (json-string)
+  - "family": address family (json-string, "ipv4" or "ipv6")
+  - "x509_dname": TLS dname (json-string, optional)
+  - "sasl_username": SASL username (json-string, optional)
+
+Example:
+
+{ "event": "VNC_INITIALIZED",
+    "data": {
+        "server": { "auth": "sasl", "family": "ipv4",
+                    "service": "5901", "host": "0.0.0.0"},
+        "client": { "family": "ipv4", "service": "46089",
+                    "host": "127.0.0.1", "sasl_username": "luiz" } },
+        "timestamp": { "seconds": 1263475302, "microseconds": 150772 } }
+
+WAKEUP
+------
+
+Emitted when the guest has woken up from S3 and is running.
+
+Data: None.
+
+Example:
+
+{ "event": "WAKEUP",
+     "timestamp": { "seconds": 1344522075, "microseconds": 745528 } }
+
+WATCHDOG
+--------
+
+Emitted when the watchdog device's timer is expired.
+
+Data:
+
+- "action": Action that has been taken, it's one of the following (json-string):
+            "reset", "shutdown", "poweroff", "pause", "debug", or "none"
+
+Example:
+
+{ "event": "WATCHDOG",
+     "data": { "action": "reset" },
+     "timestamp": { "seconds": 1267061043, "microseconds": 959568 } }
+
+Note: If action is "reset", "shutdown", or "pause" the WATCHDOG event is
+followed respectively by the RESET, SHUTDOWN, or STOP events.
-- 
1.9.3

Re: [Qemu-devel] [PATCH] qmp: add qmp-events.txt back

[Paolo Bonzini]

Il 26/06/2014 15:43, Luiz Capitulino ha scritto:
> diff --git a/docs/qmp/qmp-events.txt b/docs/qmp/qmp-events.txt
> new file mode 100644
> index 0000000..22fea58

22fea58 was indeed the hash of the file before the first conversion 
patch ("qapi event: convert SHUTDOWN").

Reviewed-by: Paolo Bonzini <pbonzini@redhat.com>

Re: [Qemu-devel] [PATCH] Makefile: Install qmp-events.txt

[Eric Blake]

[-- Attachment #1: Type: text/plain, Size: 2192 bytes --]

On 06/26/2014 07:25 AM, Paolo Bonzini wrote:
> Il 26/06/2014 15:17, Luiz Capitulino ha scritto:
>>> > We're really close to hard freeze and by extension the release.  Do
>>> > _not_ strive for perfection.  Get something that is mostly okay and is
>>> > an obvious patch.  We'll then have 3 weeks to do documentation
>>> patches.
>> The hard freeze argument is a strong one, but my understanding was that
>> we wanted to move away from duplicated information. So reverting is a
>> step back.
> 
> We sure want to move away from duplicated information.  However, at this
> point we are actively _dropping_ information compared to qmp-events.txt
> (the examples).
> 
> Considering that QEMU releases rarely add more than 1 event(*), the
> amount of duplicated work caused by qmp-events.txt is trivial for the
> foreseeable future.

Actually, there is a second new event on queue right now:
https://lists.gnu.org/archive/html/qemu-devel/2014-06/msg06561.html

> 
> Of course, the obvious steps to do things "right" are:
> 
> - automatically generate HTML/DocBook/Texinfo documentation from .json
> 
> - install the automatically-generated documentation
> 
> - move examples from qmp-events.txt and qmp-commands.hx to the .json
> 
> - when qmp-events.txt and qmp-commands.hx are entirely duplicate, kill them
> 
> But this requires manpower, of course.

Sadly, manpower is more frequently devoted to code than to documentation
improvements.

> 
> Paolo
> 
> (*)    Version         Events introduced
>        0.12.0                5
>        0.13.0                5
>        0.14.0                3
>        0.15.0                0
>        1.0                   0
>        1.1                   2
>        1.2                   2
>        1.3                   1
>        1.4                   0
>        1.5                   1
>        1.6                   1
>        1.7                   0
>        2.0                   1
>        2.1                   1

So depending on Laszlo's series, we may be adding 2 events in 2.1.

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


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 604 bytes --]

Re: [Qemu-devel] [PATCH] Makefile: Install qmp-events.txt

[Paolo Bonzini]

Il 26/06/2014 18:25, Eric Blake ha scritto:
> Actually, there is a second new event on queue right now:
> https://lists.gnu.org/archive/html/qemu-devel/2014-06/msg06561.html

Ok.  FWIW, I consider that series a bugfix so it can go in after hard 
freeze.  Same for the patch that lets management reconstruct the last 
RTC_TIME_CHANGE event.

Paolo

Re: [Qemu-devel] [PATCH] qmp: add qmp-events.txt back

[Eric Blake]

[-- Attachment #1: Type: text/plain, Size: 1580 bytes --]

On 06/26/2014 07:43 AM, Luiz Capitulino wrote:

> Fair enough. Here goes the patch. As each commit dropped a section of the
> file, it was easier just to re-add it. ACKs wanted.
> 
> Subject: [PATCH] qmp: add qmp-events.txt back
> 
> The conversion of events to the QAPI, resulted in the removal of the
> docs/qmp/qmp-events.txt file. This was done to avoid having duplicated
> information between qmp-events.txt and qapi-event.json.
> 
> However, qmp-events.txt contains examples and we're still not sure
> how to proper install QAPI docs in the host. To avoid harming users,
> it's better to re-add qmp-events.txt for now and deal with the
> duplication later.

We'll need some followup patches to fix typos, missing events, and such
to be in parallel with the schema; but a straight revive of the file to
the pre-conversion state is the easiest starting point for those followups.

> 
> Signed-off-by: Luiz Capitulino <lcapitulino@redhat.com>
> ---
>  docs/qmp/qmp-events.txt | 551 ++++++++++++++++++++++++++++++++++++++++++++++++
>  1 file changed, 551 insertions(+)
>  create mode 100644 docs/qmp/qmp-events.txt
> 
> diff --git a/docs/qmp/qmp-events.txt b/docs/qmp/qmp-events.txt
> new file mode 100644
> index 0000000..22fea58

I'm happy that this is a straight revive, based on the output of
 git ls-tree 506f40ff:docs/qmp/
 git show 506f40ff  # patch 1 of the conversion series

Reviewed-by: Eric Blake <eblake@redhat.com>


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


[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 604 bytes --]