Skip to contentSkip to conversation

conformance: clarify transitional/non-transitional

PATCH Superseded Michael S. Tsirkin 3 participants 5 messages Mar 11, 2019 – Mar 12, 2019

v3 of 4 Superseded Latest is v4 →

lore
Share & tools
lore
#0 lore raw

PATCH v3 1/1 conformance: clarify transitional/non-transitional

Clarify that:
- non-transitional just satisfy 3 main clauses
- transitional also has a legacy interface:
however note that it's not an optional component *for transitional devices* so MAY is inappropriate
- legacy device descriptions are non-normative. In fact virtio 0.9 is non-normative as a whole and always was by design: it was early days and spec evolved to document bugs in implementations.

VIRTIO-167

---

Changes from v1:
address remaining comments by Cornelia
Changes from v1:
address comments by Cornelia

 conformance.tex | 26 ++++++++++++++++++--------
 1 file changed, 18 insertions(+), 8 deletions(-)
conformance.tex +18 -8
index 1577c0c..c0df2a2 100644
@@ -344,16 +344,26 @@ Interface: Terminology}.
 
 A non-transitional implementation conforms to this specification
 if it satisfies all of the MUST or REQUIRED level requirements
-defined above.
+defined in section \ref{sec:Conformance / Conformance Targets} above.
 
-An implementation MAY choose to implement OPTIONAL support for the
-legacy interface, including support for legacy drivers
-or devices, by additionally conforming to all of the MUST or
-REQUIRED level requirements for the legacy interface
-for the transitional devices and drivers.
+A transitional implementation conforms to this specification
+if it satisfies all of the MUST or REQUIRED level requirements
+defined in section \ref{sec:Conformance / Conformance Targets} above
+and additionally implements the legacy interface
+for devices and drivers, described in
+\hyperref[intro:Virtio PCI Draft]{[Virtio PCI Draft]}.
 
-The requirements for the legacy interface for transitional implementations
-are located in sections named ``Legacy Interface'' listed below:
+\begin{note}
+No normative specification for the legacy interface exists,
+instead the ability of the device or the driver to inter-operate
+with the existing body of devices and drivers is a quality of
+implementation issue.
+\end{note}
+
+To facilitate creating transitional implementations, as well as
+to assist in converting legacy interfaces to conforming ones,
+the requirements for the legacy interface for transitional implementations
+are located in non-normative sections named ``Legacy Interface'' listed below:
 \begin{itemize}
 \item Section \ref{sec:Basic Facilities of a Virtio Device /
 Feature Bits / Legacy Interface: A Note on Feature Bits}
Signature · 6 lines
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 
Reviewed-by on v3 1/1
#1 lore raw
Quoted 15 lines · On Mon, 11 Mar 2019 12:00:46 -0400 "Michael S. Tsirkin" <[email protected]> wrote:

Clarify that:
- non-transitional just satisfy 3 main clauses
- transitional also has a legacy interface:
however note that it's not an optional component *for transitional devices* so MAY is inappropriate
- legacy device descriptions are non-normative. In fact virtio 0.9 is non-normative as a whole and always was by design: it was early days and spec evolved to document bugs in implementations.

VIRTIO-167

---

Quoted 8 lines

Changes from v1:
address remaining comments by Cornelia
Changes from v1:
address comments by Cornelia

 conformance.tex | 26 ++++++++++++++++++--------
 1 file changed, 18 insertions(+), 8 deletions(-)

---------------------------------------------------------------------
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

#2 lore raw
In reply to Michael S. Tsirkin
Quoted 28 lines · On Mon, 11 Mar 2019 12:00:46 -0400 "Michael S. Tsirkin" <[email protected]> wrote:

Clarify that:
- non-transitional just satisfy 3 main clauses
- transitional also has a legacy interface:
however note that it's not an optional component *for transitional devices* so MAY is inappropriate
- legacy device descriptions are non-normative. In fact virtio 0.9 is non-normative as a whole and always was by design: it was early days and spec evolved to document bugs in implementations.

VIRTIO-167

---

Changes from v1:
address remaining comments by Cornelia
Changes from v1:
address comments by Cornelia

 conformance.tex | 26 ++++++++++++++++++--------
 1 file changed, 18 insertions(+), 8 deletions(-)
conformance.tex +0 -0
index 1577c0c..c0df2a2 100644

conformance.tex Interface: Terminology}. · line 347

Quoted 5 lines
conformance.tex +1 -1
@@ -344,16 +344,26 @@ Interface: Terminology}.
 
 A non-transitional implementation conforms to this specification
 if it satisfies all of the MUST or REQUIRED level requirements
-defined above.
+defined in section \ref{sec:Conformance / Conformance Targets} above.

I think 'above' is superfluous.

conformance.tex Interface: Terminology}. · line 351

Quoted 9 lines
conformance.tex +3 -5
-An implementation MAY choose to implement OPTIONAL support for the
-legacy interface, including support for legacy drivers
-or devices, by additionally conforming to all of the MUST or
-REQUIRED level requirements for the legacy interface
-for the transitional devices and drivers.
+A transitional implementation conforms to this specification
+if it satisfies all of the MUST or REQUIRED level requirements
+defined in section \ref{sec:Conformance / Conformance Targets} above

I would prefer 'above' dropped, but no biggie.

conformance.tex Interface: Terminology}. · line 361

Quoted 12 lines
conformance.tex +9 -2
+and additionally implements the legacy interface
+for devices and drivers, described in
+\hyperref[intro:Virtio PCI Draft]{[Virtio PCI Draft]}.
 
-The requirements for the legacy interface for transitional implementations
-are located in sections named ``Legacy Interface'' listed below:
+\begin{note}
+No normative specification for the legacy interface exists,
+instead the ability of the device or the driver to inter-operate
+with the existing body of devices and drivers is a quality of
+implementation issue.
+\end{note}

I don't like 'existing body of devices and drivers' because IMHO this is only about legacy devices and drivers. I.e. an implementation that conforms to this specification (or a previous version of this specification) is guaranteed to be inter-operable.

conformance.tex Interface: Terminology}. · line 366

Quoted 5 lines
conformance.tex +5 -0
+
+To facilitate creating transitional implementations, as well as
+to assist in converting legacy interfaces to conforming ones,
+the requirements for the legacy interface for transitional implementations
+are located in non-normative sections named ``Legacy Interface'' listed below:

I have a hard time to tell if this change makes transitional vs non-transitional clearer or not.

I think there is a dissonance between 'no normative specification for the legacy interface exists' and 'transitional implementation conforms to this specification if ...'.

The latter suggests that based on this specification and the referenced draft together do provide, what is necessary to decide if a given implementation is a transitional implementation that conforms to this specification.

The former suggests that only the non-transitional, i.e. virtio conforming, part of the transitional device is actually well specified. Please note that the non-normative sections do contain constructs that are normally reserved for normative statements (e.g. MUST).

AFAIU a transitional implementation is any implementation that is conforming to this specification and aims to provide some inter-operability with some legacy implementations that do not conform this specification. A non-transitional implementation is an implementation that is conforms to this specification and does not care about inter-operability with implementation that don not conform to this specification.

I think people familiar with virtio already have a good understanding of transitional and non-transitional. Because of this I'm going to abstain on this.

Regards,
Halil

---------------------------------------------------------------------
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

#3 lore raw
Quoted 99 lines · Halil Pasic
Quoted 28 lines · On Mon, 11 Mar 2019 12:00:46 -0400 "Michael S. Tsirkin" <[email protected]> wrote:

Clarify that:
- non-transitional just satisfy 3 main clauses
- transitional also has a legacy interface:
however note that it's not an optional component *for transitional devices* so MAY is inappropriate
- legacy device descriptions are non-normative. In fact virtio 0.9 is non-normative as a whole and always was by design: it was early days and spec evolved to document bugs in implementations.

VIRTIO-167

---

Changes from v1:
address remaining comments by Cornelia
Changes from v1:
address comments by Cornelia

 conformance.tex | 26 ++++++++++++++++++--------
 1 file changed, 18 insertions(+), 8 deletions(-)
conformance.tex +0 -0
index 1577c0c..c0df2a2 100644

conformance.tex Interface: Terminology}. · line 347

Quoted 5 lines
conformance.tex +1 -1
@@ -344,16 +344,26 @@ Interface: Terminology}.
 
 A non-transitional implementation conforms to this specification
 if it satisfies all of the MUST or REQUIRED level requirements
-defined above.
+defined in section \ref{sec:Conformance / Conformance Targets} above.

I think 'above' is superfluous.

conformance.tex Interface: Terminology}. · line 351

Quoted 9 lines
conformance.tex +3 -5
-An implementation MAY choose to implement OPTIONAL support for the
-legacy interface, including support for legacy drivers
-or devices, by additionally conforming to all of the MUST or
-REQUIRED level requirements for the legacy interface
-for the transitional devices and drivers.
+A transitional implementation conforms to this specification
+if it satisfies all of the MUST or REQUIRED level requirements
+defined in section \ref{sec:Conformance / Conformance Targets} above

I would prefer 'above' dropped, but no biggie.

conformance.tex Interface: Terminology}. · line 361

Quoted 12 lines
conformance.tex +9 -2
+and additionally implements the legacy interface
+for devices and drivers, described in
+\hyperref[intro:Virtio PCI Draft]{[Virtio PCI Draft]}.
 
-The requirements for the legacy interface for transitional implementations
-are located in sections named ``Legacy Interface'' listed below:
+\begin{note}
+No normative specification for the legacy interface exists,
+instead the ability of the device or the driver to inter-operate
+with the existing body of devices and drivers is a quality of
+implementation issue.
+\end{note}

I don't like 'existing body of devices and drivers' because IMHO this is only about legacy devices and drivers. I.e. an implementation that conforms to this specification (or a previous version of this specification) is guaranteed to be inter-operable.

conformance.tex Interface: Terminology}. · line 366

Quoted 5 lines
conformance.tex +5 -0
+
+To facilitate creating transitional implementations, as well as
+to assist in converting legacy interfaces to conforming ones,
+the requirements for the legacy interface for transitional implementations
+are located in non-normative sections named ``Legacy Interface'' listed below:

I have a hard time to tell if this change makes transitional vs non-transitional clearer or not.

I think there is a dissonance between 'no normative specification for the legacy interface exists' and 'transitional implementation conforms to this specification if ...'.

The latter suggests that based on this specification and the referenced draft together do provide, what is necessary to decide if a given implementation is a transitional implementation that conforms to this specification.

The former suggests that only the non-transitional, i.e. virtio conforming, part of the transitional device is actually well specified. Please note that the non-normative sections do contain constructs that are normally reserved for normative statements (e.g. MUST). AFAIU a transitional implementation is any implementation that is conforming to this specification and aims to provide some inter-operability with some legacy implementations that do not conform this specification. A non-transitional implementation is an implementation that is conforms to this specification and does not care about inter-operability with implementation that don not conform to this specification.

Quoted 6 lines

I think people familiar with virtio already have a good understanding of transitional and non-transitional. Because of this I'm going to abstain on this.

Regards,
Halil

OK I'm convinced, I've send v2 which is a much smaller change. Pls review that before I start another ballot.

Signature · 6 lines
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 
#4 lore raw
Quoted 1 line · On Tue, 12 Mar 2019 12:04:39 -0400 "Michael S. Tsirkin" <[email protected]> wrote:

On Tue, Mar 12, 2019 at 04:00:41PM +0100, Halil Pasic wrote:

[..]

Quoted 7 lines
Quoted 3 lines

Regards,
Halil

OK I'm convinced, I've send v2 which is a much smaller change. Pls review that before I start another ballot.

Sure. I had some vacation and my email reading was degraded, but I'm back starting today.

Regards,
Halil

---------------------------------------------------------------------
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