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