[PATCH][14/17] USB virt 2.6 split driver---USB interdomain protocol

[PATCH][14/17] USB virt 2.6 split driver---USB interdomain protocol

[harry]

[-- Attachment #1: Type: text/plain, Size: 713 bytes --]

This patch defines the USB interdomain protocol which consists of a
number of transactions and a message sent using the xenidc_endpoint
code.

This protocol is a direct translation of the 2.4 protocol and uses
polling for device detection.

There is an issue with queued commands during error recovery.  The
queued commands need to be stalled during the unlink process but
currently they are not.

Both the polling and the queued commands issues need to be fixed.  This
may affect the protocol.

The current protocol is good enough for read only access to USB devices
and works for read-write access but is not safe for write access during
error recovery.

Signed-off-by: Harry Butterworth <butterwo@uk.ibm.com>


[-- Attachment #2: p14-usb-protocol.patch --]
[-- Type: text/x-patch, Size: 12364 bytes --]

diff -r a83315fe905d -r 941c7dbc1353 xen/include/public/io/usbif.h
--- /dev/null	Mon Nov 21 11:09:25 2005
+++ b/xen/include/public/io/usbif.h	Mon Nov 21 11:09:54 2005
@@ -0,0 +1,344 @@
+/*****************************************************************************/
+/* FE->BE transactions for the USB split driver interface.                   */
+/*                                                                           */
+/* Copyright (c) 2005 Harry Butterworth IBM Corporation                      */
+/*                                                                           */
+/* This program is free software; you can redistribute it and/or modify it   */
+/* under the terms of the GNU General Public License as published by the     */
+/* Free Software Foundation; either version 2 of the License, or (at your    */
+/* option) any later version.                                                */
+/*                                                                           */
+/* This program is distributed in the hope that it will be useful, but       */
+/* WITHOUT ANY WARRANTY; without even the implied warranty of                */
+/* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General */
+/* Public License for more details.                                          */
+/*                                                                           */
+/* You should have received a copy of the GNU General Public License along   */
+/* with this program; if not, write to the Free Software Foundation, Inc.,   */
+/* 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA                   */
+/*                                                                           */
+/*****************************************************************************/
+
+/*****************************************************************************/
+/* Based on the previous usbif.h by Mark Williamson and blkif.h, original    */
+/* copyright notice follows...                                               */
+/*****************************************************************************/
+
+/******************************************************************************
+ * usbif.h
+ * 
+ * Unified block-device I/O interface for Xen guest OSes.
+ * 
+ * Copyright (c) 2003-2004, Keir Fraser
+ */
+
+#ifndef __SHARED_USBIF_H__
+#define __SHARED_USBIF_H__
+
+#include <asm-xen/xenidc.h>
+
+/* All transactions have the same header which specifies the type of the     */
+/* transaction.                                                              */
+
+typedef struct usbif_transaction_parameters_header_struct
+ usbif_transaction_parameters_header;
+
+struct usbif_transaction_parameters_header_struct {
+	u8 transaction_type;
+	u8 reserved[7];
+};
+
+/* There are three types of transaction: */
+
+#define USBIF_TRANSACTION_TYPE_PROBE 0
+#define USBIF_TRANSACTION_TYPE_RESET 1
+#define USBIF_TRANSACTION_TYPE_IO    2
+
+/* The probe transaction is used to test whether a USB device is connected   */
+/* to a port.                                                                */
+/* Port numbers start at 1.                                                  */
+
+typedef struct usbif_probe_transaction_parameters_struct
+ usbif_probe_transaction_parameters;
+
+struct usbif_probe_transaction_parameters_struct {
+	usbif_transaction_parameters_header header;
+	u32 port;
+	u8 reserved[4];
+};
+
+typedef struct usbif_probe_transaction_status_struct
+ usbif_probe_transaction_status;
+
+struct usbif_probe_transaction_status_struct {
+	u8 result;
+	u8 reserved[7];
+};
+
+#define USBIF_PROBE_RESULT_NO_DEVICE      0
+#define USBIF_PROBE_RESULT_DEVICE_PRESENT 1
+
+/* The reset transaction is used to reset a port. On success, the speed the  */
+/* port is operating at after the reset is returned.                         */
+
+typedef struct usbif_reset_transaction_parameters_struct
+ usbif_reset_transaction_parameters;
+
+struct usbif_reset_transaction_parameters_struct {
+	usbif_transaction_parameters_header header;
+	u32 port;
+	u8 reserved[4];
+};
+
+/* On success, the reset returns status... */
+
+typedef struct usbif_reset_transaction_status_struct
+ usbif_reset_transaction_status;
+
+struct usbif_reset_transaction_status_struct {
+	u8 result;
+	u8 reserved[7];
+};
+
+#define USBIF_RESET_RESULT_FULL_SPEED 0
+#define USBIF_RESET_RESULT_LOW_SPEED  1
+#define USBIF_RESET_RESULT_HIGH_SPEED 2
+
+/* Aside from the usual transport errors, the reset transaction might fail   */
+/* if there is no device.                                                    */
+
+/* All IO transactions have a header which specifies the type of IO          */
+/* transaction and contains parameters common to all types of IO transaction.*/
+
+typedef struct usbif_io_transaction_parameters_header_struct
+ usbif_io_transaction_parameters_header;
+
+struct usbif_io_transaction_parameters_header_struct {
+	usbif_transaction_parameters_header header;
+	u8 io_transaction_type;
+	u8 device_number;
+	u8 endpoint;
+	u8 direction;
+	u32 unlink_id;
+	u32 flags;
+	u32 reserved;
+	xenidc_remote_buffer_reference rbr;
+};
+
+#define USBIF_IO_TRANSACTION_TYPE_CONTROL     0
+#define USBIF_IO_TRANSACTION_TYPE_BULK        1
+#define USBIF_IO_TRANSACTION_TYPE_INTERRUPT   2
+#define USBIF_IO_TRANSACTION_TYPE_ISOCHRONOUS 3
+/* Not a transaction type. For array bounds: */
+#define USBIF_IO_TRANSACTION_TYPE_LIMIT 4
+
+#define USBIF_IO_TRANSACTION_DIRECTION_OUT 0
+#define USBIF_IO_TRANSACTION_DIRECTION_IN  1
+
+#define USBIF_IO_FLAGS_SHORT_NOT_OK 0x00000001
+#define USBIF_IO_FLAGS_ZERO_PACKET  0x00000002
+
+typedef struct usbif_control_io_transaction_parameters_struct
+ usbif_control_io_transaction_parameters;
+
+struct usbif_control_io_transaction_parameters_struct {
+	usbif_io_transaction_parameters_header header;
+	u8 setup[8];
+};
+
+typedef struct usbif_bulk_io_transaction_parameters_struct
+ usbif_bulk_io_transaction_parameters;
+
+struct usbif_bulk_io_transaction_parameters_struct {
+	usbif_io_transaction_parameters_header header;
+};
+
+typedef struct usbif_interrupt_io_transaction_parameters_struct
+ usbif_interrupt_io_transaction_parameters;
+
+struct usbif_interrupt_io_transaction_parameters_struct {
+	usbif_io_transaction_parameters_header header;
+	u32 interval;
+};
+
+typedef struct usbif_isochronous_io_transaction_parameters_struct
+ usbif_isochronous_io_transaction_parameters;
+
+struct usbif_isochronous_io_transaction_parameters_struct {
+	usbif_io_transaction_parameters_header header;
+	u32 interval;
+	xenidc_remote_buffer_reference schedule_rbr;
+	u32 packet_count;
+};
+
+typedef struct usbif_isochronous_io_schedule_element_struct
+ usbif_isochronous_io_schedule_element;
+
+struct usbif_isochronous_io_schedule_element_struct {
+	xenidc_buffer_byte_count offset;	/* IN offset into header's rbr */
+	xenidc_buffer_byte_count length;	/* IN = expected, OUT = actual */
+	xenidc_error error;	/* OUT for this packet. */
+};
+
+typedef struct usbif_io_transaction_status_struct
+ usbif_io_transaction_status;
+
+struct usbif_io_transaction_status_struct {
+	xenidc_buffer_byte_count length;
+};
+
+/* These are the error values that have some significant meaning for the USB */
+/* protocol and might be tested for explicitly in error recovery code.       */
+/* These error values are either used in xenidc_error form by the FE or BE   */
+/* driver code or must be carefully translated to the local form of error    */
+/* value for use higher up the USB stack in the FE.                          */
+
+#define USBIF_XENIDC_ERROR_NO_DEVICE \
+  ( XENIDC_ERROR_PROTOCOL_SPECIFIC_FIRST + 1 )
+#define USBIF_XENIDC_ERROR_UNLINKED  \
+  ( XENIDC_ERROR_PROTOCOL_SPECIFIC_FIRST + 2 )
+#define USBIF_XENIDC_ERROR_PIPE      \
+  ( XENIDC_ERROR_PROTOCOL_SPECIFIC_FIRST + 3 )
+
+static inline xenidc_error usbif_error_map_local_to(int error)
+{
+	switch (error) {
+	case -ENODEV:
+		return USBIF_XENIDC_ERROR_NO_DEVICE;
+	case -ECONNRESET:
+		return USBIF_XENIDC_ERROR_UNLINKED;
+	case -EPIPE:
+		return USBIF_XENIDC_ERROR_PIPE;
+	default:
+		return xenidc_error_map_local_to(error);
+	}
+}
+
+static inline int usbif_error_map_to_local(xenidc_error error)
+{
+	switch (error) {
+	case USBIF_XENIDC_ERROR_NO_DEVICE:
+		return -ENODEV;
+	case USBIF_XENIDC_ERROR_UNLINKED:
+		return -ECONNRESET;
+	case USBIF_XENIDC_ERROR_PIPE:
+		return -EPIPE;
+	default:
+		return xenidc_error_map_to_local(error);
+	}
+}
+
+/* Lookup table for sizes of io parameters structures. */
+
+static const xenidc_buffer_byte_count usbif_io_parameters_byte_count
+    [USBIF_IO_TRANSACTION_TYPE_LIMIT] = {
+	[USBIF_IO_TRANSACTION_TYPE_CONTROL] =
+	    sizeof(usbif_control_io_transaction_parameters),
+	[USBIF_IO_TRANSACTION_TYPE_BULK] =
+	    sizeof(usbif_bulk_io_transaction_parameters),
+	[USBIF_IO_TRANSACTION_TYPE_INTERRUPT] =
+	    sizeof(usbif_interrupt_io_transaction_parameters),
+	[USBIF_IO_TRANSACTION_TYPE_ISOCHRONOUS] =
+	    sizeof(usbif_isochronous_io_transaction_parameters)
+};
+
+typedef union {
+	usbif_io_transaction_parameters_header header;
+	usbif_control_io_transaction_parameters control;
+	usbif_bulk_io_transaction_parameters bulk;
+	usbif_interrupt_io_transaction_parameters interrupt;
+	usbif_isochronous_io_transaction_parameters isochronous;
+} usbif_io_transaction_parameters;
+
+typedef union usbif_max_transaction_union usbif_max_transaction;
+
+union usbif_max_transaction_union {
+	struct {
+		usbif_probe_transaction_parameters parameters;
+		usbif_probe_transaction_status status;
+	} probe;
+	struct {
+		usbif_reset_transaction_parameters parameters;
+		usbif_reset_transaction_status status;
+	} reset;
+	struct {
+		usbif_control_io_transaction_parameters parameters;
+		usbif_io_transaction_status status;
+	} control_io;
+	struct {
+		usbif_bulk_io_transaction_parameters parameters;
+		usbif_io_transaction_status status;
+	} bulk_io;
+	struct {
+		usbif_interrupt_io_transaction_parameters parameters;
+		usbif_io_transaction_status status;
+	} interrupt_io;
+	struct {
+		usbif_isochronous_io_transaction_parameters parameters;
+		usbif_io_transaction_status status;
+	} isochronous_io;
+};
+
+/* All messages have the same header which specifies the type of the         */
+/* message.                                                                  */
+
+typedef struct usbif_message_header_struct usbif_message_header;
+
+struct usbif_message_header_struct {
+	u8 message_type;
+	u8 reserved[7];
+};
+
+/* There is only one type of message:                                        */
+
+#define USBIF_MESSAGE_TYPE_UNLINK 0
+
+/* The unlink message is sent to unlink an IO operation.  The backend will   */
+/* ensure it completes or is failed out as quickly as possible.              */
+/* This is a send and forget message: the client should wait for the         */
+/* completion of the IO transaction as normal.                               */
+
+typedef struct usbif_unlink_message_body_struct usbif_unlink_message_body;
+
+struct usbif_unlink_message_body_struct {
+	usbif_message_header header;
+	u32 unlink_id;
+	u32 reserved;
+};
+
+typedef union usbif_max_message_union usbif_max_message;
+
+union usbif_max_message_union {
+	usbif_unlink_message_body unlink;
+};
+
+typedef union usbif_max_transaction_or_message_union
+    usbif_max_transaction_or_message;
+
+union usbif_max_transaction_or_message_union {
+	usbif_max_transaction transaction;
+	usbif_max_message message;
+};
+
+#define USBIF_MAX_BULK_BYTE_COUNT       65536	/* FIXME: what value here? */
+#define USBIF_BULK_BYTE_ALIGNMENT       1	/* FIXME: what value here? */
+#define USBIF_MAX_SCHEDULE_BYTE_COUNT   65536	/* FIXME: what value here? */
+#define USBIF_SCHEDULE_BYTE_ALIGNMENT   1	/* FIXME: what value here? */
+#define USBIF_MAX_SCHEDULE_PACKET_COUNT 64	/* FIXME: what value here? */
+
+#define USBIF_BE_INITIATOR_QUOTA 0
+#define USBIF_BE_INITIATOR_MAXIMUM_BYTE_COUNT 0
+
+#define USBIF_BE_TARGET_QUOTA 32
+#define USBIF_BE_TARGET_MAXIMUM_BYTE_COUNT \
+( sizeof( usbif_max_transaction_or_message ) )
+
+#define USBIF_FE_INITIATOR_QUOTA USBIF_BE_TARGET_QUOTA
+#define USBIF_FE_INITIATOR_MAXIMUM_BYTE_COUNT \
+USBIF_BE_TARGET_MAXIMUM_BYTE_COUNT
+
+#define USBIF_FE_TARGET_QUOTA USBIF_BE_INITIATOR_QUOTA
+#define USBIF_FE_TARGET_MAXIMUM_BYTE_COUNT \
+USBIF_BE_INITIATOR_MAXIMUM_BYTE_COUNT
+
+#endif

[-- Attachment #3: Type: text/plain, Size: 138 bytes --]

_______________________________________________
Xen-devel mailing list
Xen-devel@lists.xensource.com
http://lists.xensource.com/xen-devel