|
[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 |