Re: [PATCH v7 4/4] virtio-rtc: Add normative statements for alarm feature

[Matias Ezequiel Vara Larsen <mvaralar@redhat.com>]

On Tue, Feb 25, 2025 at 12:18:51PM +0100, Peter Hilber wrote:
> On Mon, Feb 24, 2025 at 01:13:46PM +0100, Matias Ezequiel Vara Larsen wrote:
> > On Thu, Feb 20, 2025 at 06:06:38PM +0100, Peter Hilber wrote:
> > > On Wed, Feb 19, 2025 at 04:36:14PM +0100, Matias Ezequiel Vara Larsen wrote:
> > > > On Thu, Feb 13, 2025 at 07:14:30PM +0100, Peter Hilber wrote:
> > > > > On Tue, Feb 11, 2025 at 01:33:42PM +0100, Matias Ezequiel Vara Larsen wrote:
> > > > > > On Thu, Jan 23, 2025 at 11:16:15AM +0100, Peter Hilber wrote:
> > > > > > > Add the normative statements for the alarm feature added previously.
> > > > > > > 
> > > > > > > Signed-off-by: Peter Hilber <quic_philber@quicinc.com>
> > > > > > > ---
> > > > > > > 
> > > > > > > Notes:
> > > > > > >     v7:
> > > > > > >     
> > > > > > >     - Remove inadvertent v6 changes, which should have been part of
> > > > > > >       preceding patches.
> > > > > > >     
> > > > > > >     v4:
> > > > > > >     
> > > > > > >     - Update normative statements to match v4 changes to non-normative
> > > > > > >       statements (patch 3).
> > > > > > >     
> > > > > > >     - Driver should read clock to confirm that alarm has expired.
> > > > > > >     
> > > > > > >     - Formatting and wording improvements.
> > > > > > > 
> > > > > > >  device-types/rtc/description.tex        | 157 ++++++++++++++++++++++++
> > > > > > >  device-types/rtc/device-conformance.tex |   4 +
> > > > > > >  device-types/rtc/driver-conformance.tex |   2 +
> > > > > > >  3 files changed, 163 insertions(+)
> > > > > > > 
> > > 
> > > [...]
> > > 
> > > > > > > +
> > > > > > > +If a clock C steps to a time previous to C's alarm time, the device MUST
> > > > > > > +stop serving any previous alarm expiration event for C, within a grace
> > > > > > > +period.
> > > > > > > +
> > > > > > > +If an alarm expiration event happens for clock C, the device MUST stop
> > > > > > > +serving any previous alarm expiration event for C, within a grace
> > > > > > > +period.
> > > > > > > +
> > > > > > > +If the device is currently serving an alarm expiration event E, the
> > > > > > > +device MUST send a single VIRTIO_RTC_NOTIF_ALARM notification for E, as
> > > > > > > +soon as an alarmq buffer is available for this purpose.
> > > > > > > +
> > > > > > > +While the device is serving an alarm expiration event, the device MAY
> > > > > > > +execute implementation-specific alarm actions.
> > > > > > > +
> > 
> > Does not `serving` mean also that the device execute
> > implementation-specific alarm actions?
> 
> As for `serving an alarm expiration event`, I intended this to be a
> speaking name for a state to which different requirements can refer.
> Maybe this was bad naming.
> 

I just though that `serving an alarm expiration event` could include
executing implementation-specific alarm actions so that we do not need
to make a separation of the two concepts. I do not have a strong opinion
so we can keep it as it is. 

> > Besides notifying the guest when
> > an alarm has expired, is not any other action or device behavior
> > implementation-specific and then not constrained by the spec?
> 
> So this would imply that the below MUST NOT requirement should not be
> adopted? I chose to refer to implementation-specific alarm actions so
> that 
> 
> 1) it is clear to any spec reader that alarms may work even when an
>    alarmq notification would not work and
> 
> 2) an implementation's documentation can usually refer to the spec as to
>    when the implementation-specific alarm actions may be executed.
> 
> I find the references helpful, but I do not have a strong opinion about
> keeping them in the normative or non-normative parts.
> 

I do not have a strong opinion either so we can keep it as it is.

Thanks, Matias.