Re: [RFC PATCH 2/5] hw/misc/led: Add LED_STATUS_CHANGED QAPI event

[Markus Armbruster <armbru@redhat.com>]

Markus Armbruster <armbru@redhat.com> writes:

> Philippe Mathieu-Daudé <f4bug@amsat.org> writes:
[...]
>> Commits f544d174dfc and 7f1e7b23d5 refers to the qmp-events.txt
>> for documentation on rate-limiting QMP events, but I can't find
>> it in the codebase. Two files matches 'qmp-events' but don't have
>> documentation: qapi/qmp-event.c and include/qapi/qmp-event.h.
>>
>> Last trace of it is in commit 231aaf3a8217. Apparently it was
>> somehow split qapi/event.json, then later c09656f1d392 move it
>> to qapi-schema.json, finally eb815e248f50 moved it to qapi/.
>>
>> Is the referred documentation now in docs/devel/qapi-code-gen.txt?
>> There is only one occurence of 'limit' but it is unrelated to
>> rate-limit.
>
> Commit 231aaf3a8217 is part of Marc-André's herculean QAPI/QMP doc
> reorganization: use only schema doc comments instead of spreading the
> knowledge over schema and several other files, with duplicated contents,
> confused readers, and annoyed writers.
>
> Before the reorganization, docs/qmp-events.txt listed the QMP events,
> and rate-limited events carried a
>
>     Note: this event is rate-limited.
>
> The reorganization moved this note into its event's doc comment.
> Example:
>
>     ##
>     # @WATCHDOG:
>     #
>     # Emitted when the watchdog device's timer is expired
>     #
>     # @action: action that has been taken
>     #
>     # Note: If action is "reset", "shutdown", or "pause" the WATCHDOG event is
>     #       followed respectively by the RESET, SHUTDOWN, or STOP events
>     #
> --> # Note: This event is rate-limited.
>     #
>     [...]
>     ##
>     { 'event': 'WATCHDOG',
>       'data': { 'action': 'WatchdogAction' } }
>
> The QMP *protocol* is still documented in docs/interop/qmp-spec.txt.
> Relevant part:
>
>     2.5 Asynchronous events
>     -----------------------
>
>     As a result of state changes, the Server may send messages unilaterally
>     to the Client at any time, when not in the middle of any other
>     response. They are called "asynchronous events".
>
>     The format of asynchronous events is:
>
>     { "event": json-string, "data": json-object,
>       "timestamp": { "seconds": json-number, "microseconds": json-number } }
>
>      Where,
>
>     - The "event" member contains the event's name
>     - The "data" member contains event specific data, which is defined in a
>       per-event basis, it is optional
>     - The "timestamp" member contains the exact time of when the event
>       occurred in the Server. It is a fixed json-object with time in
>       seconds and microseconds relative to the Unix Epoch (1 Jan 1970); if
>       there is a failure to retrieve host time, both members of the
>       timestamp will be set to -1.
>
>     For a listing of supported asynchronous events, please, refer to the
>     qmp-events.txt file.
>
>     Some events are rate-limited to at most one per second.  If additional
>     "similar" events arrive within one second, all but the last one are
>     dropped, and the last one is delayed.  "Similar" normally means same
>     event type.  See qmp-events.txt for details.
>
> The reorganization neglected to update it for the removal of
> qmp-events.txt.  Should point to
> docs/interop/qemu-qmp-ref.{7,html,info,pdf,txt} now.
>
> Event rate-limiting is defined in monitor_qapi_event_conf[].  To
> rate-limit an event, add it to monitor_qapi_event_conf[], and also add
> the "Note: This event is rate-limited." to its schema doc comment.
>
> Doc bug: commit e2ae6159de "virtio-serial: report frontend connection
> state via monitor" neglected to add the note.
>
> Patches welcome!

Subject: [PATCH 1/3] docs/interop/qmp-spec: Point to the QEMU QMP reference manual
Message-Id: <20200806081147.3123652-2-armbru@redhat.com>

Subject: [PATCH 2/3] qapi: Document event VSERPORT_CHANGE is rate-limited
Message-Id: <20200806081147.3123652-3-armbru@redhat.com>