Re: [virtio-dev] [PATCH 05/14] legacy: make message framing normative

[Rusty Russell <rusty@au1.ibm.com>]

"Michael S. Tsirkin" <mst@redhat.com> writes:
> TODO: we really should be more specific
> ---
>  content.tex | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/content.tex b/content.tex
> index 3e7dcfc..2f467d5 100644
> --- a/content.tex
> +++ b/content.tex
> @@ -344,7 +344,7 @@ addition, the specification for virtio_blk SCSI commands required
>  intuiting field lengths from frame boundaries (see
>   \ref{sec:Device Types / Block Device / Device Operation / Legacy Interface: Device Operation}~\nameref{sec:Device Types / Block Device / Device Operation / Legacy Interface: Device Operation})
>  
> -It is thus recommended that when using legacy interfaces, transitional
> +It is thus RECOMMENDED that when using legacy interfaces, transitional
>  drivers be conservative in their assumptions, unless the
>  VIRTIO_F_ANY_LAYOUT feature is accepted.

Yes, let's turn this into a requirement, but we'll need to do it for
each section.  These requirements need to be in normative sections, too.

ie replace this with:

   Thus the VIRTIO_F_ANY_LAYOUT feature was introduced to indicate that
   no assumptions were made about framing.  Requirements for
   transitional drivers when this is not negotiated are included in each
   device section.

Net:

    When using legacy interfaces, transitional drivers which have not
    negotiated VIRTIO_F_ANY_LAYOUT MUST use a single descriptor for the
    struct virtio_net_hdr on both transmit and receive, with the network
    data in the following descriptors.  See \ref{sec:Basic Facilities of a
    Virtio Device / Virtqueues / Message Framing}.

Block: (Replaces existing "Historically, devices assumed that...")

    When using legacy interfaces, transitional drivers which have not
    negotiated VIRTIO_F_ANY_LAYOUT:

    \begin{itemize}

    \item MUST use a single 8-byte descriptor containing \field{type},
          \field{reseved} and \field{sector}, followed by descriptors
          for \field{data}, then finally a separate 1-byte descriptor
          for \field{status}.

    \item For SCSI commands there are additional constraints.
          \field{errors}, \field{data_len}, \field{sense_len} and
          \field{residual} MUST reside in a single, separate
          device-writable descriptor, \field{sense} MUST reside in a
          single separate device-writable descriptor of size 96 bytes,
          and \field{errors}, \field{data_len}, \field{sense_len} and
          \field{residual} MUST reside a single separate
          device-writable descriptor.
    \end{itemize}

    See \ref{sec:Basic Facilities of a Virtio Device / Virtqueues / Message Framing}.

Console:
    
    When using legacy interfaces, transitional drivers which have not
    negotiated VIRTIO_F_ANY_LAYOUT MUST use only a single descriptor for
    all buffers in the control receiveq and control transmitq.

Entropy: nothing
Memory Balloon Device: nothing (qemu always handled this correctly)

SCSI:

    When using legacy interfaces, transitional drivers which have not
    negotiated VIRTIO_F_ANY_LAYOUT MUST use a single descriptor for the
    \field{lun}, \field{id}, \field{task_attr}, \field{prio},
    \field{crn} and \field{cdb} fields, and MUST only use a single
    descriptor for the \field{sense_len}, \field{residual},
    \field{status_qualifier}, \field{status}, \field{response} and
    \field{sense} fields.

Cheers,
Rusty.