1 /* 2 * usbif.h 3 * 4 * USB I/O interface for Xen guest OSes. 5 * 6 * Copyright (C) 2009, FUJITSU LABORATORIES LTD. 7 * Author: Noboru Iwamatsu <n_iwamatsu@jp.fujitsu.com> 8 * 9 * Permission is hereby granted, free of charge, to any person obtaining a copy 10 * of this software and associated documentation files (the "Software"), to 11 * deal in the Software without restriction, including without limitation the 12 * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or 13 * sell copies of the Software, and to permit persons to whom the Software is 14 * furnished to do so, subject to the following conditions: 15 * 16 * The above copyright notice and this permission notice shall be included in 17 * all copies or substantial portions of the Software. 18 * 19 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 20 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 21 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 22 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 23 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 24 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 25 * DEALINGS IN THE SOFTWARE. 26 */ 27 28 #ifndef __XEN_PUBLIC_IO_USBIF_H__ 29 #define __XEN_PUBLIC_IO_USBIF_H__ 30 31 #include "ring.h" 32 #include "../grant_table.h" 33 34 /* 35 * Feature and Parameter Negotiation 36 * ================================= 37 * The two halves of a Xen pvUSB driver utilize nodes within the XenStore to 38 * communicate capabilities and to negotiate operating parameters. This 39 * section enumerates these nodes which reside in the respective front and 40 * backend portions of the XenStore, following the XenBus convention. 41 * 42 * Any specified default value is in effect if the corresponding XenBus node 43 * is not present in the XenStore. 44 * 45 * XenStore nodes in sections marked "PRIVATE" are solely for use by the 46 * driver side whose XenBus tree contains them. 47 * 48 ***************************************************************************** 49 * Backend XenBus Nodes 50 ***************************************************************************** 51 * 52 *------------------ Backend Device Identification (PRIVATE) ------------------ 53 * 54 * num-ports 55 * Values: unsigned [1...31] 56 * 57 * Number of ports for this (virtual) USB host connector. 58 * 59 * usb-ver 60 * Values: unsigned [1...2] 61 * 62 * USB version of this host connector: 1 = USB 1.1, 2 = USB 2.0. 63 * 64 * port/[1...31] 65 * Values: string 66 * 67 * Physical USB device connected to the given port, e.g. "3-1.5". 68 * 69 ***************************************************************************** 70 * Frontend XenBus Nodes 71 ***************************************************************************** 72 * 73 *----------------------- Request Transport Parameters ----------------------- 74 * 75 * event-channel 76 * Values: unsigned 77 * 78 * The identifier of the Xen event channel used to signal activity 79 * in the ring buffer. 80 * 81 * urb-ring-ref 82 * Values: unsigned 83 * 84 * The Xen grant reference granting permission for the backend to map 85 * the sole page in a single page sized ring buffer. This is the ring 86 * buffer for urb requests. 87 * 88 * conn-ring-ref 89 * Values: unsigned 90 * 91 * The Xen grant reference granting permission for the backend to map 92 * the sole page in a single page sized ring buffer. This is the ring 93 * buffer for connection/disconnection requests. 94 * 95 * protocol 96 * Values: string (XEN_IO_PROTO_ABI_*) 97 * Default Value: XEN_IO_PROTO_ABI_NATIVE 98 * 99 * The machine ABI rules governing the format of all ring request and 100 * response structures. 101 * 102 */ 103 104 enum usb_spec_version { 105 USB_VER_UNKNOWN = 0, 106 USB_VER_USB11, 107 USB_VER_USB20, 108 USB_VER_USB30, /* not supported yet */ 109 }; 110 111 /* 112 * USB pipe in usbif_request 113 * 114 * - port number: bits 0-4 115 * (USB_MAXCHILDREN is 31) 116 * 117 * - operation flag: bit 5 118 * (0 = submit urb, 119 * 1 = unlink urb) 120 * 121 * - direction: bit 7 122 * (0 = Host-to-Device [Out] 123 * 1 = Device-to-Host [In]) 124 * 125 * - device address: bits 8-14 126 * 127 * - endpoint: bits 15-18 128 * 129 * - pipe type: bits 30-31 130 * (00 = isochronous, 01 = interrupt, 131 * 10 = control, 11 = bulk) 132 */ 133 134 #define USBIF_PIPE_PORT_MASK 0x0000001f 135 #define USBIF_PIPE_UNLINK 0x00000020 136 #define USBIF_PIPE_DIR 0x00000080 137 #define USBIF_PIPE_DEV_MASK 0x0000007f 138 #define USBIF_PIPE_DEV_SHIFT 8 139 #define USBIF_PIPE_EP_MASK 0x0000000f 140 #define USBIF_PIPE_EP_SHIFT 15 141 #define USBIF_PIPE_TYPE_MASK 0x00000003 142 #define USBIF_PIPE_TYPE_SHIFT 30 143 #define USBIF_PIPE_TYPE_ISOC 0 144 #define USBIF_PIPE_TYPE_INT 1 145 #define USBIF_PIPE_TYPE_CTRL 2 146 #define USBIF_PIPE_TYPE_BULK 3 147 148 #define usbif_pipeportnum(pipe) ((pipe) & USBIF_PIPE_PORT_MASK) 149 #define usbif_setportnum_pipe(pipe, portnum) ((pipe) | (portnum)) 150 151 #define usbif_pipeunlink(pipe) ((pipe) & USBIF_PIPE_UNLINK) 152 #define usbif_pipesubmit(pipe) (!usbif_pipeunlink(pipe)) 153 #define usbif_setunlink_pipe(pipe) ((pipe) | USBIF_PIPE_UNLINK) 154 155 #define usbif_pipein(pipe) ((pipe) & USBIF_PIPE_DIR) 156 #define usbif_pipeout(pipe) (!usbif_pipein(pipe)) 157 158 #define usbif_pipedevice(pipe) \ 159 (((pipe) >> USBIF_PIPE_DEV_SHIFT) & USBIF_PIPE_DEV_MASK) 160 161 #define usbif_pipeendpoint(pipe) \ 162 (((pipe) >> USBIF_PIPE_EP_SHIFT) & USBIF_PIPE_EP_MASK) 163 164 #define usbif_pipetype(pipe) \ 165 (((pipe) >> USBIF_PIPE_TYPE_SHIFT) & USBIF_PIPE_TYPE_MASK) 166 #define usbif_pipeisoc(pipe) (usbif_pipetype(pipe) == USBIF_PIPE_TYPE_ISOC) 167 #define usbif_pipeint(pipe) (usbif_pipetype(pipe) == USBIF_PIPE_TYPE_INT) 168 #define usbif_pipectrl(pipe) (usbif_pipetype(pipe) == USBIF_PIPE_TYPE_CTRL) 169 #define usbif_pipebulk(pipe) (usbif_pipetype(pipe) == USBIF_PIPE_TYPE_BULK) 170 171 #define USBIF_MAX_SEGMENTS_PER_REQUEST (16) 172 #define USBIF_MAX_PORTNR 31 173 #define USBIF_RING_SIZE 4096 174 175 /* 176 * RING for transferring urbs. 177 */ 178 struct usbif_request_segment { 179 grant_ref_t gref; 180 uint16_t offset; 181 uint16_t length; 182 }; 183 184 struct usbif_urb_request { 185 uint16_t id; /* request id */ 186 uint16_t nr_buffer_segs; /* number of urb->transfer_buffer segments */ 187 188 /* basic urb parameter */ 189 uint32_t pipe; 190 uint16_t transfer_flags; 191 #define USBIF_SHORT_NOT_OK 0x0001 192 uint16_t buffer_length; 193 union { 194 uint8_t ctrl[8]; /* setup_packet (Ctrl) */ 195 196 struct { 197 uint16_t interval; /* maximum (1024*8) in usb core */ 198 uint16_t start_frame; /* start frame */ 199 uint16_t number_of_packets; /* number of ISO packet */ 200 uint16_t nr_frame_desc_segs; /* number of iso_frame_desc segments */ 201 } isoc; 202 203 struct { 204 uint16_t interval; /* maximum (1024*8) in usb core */ 205 uint16_t pad[3]; 206 } intr; 207 208 struct { 209 uint16_t unlink_id; /* unlink request id */ 210 uint16_t pad[3]; 211 } unlink; 212 213 } u; 214 215 /* urb data segments */ 216 struct usbif_request_segment seg[USBIF_MAX_SEGMENTS_PER_REQUEST]; 217 }; 218 typedef struct usbif_urb_request usbif_urb_request_t; 219 220 struct usbif_urb_response { 221 uint16_t id; /* request id */ 222 uint16_t start_frame; /* start frame (ISO) */ 223 int32_t status; /* status (non-ISO) */ 224 int32_t actual_length; /* actual transfer length */ 225 int32_t error_count; /* number of ISO errors */ 226 }; 227 typedef struct usbif_urb_response usbif_urb_response_t; 228 229 DEFINE_RING_TYPES(usbif_urb, struct usbif_urb_request, struct usbif_urb_response); 230 #define USB_URB_RING_SIZE __CONST_RING_SIZE(usbif_urb, USBIF_RING_SIZE) 231 232 /* 233 * RING for notifying connect/disconnect events to frontend 234 */ 235 struct usbif_conn_request { 236 uint16_t id; 237 }; 238 typedef struct usbif_conn_request usbif_conn_request_t; 239 240 struct usbif_conn_response { 241 uint16_t id; /* request id */ 242 uint8_t portnum; /* port number */ 243 uint8_t speed; /* usb_device_speed */ 244 #define USBIF_SPEED_NONE 0 245 #define USBIF_SPEED_LOW 1 246 #define USBIF_SPEED_FULL 2 247 #define USBIF_SPEED_HIGH 3 248 }; 249 typedef struct usbif_conn_response usbif_conn_response_t; 250 251 DEFINE_RING_TYPES(usbif_conn, struct usbif_conn_request, struct usbif_conn_response); 252 #define USB_CONN_RING_SIZE __CONST_RING_SIZE(usbif_conn, USBIF_RING_SIZE) 253 254 #endif /* __XEN_PUBLIC_IO_USBIF_H__ */ 255