"Michael S. Tsirkin" <[email protected]> writes:
> On Mon, Mar 06, 2023 at 01:53:50PM +0000, David Edmondson wrote:
>> "Michael S. Tsirkin" <[email protected]> writes:
>>
>> > Feature negotiation forms the basis of forward compatibility
>> > guarantees of virtio but has never been properly documented.
>> > Do it now.
>> >
>> > Suggested-by: Halil Pasic <[email protected]>
>> > Signed-off-by: Michael S. Tsirkin <[email protected]>
>> > ---
>> > content.tex | 42 ++++++++++++++++++++++++++++++++++++++++++
>> > 1 file changed, 42 insertions(+)
>> >
>> > diff --git a/content.tex b/content.tex
>> > index 0e474dd..0c2d917 100644
>> > --- a/content.tex
>> > +++ b/content.tex
>> > @@ -114,21 +114,63 @@ \section{Feature Bits}\label{sec:Basic Facilities of
>> > a Virtio Device / Feature B
>> > In particular, new fields in the device configuration space are
>> > indicated by offering a new feature bit.
>> >
>> > +To keep the feature negotiation mechanism extensible, it is important
>> > +that devices \em{do not} offer any feature bits that they would not be
>> > +able to handle if the driver accepted them (even though drivers are not
>> > +supposed to accept them in the first place even if offered, according to
>> > +this version of the specification.)
>>
>> I find this (the bit in parenthesis) confusing.
>>
>> Why are drivers not supposed to accept features that they have been
>> offered, given that they can't know that the device cannot handle the
>> feature that it just offered?
>>
>> Is this alluding to the later section:
>>
>> > feature bits not described in this specification, reserved feature
>> > bits and feature bits reserved or not supported for the specific
>> > transport or the specific device type
>>
>> ?
>
> exactly. how would you put this better? given an example?
Perhaps it would be enough to say:
> (even though drivers are not supposed to accept unrecognised features in
> the first place even if offered, according to the specification)
"Unrecognised" is intended as a shorthand for the whole "not described,
reserved, ...". Maybe "unrecognised or reserved"?
>> > Likewise, it is important that
>> > +drivers \em{do not} accept feature bits they do not know how to handle
>> > +(even though devices are not supposed to offer them in the first place,
>> > +according to this version of the specification.) The preferred way for
>> > +handling reserved and unexpected features is that the driver ignores
>> > +them.
>> > +
>> > +In particular, this is
>> > +especially important for features limited to specific transports,
>> > +as enabling these for more transports in future versions of the
>> > +specification is highly likely to require changing the behaviour
>> > +from drivers and devices.
>>
>> "require changed behaviour from drivers and devices".
>>
>> > Drivers and devices supporting
>> > +multiple transports need to carefully maintain per-transport
>> > +lists of allowed features.
>> > +
>> > \drivernormative{\subsection}{Feature Bits}{Basic Facilities of a Virtio
>> > Device / Feature Bits}
>> > The driver MUST NOT accept a feature which the device did not offer,
>> > and MUST NOT accept a feature which requires another feature which was
>> > not accepted.
>> >
>> > +The driver MUST validate the feature bits offered by the device.
>> > +The driver MUST ignore and MUST NOT accept any feature bit that is
>> > +\begin{itemize}
>> > +\item not described in this specification,
>> > +\item marked as reserved,
>> > +\item not supported for the specific transport,
>> > +\item not defined for the device type.
>> > +\end{itemize}
>> > +
>> > The driver SHOULD go into backwards compatibility mode
>> > if the device does not offer a feature it understands, otherwise MUST
>> > set the FAILED \field{device status} bit and cease initialization.
>> >
>> > +By contrast, the driver MUST NOT fail solely because a feature
>> > +it does not understand has been offered by the device.
>> > +
>> > \devicenormative{\subsection}{Feature Bits}{Basic Facilities of a Virtio
>> > Device / Feature Bits}
>> > The device MUST NOT offer a feature which requires another feature
>> > which was not offered. The device SHOULD accept any valid subset
>> > of features the driver accepts, otherwise it MUST fail to set the
>> > FEATURES_OK \field{device status} bit when the driver writes it.
>> >
>> > +The device MUST NOT offer feature bits corresponding to features
>> > +it would not support if accepted by the driver (even if the
>> > +driver is prohibited from accepting the feature bits by the
>> > +specification); for the sake of clarity, this refers to feature
>> > +bits not described in this specification, reserved feature bits
>> > +and feature bits reserved or not supported for the specific
>> > +transport or the specific device type, but this does not preclude
>> > +devices written to a future version of this specification from
>> > +offering such feature bits should such a specification have a
>> > +provision for devices to support the corresponding features.
>> > +
>> > If a device has successfully negotiated a set of features
>> > at least once (by accepting the FEATURES_OK \field{device
>> > status} bit during device initialization), then it SHOULD
>> > --
>> > MST
>> >
>> >
>> > ---------------------------------------------------------------------
>> > To unsubscribe from this mail list, you must leave the OASIS TC that
>> > generates this mail. Follow this link to all your TCs in OASIS at:
>> > https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php
--
He caught a fleeting glimpse of a man, moving uphill pursued by a bus.
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
