[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] Re: [PATCH v2 2/3] include/public: add better interface description to usbif.h
> On 29 Sep 2021, at 08:46, Juergen Gross <jgross@xxxxxxxx> wrote: > > The PV USB protocol is poorly described. Add a more detailed > description to the usbif.h header file. > > Signed-off-by: Juergen Gross <jgross@xxxxxxxx> Reviewed-by: Luca Fancellu <luca.fancellu@xxxxxxx> > --- > xen/include/public/io/usbif.h | 164 ++++++++++++++++++++++++++++++++++ > 1 file changed, 164 insertions(+) > > diff --git a/xen/include/public/io/usbif.h b/xen/include/public/io/usbif.h > index 96b9fb661d..dd378bcba5 100644 > --- a/xen/include/public/io/usbif.h > +++ b/xen/include/public/io/usbif.h > @@ -32,6 +32,34 @@ > #include "../grant_table.h" > > /* > + * Detailed Interface Description > + * ============================== > + * The pvUSB interface is using a split driver design: a frontend driver in > + * the guest and a backend driver in a driver domain (normally dom0) having > + * access to the physical USB device(s) being passed to the guest. > + * > + * The frontend and backend drivers use XenStore to initiate the connection > + * between them, the I/O activity is handled via two shared ring pages and an > + * event channel. As the interface between frontend and backend is at the USB > + * host connector level, multiple (up to 31) physical USB devices can be > + * handled by a single connection. > + * > + * The Xen pvUSB device name is "qusb", so the frontend's XenStore entries > are > + * to be found under "device/qusb", while the backend's XenStore entries are > + * under "backend/<guest-dom-id>/qusb". > + * > + * When a new pvUSB connection is established, the frontend needs to setup > the > + * two shared ring pages for communication and the event channel. The ring > + * pages need to be made available to the backend via the grant table > + * interface. > + * > + * One of the shared ring pages is used by the backend to inform the frontend > + * about USB device plug events (device to be added or removed). This is the > + * "conn-ring". > + * > + * The other ring page is used for USB I/O communication (requests and > + * responses). This is the "urb-ring". > + * > * Feature and Parameter Negotiation > * ================================= > * The two halves of a Xen pvUSB driver utilize nodes within the XenStore to > @@ -99,6 +127,142 @@ > * The machine ABI rules governing the format of all ring request and > * response structures. > * > + * Protocol Description > + * ==================== > + * > + *-------------------------- USB device plug events > -------------------------- > + * > + * USB device plug events are send via the "conn-ring" shared page. As only > + * events are being sent, the respective requests from the frontend to the > + * backend are just dummy ones. > + * The events sent to the frontend have the following layout: > + * 0 1 2 3 octet > + * +----------------+----------------+----------------+----------------+ > + * | id | portnum | speed | 4 > + * +----------------+----------------+----------------+----------------+ > + * id - uint16_t, event id (taken from the actual frontend dummy request) > + * portnum - uint8_t, port number (1 ... 31) > + * speed - uint8_t, device USBIF_SPEED_*, USBIF_SPEED_NONE == unplug > + * > + * The dummy request: > + * 0 1 octet > + * +----------------+----------------+ > + * | id | 2 > + * +----------------+----------------+ > + * id - uint16_t, guest supplied value (no need for being unique) > + * > + *-------------------------- USB I/O request > --------------------------------- > + * > + * A single USB I/O request on the "urb-ring" has the following layout: > + * 0 1 2 3 octet > + * +----------------+----------------+----------------+----------------+ > + * | id | nr_buffer_segs | 4 > + * +----------------+----------------+----------------+----------------+ > + * | pipe | 8 > + * +----------------+----------------+----------------+----------------+ > + * | transfer_flags | buffer_length | 12 > + * +----------------+----------------+----------------+----------------+ > + * | request type specific | 16 > + * | data | 20 > + * +----------------+----------------+----------------+----------------+ > + * | seg[0] | 24 > + * | data | 28 > + * +----------------+----------------+----------------+----------------+ > + * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/| > + * +----------------+----------------+----------------+----------------+ > + * | seg[USBIF_MAX_SEGMENTS_PER_REQUEST - 1] | 144 > + * | data | 148 > + * +----------------+----------------+----------------+----------------+ > + * Bit field bit number 0 is always least significant bit, undefined bits > must > + * be zero. > + * id - uint16_t, guest supplied value > + * nr_buffer_segs - uint16_t, number of segment entries in seg[] array > + * pipe - uint32_t, bit field with multiple information: > + * bits 0-4: port request to send to > + * bit 5: unlink request with specified id (cancel I/O) if set (see > below) > + * bit 7: direction (1 = read from device) > + * bits 8-14: device number on port > + * bits 15-18: endpoint of device > + * bits 30-31: request type: 00 = isochronous, 01 = interrupt, > + * 10 = control, 11 = bulk > + * transfer_flags - uint16_t, bit field with processing flags: > + * bit 0: less data than specified allowed > + * buffer_length - uint16_t, total length of data > + * request type specific data - 8 bytes, see below > + * seg[] - array with 8 byte elements, see below > + * > + * Request type specific data for isochronous request: > + * 0 1 2 3 octet > + * +----------------+----------------+----------------+----------------+ > + * | interval | start_frame | 4 > + * +----------------+----------------+----------------+----------------+ > + * | number_of_packets | nr_frame_desc_segs | 8 > + * +----------------+----------------+----------------+----------------+ > + * interval - uint16_t, time interval in msecs between frames > + * start_frame - uint16_t, start frame number > + * number_of_packets - uint16_t, number of packets to transfer > + * nr_frame_desc_segs - uint16_t number of seg[] frame descriptors elements > + * > + * Request type specific data for interrupt request: > + * 0 1 2 3 octet > + * +----------------+----------------+----------------+----------------+ > + * | interval | 0 | 4 > + * +----------------+----------------+----------------+----------------+ > + * | 0 | 8 > + * +----------------+----------------+----------------+----------------+ > + * interval - uint16_t, time in msecs until interruption > + * > + * Request type specific data for control request: > + * 0 1 2 3 octet > + * +----------------+----------------+----------------+----------------+ > + * | data of setup packet | 4 > + * | | 8 > + * +----------------+----------------+----------------+----------------+ > + * > + * Request type specific data for bulk request: > + * 0 1 2 3 octet > + * +----------------+----------------+----------------+----------------+ > + * | 0 | 4 > + * | 0 | 8 > + * +----------------+----------------+----------------+----------------+ > + * > + * Request type specific data for unlink request: > + * 0 1 2 3 octet > + * +----------------+----------------+----------------+----------------+ > + * | unlink_id | 0 | 4 > + * +----------------+----------------+----------------+----------------+ > + * | 0 | 8 > + * +----------------+----------------+----------------+----------------+ > + * unlink_id - uint16_t, request id of request to terminate > + * > + * seg[] array element layout: > + * 0 1 2 3 octet > + * +----------------+----------------+----------------+----------------+ > + * | gref | 4 > + * +----------------+----------------+----------------+----------------+ > + * | offset | length | 8 > + * +----------------+----------------+----------------+----------------+ > + * gref - uint32_t, grant reference of buffer page > + * offset - uint16_t, offset of buffer start in page > + * length - uint16_t, length of buffer in page > + * > + *-------------------------- USB I/O response > -------------------------------- > + * > + * 0 1 2 3 octet > + * +----------------+----------------+----------------+----------------+ > + * | id | start_frame | 4 > + * +----------------+----------------+----------------+----------------+ > + * | status | 8 > + * +----------------+----------------+----------------+----------------+ > + * | actual_length | 12 > + * +----------------+----------------+----------------+----------------+ > + * | error_count | 16 > + * +----------------+----------------+----------------+----------------+ > + * id - uint16_t, id of the request this response belongs to > + * start_frame - uint16_t, start_frame this response (iso requests only) > + * status - int32_t, USBIF_STATUS_* (non-iso requests) > + * actual_length - uint32_t, actual size of data transferred > + * error_count - uint32_t, number of errors (iso requests) > */ > > enum usb_spec_version { > -- > 2.26.2 > >
|
![]() |
Lists.xenproject.org is hosted with RackSpace, monitoring our |