Re: [Qemu-devel] virtio scsi host draft specification, v2

[Paolo Bonzini]

> > Device initialization
> > ---------------------
> >
> > The initialization routine should first of all discover the device's
> > control virtqueues.
> >
> > The driver should then place at least a buffer in the control receiveq.
>
> Size of the buffer?

Good catch.  I'll add this to the configuration information.

> >      The cdb, data and sense fields must reside in separate buffers.
> >      The cdb field is always read-only.  The data buffers may be either
> >      read-only or write-only, depending on the request, with the read-only
> >      buffers coming first.  The sense buffer is always write-only.
> >
> >      The request shall have num_dataout read-only data buffers and
> >      num_datain write-only data buffers.  One of these two values must be
> >      zero if the VIRTIO_SCSI_F_INOUT has not been negotiated.
>
> Why do num_datain/num_dataout need to be there?
> We can just look at the number of io/out bufs in
> virtio descriptors, no?

This depends on having a single variable-sized datum per direction.  I'd 
rather avoid this assumption.

> Also, from experience, it's better not to have any layout
> assumptions - let the guest stick everything in a single
> in + single out buffer if it desires.

Ok, changed.

> >      Remaining fields are filled in by the device.  The sense_len field
> >      indicates the number of bytes actually written to the sense buffer,
> >      while the residual field indicates the residual size, calculated as
> >      data_length - number_of_transferred_bytes.
>
> Again virtio gives you total number of written bytes in the used len
> field.  So just one of these fields will be enough.

The two fields give completely different information (sense vs. real 
data), and the math has to be done anyway in either the driver or the 
device.  The device is going to be written just once and actually it 
already has the separate information, so I put it in the struct and 
spared some annoyance to driver writers.

> > The control receiveq is used by the device to report information on
> > logical units that are attached to it.  The driver should always
> > leave a few (?) buffers ready in the control receiveq.  The device may
> > end up dropping events if it finds no buffer ready.
>
> [...] It looks like there's a finite number of possible events.

If you keep opening and closing the tray from the guest, you could fire 
a possibly unbounded number of events.

> If this mechanism is unreliable, how is it useful?

Events alone are unreliable, but the combination of events+sense is 
reliable.  And events+sense are still useful because:

1) sense codes only provide information when the driver next accesses 
the unit or, at best, the target.  Until then, the driver has no clue 
that the event happened.  Events can be reported at the time they 
happen.  This is important for example when the host requests a clean 
hot-unplug of a disk: if the disk is idle in the guest, the driver may 
never see the event and acknowledge the hot-unplug!

2) for this reason, unit attention has no way to signal events on a 
target that is unknown to the driver (because it has just been hotplugged).

Events and sense codes together are reliable because the driver is aware 
of dropped events.  The driver can react to it by rescanning the bus 
(which will let the driver see the unit attention conditions) and 
polling CD-ROM units for events it had subscribed to.

I'll add a short version of the above text to the spec, and I'll also 
add the following dummy event:

- No event

    #define VIRTIO_SCSI_T_NO_EVENT         0

    This event is fired in the following cases:

    1) When the device detects in the eventq a buffer that is shorter
    than what is indicated in the configuration field, it will use
    it immediately and put this dummy value in the event field.
    A well-written driver will never observe this situation.

    2) When events are dropped, the device may signal this event as
    soon as the drivers makes a buffer available, in order to request
    action from the driver.  In this case, of course, this event will
    be reported with the VIRTIO_SCSI_T_EVENTS_MISSED flag.

This will make it even clearer that no queuing is needed.

> > - Asynchronous notification
> >
> >      #define VIRTIO_SCSI_T_ASYNC_NOTIFY     1
> >
> >      struct virtio_scsi_an_event {
> >          u8  lun[8];
> >          u32 event;
> >      }
> >
> >      #define VIRTIO_SCSI_EVT_ASYNC_MEDIA_CHANGE        16
> >
> >      By sending this event, the device signals that an event was
> >      fired from a physical interface.  The device only sends events
> >      that the driver has subscribed to via the "Asynchronous notification
> >      subscription" command.
> >
> >      All fields are written by the device.  The event field is set to
> >      VIRTIO_SCSI_T_ASYNC_NOTIFY.
>
> We'll have to define events, right?

They are defined in terms of annex A of the MMC spec (see the 
"Asynchronous notification query" command).  Media change is the only 
supported event for now, but others are already defined by the MMC spec.

Paolo