| 1 |
|
| 2 |
|
| 3 | |
| 4 | * usbif.h
|
| 5 | *
|
| 6 | * USB I/O interface for Xen guest OSes.
|
| 7 | *
|
| 8 | * Copyright (C) 2009, FUJITSU LABORATORIES LTD.
|
| 9 | * Author: Noboru Iwamatsu <[email protected]>
|
| 10 |
|
| 11 |
|
| 12 | #ifndef __XEN_PUBLIC_IO_USBIF_H__
|
| 13 | #define __XEN_PUBLIC_IO_USBIF_H__
|
| 14 |
|
| 15 | #include "ring.h"
|
| 16 | #include "../grant_table.h"
|
| 17 |
|
| 18 | |
| 19 | * Detailed Interface Description
|
| 20 | * ==============================
|
| 21 | * The pvUSB interface is using a split driver design: a frontend driver in
|
| 22 | * the guest and a backend driver in a driver domain (normally dom0) having
|
| 23 | * access to the physical USB device(s) being passed to the guest.
|
| 24 | *
|
| 25 | * The frontend and backend drivers use XenStore to initiate the connection
|
| 26 | * between them, the I/O activity is handled via two shared ring pages and an
|
| 27 | * event channel. As the interface between frontend and backend is at the USB
|
| 28 | * host connector level, multiple (up to 31) physical USB devices can be
|
| 29 | * handled by a single connection.
|
| 30 | *
|
| 31 | * The Xen pvUSB device name is "qusb", so the frontend's XenStore entries are
|
| 32 | * to be found under "device/qusb", while the backend's XenStore entries are
|
| 33 | * under "backend/<guest-dom-id>/qusb".
|
| 34 | *
|
| 35 | * When a new pvUSB connection is established, the frontend needs to setup the
|
| 36 | * two shared ring pages for communication and the event channel. The ring
|
| 37 | * pages need to be made available to the backend via the grant table
|
| 38 | * interface.
|
| 39 | *
|
| 40 | * One of the shared ring pages is used by the backend to inform the frontend
|
| 41 | * about USB device plug events (device to be added or removed). This is the
|
| 42 | * "conn-ring".
|
| 43 | *
|
| 44 | * The other ring page is used for USB I/O communication (requests and
|
| 45 | * responses). This is the "urb-ring".
|
| 46 | *
|
| 47 | * Feature and Parameter Negotiation
|
| 48 | * =================================
|
| 49 | * The two halves of a Xen pvUSB driver utilize nodes within the XenStore to
|
| 50 | * communicate capabilities and to negotiate operating parameters. This
|
| 51 | * section enumerates these nodes which reside in the respective front and
|
| 52 | * backend portions of the XenStore, following the XenBus convention.
|
| 53 | *
|
| 54 | * Any specified default value is in effect if the corresponding XenBus node
|
| 55 | * is not present in the XenStore.
|
| 56 | *
|
| 57 | * XenStore nodes in sections marked "PRIVATE" are solely for use by the
|
| 58 | * driver side whose XenBus tree contains them.
|
| 59 | *
|
| 60 | *****************************************************************************
|
| 61 | * Backend XenBus Nodes
|
| 62 | *****************************************************************************
|
| 63 | *
|
| 64 | *------------------ Backend Device Identification (PRIVATE) ------------------
|
| 65 | *
|
| 66 | * num-ports
|
| 67 | * Values: unsigned [1...31]
|
| 68 | *
|
| 69 | * Number of ports for this (virtual) USB host connector.
|
| 70 | *
|
| 71 | * usb-ver
|
| 72 | * Values: unsigned [1...2]
|
| 73 | *
|
| 74 | * USB version of this host connector: 1 = USB 1.1, 2 = USB 2.0.
|
| 75 | *
|
| 76 | * port/[1...31]
|
| 77 | * Values: string
|
| 78 | *
|
| 79 | * Physical USB device connected to the given port, e.g. "3-1.5".
|
| 80 | *
|
| 81 | *****************************************************************************
|
| 82 | * Frontend XenBus Nodes
|
| 83 | *****************************************************************************
|
| 84 | *
|
| 85 | *----------------------- Request Transport Parameters -----------------------
|
| 86 | *
|
| 87 | * event-channel
|
| 88 | * Values: unsigned
|
| 89 | *
|
| 90 | * The identifier of the Xen event channel used to signal activity
|
| 91 | * in the ring buffer.
|
| 92 | *
|
| 93 | * urb-ring-ref
|
| 94 | * Values: unsigned
|
| 95 | *
|
| 96 | * The Xen grant reference granting permission for the backend to map
|
| 97 | * the sole page in a single page sized ring buffer. This is the ring
|
| 98 | * buffer for urb requests.
|
| 99 | *
|
| 100 | * conn-ring-ref
|
| 101 | * Values: unsigned
|
| 102 | *
|
| 103 | * The Xen grant reference granting permission for the backend to map
|
| 104 | * the sole page in a single page sized ring buffer. This is the ring
|
| 105 | * buffer for connection/disconnection requests.
|
| 106 | *
|
| 107 | * protocol
|
| 108 | * Values: string (XEN_IO_PROTO_ABI_*)
|
| 109 | * Default Value: XEN_IO_PROTO_ABI_NATIVE
|
| 110 | *
|
| 111 | * The machine ABI rules governing the format of all ring request and
|
| 112 | * response structures.
|
| 113 | *
|
| 114 | * Protocol Description
|
| 115 | * ====================
|
| 116 | *
|
| 117 | *-------------------------- USB device plug events --------------------------
|
| 118 | *
|
| 119 | * USB device plug events are send via the "conn-ring" shared page. As only
|
| 120 | * events are being sent, the respective requests from the frontend to the
|
| 121 | * backend are just dummy ones.
|
| 122 | * The events sent to the frontend have the following layout:
|
| 123 | * 0 1 2 3 octet
|
| 124 | * +----------------+----------------+----------------+----------------+
|
| 125 | * | id | portnum | speed | 4
|
| 126 | * +----------------+----------------+----------------+----------------+
|
| 127 | * id - uint16_t, event id (taken from the actual frontend dummy request)
|
| 128 | * portnum - uint8_t, port number (1 ... 31)
|
| 129 | * speed - uint8_t, device XENUSB_SPEED_*, XENUSB_SPEED_NONE == unplug
|
| 130 | *
|
| 131 | * The dummy request:
|
| 132 | * 0 1 octet
|
| 133 | * +----------------+----------------+
|
| 134 | * | id | 2
|
| 135 | * +----------------+----------------+
|
| 136 | * id - uint16_t, guest supplied value (no need for being unique)
|
| 137 | *
|
| 138 | *-------------------------- USB I/O request ---------------------------------
|
| 139 | *
|
| 140 | * A single USB I/O request on the "urb-ring" has the following layout:
|
| 141 | * 0 1 2 3 octet
|
| 142 | * +----------------+----------------+----------------+----------------+
|
| 143 | * | id | nr_buffer_segs | 4
|
| 144 | * +----------------+----------------+----------------+----------------+
|
| 145 | * | pipe | 8
|
| 146 | * +----------------+----------------+----------------+----------------+
|
| 147 | * | transfer_flags | buffer_length | 12
|
| 148 | * +----------------+----------------+----------------+----------------+
|
| 149 | * | request type specific | 16
|
| 150 | * | data | 20
|
| 151 | * +----------------+----------------+----------------+----------------+
|
| 152 | * | seg[0] | 24
|
| 153 | * | data | 28
|
| 154 | * +----------------+----------------+----------------+----------------+
|
| 155 | * |/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/\/|
|
| 156 | * +----------------+----------------+----------------+----------------+
|
| 157 | * | seg[XENUSB_MAX_SEGMENTS_PER_REQUEST - 1] | 144
|
| 158 | * | data | 148
|
| 159 | * +----------------+----------------+----------------+----------------+
|
| 160 | * Bit field bit number 0 is always least significant bit, undefined bits must
|
| 161 | * be zero.
|
| 162 | * id - uint16_t, guest supplied value
|
| 163 | * nr_buffer_segs - uint16_t, number of segment entries in seg[] array
|
| 164 | * pipe - uint32_t, bit field with multiple information:
|
| 165 | * bits 0-4: port request to send to
|
| 166 | * bit 5: unlink request with specified id (cancel I/O) if set (see below)
|
| 167 | * bit 7: direction (1 = read from device)
|
| 168 | * bits 8-14: device number on port
|
| 169 | * bits 15-18: endpoint of device
|
| 170 | * bits 30-31: request type: 00 = isochronous, 01 = interrupt,
|
| 171 | * 10 = control, 11 = bulk
|
| 172 | * transfer_flags - uint16_t, bit field with processing flags:
|
| 173 | * bit 0: less data than specified allowed
|
| 174 | * buffer_length - uint16_t, total length of data
|
| 175 | * request type specific data - 8 bytes, see below
|
| 176 | * seg[] - array with 8 byte elements, see below
|
| 177 | *
|
| 178 | * Request type specific data for isochronous request:
|
| 179 | * 0 1 2 3 octet
|
| 180 | * +----------------+----------------+----------------+----------------+
|
| 181 | * | interval | start_frame | 4
|
| 182 | * +----------------+----------------+----------------+----------------+
|
| 183 | * | number_of_packets | nr_frame_desc_segs | 8
|
| 184 | * +----------------+----------------+----------------+----------------+
|
| 185 | * interval - uint16_t, time interval in msecs between frames
|
| 186 | * start_frame - uint16_t, start frame number
|
| 187 | * number_of_packets - uint16_t, number of packets to transfer
|
| 188 | * nr_frame_desc_segs - uint16_t number of seg[] frame descriptors elements
|
| 189 | *
|
| 190 | * Request type specific data for interrupt request:
|
| 191 | * 0 1 2 3 octet
|
| 192 | * +----------------+----------------+----------------+----------------+
|
| 193 | * | interval | 0 | 4
|
| 194 | * +----------------+----------------+----------------+----------------+
|
| 195 | * | 0 | 8
|
| 196 | * +----------------+----------------+----------------+----------------+
|
| 197 | * interval - uint16_t, time in msecs until interruption
|
| 198 | *
|
| 199 | * Request type specific data for control request:
|
| 200 | * 0 1 2 3 octet
|
| 201 | * +----------------+----------------+----------------+----------------+
|
| 202 | * | data of setup packet | 4
|
| 203 | * | | 8
|
| 204 | * +----------------+----------------+----------------+----------------+
|
| 205 | *
|
| 206 | * Request type specific data for bulk request:
|
| 207 | * 0 1 2 3 octet
|
| 208 | * +----------------+----------------+----------------+----------------+
|
| 209 | * | 0 | 4
|
| 210 | * | 0 | 8
|
| 211 | * +----------------+----------------+----------------+----------------+
|
| 212 | *
|
| 213 | * Request type specific data for unlink request:
|
| 214 | * 0 1 2 3 octet
|
| 215 | * +----------------+----------------+----------------+----------------+
|
| 216 | * | unlink_id | 0 | 4
|
| 217 | * +----------------+----------------+----------------+----------------+
|
| 218 | * | 0 | 8
|
| 219 | * +----------------+----------------+----------------+----------------+
|
| 220 | * unlink_id - uint16_t, request id of request to terminate
|
| 221 | *
|
| 222 | * seg[] array element layout:
|
| 223 | * 0 1 2 3 octet
|
| 224 | * +----------------+----------------+----------------+----------------+
|
| 225 | * | gref | 4
|
| 226 | * +----------------+----------------+----------------+----------------+
|
| 227 | * | offset | length | 8
|
| 228 | * +----------------+----------------+----------------+----------------+
|
| 229 | * gref - uint32_t, grant reference of buffer page
|
| 230 | * offset - uint16_t, offset of buffer start in page
|
| 231 | * length - uint16_t, length of buffer in page
|
| 232 | *
|
| 233 | *-------------------------- USB I/O response --------------------------------
|
| 234 | *
|
| 235 | * 0 1 2 3 octet
|
| 236 | * +----------------+----------------+----------------+----------------+
|
| 237 | * | id | start_frame | 4
|
| 238 | * +----------------+----------------+----------------+----------------+
|
| 239 | * | status | 8
|
| 240 | * +----------------+----------------+----------------+----------------+
|
| 241 | * | actual_length | 12
|
| 242 | * +----------------+----------------+----------------+----------------+
|
| 243 | * | error_count | 16
|
| 244 | * +----------------+----------------+----------------+----------------+
|
| 245 | * id - uint16_t, id of the request this response belongs to
|
| 246 | * start_frame - uint16_t, start_frame this response (iso requests only)
|
| 247 | * status - int32_t, XENUSB_STATUS_* (non-iso requests)
|
| 248 | * actual_length - uint32_t, actual size of data transferred
|
| 249 | * error_count - uint32_t, number of errors (iso requests)
|
| 250 |
|
| 251 |
|
| 252 | enum xenusb_spec_version {
|
| 253 | XENUSB_VER_UNKNOWN = 0,
|
| 254 | XENUSB_VER_USB11,
|
| 255 | XENUSB_VER_USB20,
|
| 256 | XENUSB_VER_USB30,
|
| 257 | };
|
| 258 |
|
| 259 | |
| 260 | * USB pipe in xenusb_request
|
| 261 | *
|
| 262 | * - port number: bits 0-4
|
| 263 | * (USB_MAXCHILDREN is 31)
|
| 264 | *
|
| 265 | * - operation flag: bit 5
|
| 266 | * (0 = submit urb,
|
| 267 | * 1 = unlink urb)
|
| 268 | *
|
| 269 | * - direction: bit 7
|
| 270 | * (0 = Host-to-Device [Out]
|
| 271 | * 1 = Device-to-Host [In])
|
| 272 | *
|
| 273 | * - device address: bits 8-14
|
| 274 | *
|
| 275 | * - endpoint: bits 15-18
|
| 276 | *
|
| 277 | * - pipe type: bits 30-31
|
| 278 | * (00 = isochronous, 01 = interrupt,
|
| 279 | * 10 = control, 11 = bulk)
|
| 280 |
|
| 281 |
|
| 282 | #define XENUSB_PIPE_PORT_MASK 0x0000001f
|
| 283 | #define XENUSB_PIPE_UNLINK 0x00000020
|
| 284 | #define XENUSB_PIPE_DIR 0x00000080
|
| 285 | #define XENUSB_PIPE_DEV_MASK 0x0000007f
|
| 286 | #define XENUSB_PIPE_DEV_SHIFT 8
|
| 287 | #define XENUSB_PIPE_EP_MASK 0x0000000f
|
| 288 | #define XENUSB_PIPE_EP_SHIFT 15
|
| 289 | #define XENUSB_PIPE_TYPE_MASK 0x00000003
|
| 290 | #define XENUSB_PIPE_TYPE_SHIFT 30
|
| 291 | #define XENUSB_PIPE_TYPE_ISOC 0
|
| 292 | #define XENUSB_PIPE_TYPE_INT 1
|
| 293 | #define XENUSB_PIPE_TYPE_CTRL 2
|
| 294 | #define XENUSB_PIPE_TYPE_BULK 3
|
| 295 |
|
| 296 | #define xenusb_pipeportnum(pipe) ((pipe) & XENUSB_PIPE_PORT_MASK)
|
| 297 | #define xenusb_setportnum_pipe(pipe, portnum) ((pipe) | (portnum))
|
| 298 |
|
| 299 | #define xenusb_pipeunlink(pipe) ((pipe) & XENUSB_PIPE_UNLINK)
|
| 300 | #define xenusb_pipesubmit(pipe) (!xenusb_pipeunlink(pipe))
|
| 301 | #define xenusb_setunlink_pipe(pipe) ((pipe) | XENUSB_PIPE_UNLINK)
|
| 302 |
|
| 303 | #define xenusb_pipein(pipe) ((pipe) & XENUSB_PIPE_DIR)
|
| 304 | #define xenusb_pipeout(pipe) (!xenusb_pipein(pipe))
|
| 305 |
|
| 306 | #define xenusb_pipedevice(pipe) \
|
| 307 | (((pipe) >> XENUSB_PIPE_DEV_SHIFT) & XENUSB_PIPE_DEV_MASK)
|
| 308 |
|
| 309 | #define xenusb_pipeendpoint(pipe) \
|
| 310 | (((pipe) >> XENUSB_PIPE_EP_SHIFT) & XENUSB_PIPE_EP_MASK)
|
| 311 |
|
| 312 | #define xenusb_pipetype(pipe) \
|
| 313 | (((pipe) >> XENUSB_PIPE_TYPE_SHIFT) & XENUSB_PIPE_TYPE_MASK)
|
| 314 | #define xenusb_pipeisoc(pipe) (xenusb_pipetype(pipe) == XENUSB_PIPE_TYPE_ISOC)
|
| 315 | #define xenusb_pipeint(pipe) (xenusb_pipetype(pipe) == XENUSB_PIPE_TYPE_INT)
|
| 316 | #define xenusb_pipectrl(pipe) (xenusb_pipetype(pipe) == XENUSB_PIPE_TYPE_CTRL)
|
| 317 | #define xenusb_pipebulk(pipe) (xenusb_pipetype(pipe) == XENUSB_PIPE_TYPE_BULK)
|
| 318 |
|
| 319 | #define XENUSB_MAX_SEGMENTS_PER_REQUEST (16)
|
| 320 | #define XENUSB_MAX_PORTNR 31
|
| 321 | #define XENUSB_RING_SIZE 4096
|
| 322 |
|
| 323 | |
| 324 | * RING for transferring urbs.
|
| 325 |
|
| 326 | struct xenusb_request_segment {
|
| 327 | grant_ref_t gref;
|
| 328 | uint16_t offset;
|
| 329 | uint16_t length;
|
| 330 | };
|
| 331 |
|
| 332 | struct xenusb_urb_request {
|
| 333 | uint16_t id;
|
| 334 | uint16_t nr_buffer_segs;
|
| 335 |
|
| 336 |
|
| 337 | uint32_t pipe;
|
| 338 | uint16_t transfer_flags;
|
| 339 | #define XENUSB_SHORT_NOT_OK 0x0001
|
| 340 | uint16_t buffer_length;
|
| 341 | union {
|
| 342 | uint8_t ctrl[8];
|
| 343 |
|
| 344 | struct {
|
| 345 | uint16_t interval;
|
| 346 | uint16_t start_frame;
|
| 347 | uint16_t number_of_packets;
|
| 348 | uint16_t nr_frame_desc_segs;
|
| 349 | } isoc;
|
| 350 |
|
| 351 | struct {
|
| 352 | uint16_t interval;
|
| 353 | uint16_t pad[3];
|
| 354 | } intr;
|
| 355 |
|
| 356 | struct {
|
| 357 | uint16_t unlink_id;
|
| 358 | uint16_t pad[3];
|
| 359 | } unlink;
|
| 360 |
|
| 361 | } u;
|
| 362 |
|
| 363 |
|
| 364 | struct xenusb_request_segment seg[XENUSB_MAX_SEGMENTS_PER_REQUEST];
|
| 365 | };
|
| 366 |
|
| 367 | struct xenusb_urb_response {
|
| 368 | uint16_t id;
|
| 369 | uint16_t start_frame;
|
| 370 | int32_t status;
|
| 371 | #define XENUSB_STATUS_OK 0
|
| 372 | #define XENUSB_STATUS_NODEV (-19)
|
| 373 | #define XENUSB_STATUS_INVAL (-22)
|
| 374 | #define XENUSB_STATUS_STALL (-32)
|
| 375 | #define XENUSB_STATUS_IOERROR (-71)
|
| 376 | #define XENUSB_STATUS_BABBLE (-75)
|
| 377 | #define XENUSB_STATUS_SHUTDOWN (-108)
|
| 378 | int32_t actual_length;
|
| 379 | int32_t error_count;
|
| 380 | };
|
| 381 |
|
| 382 | DEFINE_RING_TYPES(xenusb_urb, struct xenusb_urb_request, struct xenusb_urb_response);
|
| 383 | #define XENUSB_URB_RING_SIZE __CONST_RING_SIZE(xenusb_urb, XENUSB_RING_SIZE)
|
| 384 |
|
| 385 | |
| 386 | * RING for notifying connect/disconnect events to frontend
|
| 387 |
|
| 388 | struct xenusb_conn_request {
|
| 389 | uint16_t id;
|
| 390 | };
|
| 391 |
|
| 392 | struct xenusb_conn_response {
|
| 393 | uint16_t id;
|
| 394 | uint8_t portnum;
|
| 395 | uint8_t speed;
|
| 396 | #define XENUSB_SPEED_NONE 0
|
| 397 | #define XENUSB_SPEED_LOW 1
|
| 398 | #define XENUSB_SPEED_FULL 2
|
| 399 | #define XENUSB_SPEED_HIGH 3
|
| 400 | };
|
| 401 |
|
| 402 | DEFINE_RING_TYPES(xenusb_conn, struct xenusb_conn_request, struct xenusb_conn_response);
|
| 403 | #define XENUSB_CONN_RING_SIZE __CONST_RING_SIZE(xenusb_conn, XENUSB_RING_SIZE)
|
| 404 |
|
| 405 | #endif
|