Re: [virtio-comment] [PATCH 15/18] CCW: Separate normative and descriptive sections.

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

Cornelia Huck <cornelia.huck@de.ibm.com> writes:
> On Wed, 19 Feb 2014 17:09:52 +1030
> Rusty Russell <rusty@au1.ibm.com> wrote:
>> +A driver SHOULD attempt to provide the correct length even if it
>> +suppresses length checks.
>
> This sentence needs to be expanded, or it is hard to understand due to
> missing context after the move:
>
> "A driver SHOULD attempt to provide the correct length in a channel
> command even if it suppresses length checks for that command."

Thanks, fixed.  In some ways, having a single list of requirement is
clear, in others it means we double up a bit.

>> +\devicenormative{Virtio Transport Options / Virtio over channel I/O / Device Operation / Guest->Host Notification}
>>  The device MUST ignore bits 0-31 (counting from the left) of GPR2.
>>  This aligns passing the subchannel ID with the way it is passed
>>  for the existing I/O instructions.
>> 
>>  Host cookie is an optional per-virtqueue 64 bit value that MAY be
>>  used by the hypervisor to speed up the notification execution.
>> +
>> +\drivernormative{Virtio Transport Options / Virtio over channel I/O / Device Operation / Guest->Host Notification}
>>  For each notification, the output value is returned in GPR2 and
>
> Hm, don't we need to split that? It is the device that returns the
> value in gpr2 and the driver that should put it into gpr4 for the next
> notification.

Ah, I was a bit unclear on this.

We already say:

  Host cookie is an optional per-virtqueue 64 bit value that MAY be
  used by the hypervisor to speed up the notification execution.

So the requirement is a SHOULD or a MUST?

I tidied the whole thing up a bit more.    Here's what I've got for now
in my feedback git tree:

\devicenormative{Virtio Transport Options / Virtio over channel I/O / Device Operation / Guest->Host Notification}
The device MUST ignore bits 0-31 (counting from the left) of GPR2.
This aligns passing the subchannel ID with the way it is passed
for the existing I/O instructions.

The driver MAY return a 64-bit host cookie in GPR2 to speed up the
notification execution.

\drivernormative{Virtio Transport Options / Virtio over channel I/O / Device Operation / Guest->Host Notification}

For each notification, the driver SHOULD use GPR4 to pass the host cookie received in GPR2 from the previous notication.

\begin{note}
For example:
\begin{lstlisting}
info->cookie = do_notify(schid,
                         virtqueue_get_queue_index(vq),
                         info->cookie);
\end{lstlisting}
\end{note}
==

Cheers,
Rusty.