[VIRTIO-63] Examples (76+) - OASIS Technical Committees Issue Tracker

Details

Type: Bug
Status: Resolved
Priority: Major
Resolution: Fixed
Affects Version/s: virtio 1.0 csprd01
Fix Version/s: virtio 1.0 csprd02
Labels:
None
Environment:

Normative

Proposal:

Hide

Examples should be identified, formatted, labeled and numbered as such.

There may be other examples that I have overlooked. Ask yourself if any text is required for an implementor to follow or is it just advice to help understand the specification? Both are valid and should be in the text of your specification, but, they should also be clearly distinguished one from the other.

Patch: https://lists.oasis-open.org/archives/virtio-comment/201403/msg00001.html

Sorry, one more example in 2.1

*****
The driver MUST update the Device Status ﬁeld in the order below to indicate its progress. This provides a simple low-level diagnostic: it's most useful to imagine them hooked up to traﬃc lights on the console indicating the status of each device. The driver MUST NOT clear a device status bit.
*****

Two normative statements separated by what could go in a note, thus:

A driver MUST update the Device Status ﬁeld in the order below to indicate its progress. A driver MUST NOT clear a device status bit.

Note: This provides a simple low-level diagnostic: it's most useful to imagine them hooked up to traﬃc lights on the console indicating the status of each device.

I would recast: This ﬁeld is 0 upon reset, otherwise at least one bit should be set:

to:

The device status field value is 0 upon reset. Other allowed values are:

Show
Examples should be identified, formatted, labeled and numbered as such. There may be other examples that I have overlooked. Ask yourself if any text is required for an implementor to follow or is it just advice to help understand the specification? Both are valid and should be in the text of your specification, but, they should also be clearly distinguished one from the other. Patch: https://lists.oasis-open.org/archives/virtio-comment/201403/msg00001.html Sorry, one more example in 2.1 ***** The driver MUST update the Device Status ﬁeld in the order below to indicate its progress. This provides a simple low-level diagnostic: it's most useful to imagine them hooked up to traﬃc lights on the console indicating the status of each device. The driver MUST NOT clear a device status bit. ***** Two normative statements separated by what could go in a note, thus: A driver MUST update the Device Status ﬁeld in the order below to indicate its progress. A driver MUST NOT clear a device status bit. Note: This provides a simple low-level diagnostic: it's most useful to imagine them hooked up to traﬃc lights on the console indicating the status of each device. I would recast: This ﬁeld is 0 upon reset, otherwise at least one bit should be set: to: The device status field value is 0 upon reset. Other allowed values are:
Resolution:

Hide

accepted on 2014-03-11
applied in commit r322

Show
accepted on 2014-03-11 applied in commit r322

Description

2 Basic Facilities of a Virtio Device reads in part:

*****
To reinforce this the examples use typenames like "le16" instead of "uint16_t".
*****

I don't think this is part of the "normative" part of the specification. The "normative" portion of a specification consists of the statements and rules that an implementer follows in order to conform to the specification.

This statement doesn't look "normative" to me.

If it was intended as an aid to the reader, not something they follow but something helpful to know, then it should be a note. Which is formatted in such a way to separate it from the normative text. So that when you reference a section as part of a conformance clause statement, everyone knows what part of it is to be followed and which parts not.

For example, you could say under section 1, that all notes in the specification are non-normative. That keeps you from having to mark every example as non-normative. They still need distinct formatting but that is a separate issue.

By my count, you use example/examples some 17 times so at a minimum, all of those should be extracted and written as notes.

I am assuming that under 2.3 Configuration Space, the grayed material that begins: u32 before, after is also an example? I could some 59 of those in the specification.

BTW, all examples should be numbered serially in the specification. It facilitates references to examples by the specification and other texts.

Examples (76+)

Details

Description

Attachments

Activity

People

Dates