[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [tab] Re: [virtio-comment] TAB comments on Virtual I/O Device (VIRTIO) Version 1.1
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
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]