interface/io/usbif.h

   1 /* SPDX-License-Identifier: MIT */
   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 <n_iwamatsu@jp.fujitsu.com>
  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,       /* not supported yet */
 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;                    /* request id */
 334         uint16_t nr_buffer_segs;        /* number of urb->transfer_buffer segments */
 335
 336         /* basic urb parameter */
 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];        /* setup_packet (Ctrl) */
 343
 344                 struct {
 345                         uint16_t interval;      /* maximum (1024*8) in usb core */
 346                         uint16_t start_frame;   /* start frame */
 347                         uint16_t number_of_packets;     /* number of ISO packet */
 348                         uint16_t nr_frame_desc_segs;    /* number of iso_frame_desc segments */
 349                 } isoc;
 350
 351                 struct {
 352                         uint16_t interval;      /* maximum (1024*8) in usb core */
 353                         uint16_t pad[3];
 354                 } intr;
 355
 356                 struct {
 357                         uint16_t unlink_id;     /* unlink request id */
 358                         uint16_t pad[3];
 359                 } unlink;
 360
 361         } u;
 362
 363         /* urb data segments */
 364         struct xenusb_request_segment seg[XENUSB_MAX_SEGMENTS_PER_REQUEST];
 365 };
 366
 367 struct xenusb_urb_response {
 368         uint16_t id;            /* request id */
 369         uint16_t start_frame;   /* start frame (ISO) */
 370         int32_t status;         /* status (non-ISO) */
 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;  /* actual transfer length */
 379         int32_t error_count;    /* number of ISO errors */
 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;            /* request id */
 394         uint8_t portnum;        /* port number */
 395         uint8_t speed;          /* usb_device_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 /* __XEN_PUBLIC_IO_USBIF_H__ */