[PATCH 0/2] qapi: Move RTC_CHANGE back out of target schema

[PATCH 0/2] qapi: Move RTC_CHANGE back out of target schema

[Peter Maydell]

This patchset moves RTC_CHANGE back to misc.json, effectively
reverting commit 183e4281a30962, which moved the RTC_CHANGE event to
the target schema.  That change was an attempt to make the event
target-specific to improve introspection, but the event isn't really
target-specific: it's machine or device specific.  Putting RTC_CHANGE
in the target schema with an ifdef list reduces maintainability (by
adding an if: list with a long list of targets that needs to be
manually updated as architectures are added or removed or as new
devices gain the RTC_CHANGE functionality) and increases compile time
(by preventing RTC devices which emit the event from being "compile
once" rather than "compile once per target", because
qapi-events-misc-target.h uses TARGET_* ifdefs, which are poisoned in
"compile once" files.)

Patch 2 fixes a minor documentation issue that I noticed while
I was doing this -- we didn't document that the units used in
the RTC_CHANGE event are seconds.

thanks
-- PMM

Peter Maydell (2):
  qapi: Move RTC_CHANGE back out of target schema
  qapi: Document the units for the offset argument to RTC_CHANGE

 qapi/misc-target.json | 33 ---------------------------------
 qapi/misc.json        | 22 ++++++++++++++++++++++
 hw/ppc/spapr_rtc.c    |  2 +-
 hw/rtc/mc146818rtc.c  |  2 +-
 4 files changed, 24 insertions(+), 35 deletions(-)

-- 
2.20.1

[PATCH 1/2] qapi: Move RTC_CHANGE back out of target schema

[Peter Maydell]

This commit effectively reverts commit 183e4281a30962, which moved
the RTC_CHANGE event to the target schema.  That change was an
attempt to make the event target-specific to improve introspection,
but the event isn't really target-specific: it's machine or device
specific.  Putting RTC_CHANGE in the target schema with an ifdef list
reduces maintainability (by adding an if: list with a long list of
targets that needs to be manually updated as architectures are added
or removed or as new devices gain the RTC_CHANGE functionality) and
increases compile time (by preventing RTC devices which emit the
event from being "compile once" rather than "compile once per
target", because qapi-events-misc-target.h uses TARGET_* ifdefs,
which are poisoned in "compile once" files.)

Move RTC_CHANGE back to misc.json.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
 qapi/misc-target.json | 33 ---------------------------------
 qapi/misc.json        | 22 ++++++++++++++++++++++
 hw/ppc/spapr_rtc.c    |  2 +-
 hw/rtc/mc146818rtc.c  |  2 +-
 4 files changed, 24 insertions(+), 35 deletions(-)

diff --git a/qapi/misc-target.json b/qapi/misc-target.json
index 3b05ad3dbfb..f442421e838 100644
--- a/qapi/misc-target.json
+++ b/qapi/misc-target.json
@@ -2,39 +2,6 @@
 # vim: filetype=python
 #
 
-##
-# @RTC_CHANGE:
-#
-# Emitted when the guest changes the RTC time.
-#
-# @offset: offset between base RTC clock (as specified by -rtc base), and
-#          new RTC clock value
-#
-# Note: This event is rate-limited.
-#
-# Since: 0.13
-#
-# Example:
-#
-# <-   { "event": "RTC_CHANGE",
-#        "data": { "offset": 78 },
-#        "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
-#
-##
-{ 'event': 'RTC_CHANGE',
-  'data': { 'offset': 'int' },
-  'if': { 'any': [ 'TARGET_ALPHA',
-                   'TARGET_ARM',
-                   'TARGET_HPPA',
-                   'TARGET_I386',
-                   'TARGET_MIPS',
-                   'TARGET_MIPS64',
-                   'TARGET_PPC',
-                   'TARGET_PPC64',
-                   'TARGET_S390X',
-                   'TARGET_SH4',
-                   'TARGET_SPARC' ] } }
-
 ##
 # @rtc-reset-reinjection:
 #
diff --git a/qapi/misc.json b/qapi/misc.json
index 5c2ca3b5566..ce7edd3f7bf 100644
--- a/qapi/misc.json
+++ b/qapi/misc.json
@@ -523,3 +523,25 @@
  'data': { '*option': 'str' },
  'returns': ['CommandLineOptionInfo'],
  'allow-preconfig': true }
+
+##
+# @RTC_CHANGE:
+#
+# Emitted when the guest changes the RTC time.
+#
+# @offset: offset between base RTC clock (as specified by -rtc base), and
+#          new RTC clock value
+#
+# Note: This event is rate-limited.
+#
+# Since: 0.13
+#
+# Example:
+#
+# <-   { "event": "RTC_CHANGE",
+#        "data": { "offset": 78 },
+#        "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
+#
+##
+{ 'event': 'RTC_CHANGE',
+  'data': { 'offset': 'int' } }
diff --git a/hw/ppc/spapr_rtc.c b/hw/ppc/spapr_rtc.c
index fba4dfca358..7a185d45400 100644
--- a/hw/ppc/spapr_rtc.c
+++ b/hw/ppc/spapr_rtc.c
@@ -32,7 +32,7 @@
 #include "hw/ppc/spapr.h"
 #include "migration/vmstate.h"
 #include "qapi/error.h"
-#include "qapi/qapi-events-misc-target.h"
+#include "qapi/qapi-events-misc.h"
 #include "qemu/cutils.h"
 #include "qemu/module.h"
 
diff --git a/hw/rtc/mc146818rtc.c b/hw/rtc/mc146818rtc.c
index 4fbafddb226..5ecf96142a1 100644
--- a/hw/rtc/mc146818rtc.c
+++ b/hw/rtc/mc146818rtc.c
@@ -40,7 +40,7 @@
 #include "hw/rtc/mc146818rtc_regs.h"
 #include "migration/vmstate.h"
 #include "qapi/error.h"
-#include "qapi/qapi-events-misc-target.h"
+#include "qapi/qapi-events-misc.h"
 #include "qapi/visitor.h"
 #include "hw/rtc/mc146818rtc_regs.h"
 
-- 
2.20.1

[PATCH 2/2] qapi: Document the units for the offset argument to RTC_CHANGE

[Peter Maydell]

The RTC_CHANGE event's offset argument is in units of seconds;
document this.

Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
---
 qapi/misc.json | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/qapi/misc.json b/qapi/misc.json
index ce7edd3f7bf..10b4eee16b3 100644
--- a/qapi/misc.json
+++ b/qapi/misc.json
@@ -529,8 +529,8 @@
 #
 # Emitted when the guest changes the RTC time.
 #
-# @offset: offset between base RTC clock (as specified by -rtc base), and
-#          new RTC clock value
+# @offset: offset in seconds between base RTC clock (as specified
+#          by -rtc base), and new RTC clock value
 #
 # Note: This event is rate-limited.
 #
-- 
2.20.1

Re: [PATCH 1/2] qapi: Move RTC_CHANGE back out of target schema

[Greg Kurz]

On Fri, 24 Sep 2021 15:01:41 +0100
Peter Maydell <peter.maydell@linaro.org> wrote:

> This commit effectively reverts commit 183e4281a30962, which moved
> the RTC_CHANGE event to the target schema.  That change was an
> attempt to make the event target-specific to improve introspection,
> but the event isn't really target-specific: it's machine or device
> specific.  Putting RTC_CHANGE in the target schema with an ifdef list
> reduces maintainability (by adding an if: list with a long list of
> targets that needs to be manually updated as architectures are added
> or removed or as new devices gain the RTC_CHANGE functionality) and
> increases compile time (by preventing RTC devices which emit the
> event from being "compile once" rather than "compile once per
> target", because qapi-events-misc-target.h uses TARGET_* ifdefs,
> which are poisoned in "compile once" files.)
> 
> Move RTC_CHANGE back to misc.json.
> 
> Signed-off-by: Peter Maydell <peter.maydell@linaro.org>
> ---

For the ppc part,

Acked-by: Greg Kurz <groug@kaod.org>

>  qapi/misc-target.json | 33 ---------------------------------
>  qapi/misc.json        | 22 ++++++++++++++++++++++
>  hw/ppc/spapr_rtc.c    |  2 +-
>  hw/rtc/mc146818rtc.c  |  2 +-
>  4 files changed, 24 insertions(+), 35 deletions(-)
> 
> diff --git a/qapi/misc-target.json b/qapi/misc-target.json
> index 3b05ad3dbfb..f442421e838 100644
> --- a/qapi/misc-target.json
> +++ b/qapi/misc-target.json
> @@ -2,39 +2,6 @@
>  # vim: filetype=python
>  #
>  
> -##
> -# @RTC_CHANGE:
> -#
> -# Emitted when the guest changes the RTC time.
> -#
> -# @offset: offset between base RTC clock (as specified by -rtc base), and
> -#          new RTC clock value
> -#
> -# Note: This event is rate-limited.
> -#
> -# Since: 0.13
> -#
> -# Example:
> -#
> -# <-   { "event": "RTC_CHANGE",
> -#        "data": { "offset": 78 },
> -#        "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
> -#
> -##
> -{ 'event': 'RTC_CHANGE',
> -  'data': { 'offset': 'int' },
> -  'if': { 'any': [ 'TARGET_ALPHA',
> -                   'TARGET_ARM',
> -                   'TARGET_HPPA',
> -                   'TARGET_I386',
> -                   'TARGET_MIPS',
> -                   'TARGET_MIPS64',
> -                   'TARGET_PPC',
> -                   'TARGET_PPC64',
> -                   'TARGET_S390X',
> -                   'TARGET_SH4',
> -                   'TARGET_SPARC' ] } }
> -
>  ##
>  # @rtc-reset-reinjection:
>  #
> diff --git a/qapi/misc.json b/qapi/misc.json
> index 5c2ca3b5566..ce7edd3f7bf 100644
> --- a/qapi/misc.json
> +++ b/qapi/misc.json
> @@ -523,3 +523,25 @@
>   'data': { '*option': 'str' },
>   'returns': ['CommandLineOptionInfo'],
>   'allow-preconfig': true }
> +
> +##
> +# @RTC_CHANGE:
> +#
> +# Emitted when the guest changes the RTC time.
> +#
> +# @offset: offset between base RTC clock (as specified by -rtc base), and
> +#          new RTC clock value
> +#
> +# Note: This event is rate-limited.
> +#
> +# Since: 0.13
> +#
> +# Example:
> +#
> +# <-   { "event": "RTC_CHANGE",
> +#        "data": { "offset": 78 },
> +#        "timestamp": { "seconds": 1267020223, "microseconds": 435656 } }
> +#
> +##
> +{ 'event': 'RTC_CHANGE',
> +  'data': { 'offset': 'int' } }
> diff --git a/hw/ppc/spapr_rtc.c b/hw/ppc/spapr_rtc.c
> index fba4dfca358..7a185d45400 100644
> --- a/hw/ppc/spapr_rtc.c
> +++ b/hw/ppc/spapr_rtc.c
> @@ -32,7 +32,7 @@
>  #include "hw/ppc/spapr.h"
>  #include "migration/vmstate.h"
>  #include "qapi/error.h"
> -#include "qapi/qapi-events-misc-target.h"
> +#include "qapi/qapi-events-misc.h"
>  #include "qemu/cutils.h"
>  #include "qemu/module.h"
>  
> diff --git a/hw/rtc/mc146818rtc.c b/hw/rtc/mc146818rtc.c
> index 4fbafddb226..5ecf96142a1 100644
> --- a/hw/rtc/mc146818rtc.c
> +++ b/hw/rtc/mc146818rtc.c
> @@ -40,7 +40,7 @@
>  #include "hw/rtc/mc146818rtc_regs.h"
>  #include "migration/vmstate.h"
>  #include "qapi/error.h"
> -#include "qapi/qapi-events-misc-target.h"
> +#include "qapi/qapi-events-misc.h"
>  #include "qapi/visitor.h"
>  #include "hw/rtc/mc146818rtc_regs.h"
>  

Re: [PATCH 0/2] qapi: Move RTC_CHANGE back out of target schema

[Markus Armbruster]

Peter Maydell <peter.maydell@linaro.org> writes:

> This patchset moves RTC_CHANGE back to misc.json, effectively
> reverting commit 183e4281a30962, which moved the RTC_CHANGE event to
> the target schema.  That change was an attempt to make the event
> target-specific to improve introspection, but the event isn't really
> target-specific: it's machine or device specific.  Putting RTC_CHANGE
> in the target schema with an ifdef list reduces maintainability (by
> adding an if: list with a long list of targets that needs to be
> manually updated as architectures are added or removed or as new
> devices gain the RTC_CHANGE functionality) and increases compile time
> (by preventing RTC devices which emit the event from being "compile
> once" rather than "compile once per target", because
> qapi-events-misc-target.h uses TARGET_* ifdefs, which are poisoned in
> "compile once" files.)
>
> Patch 2 fixes a minor documentation issue that I noticed while
> I was doing this -- we didn't document that the units used in
> the RTC_CHANGE event are seconds.

Series
Reviewed-by: Markus Armbruster <armbru@redhat.com>

An additional patch documenting that not all RTCs implement RTC_CHANGE
would be nice.  Listing them would be even nicer.

An additional patch adding @qom-path event argument would be nice.

Re: [PATCH 0/2] qapi: Move RTC_CHANGE back out of target schema

[Peter Maydell]

On Sat, 25 Sept 2021 at 08:44, Markus Armbruster <armbru@redhat.com> wrote:
>
> Peter Maydell <peter.maydell@linaro.org> writes:
>
> > This patchset moves RTC_CHANGE back to misc.json, effectively
> > reverting commit 183e4281a30962, which moved the RTC_CHANGE event to
> > the target schema.  That change was an attempt to make the event
> > target-specific to improve introspection, but the event isn't really
> > target-specific: it's machine or device specific.  Putting RTC_CHANGE
> > in the target schema with an ifdef list reduces maintainability (by
> > adding an if: list with a long list of targets that needs to be
> > manually updated as architectures are added or removed or as new
> > devices gain the RTC_CHANGE functionality) and increases compile time
> > (by preventing RTC devices which emit the event from being "compile
> > once" rather than "compile once per target", because
> > qapi-events-misc-target.h uses TARGET_* ifdefs, which are poisoned in
> > "compile once" files.)
> >
> > Patch 2 fixes a minor documentation issue that I noticed while
> > I was doing this -- we didn't document that the units used in
> > the RTC_CHANGE event are seconds.
>
> Series
> Reviewed-by: Markus Armbruster <armbru@redhat.com>

I realized that this patchset never got applied -- I think I was
expecting it to be picked up via a QAPI related tree, and then
it was a bit close to a release to be put in, or something.
Anyway, I'm going to resend it in a moment.

> An additional patch documenting that not all RTCs implement RTC_CHANGE
> would be nice.  Listing them would be even nicer.

I disagree that listing them would be nice -- the whole point of
the series is to avoid having lists that get out of date when we
add a new RTC implementation or fix the missing-feature in an
existing one. I can add a sentence to the patch 2 docs change:
"Note that it is not guaranteed that the RTC in a system implements
this event, or even that the system has an RTC at all."

> An additional patch adding @qom-path event argument would be nice.

I don't understand what this would involve, so I'll leave it to you
if you want it.

thanks
-- PMM

Re: [PATCH 0/2] qapi: Move RTC_CHANGE back out of target schema

[Markus Armbruster]

Peter Maydell <peter.maydell@linaro.org> writes:

> On Sat, 25 Sept 2021 at 08:44, Markus Armbruster <armbru@redhat.com> wrote:
>>
>> Peter Maydell <peter.maydell@linaro.org> writes:
>>
>> > This patchset moves RTC_CHANGE back to misc.json, effectively
>> > reverting commit 183e4281a30962, which moved the RTC_CHANGE event to
>> > the target schema.  That change was an attempt to make the event
>> > target-specific to improve introspection, but the event isn't really
>> > target-specific: it's machine or device specific.  Putting RTC_CHANGE
>> > in the target schema with an ifdef list reduces maintainability (by
>> > adding an if: list with a long list of targets that needs to be
>> > manually updated as architectures are added or removed or as new
>> > devices gain the RTC_CHANGE functionality) and increases compile time
>> > (by preventing RTC devices which emit the event from being "compile
>> > once" rather than "compile once per target", because
>> > qapi-events-misc-target.h uses TARGET_* ifdefs, which are poisoned in
>> > "compile once" files.)
>> >
>> > Patch 2 fixes a minor documentation issue that I noticed while
>> > I was doing this -- we didn't document that the units used in
>> > the RTC_CHANGE event are seconds.
>>
>> Series
>> Reviewed-by: Markus Armbruster <armbru@redhat.com>
>
> I realized that this patchset never got applied -- I think I was
> expecting it to be picked up via a QAPI related tree, and then
> it was a bit close to a release to be put in, or something.
> Anyway, I'm going to resend it in a moment.

Want me to take care of merging v2?

>> An additional patch documenting that not all RTCs implement RTC_CHANGE
>> would be nice.  Listing them would be even nicer.
>
> I disagree that listing them would be nice -- the whole point of
> the series is to avoid having lists that get out of date when we
> add a new RTC implementation or fix the missing-feature in an
> existing one. I can add a sentence to the patch 2 docs change:
> "Note that it is not guaranteed that the RTC in a system implements
> this event, or even that the system has an RTC at all."

For a user, "you can rely on RTC_CHANGE with RTCs x, y, z provided by
machines a, b, c" is definitely nicer than "RTC_CHANGE may or may not
work, good luck", which is in turn nicer than nothing at all.

I think you're arguing for being as nice to users as we can without
having to pay for it in maintenance, which is fair.

>> An additional patch adding @qom-path event argument would be nice.
>
> I don't understand what this would involve, so I'll leave it to you
> if you want it.

Okay.