[virtio-comment] TAB comments on Virtual I/O Device (VIRTIO) Version 1.1

[virtio-comment] TAB comments on Virtual I/O Device (VIRTIO) Version 1.1

[Patrick Durusau]

[-- Attachment #1.1.1: Type: text/plain, Size: 846 bytes --]

Greetings!

Members of the Technical Advisory Board endeavor to comment on all 30 day public review drafts.

Comments on: Virtual I/O Device (VIRTIO) Version 1.1 CS01 PRD01 are attached.

It isn't necessary to acknowledge each comment separately. A single email acknowledging this email will be sufficient.

When the TC has acted on these issues, I would appreciate a pointer to the TCs resolution as the TAB is tracking the resolution of comments from TAB members.

Hope everyone is having a great week!

Patrick

-- 
Patrick Durusau
patrick@durusau.net
Technical Advisory Board, OASIS (TAB)
Editor, OpenDocument Format TC (OASIS), Project Editor ISO/IEC 26300
Co-Editor, ISO/IEC 13250-1, 13250-5 (Topic Maps)

Another Word For It (blog): http://tm.durusau.net
Homepage: http://www.durusau.net
Twitter: patrickDurusau 


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #1.1.2: virtio-v1.1-21Feb2019.csv --]
[-- Type: text/csv; name="virtio-v1.1-21Feb2019.csv", Size: 11569 bytes --]

Issue key,Issue id,Affects Version/s,Issue Type,Custom field (Proposal),Description
TAB-1674,47718,Virtual I/O Device (VIRTIO) Version 1.1,Bug,Change bulleted lists into numbered lists and *always* introduce a list with the number of items to follow.,"Understanding and navigation of content is impaired by the use of bulleted lists. Compare for example, 2.7.21.1, being read aloud and being able to answer/find, where is your place in this list, as opposed to the second bulleted list in 2.7 Packed Virtqueues, or either of the lists/sub-lists in 2.6.10.1."
TAB-1673,47717,Virtual I/O Device (VIRTIO) Version 1.1,Bug,Devise and insert uniform start and end markers for examples.,"Most of the examples of memory structures being with struct but not all. Moreover, most examples end with }; but not all, for example, under 2.7.21.3.

My usual accessibility checker is offline but if you were reading the text aloud, if the start and end of examples is not uniformly signaled to someone hearing the text, the examples would be much harder to contrast with the surrounding normative text.

An accessibility issue  in general but also a personal one because after nearly 30 years as a diabetic my vision remains normal, but they can't promise how much longer that will be the case. Adding uniform start and end markers won't inconvenience sighted readers and will enhance access to your work for those using assistive technologies."
TAB-1672,47716,Virtual I/O Device (VIRTIO) Version 1.1,Bug,,"We read in 7.4:

""A non-transitional implementation conforms to this specification if it satisfies all of the MUST or REQUIRED level requirements defined above. ""

Is that true? ALL the ""MUST"" in all previous sections? Probably not. Or maybe it is ""below"" and not ""above"". (always explicitly refer to requirements sets by using a sub-section number & name)

I suggest to make ""transitional"" just a variable (i.e. a parameter) in previous top-level conf clauses. (see TAB conformance guideline [http://docs.oasis-open.org/templates/TCHandbook/ConformanceGuidelines.html, section 5.5) |http://docs.oasis-open.org/templates/TCHandbook/ConformanceGuidelines.html)]E.g. someone claiming conformance as ""PCI driver"" should always clarify: ""transitional PCI driver"" or ""non-transitional PCI driver"""
TAB-1671,47715,Virtual I/O Device (VIRTIO) Version 1.1,Bug,,"Each conformance clause sub-section starts with something that looks like a mandatory requirement:

e.g.:

""A network device MUST conform to the following normative statements:""

But many of the following statements are optional (SHOULD) in the specification body. So it is then confusing to say ""... MUST conform to a SHOULD statement....""

That is why it is NOT recommended to use normative language like MUST (and even less SHOULD) in a conformance clause. A conf clause is not there to tell you what to do or not do (MUST....), but only to state under which conditions you can claim conformance to XYZ.

It is better to say:

""an implementation that satisfies all mandatory (MUST) requirements in 5.1.4.1, 5.1.6.2.... qualifies (or may claim conformance) as a VIRTIO1.1 network device""

Or in some conformance profiles, you can override a SHOULD in the spec body and make it mandatory."
TAB-1670,47714,Virtual I/O Device (VIRTIO) Version 1.1,Bug,,"Sections 7.2.10 and 7.2.11 are never referred to, by any conformance clause. Same for 7.3.10 and 7.3.11.

That seems like an omission? They should be used in at least one conformance profile each. Or else, these sections should not be normative."
TAB-1669,47713,Virtual I/O Device (VIRTIO) Version 1.1,Bug,,"Overall, well-formed conformance section (one of the best we  TAB reviewers have seen!) The main conformance targets - drivers, devices - are well identified. The specification is clearly attributing normative requirements to either driver, or device.

Some conformance aspects could still be clarified:
 * All the subsections under 7.2 or 7.3 are named ""clauses"" in 7.1. So their titles should be ""Clause XYZ"". Or else if we want to keep ""CLause"" to only the top-level set of requirements - then define just a couple of clauses in 7.1, e.g. ""Conformance Clause for VIRTIO1.1 drivers"". Then all thee following subsections should just be titled ""Conformance requirements sets"" e.g. ""COnformance requirements for PCI drivers""), and preferably not ""clause"" (keeping ""clause"" for only  the full set of requirements that a product can claim for conformance).
 * In any case, it is good to associate a clear name to each conformance level/profile that can be claimed. For example, ""PCI network driver"" (if satisfying 7.2 + 7.2.1 + 7.2.4. Is that a meaningful combination? irt seems so according to 7.1). So that there is no ambiguity of what are the valid  conformance profiles. Some parameterization of a clause can be used: Look in TAB guideline : [http://docs.oasis-open.org/templates/TCHandbook/ConformanceGuidelines.html] for ""variable conformance clauses"" (section 5.5). In other words: define the precise statement that someone should use when claiming a conformance profile.

 "
TAB-1668,47707,Virtual I/O Device (VIRTIO) Version 1.1,Bug,"The accessibility site that I commonly use, [https://achecker.ca/checker/index.php,] is down tonight but use it to check your usage for other problems. 

 ","In terms of accessibility, ""what follows,"" ""below,"" and ""follows"" all inhibit the use of VIRTIO by users assisted by reading software.

Take 2.2 Feature Bits as an example:

""Feature bits are allocated as follows:

0 to 23 Feature bits for the specific device type

24 to 37 Feature bits reserved for extensions to the queue and feature negotiation mechanisms

38 and above Feature bits reserved for future extensions.""

A sighted reader is clued in that 3 entries follow, but reading software does not offer, in this form, the same clue.

Compare:

""Feature bits are allocated in three ways:

1. 0 to 23 Feature bits for the specific device type

2. 24 to 37 Feature bits reserved for extensions to the queue and feature negotiation mechanisms

3. 38 and above Feature bits reserved for future extensions.""

Same text but now both sighted as well as assisted readers know there are 3 ways to allocate feature bits and each of those ways is numbered and recited to the reader.

 

 

 "
TAB-1667,47706,Virtual I/O Device (VIRTIO) Version 1.1,Bug,Update the IEEE 802 link and re-check with [http://validator.w3.org/checklink],"|[IEEE 802] |IEEE Standard for Local and Metropolitan Area Networks: Overview and Architecture, 
[http://standards.ieee.org/about/get/802/802.html], IEEE|

reports a 404.

Did you mean: [https://standards.ieee.org/standard/802-2001.html]  ??"
TAB-1666,47705,Virtual I/O Device (VIRTIO) Version 1.1,Bug,Update the links indicated and re-check with http://validator.w3.org/checklink,"The link checker at [http://validator.w3.org/checklink] reports the following redirects:

!http://validator.w3.org/checklink/images/info_icons/warning.png! Line: 6875 [http://www.pcisig.com/] redirected to [http://pcisig.com/] *Status*: 301 -> 200 OK

This is a permanent redirect. The link should be updated.

!http://validator.w3.org/checklink/images/info_icons/warning.png! Lines: 55, 60, 63 [http://www.redhat.com/] redirected to [https://www.redhat.com/en] *Status*: 301 -> 200 OK

This is a permanent redirect. The link should be updated.

!http://validator.w3.org/checklink/images/info_icons/warning.png! Line: 21250 [http://git.qemu-project.org/?p=qemu.git;a=blob;f=docs/specs/standard-vga.txt;hb=HEAD] redirected to [https://git.qemu.org/?p=qemu.git;a=blob;f=docs/specs/standard-vga.txt;hb=HEAD] *Status*: 301 -> 200 OK

This is a permanent redirect. The link should be updated.

!http://validator.w3.org/checklink/images/info_icons/warning.png! Line: 768 [http://www.pcisig.com/specifications/pciexpress/] redirected to [http://pcisig.com/specifications/pciexpress/] *Status*: 301 -> 200 OK

This is a permanent redirect. The link should be updated.

!http://validator.w3.org/checklink/images/info_icons/warning.png! Line:  [https://www.oasis-open.org/policies-guidelines/tc-process] redirected to [https://www.oasis-open.org/policies-guidelines/tc-process-2017-05-26] *Status*: 301 -> 200 OK

This is a permanent redirect. The link should be updated.

!http://validator.w3.org/checklink/images/info_icons/warning.png! Line: 759 [http://www.pcisig.com/specifications/conventional/] redirected to [http://pcisig.com/specifications/conventional/] *Status*: 301 -> 200 OK

This is a permanent redirect. The link should be updated."
TAB-1665,47704,Virtual I/O Device (VIRTIO) Version 1.1,Bug,Number and label the in-memory structure illustrations and add anchors to enable remote pointing to particular illustrations.,"While I appreciate that the use of C struct syntax is illustrative only, the in-memory structures it documents are normative.

And in a number of cases, those in-memory structures occur in the same numbered section, making reference to any specified in-memory structure uncertain.

Labeling and numbering the in-memory structures (to say nothing of adding anchors for remote pointing), would greatly improve the usefulness of this document.

 "
TAB-1664,47703,Virtual I/O Device (VIRTIO) Version 1.1,Bug,"For consistency of presentation, the ""device and driver in-memory structure layouts"" should always follow descriptive prose in each section.","In 2.6.6, 2.6.8, 5.1.6.5.6.1, 5.7.4 (no prose at all), 5.7.6.7, 5.9.5, and 5.10.4, the ""device and driver in-memory structure layouts"" appear prior to any prose, which is different from the other sections. Was this a production, editorial or other type of error"
TAB-1663,47702,Virtual I/O Device (VIRTIO) Version 1.1,Bug,Recast the sentences in question to remove the hyphens and elsewhere when improperly used in sentences.,"In 2.5 Virtqueues, the ""-"" hyphen appears to be a common precursor to ""i.e."" and elsewhere in the second sentence of that section. By count there are only seven (7) cases of - i.e.

Given the care taken produce this work, it should not be marred by non-standard English usage such as this."
TAB-1662,47701,Virtual I/O Device (VIRTIO) Version 1.1,Bug,"""Device and driver in-memory structure layouts are documented using the C struct syntax.""","1.4 Structure Specifications begins with: ""Many device and driver in-memory structure layouts are documented using the C struct syntax.""

Many? Not all? Many leave it doubtful that some are defined.

Why not: ""Device and driver in-memory structure layouts are documented using the C struct syntax.""

If you are missing any, add them."
TAB-1661,47700,Virtual I/O Device (VIRTIO) Version 1.1,Bug,"Define marking of non-normative text and use it, quite possibly declare all notes non-normative (but check all of the notes first).","I'm assuming that 1 Introduction, your ""for example"" under 1.4 Structure Specifications, and at least some of the 62 Notes: are non-normative, but have not been so marked or described. That is you can use non-normative on a section heading and/or say: All notes are non-normative.

In particular I have in mind notes like: 4.1.5.1.2.1

""Note: For example, a device which does not expect to send interrupts at a high rate might only specify 2 MSI-X vectors.""

In terms of conformance to this specification, clearly non-normative language. As are many of the remaining 61 uses of note.

 "

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

Re: [virtio-comment] TAB comments on Virtual I/O Device (VIRTIO) Version 1.1

[Michael S. Tsirkin]

On Thu, Feb 21, 2019 at 05:36:51PM -0500, Patrick Durusau wrote:
> Greetings!
> 
> Members of the Technical Advisory Board endeavor to comment on all 30 day public review drafts.
> 
> Comments on: Virtual I/O Device (VIRTIO) Version 1.1 CS01 PRD01 are attached.
> 
> It isn't necessary to acknowledge each comment separately. A single email acknowledging this email will be sufficient.
> 
> When the TC has acted on these issues, I would appreciate a pointer to the TCs resolution as the TAB is tracking the resolution of comments from TAB members.
> 
> Hope everyone is having a great week!
> 
> Patrick


Thanks a lot for the comments!
I will try to split this CSV up and create github issues
so it is easier to address individual comments.




> -- 
> Patrick Durusau
> patrick@durusau.net
> Technical Advisory Board, OASIS (TAB)
> Editor, OpenDocument Format TC (OASIS), Project Editor ISO/IEC 26300
> Co-Editor, ISO/IEC 13250-1, 13250-5 (Topic Maps)
> 
> Another Word For It (blog): http://tm.durusau.net
> Homepage: http://www.durusau.net
> Twitter: patrickDurusau 
> 

> Issue key,Issue id,Affects Version/s,Issue Type,Custom field (Proposal),Description
> TAB-1674,47718,Virtual I/O Device (VIRTIO) Version 1.1,Bug,Change bulleted lists into numbered lists and *always* introduce a list with the number of items to follow.,"Understanding and navigation of content is impaired by the use of bulleted lists. Compare for example, 2.7.21.1, being read aloud and being able to answer/find, where is your place in this list, as opposed to the second bulleted list in 2.7 Packed Virtqueues, or either of the lists/sub-lists in 2.6.10.1."
> TAB-1673,47717,Virtual I/O Device (VIRTIO) Version 1.1,Bug,Devise and insert uniform start and end markers for examples.,"Most of the examples of memory structures being with struct but not all. Moreover, most examples end with }; but not all, for example, under 2.7.21.3.
> 
> My usual accessibility checker is offline but if you were reading the text aloud, if the start and end of examples is not uniformly signaled to someone hearing the text, the examples would be much harder to contrast with the surrounding normative text.
> 
> An accessibility issue?? in general but also a personal one because after nearly 30 years as a diabetic my vision remains normal, but they can't promise how much longer that will be the case. Adding uniform start and end markers won't inconvenience sighted readers and will enhance access to your work for those using assistive technologies."
> TAB-1672,47716,Virtual I/O Device (VIRTIO) Version 1.1,Bug,,"We read in 7.4:
> 
> ""A non-transitional implementation conforms to this specification if it satisfies all of the MUST or REQUIRED level requirements defined above. ""
> 
> Is that true? ALL the ""MUST"" in all previous sections? Probably not. Or maybe it is ""below"" and not ""above"". (always explicitly refer to requirements sets by using a sub-section number & name)
> 
> I suggest to make ""transitional"" just a variable (i.e. a parameter) in previous top-level conf clauses. (see TAB conformance guideline [http://docs.oasis-open.org/templates/TCHandbook/ConformanceGuidelines.html, section 5.5)??|http://docs.oasis-open.org/templates/TCHandbook/ConformanceGuidelines.html)]E.g. someone claiming conformance as ""PCI driver"" should always clarify: ""transitional PCI driver"" or ""non-transitional PCI driver"""
> TAB-1671,47715,Virtual I/O Device (VIRTIO) Version 1.1,Bug,,"Each conformance clause sub-section starts with something that looks like a mandatory requirement:
> 
> e.g.:
> 
> ""A network device MUST conform to the following normative statements:""
> 
> But many of the following statements are optional (SHOULD) in the specification body. So it is then confusing to say ""... MUST conform to a SHOULD statement....""
> 
> That is why it is NOT recommended to use normative language like MUST (and even less SHOULD) in a conformance clause. A conf clause is not there to tell you what to do or not do (MUST....), but only to state under which conditions you can claim conformance to XYZ.
> 
> It is better to say:
> 
> ""an implementation that satisfies all mandatory (MUST) requirements in 5.1.4.1, 5.1.6.2.... qualifies (or may claim conformance) as a VIRTIO1.1 network device""
> 
> Or in some conformance profiles, you can override a SHOULD in the spec body and make it mandatory."
> TAB-1670,47714,Virtual I/O Device (VIRTIO) Version 1.1,Bug,,"Sections 7.2.10 and 7.2.11 are never referred to, by any conformance clause. Same for 7.3.10 and 7.3.11.
> 
> That seems like an omission? They should be used in at least one conformance profile each. Or else, these sections should not be normative."
> TAB-1669,47713,Virtual I/O Device (VIRTIO) Version 1.1,Bug,,"Overall, well-formed conformance section (one of the best we?? TAB reviewers have seen!) The main conformance targets - drivers, devices - are well identified. The specification is clearly attributing normative requirements to either driver, or device.
> 
> Some conformance aspects could still be clarified:
>  * All the subsections under 7.2 or 7.3 are named ""clauses"" in 7.1. So their titles should be ""Clause XYZ"". Or else if we want to keep ""CLause"" to only the top-level set of requirements - then define just a couple of clauses in 7.1, e.g. ""Conformance Clause for VIRTIO1.1 drivers"". Then all thee following subsections should just be titled ""Conformance requirements sets"" e.g. ""COnformance requirements for PCI drivers""), and preferably not ""clause"" (keeping ""clause"" for only?? the full set of requirements that a product can claim for conformance).
>  * In any case, it is good to associate a clear name to each conformance level/profile that can be claimed. For example, ""PCI network driver"" (if satisfying 7.2 + 7.2.1 + 7.2.4. Is that a meaningful combination? irt seems so according to 7.1). So that there is no ambiguity of what are the valid?? conformance profiles. Some parameterization of a clause can be used: Look in TAB guideline : [http://docs.oasis-open.org/templates/TCHandbook/ConformanceGuidelines.html] for ""variable conformance clauses"" (section 5.5). In other words: define the precise statement that someone should use when claiming a conformance profile.
> 
> ??"
> TAB-1668,47707,Virtual I/O Device (VIRTIO) Version 1.1,Bug,"The accessibility site that I commonly use, [https://achecker.ca/checker/index.php,] is down tonight but use it to check your usage for other problems. 
> 
> ??","In terms of accessibility, ""what follows,"" ""below,"" and ""follows"" all inhibit the use of VIRTIO by users assisted by reading software.
> 
> Take 2.2 Feature Bits as an example:
> 
> ""Feature bits are allocated as follows:
> 
> 0 to 23 Feature bits for the specific device type
> 
> 24 to 37 Feature bits reserved for extensions to the queue and feature negotiation mechanisms
> 
> 38 and above Feature bits reserved for future extensions.""
> 
> A sighted reader is clued in that 3 entries follow, but reading software does not offer, in this form, the same clue.
> 
> Compare:
> 
> ""Feature bits are allocated in three ways:
> 
> 1. 0 to 23 Feature bits for the specific device type
> 
> 2. 24 to 37 Feature bits reserved for extensions to the queue and feature negotiation mechanisms
> 
> 3. 38 and above Feature bits reserved for future extensions.""
> 
> Same text but now both sighted as well as assisted readers know there are 3 ways to allocate feature bits and each of those ways is numbered and recited to the reader.
> 
> ??
> 
> ??
> 
> ??"
> TAB-1667,47706,Virtual I/O Device (VIRTIO) Version 1.1,Bug,Update the IEEE 802 link and re-check with [http://validator.w3.org/checklink],"|[IEEE 802] |IEEE Standard for Local and Metropolitan Area Networks: Overview and Architecture, 
> [http://standards.ieee.org/about/get/802/802.html], IEEE|
> 
> reports a 404.
> 
> Did you mean: [https://standards.ieee.org/standard/802-2001.html]?? ??"
> TAB-1666,47705,Virtual I/O Device (VIRTIO) Version 1.1,Bug,Update the links indicated and re-check with http://validator.w3.org/checklink,"The link checker at [http://validator.w3.org/checklink] reports the following redirects:
> 
> !http://validator.w3.org/checklink/images/info_icons/warning.png! Line: 6875 [http://www.pcisig.com/] redirected to [http://pcisig.com/] *Status*: 301 -> 200 OK
> 
> This is a permanent redirect. The link should be updated.
> 
> !http://validator.w3.org/checklink/images/info_icons/warning.png! Lines: 55, 60, 63 [http://www.redhat.com/] redirected to [https://www.redhat.com/en] *Status*: 301 -> 200 OK
> 
> This is a permanent redirect. The link should be updated.
> 
> !http://validator.w3.org/checklink/images/info_icons/warning.png! Line: 21250 [http://git.qemu-project.org/?p=qemu.git;a=blob;f=docs/specs/standard-vga.txt;hb=HEAD] redirected to [https://git.qemu.org/?p=qemu.git;a=blob;f=docs/specs/standard-vga.txt;hb=HEAD] *Status*: 301 -> 200 OK
> 
> This is a permanent redirect. The link should be updated.
> 
> !http://validator.w3.org/checklink/images/info_icons/warning.png! Line: 768 [http://www.pcisig.com/specifications/pciexpress/] redirected to [http://pcisig.com/specifications/pciexpress/] *Status*: 301 -> 200 OK
> 
> This is a permanent redirect. The link should be updated.
> 
> !http://validator.w3.org/checklink/images/info_icons/warning.png! Line:  [https://www.oasis-open.org/policies-guidelines/tc-process] redirected to [https://www.oasis-open.org/policies-guidelines/tc-process-2017-05-26] *Status*: 301 -> 200 OK
> 
> This is a permanent redirect. The link should be updated.
> 
> !http://validator.w3.org/checklink/images/info_icons/warning.png! Line: 759 [http://www.pcisig.com/specifications/conventional/] redirected to [http://pcisig.com/specifications/conventional/] *Status*: 301 -> 200 OK
> 
> This is a permanent redirect. The link should be updated."
> TAB-1665,47704,Virtual I/O Device (VIRTIO) Version 1.1,Bug,Number and label the in-memory structure illustrations and add anchors to enable remote pointing to particular illustrations.,"While I appreciate that the use of C struct syntax is illustrative only, the in-memory structures it documents are normative.
> 
> And in a number of cases, those in-memory structures occur in the same numbered section, making reference to any specified in-memory structure uncertain.
> 
> Labeling and numbering the in-memory structures (to say nothing of adding anchors for remote pointing), would greatly improve the usefulness of this document.
> 
> ??"
> TAB-1664,47703,Virtual I/O Device (VIRTIO) Version 1.1,Bug,"For consistency of presentation, the ""device and driver in-memory structure layouts"" should always follow descriptive prose in each section.","In 2.6.6, 2.6.8, 5.1.6.5.6.1, 5.7.4 (no prose at all), 5.7.6.7, 5.9.5, and 5.10.4, the ""device and driver in-memory structure layouts"" appear prior to any prose, which is different from the other sections. Was this a production, editorial or other type of error"
> TAB-1663,47702,Virtual I/O Device (VIRTIO) Version 1.1,Bug,Recast the sentences in question to remove the hyphens and elsewhere when improperly used in sentences.,"In 2.5 Virtqueues, the ""-"" hyphen appears to be a common precursor to ""i.e."" and elsewhere in the second sentence of that section. By count there are only seven (7) cases of - i.e.
> 
> Given the care taken produce this work, it should not be marred by non-standard English usage such as this."
> TAB-1662,47701,Virtual I/O Device (VIRTIO) Version 1.1,Bug,"""Device and driver in-memory structure layouts are documented using the C struct syntax.""","1.4 Structure Specifications begins with: ""Many device and driver in-memory structure layouts are documented using the C struct syntax.""
> 
> Many? Not all? Many leave it doubtful that some are defined.
> 
> Why not: ""Device and driver in-memory structure layouts are documented using the C struct syntax.""
> 
> If you are missing any, add them."
> TAB-1661,47700,Virtual I/O Device (VIRTIO) Version 1.1,Bug,"Define marking of non-normative text and use it, quite possibly declare all notes non-normative (but check all of the notes first).","I'm assuming that 1 Introduction, your ""for example"" under 1.4 Structure Specifications, and at least some of the 62 Notes: are non-normative, but have not been so marked or described. That is you can use non-normative on a section heading and/or say: All notes are non-normative.
> 
> In particular I have in mind notes like: 4.1.5.1.2.1
> 
> ""Note: For example, a device which does not expect to send interrupts at a high rate might only specify 2 MSI-X vectors.""
> 
> In terms of conformance to this specification, clearly non-normative language. As are many of the remaining 61 uses of note.
> 
> ??"





This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.

Subscribe: virtio-comment-subscribe@lists.oasis-open.org
Unsubscribe: virtio-comment-unsubscribe@lists.oasis-open.org
List help: virtio-comment-help@lists.oasis-open.org
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/

[virtio-comment] Re: [tab] Re: [virtio-comment] TAB comments on Virtual I/O Device (VIRTIO) Version 1.1

[Chet Ensign]

[-- Attachment #1: Type: text/plain, Size: 14054 bytes --]

Michael, if it would help, I believe I can move the issues from the TAB
JIRA to the Virtio JIRA. Save you the work of importing them one by one.

/chet

On Tue, Feb 26, 2019 at 3:58 PM Michael S. Tsirkin <mst@redhat.com> wrote:

> On Thu, Feb 21, 2019 at 05:36:51PM -0500, Patrick Durusau wrote:
> > Greetings!
> >
> > Members of the Technical Advisory Board endeavor to comment on all 30
> day public review drafts.
> >
> > Comments on: Virtual I/O Device (VIRTIO) Version 1.1 CS01 PRD01 are
> attached.
> >
> > It isn't necessary to acknowledge each comment separately. A single
> email acknowledging this email will be sufficient.
> >
> > When the TC has acted on these issues, I would appreciate a pointer to
> the TCs resolution as the TAB is tracking the resolution of comments from
> TAB members.
> >
> > Hope everyone is having a great week!
> >
> > Patrick
>
>
> Thanks a lot for the comments!
> I will try to split this CSV up and create github issues
> so it is easier to address individual comments.
>
>
>
>
> > --
> > Patrick Durusau
> > patrick@durusau.net
> > Technical Advisory Board, OASIS (TAB)
> > Editor, OpenDocument Format TC (OASIS), Project Editor ISO/IEC 26300
> > Co-Editor, ISO/IEC 13250-1, 13250-5 (Topic Maps)
> >
> > Another Word For It (blog): http://tm.durusau.net
> > Homepage: http://www.durusau.net
> > Twitter: patrickDurusau
> >
>
> > Issue key,Issue id,Affects Version/s,Issue Type,Custom field
> (Proposal),Description
> > TAB-1674,47718,Virtual I/O Device (VIRTIO) Version 1.1,Bug,Change
> bulleted lists into numbered lists and *always* introduce a list with the
> number of items to follow.,"Understanding and navigation of content is
> impaired by the use of bulleted lists. Compare for example, 2.7.21.1, being
> read aloud and being able to answer/find, where is your place in this list,
> as opposed to the second bulleted list in 2.7 Packed Virtqueues, or either
> of the lists/sub-lists in 2.6.10.1."
> > TAB-1673,47717,Virtual I/O Device (VIRTIO) Version 1.1,Bug,Devise and
> insert uniform start and end markers for examples.,"Most of the examples of
> memory structures being with struct but not all. Moreover, most examples
> end with }; but not all, for example, under 2.7.21.3.
> >
> > My usual accessibility checker is offline but if you were reading the
> text aloud, if the start and end of examples is not uniformly signaled to
> someone hearing the text, the examples would be much harder to contrast
> with the surrounding normative text.
> >
> > An accessibility issue?? in general but also a personal one because
> after nearly 30 years as a diabetic my vision remains normal, but they
> can't promise how much longer that will be the case. Adding uniform start
> and end markers won't inconvenience sighted readers and will enhance access
> to your work for those using assistive technologies."
> > TAB-1672,47716,Virtual I/O Device (VIRTIO) Version 1.1,Bug,,"We read in
> 7.4:
> >
> > ""A non-transitional implementation conforms to this specification if it
> satisfies all of the MUST or REQUIRED level requirements defined above. ""
> >
> > Is that true? ALL the ""MUST"" in all previous sections? Probably not.
> Or maybe it is ""below"" and not ""above"". (always explicitly refer to
> requirements sets by using a sub-section number & name)
> >
> > I suggest to make ""transitional"" just a variable (i.e. a parameter) in
> previous top-level conf clauses. (see TAB conformance guideline [
> http://docs.oasis-open.org/templates/TCHandbook/ConformanceGuidelines.html,
> section 5.5)??|
> http://docs.oasis-open.org/templates/TCHandbook/ConformanceGuidelines.html)]E.g.
> someone claiming conformance as ""PCI driver"" should always clarify:
> ""transitional PCI driver"" or ""non-transitional PCI driver"""
> > TAB-1671,47715,Virtual I/O Device (VIRTIO) Version 1.1,Bug,,"Each
> conformance clause sub-section starts with something that looks like a
> mandatory requirement:
> >
> > e.g.:
> >
> > ""A network device MUST conform to the following normative statements:""
> >
> > But many of the following statements are optional (SHOULD) in the
> specification body. So it is then confusing to say ""... MUST conform to a
> SHOULD statement....""
> >
> > That is why it is NOT recommended to use normative language like MUST
> (and even less SHOULD) in a conformance clause. A conf clause is not there
> to tell you what to do or not do (MUST....), but only to state under which
> conditions you can claim conformance to XYZ.
> >
> > It is better to say:
> >
> > ""an implementation that satisfies all mandatory (MUST) requirements in
> 5.1.4.1, 5.1.6.2.... qualifies (or may claim conformance) as a VIRTIO1.1
> network device""
> >
> > Or in some conformance profiles, you can override a SHOULD in the spec
> body and make it mandatory."
> > TAB-1670,47714,Virtual I/O Device (VIRTIO) Version 1.1,Bug,,"Sections
> 7.2.10 and 7.2.11 are never referred to, by any conformance clause. Same
> for 7.3.10 and 7.3.11.
> >
> > That seems like an omission? They should be used in at least one
> conformance profile each. Or else, these sections should not be normative."
> > TAB-1669,47713,Virtual I/O Device (VIRTIO) Version 1.1,Bug,,"Overall,
> well-formed conformance section (one of the best we?? TAB reviewers have
> seen!) The main conformance targets - drivers, devices - are well
> identified. The specification is clearly attributing normative requirements
> to either driver, or device.
> >
> > Some conformance aspects could still be clarified:
> >  * All the subsections under 7.2 or 7.3 are named ""clauses"" in 7.1. So
> their titles should be ""Clause XYZ"". Or else if we want to keep
> ""CLause"" to only the top-level set of requirements - then define just a
> couple of clauses in 7.1, e.g. ""Conformance Clause for VIRTIO1.1
> drivers"". Then all thee following subsections should just be titled
> ""Conformance requirements sets"" e.g. ""COnformance requirements for PCI
> drivers""), and preferably not ""clause"" (keeping ""clause"" for only??
> the full set of requirements that a product can claim for conformance).
> >  * In any case, it is good to associate a clear name to each conformance
> level/profile that can be claimed. For example, ""PCI network driver"" (if
> satisfying 7.2 + 7.2.1 + 7.2.4. Is that a meaningful combination? irt seems
> so according to 7.1). So that there is no ambiguity of what are the valid??
> conformance profiles. Some parameterization of a clause can be used: Look
> in TAB guideline : [
> http://docs.oasis-open.org/templates/TCHandbook/ConformanceGuidelines.html]
> for ""variable conformance clauses"" (section 5.5). In other words: define
> the precise statement that someone should use when claiming a conformance
> profile.
> >
> > ??"
> > TAB-1668,47707,Virtual I/O Device (VIRTIO) Version 1.1,Bug,"The
> accessibility site that I commonly use, [
> https://achecker.ca/checker/index.php,] is down tonight but use it to
> check your usage for other problems.
> >
> > ??","In terms of accessibility, ""what follows,"" ""below,"" and
> ""follows"" all inhibit the use of VIRTIO by users assisted by reading
> software.
> >
> > Take 2.2 Feature Bits as an example:
> >
> > ""Feature bits are allocated as follows:
> >
> > 0 to 23 Feature bits for the specific device type
> >
> > 24 to 37 Feature bits reserved for extensions to the queue and feature
> negotiation mechanisms
> >
> > 38 and above Feature bits reserved for future extensions.""
> >
> > A sighted reader is clued in that 3 entries follow, but reading software
> does not offer, in this form, the same clue.
> >
> > Compare:
> >
> > ""Feature bits are allocated in three ways:
> >
> > 1. 0 to 23 Feature bits for the specific device type
> >
> > 2. 24 to 37 Feature bits reserved for extensions to the queue and
> feature negotiation mechanisms
> >
> > 3. 38 and above Feature bits reserved for future extensions.""
> >
> > Same text but now both sighted as well as assisted readers know there
> are 3 ways to allocate feature bits and each of those ways is numbered and
> recited to the reader.
> >
> > ??
> >
> > ??
> >
> > ??"
> > TAB-1667,47706,Virtual I/O Device (VIRTIO) Version 1.1,Bug,Update the
> IEEE 802 link and re-check with [http://validator.w3.org/checklink],"|[IEEE
> 802] |IEEE Standard for Local and Metropolitan Area Networks: Overview and
> Architecture,
> > [http://standards.ieee.org/about/get/802/802.html], IEEE|
> >
> > reports a 404.
> >
> > Did you mean: [https://standards.ieee.org/standard/802-2001.html]?? ??"
> > TAB-1666,47705,Virtual I/O Device (VIRTIO) Version 1.1,Bug,Update the
> links indicated and re-check with http://validator.w3.org/checklink,"The
> link checker at [http://validator.w3.org/checklink] reports the following
> redirects:
> >
> > !http://validator.w3.org/checklink/images/info_icons/warning.png! Line:
> 6875 [http://www.pcisig.com/] redirected to [http://pcisig.com/]
> *Status*: 301 -> 200 OK
> >
> > This is a permanent redirect. The link should be updated.
> >
> > !http://validator.w3.org/checklink/images/info_icons/warning.png!
> Lines: 55, 60, 63 [http://www.redhat.com/] redirected to [
> https://www.redhat.com/en] *Status*: 301 -> 200 OK
> >
> > This is a permanent redirect. The link should be updated.
> >
> > !http://validator.w3.org/checklink/images/info_icons/warning.png! Line:
> 21250 [
> http://git.qemu-project.org/?p=qemu.git;a=blob;f=docs/specs/standard-vga.txt;hb=HEAD]
> redirected to [
> https://git.qemu.org/?p=qemu.git;a=blob;f=docs/specs/standard-vga.txt;hb=HEAD]
> *Status*: 301 -> 200 OK
> >
> > This is a permanent redirect. The link should be updated.
> >
> > !http://validator.w3.org/checklink/images/info_icons/warning.png! Line:
> 768 [http://www.pcisig.com/specifications/pciexpress/] redirected to [
> http://pcisig.com/specifications/pciexpress/] *Status*: 301 -> 200 OK
> >
> > This is a permanent redirect. The link should be updated.
> >
> > !http://validator.w3.org/checklink/images/info_icons/warning.png!
> Line:  [https://www.oasis-open.org/policies-guidelines/tc-process]
> redirected to [
> https://www.oasis-open.org/policies-guidelines/tc-process-2017-05-26]
> *Status*: 301 -> 200 OK
> >
> > This is a permanent redirect. The link should be updated.
> >
> > !http://validator.w3.org/checklink/images/info_icons/warning.png! Line:
> 759 [http://www.pcisig.com/specifications/conventional/] redirected to [
> http://pcisig.com/specifications/conventional/] *Status*: 301 -> 200 OK
> >
> > This is a permanent redirect. The link should be updated."
> > TAB-1665,47704,Virtual I/O Device (VIRTIO) Version 1.1,Bug,Number and
> label the in-memory structure illustrations and add anchors to enable
> remote pointing to particular illustrations.,"While I appreciate that the
> use of C struct syntax is illustrative only, the in-memory structures it
> documents are normative.
> >
> > And in a number of cases, those in-memory structures occur in the same
> numbered section, making reference to any specified in-memory structure
> uncertain.
> >
> > Labeling and numbering the in-memory structures (to say nothing of
> adding anchors for remote pointing), would greatly improve the usefulness
> of this document.
> >
> > ??"
> > TAB-1664,47703,Virtual I/O Device (VIRTIO) Version 1.1,Bug,"For
> consistency of presentation, the ""device and driver in-memory structure
> layouts"" should always follow descriptive prose in each section.","In
> 2.6.6, 2.6.8, 5.1.6.5.6.1, 5.7.4 (no prose at all), 5.7.6.7, 5.9.5, and
> 5.10.4, the ""device and driver in-memory structure layouts"" appear prior
> to any prose, which is different from the other sections. Was this a
> production, editorial or other type of error"
> > TAB-1663,47702,Virtual I/O Device (VIRTIO) Version 1.1,Bug,Recast the
> sentences in question to remove the hyphens and elsewhere when improperly
> used in sentences.,"In 2.5 Virtqueues, the ""-"" hyphen appears to be a
> common precursor to ""i.e."" and elsewhere in the second sentence of that
> section. By count there are only seven (7) cases of - i.e.
> >
> > Given the care taken produce this work, it should not be marred by
> non-standard English usage such as this."
> > TAB-1662,47701,Virtual I/O Device (VIRTIO) Version 1.1,Bug,"""Device and
> driver in-memory structure layouts are documented using the C struct
> syntax.""","1.4 Structure Specifications begins with: ""Many device and
> driver in-memory structure layouts are documented using the C struct
> syntax.""
> >
> > Many? Not all? Many leave it doubtful that some are defined.
> >
> > Why not: ""Device and driver in-memory structure layouts are documented
> using the C struct syntax.""
> >
> > If you are missing any, add them."
> > TAB-1661,47700,Virtual I/O Device (VIRTIO) Version 1.1,Bug,"Define
> marking of non-normative text and use it, quite possibly declare all notes
> non-normative (but check all of the notes first).","I'm assuming that 1
> Introduction, your ""for example"" under 1.4 Structure Specifications, and
> at least some of the 62 Notes: are non-normative, but have not been so
> marked or described. That is you can use non-normative on a section heading
> and/or say: All notes are non-normative.
> >
> > In particular I have in mind notes like: 4.1.5.1.2.1
> >
> > ""Note: For example, a device which does not expect to send interrupts
> at a high rate might only specify 2 MSI-X vectors.""
> >
> > In terms of conformance to this specification, clearly non-normative
> language. As are many of the remaining 61 uses of note.
> >
> > ??"
>
>
>
>
>
> ---------------------------------------------------------------------
> 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
>
>

-- 

/chet
----------------
Chet Ensign
Chief Technical Community Steward
OASIS: Advancing open standards for the information society
http://www.oasis-open.org

Primary: +1 973-996-2298
Mobile: +1 201-341-1393

[-- Attachment #2: Type: text/html, Size: 19478 bytes --]

[virtio-comment] Re: [tab] Re: [virtio-comment] TAB comments on Virtual I/O Device (VIRTIO) Version 1.1

[Michael S. Tsirkin]

Thanks! Yes please do. We mostly switched over to github issues but jira
isn't too bad just for this.


On Tue, Feb 26, 2019 at 04:29:42PM -0500, Chet Ensign wrote:
> Michael, if it would help, I believe I can move the issues from the TAB JIRA to
> the Virtio JIRA. Save you the work of importing them one by one. 
> 
> /chet
> 
> On Tue, Feb 26, 2019 at 3:58 PM Michael S. Tsirkin <mst@redhat.com> wrote:
> 
>     On Thu, Feb 21, 2019 at 05:36:51PM -0500, Patrick Durusau wrote:
>     > Greetings!
>     >
>     > Members of the Technical Advisory Board endeavor to comment on all 30 day
>     public review drafts.
>     >
>     > Comments on: Virtual I/O Device (VIRTIO) Version 1.1 CS01 PRD01 are
>     attached.
>     >
>     > It isn't necessary to acknowledge each comment separately. A single email
>     acknowledging this email will be sufficient.
>     >
>     > When the TC has acted on these issues, I would appreciate a pointer to
>     the TCs resolution as the TAB is tracking the resolution of comments from
>     TAB members.
>     >
>     > Hope everyone is having a great week!
>     >
>     > Patrick
> 
> 
>     Thanks a lot for the comments!
>     I will try to split this CSV up and create github issues
>     so it is easier to address individual comments.
> 
> 
> 
> 
>     > --
>     > Patrick Durusau
>     > patrick@durusau.net
>     > Technical Advisory Board, OASIS (TAB)
>     > Editor, OpenDocument Format TC (OASIS), Project Editor ISO/IEC 26300
>     > Co-Editor, ISO/IEC 13250-1, 13250-5 (Topic Maps)
>     >
>     > Another Word For It (blog): http://tm.durusau.net
>     > Homepage: http://www.durusau.net
>     > Twitter: patrickDurusau
>     >
> 
>     > Issue key,Issue id,Affects Version/s,Issue Type,Custom field
>     (Proposal),Description
>     > TAB-1674,47718,Virtual I/O Device (VIRTIO) Version 1.1,Bug,Change
>     bulleted lists into numbered lists and *always* introduce a list with the
>     number of items to follow.,"Understanding and navigation of content is
>     impaired by the use of bulleted lists. Compare for example, 2.7.21.1, being
>     read aloud and being able to answer/find, where is your place in this list,
>     as opposed to the second bulleted list in 2.7 Packed Virtqueues, or either
>     of the lists/sub-lists in 2.6.10.1."
>     > TAB-1673,47717,Virtual I/O Device (VIRTIO) Version 1.1,Bug,Devise and
>     insert uniform start and end markers for examples.,"Most of the examples of
>     memory structures being with struct but not all. Moreover, most examples
>     end with }; but not all, for example, under 2.7.21.3.
>     >
>     > My usual accessibility checker is offline but if you were reading the
>     text aloud, if the start and end of examples is not uniformly signaled to
>     someone hearing the text, the examples would be much harder to contrast
>     with the surrounding normative text.
>     >
>     > An accessibility issue?? in general but also a personal one because after
>     nearly 30 years as a diabetic my vision remains normal, but they can't
>     promise how much longer that will be the case. Adding uniform start and end
>     markers won't inconvenience sighted readers and will enhance access to your
>     work for those using assistive technologies."
>     > TAB-1672,47716,Virtual I/O Device (VIRTIO) Version 1.1,Bug,,"We read in
>     7.4:
>     >
>     > ""A non-transitional implementation conforms to this specification if it
>     satisfies all of the MUST or REQUIRED level requirements defined above. ""
>     >
>     > Is that true? ALL the ""MUST"" in all previous sections? Probably not. Or
>     maybe it is ""below"" and not ""above"". (always explicitly refer to
>     requirements sets by using a sub-section number & name)
>     >
>     > I suggest to make ""transitional"" just a variable (i.e. a parameter) in
>     previous top-level conf clauses. (see TAB conformance guideline [http://
>     docs.oasis-open.org/templates/TCHandbook/ConformanceGuidelines.html,
>     section 5.5)??|http://docs.oasis-open.org/templates/TCHandbook/
>     ConformanceGuidelines.html)]E.g. someone claiming conformance as ""PCI
>     driver"" should always clarify: ""transitional PCI driver"" or
>     ""non-transitional PCI driver"""
>     > TAB-1671,47715,Virtual I/O Device (VIRTIO) Version 1.1,Bug,,"Each
>     conformance clause sub-section starts with something that looks like a
>     mandatory requirement:
>     >
>     > e.g.:
>     >
>     > ""A network device MUST conform to the following normative statements:""
>     >
>     > But many of the following statements are optional (SHOULD) in the
>     specification body. So it is then confusing to say ""... MUST conform to a
>     SHOULD statement....""
>     >
>     > That is why it is NOT recommended to use normative language like MUST
>     (and even less SHOULD) in a conformance clause. A conf clause is not there
>     to tell you what to do or not do (MUST....), but only to state under which
>     conditions you can claim conformance to XYZ.
>     >
>     > It is better to say:
>     >
>     > ""an implementation that satisfies all mandatory (MUST) requirements in
>     5.1.4.1, 5.1.6.2.... qualifies (or may claim conformance) as a VIRTIO1.1
>     network device""
>     >
>     > Or in some conformance profiles, you can override a SHOULD in the spec
>     body and make it mandatory."
>     > TAB-1670,47714,Virtual I/O Device (VIRTIO) Version 1.1,Bug,,"Sections
>     7.2.10 and 7.2.11 are never referred to, by any conformance clause. Same
>     for 7.3.10 and 7.3.11.
>     >
>     > That seems like an omission? They should be used in at least one
>     conformance profile each. Or else, these sections should not be normative."
>     > TAB-1669,47713,Virtual I/O Device (VIRTIO) Version 1.1,Bug,,"Overall,
>     well-formed conformance section (one of the best we?? TAB reviewers have
>     seen!) The main conformance targets - drivers, devices - are well
>     identified. The specification is clearly attributing normative requirements
>     to either driver, or device.
>     >
>     > Some conformance aspects could still be clarified:
>     >  * All the subsections under 7.2 or 7.3 are named ""clauses"" in 7.1. So
>     their titles should be ""Clause XYZ"". Or else if we want to keep
>     ""CLause"" to only the top-level set of requirements - then define just a
>     couple of clauses in 7.1, e.g. ""Conformance Clause for VIRTIO1.1
>     drivers"". Then all thee following subsections should just be titled
>     ""Conformance requirements sets"" e.g. ""COnformance requirements for PCI
>     drivers""), and preferably not ""clause"" (keeping ""clause"" for only??
>     the full set of requirements that a product can claim for conformance).
>     >  * In any case, it is good to associate a clear name to each conformance
>     level/profile that can be claimed. For example, ""PCI network driver"" (if
>     satisfying 7.2 + 7.2.1 + 7.2.4. Is that a meaningful combination? irt seems
>     so according to 7.1). So that there is no ambiguity of what are the valid??
>     conformance profiles. Some parameterization of a clause can be used: Look
>     in TAB guideline : [http://docs.oasis-open.org/templates/TCHandbook/
>     ConformanceGuidelines.html] for ""variable conformance clauses"" (section
>     5.5). In other words: define the precise statement that someone should use
>     when claiming a conformance profile.
>     >
>     > ??"
>     > TAB-1668,47707,Virtual I/O Device (VIRTIO) Version 1.1,Bug,"The
>     accessibility site that I commonly use, [https://achecker.ca/checker/
>     index.php,] is down tonight but use it to check your usage for other
>     problems.
>     >
>     > ??","In terms of accessibility, ""what follows,"" ""below,"" and
>     ""follows"" all inhibit the use of VIRTIO by users assisted by reading
>     software.
>     >
>     > Take 2.2 Feature Bits as an example:
>     >
>     > ""Feature bits are allocated as follows:
>     >
>     > 0 to 23 Feature bits for the specific device type
>     >
>     > 24 to 37 Feature bits reserved for extensions to the queue and feature
>     negotiation mechanisms
>     >
>     > 38 and above Feature bits reserved for future extensions.""
>     >
>     > A sighted reader is clued in that 3 entries follow, but reading software
>     does not offer, in this form, the same clue.
>     >
>     > Compare:
>     >
>     > ""Feature bits are allocated in three ways:
>     >
>     > 1. 0 to 23 Feature bits for the specific device type
>     >
>     > 2. 24 to 37 Feature bits reserved for extensions to the queue and feature
>     negotiation mechanisms
>     >
>     > 3. 38 and above Feature bits reserved for future extensions.""
>     >
>     > Same text but now both sighted as well as assisted readers know there are
>     3 ways to allocate feature bits and each of those ways is numbered and
>     recited to the reader.
>     >
>     > ??
>     >
>     > ??
>     >
>     > ??"
>     > TAB-1667,47706,Virtual I/O Device (VIRTIO) Version 1.1,Bug,Update the
>     IEEE 802 link and re-check with [http://validator.w3.org/checklink],"|[IEEE
>     802] |IEEE Standard for Local and Metropolitan Area Networks: Overview and
>     Architecture,
>     > [http://standards.ieee.org/about/get/802/802.html], IEEE|
>     >
>     > reports a 404.
>     >
>     > Did you mean: [https://standards.ieee.org/standard/802-2001.html]?? ??"
>     > TAB-1666,47705,Virtual I/O Device (VIRTIO) Version 1.1,Bug,Update the
>     links indicated and re-check with http://validator.w3.org/checklink,"The
>     link checker at [http://validator.w3.org/checklink] reports the following
>     redirects:
>     >
>     > !http://validator.w3.org/checklink/images/info_icons/warning.png! Line:
>     6875 [http://www.pcisig.com/] redirected to [http://pcisig.com/] *Status*:
>     301 -> 200 OK
>     >
>     > This is a permanent redirect. The link should be updated.
>     >
>     > !http://validator.w3.org/checklink/images/info_icons/warning.png! Lines:
>     55, 60, 63 [http://www.redhat.com/] redirected to [https://www.redhat.com/
>     en] *Status*: 301 -> 200 OK
>     >
>     > This is a permanent redirect. The link should be updated.
>     >
>     > !http://validator.w3.org/checklink/images/info_icons/warning.png! Line:
>     21250 [http://git.qemu-project.org/?p=qemu.git;a=blob;f=docs/specs/
>     standard-vga.txt;hb=HEAD] redirected to [https://git.qemu.org/?p=qemu.git;a
>     =blob;f=docs/specs/standard-vga.txt;hb=HEAD] *Status*: 301 -> 200 OK
>     >
>     > This is a permanent redirect. The link should be updated.
>     >
>     > !http://validator.w3.org/checklink/images/info_icons/warning.png! Line:
>     768 [http://www.pcisig.com/specifications/pciexpress/] redirected to [http:
>     //pcisig.com/specifications/pciexpress/] *Status*: 301 -> 200 OK
>     >
>     > This is a permanent redirect. The link should be updated.
>     >
>     > !http://validator.w3.org/checklink/images/info_icons/warning.png! Line: 
>     [https://www.oasis-open.org/policies-guidelines/tc-process] redirected to [
>     https://www.oasis-open.org/policies-guidelines/tc-process-2017-05-26]
>     *Status*: 301 -> 200 OK
>     >
>     > This is a permanent redirect. The link should be updated.
>     >
>     > !http://validator.w3.org/checklink/images/info_icons/warning.png! Line:
>     759 [http://www.pcisig.com/specifications/conventional/] redirected to [
>     http://pcisig.com/specifications/conventional/] *Status*: 301 -> 200 OK
>     >
>     > This is a permanent redirect. The link should be updated."
>     > TAB-1665,47704,Virtual I/O Device (VIRTIO) Version 1.1,Bug,Number and
>     label the in-memory structure illustrations and add anchors to enable
>     remote pointing to particular illustrations.,"While I appreciate that the
>     use of C struct syntax is illustrative only, the in-memory structures it
>     documents are normative.
>     >
>     > And in a number of cases, those in-memory structures occur in the same
>     numbered section, making reference to any specified in-memory structure
>     uncertain.
>     >
>     > Labeling and numbering the in-memory structures (to say nothing of adding
>     anchors for remote pointing), would greatly improve the usefulness of this
>     document.
>     >
>     > ??"
>     > TAB-1664,47703,Virtual I/O Device (VIRTIO) Version 1.1,Bug,"For
>     consistency of presentation, the ""device and driver in-memory structure
>     layouts"" should always follow descriptive prose in each section.","In
>     2.6.6, 2.6.8, 5.1.6.5.6.1, 5.7.4 (no prose at all), 5.7.6.7, 5.9.5, and
>     5.10.4, the ""device and driver in-memory structure layouts"" appear prior
>     to any prose, which is different from the other sections. Was this a
>     production, editorial or other type of error"
>     > TAB-1663,47702,Virtual I/O Device (VIRTIO) Version 1.1,Bug,Recast the
>     sentences in question to remove the hyphens and elsewhere when improperly
>     used in sentences.,"In 2.5 Virtqueues, the ""-"" hyphen appears to be a
>     common precursor to ""i.e."" and elsewhere in the second sentence of that
>     section. By count there are only seven (7) cases of - i.e.
>     >
>     > Given the care taken produce this work, it should not be marred by
>     non-standard English usage such as this."
>     > TAB-1662,47701,Virtual I/O Device (VIRTIO) Version 1.1,Bug,"""Device and
>     driver in-memory structure layouts are documented using the C struct
>     syntax.""","1.4 Structure Specifications begins with: ""Many device and
>     driver in-memory structure layouts are documented using the C struct
>     syntax.""
>     >
>     > Many? Not all? Many leave it doubtful that some are defined.
>     >
>     > Why not: ""Device and driver in-memory structure layouts are documented
>     using the C struct syntax.""
>     >
>     > If you are missing any, add them."
>     > TAB-1661,47700,Virtual I/O Device (VIRTIO) Version 1.1,Bug,"Define
>     marking of non-normative text and use it, quite possibly declare all notes
>     non-normative (but check all of the notes first).","I'm assuming that 1
>     Introduction, your ""for example"" under 1.4 Structure Specifications, and
>     at least some of the 62 Notes: are non-normative, but have not been so
>     marked or described. That is you can use non-normative on a section heading
>     and/or say: All notes are non-normative.
>     >
>     > In particular I have in mind notes like: 4.1.5.1.2.1
>     >
>     > ""Note: For example, a device which does not expect to send interrupts at
>     a high rate might only specify 2 MSI-X vectors.""
>     >
>     > In terms of conformance to this specification, clearly non-normative
>     language. As are many of the remaining 61 uses of note.
>     >
>     > ??"
> 
> 
> 
> 
> 
>     ---------------------------------------------------------------------
>     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
> 
> 
> 
> 
> --
> 
> /chet 
> ----------------
> Chet Ensign
> Chief Technical Community Steward
> OASIS: Advancing open standards for the information society
> http://www.oasis-open.org
> 
> Primary: +1 973-996-2298
> Mobile: +1 201-341-1393 

This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.

Subscribe: virtio-comment-subscribe@lists.oasis-open.org
Unsubscribe: virtio-comment-unsubscribe@lists.oasis-open.org
List help: virtio-comment-help@lists.oasis-open.org
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/

[virtio-comment] Re: [tab] Re: [virtio-comment] TAB comments on Virtual I/O Device (VIRTIO) Version 1.1

[Chet Ensign]

[-- Attachment #1: Type: text/plain, Size: 16658 bytes --]

Will do - sorry that I can't get it to the github issues for you; JIRA
though is straightforward.

On Wed, Feb 27, 2019 at 9:10 AM Michael S. Tsirkin <mst@redhat.com> wrote:

> Thanks! Yes please do. We mostly switched over to github issues but jira
> isn't too bad just for this.
>
>
> On Tue, Feb 26, 2019 at 04:29:42PM -0500, Chet Ensign wrote:
> > Michael, if it would help, I believe I can move the issues from the TAB
> JIRA to
> > the Virtio JIRA. Save you the work of importing them one by one.
> >
> > /chet
> >
> > On Tue, Feb 26, 2019 at 3:58 PM Michael S. Tsirkin <mst@redhat.com>
> wrote:
> >
> >     On Thu, Feb 21, 2019 at 05:36:51PM -0500, Patrick Durusau wrote:
> >     > Greetings!
> >     >
> >     > Members of the Technical Advisory Board endeavor to comment on all
> 30 day
> >     public review drafts.
> >     >
> >     > Comments on: Virtual I/O Device (VIRTIO) Version 1.1 CS01 PRD01 are
> >     attached.
> >     >
> >     > It isn't necessary to acknowledge each comment separately. A
> single email
> >     acknowledging this email will be sufficient.
> >     >
> >     > When the TC has acted on these issues, I would appreciate a
> pointer to
> >     the TCs resolution as the TAB is tracking the resolution of comments
> from
> >     TAB members.
> >     >
> >     > Hope everyone is having a great week!
> >     >
> >     > Patrick
> >
> >
> >     Thanks a lot for the comments!
> >     I will try to split this CSV up and create github issues
> >     so it is easier to address individual comments.
> >
> >
> >
> >
> >     > --
> >     > Patrick Durusau
> >     > patrick@durusau.net
> >     > Technical Advisory Board, OASIS (TAB)
> >     > Editor, OpenDocument Format TC (OASIS), Project Editor ISO/IEC
> 26300
> >     > Co-Editor, ISO/IEC 13250-1, 13250-5 (Topic Maps)
> >     >
> >     > Another Word For It (blog): http://tm.durusau.net
> >     > Homepage: http://www.durusau.net
> >     > Twitter: patrickDurusau
> >     >
> >
> >     > Issue key,Issue id,Affects Version/s,Issue Type,Custom field
> >     (Proposal),Description
> >     > TAB-1674,47718,Virtual I/O Device (VIRTIO) Version 1.1,Bug,Change
> >     bulleted lists into numbered lists and *always* introduce a list
> with the
> >     number of items to follow.,"Understanding and navigation of content
> is
> >     impaired by the use of bulleted lists. Compare for example,
> 2.7.21.1, being
> >     read aloud and being able to answer/find, where is your place in
> this list,
> >     as opposed to the second bulleted list in 2.7 Packed Virtqueues, or
> either
> >     of the lists/sub-lists in 2.6.10.1."
> >     > TAB-1673,47717,Virtual I/O Device (VIRTIO) Version 1.1,Bug,Devise
> and
> >     insert uniform start and end markers for examples.,"Most of the
> examples of
> >     memory structures being with struct but not all. Moreover, most
> examples
> >     end with }; but not all, for example, under 2.7.21.3.
> >     >
> >     > My usual accessibility checker is offline but if you were reading
> the
> >     text aloud, if the start and end of examples is not uniformly
> signaled to
> >     someone hearing the text, the examples would be much harder to
> contrast
> >     with the surrounding normative text.
> >     >
> >     > An accessibility issue?? in general but also a personal one
> because after
> >     nearly 30 years as a diabetic my vision remains normal, but they
> can't
> >     promise how much longer that will be the case. Adding uniform start
> and end
> >     markers won't inconvenience sighted readers and will enhance access
> to your
> >     work for those using assistive technologies."
> >     > TAB-1672,47716,Virtual I/O Device (VIRTIO) Version 1.1,Bug,,"We
> read in
> >     7.4:
> >     >
> >     > ""A non-transitional implementation conforms to this specification
> if it
> >     satisfies all of the MUST or REQUIRED level requirements defined
> above. ""
> >     >
> >     > Is that true? ALL the ""MUST"" in all previous sections? Probably
> not. Or
> >     maybe it is ""below"" and not ""above"". (always explicitly refer to
> >     requirements sets by using a sub-section number & name)
> >     >
> >     > I suggest to make ""transitional"" just a variable (i.e. a
> parameter) in
> >     previous top-level conf clauses. (see TAB conformance guideline
> [http://
> >     docs.oasis-open.org/templates/TCHandbook/ConformanceGuidelines.html,
> >     section 5.5)??|http://docs.oasis-open.org/templates/TCHandbook/
> >     ConformanceGuidelines.html)]E.g. someone claiming conformance as
> ""PCI
> >     driver"" should always clarify: ""transitional PCI driver"" or
> >     ""non-transitional PCI driver"""
> >     > TAB-1671,47715,Virtual I/O Device (VIRTIO) Version 1.1,Bug,,"Each
> >     conformance clause sub-section starts with something that looks like
> a
> >     mandatory requirement:
> >     >
> >     > e.g.:
> >     >
> >     > ""A network device MUST conform to the following normative
> statements:""
> >     >
> >     > But many of the following statements are optional (SHOULD) in the
> >     specification body. So it is then confusing to say ""... MUST
> conform to a
> >     SHOULD statement....""
> >     >
> >     > That is why it is NOT recommended to use normative language like
> MUST
> >     (and even less SHOULD) in a conformance clause. A conf clause is not
> there
> >     to tell you what to do or not do (MUST....), but only to state under
> which
> >     conditions you can claim conformance to XYZ.
> >     >
> >     > It is better to say:
> >     >
> >     > ""an implementation that satisfies all mandatory (MUST)
> requirements in
> >     5.1.4.1, 5.1.6.2.... qualifies (or may claim conformance) as a
> VIRTIO1.1
> >     network device""
> >     >
> >     > Or in some conformance profiles, you can override a SHOULD in the
> spec
> >     body and make it mandatory."
> >     > TAB-1670,47714,Virtual I/O Device (VIRTIO) Version
> 1.1,Bug,,"Sections
> >     7.2.10 and 7.2.11 are never referred to, by any conformance clause.
> Same
> >     for 7.3.10 and 7.3.11.
> >     >
> >     > That seems like an omission? They should be used in at least one
> >     conformance profile each. Or else, these sections should not be
> normative."
> >     > TAB-1669,47713,Virtual I/O Device (VIRTIO) Version
> 1.1,Bug,,"Overall,
> >     well-formed conformance section (one of the best we?? TAB reviewers
> have
> >     seen!) The main conformance targets - drivers, devices - are well
> >     identified. The specification is clearly attributing normative
> requirements
> >     to either driver, or device.
> >     >
> >     > Some conformance aspects could still be clarified:
> >     >  * All the subsections under 7.2 or 7.3 are named ""clauses"" in
> 7.1. So
> >     their titles should be ""Clause XYZ"". Or else if we want to keep
> >     ""CLause"" to only the top-level set of requirements - then define
> just a
> >     couple of clauses in 7.1, e.g. ""Conformance Clause for VIRTIO1.1
> >     drivers"". Then all thee following subsections should just be titled
> >     ""Conformance requirements sets"" e.g. ""COnformance requirements
> for PCI
> >     drivers""), and preferably not ""clause"" (keeping ""clause"" for
> only??
> >     the full set of requirements that a product can claim for
> conformance).
> >     >  * In any case, it is good to associate a clear name to each
> conformance
> >     level/profile that can be claimed. For example, ""PCI network
> driver"" (if
> >     satisfying 7.2 + 7.2.1 + 7.2.4. Is that a meaningful combination?
> irt seems
> >     so according to 7.1). So that there is no ambiguity of what are the
> valid??
> >     conformance profiles. Some parameterization of a clause can be used:
> Look
> >     in TAB guideline : [http://docs.oasis-open.org/templates/TCHandbook/
> >     ConformanceGuidelines.html] for ""variable conformance clauses""
> (section
> >     5.5). In other words: define the precise statement that someone
> should use
> >     when claiming a conformance profile.
> >     >
> >     > ??"
> >     > TAB-1668,47707,Virtual I/O Device (VIRTIO) Version 1.1,Bug,"The
> >     accessibility site that I commonly use, [
> https://achecker.ca/checker/
> >     index.php,] is down tonight but use it to check your usage for other
> >     problems.
> >     >
> >     > ??","In terms of accessibility, ""what follows,"" ""below,"" and
> >     ""follows"" all inhibit the use of VIRTIO by users assisted by
> reading
> >     software.
> >     >
> >     > Take 2.2 Feature Bits as an example:
> >     >
> >     > ""Feature bits are allocated as follows:
> >     >
> >     > 0 to 23 Feature bits for the specific device type
> >     >
> >     > 24 to 37 Feature bits reserved for extensions to the queue and
> feature
> >     negotiation mechanisms
> >     >
> >     > 38 and above Feature bits reserved for future extensions.""
> >     >
> >     > A sighted reader is clued in that 3 entries follow, but reading
> software
> >     does not offer, in this form, the same clue.
> >     >
> >     > Compare:
> >     >
> >     > ""Feature bits are allocated in three ways:
> >     >
> >     > 1. 0 to 23 Feature bits for the specific device type
> >     >
> >     > 2. 24 to 37 Feature bits reserved for extensions to the queue and
> feature
> >     negotiation mechanisms
> >     >
> >     > 3. 38 and above Feature bits reserved for future extensions.""
> >     >
> >     > Same text but now both sighted as well as assisted readers know
> there are
> >     3 ways to allocate feature bits and each of those ways is numbered
> and
> >     recited to the reader.
> >     >
> >     > ??
> >     >
> >     > ??
> >     >
> >     > ??"
> >     > TAB-1667,47706,Virtual I/O Device (VIRTIO) Version 1.1,Bug,Update
> the
> >     IEEE 802 link and re-check with [http://validator.w3.org/checklink
> ],"|[IEEE
> >     802] |IEEE Standard for Local and Metropolitan Area Networks:
> Overview and
> >     Architecture,
> >     > [http://standards.ieee.org/about/get/802/802.html], IEEE|
> >     >
> >     > reports a 404.
> >     >
> >     > Did you mean: [https://standards.ieee.org/standard/802-2001.html]??
> ??"
> >     > TAB-1666,47705,Virtual I/O Device (VIRTIO) Version 1.1,Bug,Update
> the
> >     links indicated and re-check with http://validator.w3.org/checklink,
> "The
> >     link checker at [http://validator.w3.org/checklink] reports the
> following
> >     redirects:
> >     >
> >     > !http://validator.w3.org/checklink/images/info_icons/warning.png!
> Line:
> >     6875 [http://www.pcisig.com/] redirected to [http://pcisig.com/]
> *Status*:
> >     301 -> 200 OK
> >     >
> >     > This is a permanent redirect. The link should be updated.
> >     >
> >     > !http://validator.w3.org/checklink/images/info_icons/warning.png!
> Lines:
> >     55, 60, 63 [http://www.redhat.com/] redirected to [
> https://www.redhat.com/
> >     en] *Status*: 301 -> 200 OK
> >     >
> >     > This is a permanent redirect. The link should be updated.
> >     >
> >     > !http://validator.w3.org/checklink/images/info_icons/warning.png!
> Line:
> >     21250 [http://git.qemu-project.org/?p=qemu.git;a=blob;f=docs/specs/
> >     standard-vga.txt;hb=HEAD] redirected to [
> https://git.qemu.org/?p=qemu.git;a
> >     =blob;f=docs/specs/standard-vga.txt;hb=HEAD] *Status*: 301 -> 200 OK
> >     >
> >     > This is a permanent redirect. The link should be updated.
> >     >
> >     > !http://validator.w3.org/checklink/images/info_icons/warning.png!
> Line:
> >     768 [http://www.pcisig.com/specifications/pciexpress/] redirected
> to [http:
> >     //pcisig.com/specifications/pciexpress/] *Status*: 301 -> 200 OK
> >     >
> >     > This is a permanent redirect. The link should be updated.
> >     >
> >     > !http://validator.w3.org/checklink/images/info_icons/warning.png!
> Line:
> >     [https://www.oasis-open.org/policies-guidelines/tc-process]
> redirected to [
> >     https://www.oasis-open.org/policies-guidelines/tc-process-2017-05-26
> ]
> >     *Status*: 301 -> 200 OK
> >     >
> >     > This is a permanent redirect. The link should be updated.
> >     >
> >     > !http://validator.w3.org/checklink/images/info_icons/warning.png!
> Line:
> >     759 [http://www.pcisig.com/specifications/conventional/] redirected
> to [
> >     http://pcisig.com/specifications/conventional/] *Status*: 301 ->
> 200 OK
> >     >
> >     > This is a permanent redirect. The link should be updated."
> >     > TAB-1665,47704,Virtual I/O Device (VIRTIO) Version 1.1,Bug,Number
> and
> >     label the in-memory structure illustrations and add anchors to enable
> >     remote pointing to particular illustrations.,"While I appreciate
> that the
> >     use of C struct syntax is illustrative only, the in-memory
> structures it
> >     documents are normative.
> >     >
> >     > And in a number of cases, those in-memory structures occur in the
> same
> >     numbered section, making reference to any specified in-memory
> structure
> >     uncertain.
> >     >
> >     > Labeling and numbering the in-memory structures (to say nothing of
> adding
> >     anchors for remote pointing), would greatly improve the usefulness
> of this
> >     document.
> >     >
> >     > ??"
> >     > TAB-1664,47703,Virtual I/O Device (VIRTIO) Version 1.1,Bug,"For
> >     consistency of presentation, the ""device and driver in-memory
> structure
> >     layouts"" should always follow descriptive prose in each
> section.","In
> >     2.6.6, 2.6.8, 5.1.6.5.6.1, 5.7.4 (no prose at all), 5.7.6.7, 5.9.5,
> and
> >     5.10.4, the ""device and driver in-memory structure layouts"" appear
> prior
> >     to any prose, which is different from the other sections. Was this a
> >     production, editorial or other type of error"
> >     > TAB-1663,47702,Virtual I/O Device (VIRTIO) Version 1.1,Bug,Recast
> the
> >     sentences in question to remove the hyphens and elsewhere when
> improperly
> >     used in sentences.,"In 2.5 Virtqueues, the ""-"" hyphen appears to
> be a
> >     common precursor to ""i.e."" and elsewhere in the second sentence of
> that
> >     section. By count there are only seven (7) cases of - i.e.
> >     >
> >     > Given the care taken produce this work, it should not be marred by
> >     non-standard English usage such as this."
> >     > TAB-1662,47701,Virtual I/O Device (VIRTIO) Version
> 1.1,Bug,"""Device and
> >     driver in-memory structure layouts are documented using the C struct
> >     syntax.""","1.4 Structure Specifications begins with: ""Many device
> and
> >     driver in-memory structure layouts are documented using the C struct
> >     syntax.""
> >     >
> >     > Many? Not all? Many leave it doubtful that some are defined.
> >     >
> >     > Why not: ""Device and driver in-memory structure layouts are
> documented
> >     using the C struct syntax.""
> >     >
> >     > If you are missing any, add them."
> >     > TAB-1661,47700,Virtual I/O Device (VIRTIO) Version 1.1,Bug,"Define
> >     marking of non-normative text and use it, quite possibly declare all
> notes
> >     non-normative (but check all of the notes first).","I'm assuming
> that 1
> >     Introduction, your ""for example"" under 1.4 Structure
> Specifications, and
> >     at least some of the 62 Notes: are non-normative, but have not been
> so
> >     marked or described. That is you can use non-normative on a section
> heading
> >     and/or say: All notes are non-normative.
> >     >
> >     > In particular I have in mind notes like: 4.1.5.1.2.1
> >     >
> >     > ""Note: For example, a device which does not expect to send
> interrupts at
> >     a high rate might only specify 2 MSI-X vectors.""
> >     >
> >     > In terms of conformance to this specification, clearly
> non-normative
> >     language. As are many of the remaining 61 uses of note.
> >     >
> >     > ??"
> >
> >
> >
> >
> >
> >     ---------------------------------------------------------------------
> >     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
> >
> >
> >
> >
> > --
> >
> > /chet
> > ----------------
> > Chet Ensign
> > Chief Technical Community Steward
> > OASIS: Advancing open standards for the information society
> > http://www.oasis-open.org
> >
> > Primary: +1 973-996-2298
> > Mobile: +1 201-341-1393
>


-- 

/chet
----------------
Chet Ensign
Chief Technical Community Steward
OASIS: Advancing open standards for the information society
http://www.oasis-open.org

Primary: +1 973-996-2298
Mobile: +1 201-341-1393

[-- Attachment #2: Type: text/html, Size: 24338 bytes --]

[virtio-comment] Re: [tab] Re: [virtio-comment] TAB comments on Virtual I/O Device (VIRTIO) Version 1.1

[Patrick Durusau]

[-- Attachment #1.1.1: Type: text/plain, Size: 21001 bytes --]

Chet,

Thanks!

I assume there will be only one copy of the issues, now with the Virtio
JIRA?

I was wondering, can we add users, such as Michael, for a specific set
of issues in JIRA?

I ask because I'll need to remember these issues when we do stats for
TAB reviews for the board.

Thanks!

Hope you are having a great week!

Patrick

On 2/27/19 9:20 AM, Chet Ensign wrote:
> Will do - sorry that I can't get it to the github issues for you; JIRA
> though is straightforward.
>
> On Wed, Feb 27, 2019 at 9:10 AM Michael S. Tsirkin <mst@redhat.com
> <mailto:mst@redhat.com>> wrote:
>
>     Thanks! Yes please do. We mostly switched over to github issues
>     but jira
>     isn't too bad just for this.
>
>
>     On Tue, Feb 26, 2019 at 04:29:42PM -0500, Chet Ensign wrote:
>     > Michael, if it would help, I believe I can move the issues from
>     the TAB JIRA to
>     > the Virtio JIRA. Save you the work of importing them one by one. 
>     >
>     > /chet
>     >
>     > On Tue, Feb 26, 2019 at 3:58 PM Michael S. Tsirkin
>     <mst@redhat.com <mailto:mst@redhat.com>> wrote:
>     >
>     >     On Thu, Feb 21, 2019 at 05:36:51PM -0500, Patrick Durusau wrote:
>     >     > Greetings!
>     >     >
>     >     > Members of the Technical Advisory Board endeavor to
>     comment on all 30 day
>     >     public review drafts.
>     >     >
>     >     > Comments on: Virtual I/O Device (VIRTIO) Version 1.1 CS01
>     PRD01 are
>     >     attached.
>     >     >
>     >     > It isn't necessary to acknowledge each comment separately.
>     A single email
>     >     acknowledging this email will be sufficient.
>     >     >
>     >     > When the TC has acted on these issues, I would appreciate
>     a pointer to
>     >     the TCs resolution as the TAB is tracking the resolution of
>     comments from
>     >     TAB members.
>     >     >
>     >     > Hope everyone is having a great week!
>     >     >
>     >     > Patrick
>     >
>     >
>     >     Thanks a lot for the comments!
>     >     I will try to split this CSV up and create github issues
>     >     so it is easier to address individual comments.
>     >
>     >
>     >
>     >
>     >     > --
>     >     > Patrick Durusau
>     >     > patrick@durusau.net <mailto:patrick@durusau.net>
>     >     > Technical Advisory Board, OASIS (TAB)
>     >     > Editor, OpenDocument Format TC (OASIS), Project Editor
>     ISO/IEC 26300
>     >     > Co-Editor, ISO/IEC 13250-1, 13250-5 (Topic Maps)
>     >     >
>     >     > Another Word For It (blog): http://tm.durusau.net
>     >     > Homepage: http://www.durusau.net
>     >     > Twitter: patrickDurusau
>     >     >
>     >
>     >     > Issue key,Issue id,Affects Version/s,Issue Type,Custom field
>     >     (Proposal),Description
>     >     > TAB-1674,47718,Virtual I/O Device (VIRTIO) Version
>     1.1,Bug,Change
>     >     bulleted lists into numbered lists and *always* introduce a
>     list with the
>     >     number of items to follow.,"Understanding and navigation of
>     content is
>     >     impaired by the use of bulleted lists. Compare for example,
>     2.7.21.1, being
>     >     read aloud and being able to answer/find, where is your
>     place in this list,
>     >     as opposed to the second bulleted list in 2.7 Packed
>     Virtqueues, or either
>     >     of the lists/sub-lists in 2.6.10.1."
>     >     > TAB-1673,47717,Virtual I/O Device (VIRTIO) Version
>     1.1,Bug,Devise and
>     >     insert uniform start and end markers for examples.,"Most of
>     the examples of
>     >     memory structures being with struct but not all. Moreover,
>     most examples
>     >     end with }; but not all, for example, under 2.7.21.3.
>     >     >
>     >     > My usual accessibility checker is offline but if you were
>     reading the
>     >     text aloud, if the start and end of examples is not
>     uniformly signaled to
>     >     someone hearing the text, the examples would be much harder
>     to contrast
>     >     with the surrounding normative text.
>     >     >
>     >     > An accessibility issue?? in general but also a personal
>     one because after
>     >     nearly 30 years as a diabetic my vision remains normal, but
>     they can't
>     >     promise how much longer that will be the case. Adding
>     uniform start and end
>     >     markers won't inconvenience sighted readers and will enhance
>     access to your
>     >     work for those using assistive technologies."
>     >     > TAB-1672,47716,Virtual I/O Device (VIRTIO) Version
>     1.1,Bug,,"We read in
>     >     7.4:
>     >     >
>     >     > ""A non-transitional implementation conforms to this
>     specification if it
>     >     satisfies all of the MUST or REQUIRED level requirements
>     defined above. ""
>     >     >
>     >     > Is that true? ALL the ""MUST"" in all previous sections?
>     Probably not. Or
>     >     maybe it is ""below"" and not ""above"". (always explicitly
>     refer to
>     >     requirements sets by using a sub-section number & name)
>     >     >
>     >     > I suggest to make ""transitional"" just a variable (i.e. a
>     parameter) in
>     >     previous top-level conf clauses. (see TAB conformance
>     guideline [http://
>     >   
>      docs.oasis-open.org/templates/TCHandbook/ConformanceGuidelines.html
>     <http://docs.oasis-open.org/templates/TCHandbook/ConformanceGuidelines.html>,
>     >     section 5.5)??|http://docs.oasis-open.org/templates/TCHandbook/
>     >     ConformanceGuidelines.html)]E.g. someone claiming
>     conformance as ""PCI
>     >     driver"" should always clarify: ""transitional PCI driver"" or
>     >     ""non-transitional PCI driver"""
>     >     > TAB-1671,47715,Virtual I/O Device (VIRTIO) Version
>     1.1,Bug,,"Each
>     >     conformance clause sub-section starts with something that
>     looks like a
>     >     mandatory requirement:
>     >     >
>     >     > e.g.:
>     >     >
>     >     > ""A network device MUST conform to the following normative
>     statements:""
>     >     >
>     >     > But many of the following statements are optional (SHOULD)
>     in the
>     >     specification body. So it is then confusing to say ""...
>     MUST conform to a
>     >     SHOULD statement....""
>     >     >
>     >     > That is why it is NOT recommended to use normative
>     language like MUST
>     >     (and even less SHOULD) in a conformance clause. A conf
>     clause is not there
>     >     to tell you what to do or not do (MUST....), but only to
>     state under which
>     >     conditions you can claim conformance to XYZ.
>     >     >
>     >     > It is better to say:
>     >     >
>     >     > ""an implementation that satisfies all mandatory (MUST)
>     requirements in
>     >     5.1.4.1, 5.1.6.2.... qualifies (or may claim conformance) as
>     a VIRTIO1.1
>     >     network device""
>     >     >
>     >     > Or in some conformance profiles, you can override a SHOULD
>     in the spec
>     >     body and make it mandatory."
>     >     > TAB-1670,47714,Virtual I/O Device (VIRTIO) Version
>     1.1,Bug,,"Sections
>     >     7.2.10 and 7.2.11 are never referred to, by any conformance
>     clause. Same
>     >     for 7.3.10 and 7.3.11.
>     >     >
>     >     > That seems like an omission? They should be used in at
>     least one
>     >     conformance profile each. Or else, these sections should not
>     be normative."
>     >     > TAB-1669,47713,Virtual I/O Device (VIRTIO) Version
>     1.1,Bug,,"Overall,
>     >     well-formed conformance section (one of the best we?? TAB
>     reviewers have
>     >     seen!) The main conformance targets - drivers, devices - are
>     well
>     >     identified. The specification is clearly attributing
>     normative requirements
>     >     to either driver, or device.
>     >     >
>     >     > Some conformance aspects could still be clarified:
>     >     >  * All the subsections under 7.2 or 7.3 are named
>     ""clauses"" in 7.1. So
>     >     their titles should be ""Clause XYZ"". Or else if we want to
>     keep
>     >     ""CLause"" to only the top-level set of requirements - then
>     define just a
>     >     couple of clauses in 7.1, e.g. ""Conformance Clause for
>     VIRTIO1.1
>     >     drivers"". Then all thee following subsections should just
>     be titled
>     >     ""Conformance requirements sets"" e.g. ""COnformance
>     requirements for PCI
>     >     drivers""), and preferably not ""clause"" (keeping
>     ""clause"" for only??
>     >     the full set of requirements that a product can claim for
>     conformance).
>     >     >  * In any case, it is good to associate a clear name to
>     each conformance
>     >     level/profile that can be claimed. For example, ""PCI
>     network driver"" (if
>     >     satisfying 7.2 + 7.2.1 + 7.2.4. Is that a meaningful
>     combination? irt seems
>     >     so according to 7.1). So that there is no ambiguity of what
>     are the valid??
>     >     conformance profiles. Some parameterization of a clause can
>     be used: Look
>     >     in TAB guideline :
>     [http://docs.oasis-open.org/templates/TCHandbook/
>     >     ConformanceGuidelines.html] for ""variable conformance
>     clauses"" (section
>     >     5.5). In other words: define the precise statement that
>     someone should use
>     >     when claiming a conformance profile.
>     >     >
>     >     > ??"
>     >     > TAB-1668,47707,Virtual I/O Device (VIRTIO) Version
>     1.1,Bug,"The
>     >     accessibility site that I commonly use,
>     [https://achecker.ca/checker/
>     >     index.php,] is down tonight but use it to check your usage
>     for other
>     >     problems.
>     >     >
>     >     > ??","In terms of accessibility, ""what follows,""
>     ""below,"" and
>     >     ""follows"" all inhibit the use of VIRTIO by users assisted
>     by reading
>     >     software.
>     >     >
>     >     > Take 2.2 Feature Bits as an example:
>     >     >
>     >     > ""Feature bits are allocated as follows:
>     >     >
>     >     > 0 to 23 Feature bits for the specific device type
>     >     >
>     >     > 24 to 37 Feature bits reserved for extensions to the queue
>     and feature
>     >     negotiation mechanisms
>     >     >
>     >     > 38 and above Feature bits reserved for future extensions.""
>     >     >
>     >     > A sighted reader is clued in that 3 entries follow, but
>     reading software
>     >     does not offer, in this form, the same clue.
>     >     >
>     >     > Compare:
>     >     >
>     >     > ""Feature bits are allocated in three ways:
>     >     >
>     >     > 1. 0 to 23 Feature bits for the specific device type
>     >     >
>     >     > 2. 24 to 37 Feature bits reserved for extensions to the
>     queue and feature
>     >     negotiation mechanisms
>     >     >
>     >     > 3. 38 and above Feature bits reserved for future extensions.""
>     >     >
>     >     > Same text but now both sighted as well as assisted readers
>     know there are
>     >     3 ways to allocate feature bits and each of those ways is
>     numbered and
>     >     recited to the reader.
>     >     >
>     >     > ??
>     >     >
>     >     > ??
>     >     >
>     >     > ??"
>     >     > TAB-1667,47706,Virtual I/O Device (VIRTIO) Version
>     1.1,Bug,Update the
>     >     IEEE 802 link and re-check with
>     [http://validator.w3.org/checklink],"|[IEEE
>     >     802] |IEEE Standard for Local and Metropolitan Area
>     Networks: Overview and
>     >     Architecture,
>     >     > [http://standards.ieee.org/about/get/802/802.html], IEEE|
>     >     >
>     >     > reports a 404.
>     >     >
>     >     > Did you mean:
>     [https://standards.ieee.org/standard/802-2001.html]
>     <https://standards.ieee.org/standard/802-2001.html%5D>?? ??"
>     >     > TAB-1666,47705,Virtual I/O Device (VIRTIO) Version
>     1.1,Bug,Update the
>     >     links indicated and re-check with
>     http://validator.w3.org/checklink,"The
>     >     link checker at [http://validator.w3.org/checklink] reports
>     the following
>     >     redirects:
>     >     >
>     >     >
>     !http://validator.w3.org/checklink/images/info_icons/warning.png!
>     Line:
>     >     6875 [http://www.pcisig.com/] redirected to
>     [http://pcisig.com/] *Status*:
>     >     301 -> 200 OK
>     >     >
>     >     > This is a permanent redirect. The link should be updated.
>     >     >
>     >     >
>     !http://validator.w3.org/checklink/images/info_icons/warning.png!
>     Lines:
>     >     55, 60, 63 [http://www.redhat.com/] redirected to
>     [https://www.redhat.com/
>     >     en] *Status*: 301 -> 200 OK
>     >     >
>     >     > This is a permanent redirect. The link should be updated.
>     >     >
>     >     >
>     !http://validator.w3.org/checklink/images/info_icons/warning.png!
>     Line:
>     >     21250
>     [http://git.qemu-project.org/?p=qemu.git;a=blob;f=docs/specs/
>     >     standard-vga.txt;hb=HEAD] redirected to
>     [https://git.qemu.org/?p=qemu.git;a
>     >     =blob;f=docs/specs/standard-vga.txt;hb=HEAD] *Status*: 301
>     -> 200 OK
>     >     >
>     >     > This is a permanent redirect. The link should be updated.
>     >     >
>     >     >
>     !http://validator.w3.org/checklink/images/info_icons/warning.png!
>     Line:
>     >     768 [http://www.pcisig.com/specifications/pciexpress/]
>     redirected to [http:
>     >     //pcisig.com/specifications/pciexpress/
>     <http://pcisig.com/specifications/pciexpress/>] *Status*: 301 ->
>     200 OK
>     >     >
>     >     > This is a permanent redirect. The link should be updated.
>     >     >
>     >     >
>     !http://validator.w3.org/checklink/images/info_icons/warning.png!
>     Line: 
>     >     [https://www.oasis-open.org/policies-guidelines/tc-process]
>     redirected to [
>     >   
>      https://www.oasis-open.org/policies-guidelines/tc-process-2017-05-26]
>     >     *Status*: 301 -> 200 OK
>     >     >
>     >     > This is a permanent redirect. The link should be updated.
>     >     >
>     >     >
>     !http://validator.w3.org/checklink/images/info_icons/warning.png!
>     Line:
>     >     759 [http://www.pcisig.com/specifications/conventional/]
>     redirected to [
>     >     http://pcisig.com/specifications/conventional/] *Status*:
>     301 -> 200 OK
>     >     >
>     >     > This is a permanent redirect. The link should be updated."
>     >     > TAB-1665,47704,Virtual I/O Device (VIRTIO) Version
>     1.1,Bug,Number and
>     >     label the in-memory structure illustrations and add anchors
>     to enable
>     >     remote pointing to particular illustrations.,"While I
>     appreciate that the
>     >     use of C struct syntax is illustrative only, the in-memory
>     structures it
>     >     documents are normative.
>     >     >
>     >     > And in a number of cases, those in-memory structures occur
>     in the same
>     >     numbered section, making reference to any specified
>     in-memory structure
>     >     uncertain.
>     >     >
>     >     > Labeling and numbering the in-memory structures (to say
>     nothing of adding
>     >     anchors for remote pointing), would greatly improve the
>     usefulness of this
>     >     document.
>     >     >
>     >     > ??"
>     >     > TAB-1664,47703,Virtual I/O Device (VIRTIO) Version
>     1.1,Bug,"For
>     >     consistency of presentation, the ""device and driver
>     in-memory structure
>     >     layouts"" should always follow descriptive prose in each
>     section.","In
>     >     2.6.6, 2.6.8, 5.1.6.5.6.1, 5.7.4 (no prose at all), 5.7.6.7,
>     5.9.5, and
>     >     5.10.4, the ""device and driver in-memory structure
>     layouts"" appear prior
>     >     to any prose, which is different from the other sections.
>     Was this a
>     >     production, editorial or other type of error"
>     >     > TAB-1663,47702,Virtual I/O Device (VIRTIO) Version
>     1.1,Bug,Recast the
>     >     sentences in question to remove the hyphens and elsewhere
>     when improperly
>     >     used in sentences.,"In 2.5 Virtqueues, the ""-"" hyphen
>     appears to be a
>     >     common precursor to ""i.e."" and elsewhere in the second
>     sentence of that
>     >     section. By count there are only seven (7) cases of - i.e.
>     >     >
>     >     > Given the care taken produce this work, it should not be
>     marred by
>     >     non-standard English usage such as this."
>     >     > TAB-1662,47701,Virtual I/O Device (VIRTIO) Version
>     1.1,Bug,"""Device and
>     >     driver in-memory structure layouts are documented using the
>     C struct
>     >     syntax.""","1.4 Structure Specifications begins with: ""Many
>     device and
>     >     driver in-memory structure layouts are documented using the
>     C struct
>     >     syntax.""
>     >     >
>     >     > Many? Not all? Many leave it doubtful that some are defined.
>     >     >
>     >     > Why not: ""Device and driver in-memory structure layouts
>     are documented
>     >     using the C struct syntax.""
>     >     >
>     >     > If you are missing any, add them."
>     >     > TAB-1661,47700,Virtual I/O Device (VIRTIO) Version
>     1.1,Bug,"Define
>     >     marking of non-normative text and use it, quite possibly
>     declare all notes
>     >     non-normative (but check all of the notes first).","I'm
>     assuming that 1
>     >     Introduction, your ""for example"" under 1.4 Structure
>     Specifications, and
>     >     at least some of the 62 Notes: are non-normative, but have
>     not been so
>     >     marked or described. That is you can use non-normative on a
>     section heading
>     >     and/or say: All notes are non-normative.
>     >     >
>     >     > In particular I have in mind notes like: 4.1.5.1.2.1
>     >     >
>     >     > ""Note: For example, a device which does not expect to
>     send interrupts at
>     >     a high rate might only specify 2 MSI-X vectors.""
>     >     >
>     >     > In terms of conformance to this specification, clearly
>     non-normative
>     >     language. As are many of the remaining 61 uses of note.
>     >     >
>     >     > ??"
>     >
>     >
>     >
>     >
>     >
>     >   
>      ---------------------------------------------------------------------
>     >     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
>     >
>     >
>     >
>     >
>     > --
>     >
>     > /chet 
>     > ----------------
>     > Chet Ensign
>     > Chief Technical Community Steward
>     > OASIS: Advancing open standards for the information society
>     > http://www.oasis-open.org
>     >
>     > Primary: +1 973-996-2298
>     > Mobile: +1 201-341-1393 
>
>
>
> -- 
>
> /chet 
> ----------------
> Chet Ensign
> Chief Technical Community Steward
> OASIS: Advancing open standards for the information society
> http://www.oasis-open.org
>
> Primary: +1 973-996-2298
> Mobile: +1 201-341-1393 

-- 
Patrick Durusau
patrick@durusau.net
Technical Advisory Board, OASIS (TAB)
Editor, OpenDocument Format TC (OASIS), Project Editor ISO/IEC 26300
Co-Editor, ISO/IEC 13250-1, 13250-5 (Topic Maps)

Another Word For It (blog): http://tm.durusau.net
Homepage: http://www.durusau.net
Twitter: patrickDurusau 


[-- Attachment #1.1.2: Type: text/html, Size: 32223 bytes --]

[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]

[virtio-comment] Re: [tab] Re: [virtio-comment] TAB comments on Virtual I/O Device (VIRTIO) Version 1.1

[Chet Ensign]

[-- Attachment #1: Type: text/plain, Size: 18497 bytes --]

On Wed, Feb 27, 2019 at 9:32 AM Patrick Durusau <patrick@durusau.net> wrote:

> Chet,
>
> Thanks!
>
> I assume there will be only one copy of the issues, now with the Virtio
> JIRA?
>
Yes. I just made the move. Michael, you'll find 14 new issues in the VIRTIO
JIRA project.

> I was wondering, can we add users, such as Michael, for a specific set of
> issues in JIRA?
>
Patrick, do you mean add them as watchers on one or more issues in the TAB
JIRA? I may need to change the project configuration to do that but I'm
sure I can bulk add a watcher.

> I ask because I'll need to remember these issues when we do stats for TAB
> reviews for the board.
>
Right - that's the one downside is that we lose them from the TAB JIRA

> Thanks!
>
> Hope you are having a great week!
>
> Patrick
> On 2/27/19 9:20 AM, Chet Ensign wrote:
>
> Will do - sorry that I can't get it to the github issues for you; JIRA
> though is straightforward.
>
> On Wed, Feb 27, 2019 at 9:10 AM Michael S. Tsirkin <mst@redhat.com> wrote:
>
>> Thanks! Yes please do. We mostly switched over to github issues but jira
>> isn't too bad just for this.
>>
>>
>> On Tue, Feb 26, 2019 at 04:29:42PM -0500, Chet Ensign wrote:
>> > Michael, if it would help, I believe I can move the issues from the TAB
>> JIRA to
>> > the Virtio JIRA. Save you the work of importing them one by one.
>> >
>> > /chet
>> >
>> > On Tue, Feb 26, 2019 at 3:58 PM Michael S. Tsirkin <mst@redhat.com>
>> wrote:
>> >
>> >     On Thu, Feb 21, 2019 at 05:36:51PM -0500, Patrick Durusau wrote:
>> >     > Greetings!
>> >     >
>> >     > Members of the Technical Advisory Board endeavor to comment on
>> all 30 day
>> >     public review drafts.
>> >     >
>> >     > Comments on: Virtual I/O Device (VIRTIO) Version 1.1 CS01 PRD01
>> are
>> >     attached.
>> >     >
>> >     > It isn't necessary to acknowledge each comment separately. A
>> single email
>> >     acknowledging this email will be sufficient.
>> >     >
>> >     > When the TC has acted on these issues, I would appreciate a
>> pointer to
>> >     the TCs resolution as the TAB is tracking the resolution of
>> comments from
>> >     TAB members.
>> >     >
>> >     > Hope everyone is having a great week!
>> >     >
>> >     > Patrick
>> >
>> >
>> >     Thanks a lot for the comments!
>> >     I will try to split this CSV up and create github issues
>> >     so it is easier to address individual comments.
>> >
>> >
>> >
>> >
>> >     > --
>> >     > Patrick Durusau
>> >     > patrick@durusau.net
>> >     > Technical Advisory Board, OASIS (TAB)
>> >     > Editor, OpenDocument Format TC (OASIS), Project Editor ISO/IEC
>> 26300
>> >     > Co-Editor, ISO/IEC 13250-1, 13250-5 (Topic Maps)
>> >     >
>> >     > Another Word For It (blog): http://tm.durusau.net
>> >     > Homepage: http://www.durusau.net
>> >     > Twitter: patrickDurusau
>> >     >
>> >
>> >     > Issue key,Issue id,Affects Version/s,Issue Type,Custom field
>> >     (Proposal),Description
>> >     > TAB-1674,47718,Virtual I/O Device (VIRTIO) Version 1.1,Bug,Change
>> >     bulleted lists into numbered lists and *always* introduce a list
>> with the
>> >     number of items to follow.,"Understanding and navigation of content
>> is
>> >     impaired by the use of bulleted lists. Compare for example,
>> 2.7.21.1, being
>> >     read aloud and being able to answer/find, where is your place in
>> this list,
>> >     as opposed to the second bulleted list in 2.7 Packed Virtqueues, or
>> either
>> >     of the lists/sub-lists in 2.6.10.1."
>> >     > TAB-1673,47717,Virtual I/O Device (VIRTIO) Version 1.1,Bug,Devise
>> and
>> >     insert uniform start and end markers for examples.,"Most of the
>> examples of
>> >     memory structures being with struct but not all. Moreover, most
>> examples
>> >     end with }; but not all, for example, under 2.7.21.3.
>> >     >
>> >     > My usual accessibility checker is offline but if you were reading
>> the
>> >     text aloud, if the start and end of examples is not uniformly
>> signaled to
>> >     someone hearing the text, the examples would be much harder to
>> contrast
>> >     with the surrounding normative text.
>> >     >
>> >     > An accessibility issue?? in general but also a personal one
>> because after
>> >     nearly 30 years as a diabetic my vision remains normal, but they
>> can't
>> >     promise how much longer that will be the case. Adding uniform start
>> and end
>> >     markers won't inconvenience sighted readers and will enhance access
>> to your
>> >     work for those using assistive technologies."
>> >     > TAB-1672,47716,Virtual I/O Device (VIRTIO) Version 1.1,Bug,,"We
>> read in
>> >     7.4:
>> >     >
>> >     > ""A non-transitional implementation conforms to this
>> specification if it
>> >     satisfies all of the MUST or REQUIRED level requirements defined
>> above. ""
>> >     >
>> >     > Is that true? ALL the ""MUST"" in all previous sections? Probably
>> not. Or
>> >     maybe it is ""below"" and not ""above"". (always explicitly refer to
>> >     requirements sets by using a sub-section number & name)
>> >     >
>> >     > I suggest to make ""transitional"" just a variable (i.e. a
>> parameter) in
>> >     previous top-level conf clauses. (see TAB conformance guideline
>> [http://
>> >     docs.oasis-open.org/templates/TCHandbook/ConformanceGuidelines.html
>> ,
>> >     section 5.5)??|http://docs.oasis-open.org/templates/TCHandbook/
>> >     ConformanceGuidelines.html)]E.g. someone claiming conformance as
>> ""PCI
>> >     driver"" should always clarify: ""transitional PCI driver"" or
>> >     ""non-transitional PCI driver"""
>> >     > TAB-1671,47715,Virtual I/O Device (VIRTIO) Version 1.1,Bug,,"Each
>> >     conformance clause sub-section starts with something that looks
>> like a
>> >     mandatory requirement:
>> >     >
>> >     > e.g.:
>> >     >
>> >     > ""A network device MUST conform to the following normative
>> statements:""
>> >     >
>> >     > But many of the following statements are optional (SHOULD) in the
>> >     specification body. So it is then confusing to say ""... MUST
>> conform to a
>> >     SHOULD statement....""
>> >     >
>> >     > That is why it is NOT recommended to use normative language like
>> MUST
>> >     (and even less SHOULD) in a conformance clause. A conf clause is
>> not there
>> >     to tell you what to do or not do (MUST....), but only to state
>> under which
>> >     conditions you can claim conformance to XYZ.
>> >     >
>> >     > It is better to say:
>> >     >
>> >     > ""an implementation that satisfies all mandatory (MUST)
>> requirements in
>> >     5.1.4.1, 5.1.6.2.... qualifies (or may claim conformance) as a
>> VIRTIO1.1
>> >     network device""
>> >     >
>> >     > Or in some conformance profiles, you can override a SHOULD in the
>> spec
>> >     body and make it mandatory."
>> >     > TAB-1670,47714,Virtual I/O Device (VIRTIO) Version
>> 1.1,Bug,,"Sections
>> >     7.2.10 and 7.2.11 are never referred to, by any conformance clause.
>> Same
>> >     for 7.3.10 and 7.3.11.
>> >     >
>> >     > That seems like an omission? They should be used in at least one
>> >     conformance profile each. Or else, these sections should not be
>> normative."
>> >     > TAB-1669,47713,Virtual I/O Device (VIRTIO) Version
>> 1.1,Bug,,"Overall,
>> >     well-formed conformance section (one of the best we?? TAB reviewers
>> have
>> >     seen!) The main conformance targets - drivers, devices - are well
>> >     identified. The specification is clearly attributing normative
>> requirements
>> >     to either driver, or device.
>> >     >
>> >     > Some conformance aspects could still be clarified:
>> >     >  * All the subsections under 7.2 or 7.3 are named ""clauses"" in
>> 7.1. So
>> >     their titles should be ""Clause XYZ"". Or else if we want to keep
>> >     ""CLause"" to only the top-level set of requirements - then define
>> just a
>> >     couple of clauses in 7.1, e.g. ""Conformance Clause for VIRTIO1.1
>> >     drivers"". Then all thee following subsections should just be titled
>> >     ""Conformance requirements sets"" e.g. ""COnformance requirements
>> for PCI
>> >     drivers""), and preferably not ""clause"" (keeping ""clause"" for
>> only??
>> >     the full set of requirements that a product can claim for
>> conformance).
>> >     >  * In any case, it is good to associate a clear name to each
>> conformance
>> >     level/profile that can be claimed. For example, ""PCI network
>> driver"" (if
>> >     satisfying 7.2 + 7.2.1 + 7.2.4. Is that a meaningful combination?
>> irt seems
>> >     so according to 7.1). So that there is no ambiguity of what are the
>> valid??
>> >     conformance profiles. Some parameterization of a clause can be
>> used: Look
>> >     in TAB guideline : [
>> http://docs.oasis-open.org/templates/TCHandbook/
>> >     ConformanceGuidelines.html] for ""variable conformance clauses""
>> (section
>> >     5.5). In other words: define the precise statement that someone
>> should use
>> >     when claiming a conformance profile.
>> >     >
>> >     > ??"
>> >     > TAB-1668,47707,Virtual I/O Device (VIRTIO) Version 1.1,Bug,"The
>> >     accessibility site that I commonly use, [
>> https://achecker.ca/checker/
>> >     index.php,] is down tonight but use it to check your usage for other
>> >     problems.
>> >     >
>> >     > ??","In terms of accessibility, ""what follows,"" ""below,"" and
>> >     ""follows"" all inhibit the use of VIRTIO by users assisted by
>> reading
>> >     software.
>> >     >
>> >     > Take 2.2 Feature Bits as an example:
>> >     >
>> >     > ""Feature bits are allocated as follows:
>> >     >
>> >     > 0 to 23 Feature bits for the specific device type
>> >     >
>> >     > 24 to 37 Feature bits reserved for extensions to the queue and
>> feature
>> >     negotiation mechanisms
>> >     >
>> >     > 38 and above Feature bits reserved for future extensions.""
>> >     >
>> >     > A sighted reader is clued in that 3 entries follow, but reading
>> software
>> >     does not offer, in this form, the same clue.
>> >     >
>> >     > Compare:
>> >     >
>> >     > ""Feature bits are allocated in three ways:
>> >     >
>> >     > 1. 0 to 23 Feature bits for the specific device type
>> >     >
>> >     > 2. 24 to 37 Feature bits reserved for extensions to the queue and
>> feature
>> >     negotiation mechanisms
>> >     >
>> >     > 3. 38 and above Feature bits reserved for future extensions.""
>> >     >
>> >     > Same text but now both sighted as well as assisted readers know
>> there are
>> >     3 ways to allocate feature bits and each of those ways is numbered
>> and
>> >     recited to the reader.
>> >     >
>> >     > ??
>> >     >
>> >     > ??
>> >     >
>> >     > ??"
>> >     > TAB-1667,47706,Virtual I/O Device (VIRTIO) Version 1.1,Bug,Update
>> the
>> >     IEEE 802 link and re-check with [http://validator.w3.org/checklink
>> ],"|[IEEE
>> >     802] |IEEE Standard for Local and Metropolitan Area Networks:
>> Overview and
>> >     Architecture,
>> >     > [http://standards.ieee.org/about/get/802/802.html], IEEE|
>> >     >
>> >     > reports a 404.
>> >     >
>> >     > Did you mean: [https://standards.ieee.org/standard/802-2001.html]??
>> ??"
>> >     > TAB-1666,47705,Virtual I/O Device (VIRTIO) Version 1.1,Bug,Update
>> the
>> >     links indicated and re-check with
>> http://validator.w3.org/checklink,"The
>> >     link checker at [http://validator.w3.org/checklink] reports the
>> following
>> >     redirects:
>> >     >
>> >     > !http://validator.w3.org/checklink/images/info_icons/warning.png!
>> Line:
>> >     6875 [http://www.pcisig.com/] redirected to [http://pcisig.com/]
>> *Status*:
>> >     301 -> 200 OK
>> >     >
>> >     > This is a permanent redirect. The link should be updated.
>> >     >
>> >     > !http://validator.w3.org/checklink/images/info_icons/warning.png!
>> Lines:
>> >     55, 60, 63 [http://www.redhat.com/] redirected to [
>> https://www.redhat.com/
>> >     en] *Status*: 301 -> 200 OK
>> >     >
>> >     > This is a permanent redirect. The link should be updated.
>> >     >
>> >     > !http://validator.w3.org/checklink/images/info_icons/warning.png!
>> Line:
>> >     21250 [http://git.qemu-project.org/?p=qemu.git;a=blob;f=docs/specs/
>> >     standard-vga.txt;hb=HEAD] redirected to [
>> https://git.qemu.org/?p=qemu.git;a
>> >     =blob;f=docs/specs/standard-vga.txt;hb=HEAD] *Status*: 301 -> 200 OK
>> >     >
>> >     > This is a permanent redirect. The link should be updated.
>> >     >
>> >     > !http://validator.w3.org/checklink/images/info_icons/warning.png!
>> Line:
>> >     768 [http://www.pcisig.com/specifications/pciexpress/] redirected
>> to [http:
>> >     //pcisig.com/specifications/pciexpress/] *Status*: 301 -> 200 OK
>> >     >
>> >     > This is a permanent redirect. The link should be updated.
>> >     >
>> >     > !http://validator.w3.org/checklink/images/info_icons/warning.png!
>> Line:
>> >     [https://www.oasis-open.org/policies-guidelines/tc-process]
>> redirected to [
>> >
>> https://www.oasis-open.org/policies-guidelines/tc-process-2017-05-26]
>> >     *Status*: 301 -> 200 OK
>> >     >
>> >     > This is a permanent redirect. The link should be updated.
>> >     >
>> >     > !http://validator.w3.org/checklink/images/info_icons/warning.png!
>> Line:
>> >     759 [http://www.pcisig.com/specifications/conventional/]
>> redirected to [
>> >     http://pcisig.com/specifications/conventional/] *Status*: 301 ->
>> 200 OK
>> >     >
>> >     > This is a permanent redirect. The link should be updated."
>> >     > TAB-1665,47704,Virtual I/O Device (VIRTIO) Version 1.1,Bug,Number
>> and
>> >     label the in-memory structure illustrations and add anchors to
>> enable
>> >     remote pointing to particular illustrations.,"While I appreciate
>> that the
>> >     use of C struct syntax is illustrative only, the in-memory
>> structures it
>> >     documents are normative.
>> >     >
>> >     > And in a number of cases, those in-memory structures occur in the
>> same
>> >     numbered section, making reference to any specified in-memory
>> structure
>> >     uncertain.
>> >     >
>> >     > Labeling and numbering the in-memory structures (to say nothing
>> of adding
>> >     anchors for remote pointing), would greatly improve the usefulness
>> of this
>> >     document.
>> >     >
>> >     > ??"
>> >     > TAB-1664,47703,Virtual I/O Device (VIRTIO) Version 1.1,Bug,"For
>> >     consistency of presentation, the ""device and driver in-memory
>> structure
>> >     layouts"" should always follow descriptive prose in each
>> section.","In
>> >     2.6.6, 2.6.8, 5.1.6.5.6.1, 5.7.4 (no prose at all), 5.7.6.7, 5.9.5,
>> and
>> >     5.10.4, the ""device and driver in-memory structure layouts""
>> appear prior
>> >     to any prose, which is different from the other sections. Was this a
>> >     production, editorial or other type of error"
>> >     > TAB-1663,47702,Virtual I/O Device (VIRTIO) Version 1.1,Bug,Recast
>> the
>> >     sentences in question to remove the hyphens and elsewhere when
>> improperly
>> >     used in sentences.,"In 2.5 Virtqueues, the ""-"" hyphen appears to
>> be a
>> >     common precursor to ""i.e."" and elsewhere in the second sentence
>> of that
>> >     section. By count there are only seven (7) cases of - i.e.
>> >     >
>> >     > Given the care taken produce this work, it should not be marred by
>> >     non-standard English usage such as this."
>> >     > TAB-1662,47701,Virtual I/O Device (VIRTIO) Version
>> 1.1,Bug,"""Device and
>> >     driver in-memory structure layouts are documented using the C struct
>> >     syntax.""","1.4 Structure Specifications begins with: ""Many device
>> and
>> >     driver in-memory structure layouts are documented using the C struct
>> >     syntax.""
>> >     >
>> >     > Many? Not all? Many leave it doubtful that some are defined.
>> >     >
>> >     > Why not: ""Device and driver in-memory structure layouts are
>> documented
>> >     using the C struct syntax.""
>> >     >
>> >     > If you are missing any, add them."
>> >     > TAB-1661,47700,Virtual I/O Device (VIRTIO) Version 1.1,Bug,"Define
>> >     marking of non-normative text and use it, quite possibly declare
>> all notes
>> >     non-normative (but check all of the notes first).","I'm assuming
>> that 1
>> >     Introduction, your ""for example"" under 1.4 Structure
>> Specifications, and
>> >     at least some of the 62 Notes: are non-normative, but have not been
>> so
>> >     marked or described. That is you can use non-normative on a section
>> heading
>> >     and/or say: All notes are non-normative.
>> >     >
>> >     > In particular I have in mind notes like: 4.1.5.1.2.1
>> >     >
>> >     > ""Note: For example, a device which does not expect to send
>> interrupts at
>> >     a high rate might only specify 2 MSI-X vectors.""
>> >     >
>> >     > In terms of conformance to this specification, clearly
>> non-normative
>> >     language. As are many of the remaining 61 uses of note.
>> >     >
>> >     > ??"
>> >
>> >
>> >
>> >
>> >
>> >
>>  ---------------------------------------------------------------------
>> >     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
>> >
>> >
>> >
>> >
>> > --
>> >
>> > /chet
>> > ----------------
>> > Chet Ensign
>> > Chief Technical Community Steward
>> > OASIS: Advancing open standards for the information society
>> > http://www.oasis-open.org
>> >
>> > Primary: +1 973-996-2298
>> > Mobile: +1 201-341-1393
>>
>
>
> --
>
> /chet
> ----------------
> Chet Ensign
> Chief Technical Community Steward
> OASIS: Advancing open standards for the information society
> http://www.oasis-open.org
>
> Primary: +1 973-996-2298
> Mobile: +1 201-341-1393
>
> --
> Patrick Durusaupatrick@durusau.net
> Technical Advisory Board, OASIS (TAB)
> Editor, OpenDocument Format TC (OASIS), Project Editor ISO/IEC 26300
> Co-Editor, ISO/IEC 13250-1, 13250-5 (Topic Maps)
>
> Another Word For It (blog): http://tm.durusau.net
> Homepage: http://www.durusau.net
> Twitter: patrickDurusau
>
>

-- 

/chet
----------------
Chet Ensign
Chief Technical Community Steward
OASIS: Advancing open standards for the information society
http://www.oasis-open.org

Primary: +1 973-996-2298
Mobile: +1 201-341-1393

[-- Attachment #2: Type: text/html, Size: 27555 bytes --]

[virtio-comment] Re: [tab] Re: [virtio-comment] TAB comments on Virtual I/O Device (VIRTIO) Version 1.1

[Michael S. Tsirkin]

Chet, I have a question:
lots of links to other specifications moved around since virtio 1.0.
Some have a redirect.  Some are just silently broken.  Sure we can keep
chasing them around but I wonder about the utility of this.

OASIS is in fact unusual in that it tries hard to keep old links alive.

Is there an issue wrt OASIS bylaws to link to a wikipedia page instead?
Hard to make any guarantees anyway, but at least for now there are
people that watch this space and keep updating the links there.  For
example:

https://en.wikipedia.org/wiki/IEEE_802

instead of the (now dead)
	http://standards.ieee.org/about/get/802/802.html

Thanks!

-- 
MST

This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.

Subscribe: virtio-comment-subscribe@lists.oasis-open.org
Unsubscribe: virtio-comment-unsubscribe@lists.oasis-open.org
List help: virtio-comment-help@lists.oasis-open.org
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/

[virtio-comment] Re: [tab] Re: [virtio-comment] TAB comments on Virtual I/O Device (VIRTIO) Version 1.1

[Chet Ensign]

[-- Attachment #1: Type: text/plain, Size: 1072 bytes --]

Michael, where are the links you are referring to? Can you point me to some
examples?

On Wed, Feb 27, 2019 at 10:14 AM Michael S. Tsirkin <mst@redhat.com> wrote:

> Chet, I have a question:
> lots of links to other specifications moved around since virtio 1.0.
> Some have a redirect.  Some are just silently broken.  Sure we can keep
> chasing them around but I wonder about the utility of this.
>
> OASIS is in fact unusual in that it tries hard to keep old links alive.
>
> Is there an issue wrt OASIS bylaws to link to a wikipedia page instead?
> Hard to make any guarantees anyway, but at least for now there are
> people that watch this space and keep updating the links there.  For
> example:
>
> https://en.wikipedia.org/wiki/IEEE_802
>
> instead of the (now dead)
>         http://standards.ieee.org/about/get/802/802.html
>
> Thanks!
>
> --
> MST
>


-- 

/chet
----------------
Chet Ensign
Chief Technical Community Steward
OASIS: Advancing open standards for the information society
http://www.oasis-open.org

Primary: +1 973-996-2298
Mobile: +1 201-341-1393

[-- Attachment #2: Type: text/html, Size: 1993 bytes --]

[virtio-comment] Re: [tab] Re: [virtio-comment] TAB comments on Virtual I/O Device (VIRTIO) Version 1.1

[Michael S. Tsirkin]

See VIRTIO-175 (link died, and this isn't the first time for IEEE)
as well as VIRTIO-173 (a bunch of links which now redirect, but
we have no idea whether the old or the new link is
more likely to stay live for longer).


On Wed, Feb 27, 2019 at 10:42:12AM -0500, Chet Ensign wrote:
> Michael, where are the links you are referring to? Can you point me to some
> examples? 
> 
> On Wed, Feb 27, 2019 at 10:14 AM Michael S. Tsirkin <mst@redhat.com> wrote:
> 
>     Chet, I have a question:
>     lots of links to other specifications moved around since virtio 1.0.
>     Some have a redirect.  Some are just silently broken.  Sure we can keep
>     chasing them around but I wonder about the utility of this.
> 
>     OASIS is in fact unusual in that it tries hard to keep old links alive.
> 
>     Is there an issue wrt OASIS bylaws to link to a wikipedia page instead?
>     Hard to make any guarantees anyway, but at least for now there are
>     people that watch this space and keep updating the links there.  For
>     example:
> 
>     https://en.wikipedia.org/wiki/IEEE_802
> 
>     instead of the (now dead)
>             http://standards.ieee.org/about/get/802/802.html
> 
>     Thanks!
> 
>     --
>     MST
> 
> 
> 
> --
> 
> /chet 
> ----------------
> Chet Ensign
> Chief Technical Community Steward
> OASIS: Advancing open standards for the information society
> http://www.oasis-open.org
> 
> Primary: +1 973-996-2298
> Mobile: +1 201-341-1393 

This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.

Subscribe: virtio-comment-subscribe@lists.oasis-open.org
Unsubscribe: virtio-comment-unsubscribe@lists.oasis-open.org
List help: virtio-comment-help@lists.oasis-open.org
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/

Re: [virtio-comment] TAB comments on Virtual I/O Device (VIRTIO) Version 1.1

[Michael S. Tsirkin]

Thanks for the comments!
I would appreciate an advice on the following:

On Thu, Feb 21, 2019 at 05:36:51PM -0500, Patrick Durusau wrote:
> TAB-1668,47707,Virtual I/O Device (VIRTIO) Version 1.1,Bug,"The accessibility site that I commonly use, [https://achecker.ca/checker/index.php,] is down tonight but use it to check your usage for other problems. 

When I attempt to upload the spec to this tool, I receive
a response that the document is too large.
Is there an offline version we could use?

-- 
MST

This publicly archived list offers a means to provide input to the
OASIS Virtual I/O Device (VIRTIO) TC.

In order to verify user consent to the Feedback License terms and
to minimize spam in the list archive, subscription is required
before posting.

Subscribe: virtio-comment-subscribe@lists.oasis-open.org
Unsubscribe: virtio-comment-unsubscribe@lists.oasis-open.org
List help: virtio-comment-help@lists.oasis-open.org
List archive: https://lists.oasis-open.org/archives/virtio-comment/
Feedback License: https://www.oasis-open.org/who/ipr/feedback_license.pdf
List Guidelines: https://www.oasis-open.org/policies-guidelines/mailing-lists
Committee: https://www.oasis-open.org/committees/virtio/
Join OASIS: https://www.oasis-open.org/join/

Re: [virtio-comment] TAB comments on Virtual I/O Device (VIRTIO) Version 1.1

[Patrick Durusau]

[-- Attachment #1.1: Type: text/plain, Size: 1274 bytes --]

Michael,

I can't connect to its parent site at the moment but will keep trying.

In the meantime, apologies but as a former sysadmin, you could try
cutting the file in half, replicate your header on the second half and
test it that way.

Crude I know but gets you results more quickly than I am likely to from
the authors.

Hope you are having a great week!

Patrick


On 2/27/19 10:50 AM, Michael S. Tsirkin wrote:
> Thanks for the comments!
> I would appreciate an advice on the following:
>
> On Thu, Feb 21, 2019 at 05:36:51PM -0500, Patrick Durusau wrote:
>> TAB-1668,47707,Virtual I/O Device (VIRTIO) Version 1.1,Bug,"The accessibility site that I commonly use, [https://achecker.ca/checker/index.php,] is down tonight but use it to check your usage for other problems. 
> When I attempt to upload the spec to this tool, I receive
> a response that the document is too large.
> Is there an offline version we could use?
>
-- 
Patrick Durusau
patrick@durusau.net
Technical Advisory Board, OASIS (TAB)
Editor, OpenDocument Format TC (OASIS), Project Editor ISO/IEC 26300
Co-Editor, ISO/IEC 13250-1, 13250-5 (Topic Maps)

Another Word For It (blog): http://tm.durusau.net
Homepage: http://www.durusau.net
Twitter: patrickDurusau 



[-- Attachment #2: OpenPGP digital signature --]
[-- Type: application/pgp-signature, Size: 833 bytes --]