Uploaded image for project: 'OASIS Virtual I/O Device (VIRTIO) TC'
  1. OASIS Virtual I/O Device (VIRTIO) TC
  2. VIRTIO-89

VIRTIO Spec feedback #7 From: Arun Subbarao

    XMLWordPrintable

    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
    • Proposal:
      Hide

      Use \field{} for all register and field names.

      This currently just makes it italic. Generally this means changing
      phrases of form "the XXX field" to "\field

      {XXX}

      ", but other minor
      consistency and formatting changes were made along the way:

      1) Device Status became "device status" to match other fields.

      2) PCI: The legacy PCI fields now have the same name as modern ones (where
      appropriate) so the general text still stands.

      3) PCI: the msix_config field is renamed config_msix_vector to match the
      queue equivalent.

      4) MMIO: use italics for field names in table instead of bold (to match
      the rest of the document)

      5) MMIO: extra spacing in "QueueDescLow/ QueueDescHigh" and "QueueUsedLow/
      QueueUsedHigh" removed.

      6) NET: CAN changed to MAY (was: 'a transitional device CAN defer MAC
      update, or CAN defer')

      7) SCSI: control commands are now an item list, for better formatting.

      8) SCSI: events now an item list. reason fields now a description list.

      9) VIRTIO_F_RING_EVENT_IDX is now a coherent sentence instead of just
      ending "; the flags field is used".

      Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>

      Show
      Use \field{} for all register and field names. This currently just makes it italic. Generally this means changing phrases of form "the XXX field" to "\field {XXX} ", but other minor consistency and formatting changes were made along the way: 1) Device Status became "device status" to match other fields. 2) PCI: The legacy PCI fields now have the same name as modern ones (where appropriate) so the general text still stands. 3) PCI: the msix_config field is renamed config_msix_vector to match the queue equivalent. 4) MMIO: use italics for field names in table instead of bold (to match the rest of the document) 5) MMIO: extra spacing in "QueueDescLow/ QueueDescHigh" and "QueueUsedLow/ QueueUsedHigh" removed. 6) NET: CAN changed to MAY (was: 'a transitional device CAN defer MAC update, or CAN defer') 7) SCSI: control commands are now an item list, for better formatting. 8) SCSI: events now an item list. reason fields now a description list. 9) VIRTIO_F_RING_EVENT_IDX is now a coherent sentence instead of just ending "; the flags field is used". Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>
    • Resolution:
      Hide

      Decision: 2014-02-11 minutes: Applied
      revision r238

      Show
      Decision: 2014-02-11 minutes: Applied revision r238

      Description

      Link to Mail: https://lists.oasis-open.org/archives/virtio-comment/201401/msg00058.html
      Commenter name: Arun Subbarao <asubbarao@lnxw.com>

      (PARTIAL: there is more feedback)

      The lack of any kind of distinguishing emphasis used consistently with field names in this document makes it hard to read. For example, here, is it literally the next field or the field called "next"? Because there is a field called "next" defined by this spec. This made me scroll back to the used ring definition to refresh the meaning of field "next" in my head, only to realize there is no such field in that particular structure. You are not kind to the reader.

      If you search for the field name "avail_event", you will see that sometimes it is emphasized with quotes and sometimes it isn't. Probably better to use a monospace font instead.

        Attachments

          Activity

            People

            • Assignee:
              Unassigned
              Reporter:
              mstsirkin Michael S. Tsirkin
            • Watchers:
              1 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved: