sys/dev/usb/usb_core.h

   1 /* $FreeBSD$ */
   2 /*-
   3  * Copyright (c) 2008 Hans Petter Selasky. All rights reserved.
   4  *
   5  * Redistribution and use in source and binary forms, with or without
   6  * modification, are permitted provided that the following conditions
   7  * are met:
   8  * 1. Redistributions of source code must retain the above copyright
   9  *    notice, this list of conditions and the following disclaimer.
  10  * 2. Redistributions in binary form must reproduce the above copyright
  11  *    notice, this list of conditions and the following disclaimer in the
  12  *    documentation and/or other materials provided with the distribution.
  13  *
  14  * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  15  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17  * ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  18  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24  * SUCH DAMAGE.
  25  */
  26
  27 /*
  28  * Including this file is mandatory for all USB related c-files in the kernel.
  29  */
  30
  31 #ifndef _USB2_CORE_H_
  32 #define _USB2_CORE_H_
  33
  34 #define USB_STACK_VERSION 2000          /* 2.0 */
  35
  36 /* Allow defines in "opt_usb.h" to override configuration */
  37
  38 #include "opt_usb.h"
  39 #include "opt_bus.h"
  40
  41 /* Default USB configuration */
  42
  43 /*
  44  * The following macro defines if the code shall use cv_xxx() instead
  45  * of msleep() and wakeup().
  46  */
  47 #ifndef USB_HAVE_CONDVAR
  48 #define USB_HAVE_CONDVAR 0
  49 #endif
  50
  51 /*
  52  * The following macro defines if the code shall support
  53  * /dev/usb/x.y.z.
  54  */
  55 #ifndef USB_HAVE_UGEN
  56 #define USB_HAVE_UGEN 1
  57 #endif
  58
  59 /*
  60  * The following macro defines if the code shall support BUS-DMA.
  61  */
  62 #ifndef USB_HAVE_BUSDMA
  63 #define USB_HAVE_BUSDMA 1
  64 #endif
  65
  66 /*
  67  * The following macro defines if the code shall support the Linux
  68  * compatibility layer.
  69  */
  70 #ifndef USB_HAVE_COMPAT_LINUX
  71 #define USB_HAVE_COMPAT_LINUX 1
  72 #endif
  73
  74 /*
  75  * The following macro defines if the code shall support
  76  * userland data transfer via copyin() and copyout()
  77  */
  78 #ifndef USB_HAVE_USER_IO
  79 #define USB_HAVE_USER_IO 1
  80 #endif
  81
  82 /*
  83  * The following macro defines if the code shall support copy in via
  84  * bsd-mbufs to USB.
  85  */
  86 #ifndef USB_HAVE_MBUF
  87 #define USB_HAVE_MBUF 1
  88 #endif
  89
  90 /*
  91  * The following macro defines if the code shall compile a table
  92  * describing USB vendor and product IDs.
  93  */
  94 #ifndef USB_VERBOSE
  95 #define USB_VERBOSE 1
  96 #endif
  97
  98 /*
  99  * The following macro defines if USB debugging support shall be
 100  * compiled for the USB core and all drivers.
 101  */
 102 #ifndef USB_DEBUG
 103 #define USB_DEBUG 1
 104 #endif
 105
 106 /*
 107  * The following macro defines if USB transaction translator support
 108  * shall be supported for the USB HUB and USB controller drivers.
 109  */
 110 #ifndef USB_HAVE_TT_SUPPORT
 111 #define USB_HAVE_TT_SUPPORT 1
 112 #endif
 113
 114 /*
 115  * The following macro defines if the USB power daemon shall
 116  * be supported in the USB core.
 117  */
 118 #ifndef USB_HAVE_POWERD
 119 #define USB_HAVE_POWERD 1
 120 #endif
 121
 122 /*
 123  * The following macro defines if the USB autoinstall detection shall
 124  * be supported in the USB core.
 125  */
 126 #ifndef USB_HAVE_MSCTEST
 127 #define USB_HAVE_MSCTEST 1
 128 #endif
 129
 130 #ifndef USB_TD_GET_PROC
 131 #define USB_TD_GET_PROC(td) (td)->td_proc
 132 #endif
 133
 134 #ifndef USB_PROC_GET_GID
 135 #define USB_PROC_GET_GID(td) (td)->p_pgid
 136 #endif
 137
 138 /* Include files */
 139
 140 #include <sys/stdint.h>
 141 #include <sys/stddef.h>
 142 #include <sys/param.h>
 143 #include <sys/queue.h>
 144 #include <sys/types.h>
 145 #include <sys/systm.h>
 146 #include <sys/kernel.h>
 147 #include <sys/bus.h>
 148 #include <sys/linker_set.h>
 149 #include <sys/module.h>
 150 #include <sys/lock.h>
 151 #include <sys/mutex.h>
 152 #include <sys/condvar.h>
 153 #include <sys/sysctl.h>
 154 #include <sys/sx.h>
 155 #include <sys/unistd.h>
 156 #include <sys/callout.h>
 157 #include <sys/malloc.h>
 158 #include <sys/priv.h>
 159
 160 #include <dev/usb/usb_defs.h>
 161 #include <dev/usb/usb_revision.h>
 162
 163 #include "usb_if.h"
 164
 165 #ifndef USB_HOST_ALIGN
 166 #define USB_HOST_ALIGN    8             /* bytes, must be power of two */
 167 #endif
 168
 169 #ifndef USB_FS_ISOC_UFRAME_MAX
 170 #define USB_FS_ISOC_UFRAME_MAX 4        /* exclusive unit */
 171 #endif
 172
 173 #if (USB_FS_ISOC_UFRAME_MAX > 6)
 174 #error "USB_FS_ISOC_UFRAME_MAX cannot be set higher than 6"
 175 #endif
 176
 177 #ifndef USB_BUS_MAX
 178 #define USB_BUS_MAX 256                 /* units */
 179 #endif
 180
 181 #ifndef USB_MAX_DEVICES
 182 #define USB_MAX_DEVICES 128             /* units */
 183 #endif
 184
 185 #if (USB_MAX_DEVICES < USB_MIN_DEVICES)
 186 #error "Minimum number of devices is greater than maximum number of devices."
 187 #endif
 188
 189 #ifndef USB_IFACE_MAX
 190 #define USB_IFACE_MAX 32                /* units */
 191 #endif
 192
 193 #ifndef USB_FIFO_MAX
 194 #define USB_FIFO_MAX 128                /* units */
 195 #endif
 196
 197 #if (USB_FIFO_MAX & 1)
 198 #error "Number of FIFOs must be odd."
 199 #endif
 200
 201 #define USB_MAX_FS_ISOC_FRAMES_PER_XFER (120)   /* units */
 202 #define USB_MAX_HS_ISOC_FRAMES_PER_XFER (8*120) /* units */
 203
 204 #ifndef USB_HUB_MAX_DEPTH
 205 #define USB_HUB_MAX_DEPTH       5
 206 #endif
 207
 208 #ifndef USB_EP0_BUFSIZE
 209 #define USB_EP0_BUFSIZE         1024    /* bytes */
 210 #endif
 211
 212 /* USB transfer states */
 213
 214 #define USB_ST_SETUP       0
 215 #define USB_ST_TRANSFERRED 1
 216 #define USB_ST_ERROR       2
 217
 218 /*
 219  * The following macro will return the current state of an USB
 220  * transfer like defined by the "USB_ST_XXX" enums.
 221  */
 222 #define USB_GET_STATE(xfer) ((xfer)->usb2_state)
 223
 224 /*
 225  * The following macro will tell if an USB transfer is currently
 226  * receiving or transferring data.
 227  */
 228 #define USB_GET_DATA_ISREAD(xfer) ((xfer)->flags_int.usb_mode == \
 229         USB_MODE_DEVICE ? (((xfer)->endpoint & UE_DIR_IN) ? 0 : 1) : \
 230         (((xfer)->endpoint & UE_DIR_IN) ? 1 : 0))
 231
 232 /*
 233  * The following macros are used used to convert milliseconds into
 234  * HZ. We use 1024 instead of 1000 milliseconds per second to save a
 235  * full division.
 236  */
 237 #define USB_MS_HZ 1024
 238
 239 #define USB_MS_TO_TICKS(ms) \
 240   (((uint32_t)((((uint32_t)(ms)) * ((uint32_t)(hz))) + USB_MS_HZ - 1)) / USB_MS_HZ)
 241
 242 /* macros */
 243
 244 #define usb2_callout_init_mtx(c,m,f) callout_init_mtx(&(c)->co,m,f)
 245 #define usb2_callout_reset(c,t,f,d) callout_reset(&(c)->co,t,f,d)
 246 #define usb2_callout_stop(c) callout_stop(&(c)->co)
 247 #define usb2_callout_drain(c) callout_drain(&(c)->co)
 248 #define usb2_callout_pending(c) callout_pending(&(c)->co)
 249
 250 #define USB_BUS_LOCK(_b)                mtx_lock(&(_b)->bus_mtx)
 251 #define USB_BUS_UNLOCK(_b)              mtx_unlock(&(_b)->bus_mtx)
 252 #define USB_BUS_LOCK_ASSERT(_b, _t)     mtx_assert(&(_b)->bus_mtx, _t)
 253 #define USB_XFER_LOCK(_x)               mtx_lock((_x)->xroot->xfer_mtx)
 254 #define USB_XFER_UNLOCK(_x)             mtx_unlock((_x)->xroot->xfer_mtx)
 255 #define USB_XFER_LOCK_ASSERT(_x, _t)    mtx_assert((_x)->xroot->xfer_mtx, _t)
 256 /* structure prototypes */
 257
 258 struct file;
 259 struct usb_bus;
 260 struct usb_device;
 261 struct usb_device_request;
 262 struct usb_page;
 263 struct usb_page_cache;
 264 struct usb_xfer;
 265 struct usb_xfer_root;
 266
 267 /* typedefs */
 268
 269 typedef void (usb_callback_t)(struct usb_xfer *);
 270
 271 #ifndef USB_HAVE_USB_ERROR_T
 272 typedef uint8_t usb_error_t;            /* see "USB_ERR_XXX" */
 273 #endif
 274
 275 #ifndef USB_HAVE_TIMEOUT_T
 276 typedef uint32_t usb_timeout_t; /* milliseconds */
 277 #endif
 278
 279 #ifndef USB_HAVE_FRLENGTH_T
 280 typedef uint32_t usb_frlength_t;        /* bytes */
 281 #endif
 282
 283 #ifndef USB_HAVE_FRCOUNT_T
 284 typedef uint32_t usb_frcount_t; /* units */
 285 #endif
 286
 287 #ifndef USB_HAVE_TICKS_T
 288 typedef uint32_t usb_ticks_t;           /* system defined */
 289 #endif
 290
 291 #ifndef USB_HAVE_POWER_MASK_T
 292 typedef uint16_t usb_power_mask_t;      /* see "USB_HW_POWER_XXX" */
 293 #endif
 294
 295 typedef usb_error_t (usb_handle_req_t)(struct usb_device *,
 296     struct usb_device_request *, const void **, uint16_t *);
 297
 298 /* structures */
 299
 300 /*
 301  * Common queue structure for USB transfers.
 302  */
 303 struct usb_xfer_queue {
 304         TAILQ_HEAD(, usb_xfer) head;
 305         struct usb_xfer *curr;          /* current USB transfer processed */
 306         void    (*command) (struct usb_xfer_queue *pq);
 307         uint8_t recurse_1:1;
 308         uint8_t recurse_2:1;
 309 };
 310
 311 /*
 312  * The following is a wrapper for the callout structure to ease
 313  * porting the code to other platforms.
 314  */
 315 struct usb_callout {
 316         struct callout co;
 317 };
 318
 319 /*
 320  * The following structure defines a set of USB transfer flags.
 321  */
 322 struct usb_xfer_flags {
 323         uint8_t force_short_xfer:1;     /* force a short transmit transfer
 324                                          * last */
 325         uint8_t short_xfer_ok:1;        /* allow short receive transfers */
 326         uint8_t short_frames_ok:1;      /* allow short frames */
 327         uint8_t pipe_bof:1;             /* block pipe on failure */
 328         uint8_t proxy_buffer:1;         /* makes buffer size a factor of
 329                                          * "max_frame_size" */
 330         uint8_t ext_buffer:1;           /* uses external DMA buffer */
 331         uint8_t manual_status:1;        /* non automatic status stage on
 332                                          * control transfers */
 333         uint8_t no_pipe_ok:1;           /* set if "USB_ERR_NO_PIPE" error can
 334                                          * be ignored */
 335         uint8_t stall_pipe:1;           /* set if the endpoint belonging to
 336                                          * this USB transfer should be stalled
 337                                          * before starting this transfer! */
 338 };
 339
 340 /*
 341  * The following structure defines a set of internal USB transfer
 342  * flags.
 343  */
 344 struct usb_xfer_flags_int {
 345
 346         enum usb_hc_mode usb_mode;      /* shadow copy of "udev->usb_mode" */
 347         uint16_t control_rem;           /* remainder in bytes */
 348
 349         uint8_t open:1;                 /* set if USB pipe has been opened */
 350         uint8_t transferring:1;         /* set if an USB transfer is in
 351                                          * progress */
 352         uint8_t did_dma_delay:1;        /* set if we waited for HW DMA */
 353         uint8_t did_close:1;            /* set if we closed the USB transfer */
 354         uint8_t draining:1;             /* set if we are draining an USB
 355                                          * transfer */
 356         uint8_t started:1;              /* keeps track of started or stopped */
 357         uint8_t bandwidth_reclaimed:1;
 358         uint8_t control_xfr:1;          /* set if control transfer */
 359         uint8_t control_hdr:1;          /* set if control header should be
 360                                          * sent */
 361         uint8_t control_act:1;          /* set if control transfer is active */
 362         uint8_t control_stall:1;        /* set if control transfer should be stalled */
 363
 364         uint8_t short_frames_ok:1;      /* filtered version */
 365         uint8_t short_xfer_ok:1;        /* filtered version */
 366 #if USB_HAVE_BUSDMA
 367         uint8_t bdma_enable:1;          /* filtered version (only set if
 368                                          * hardware supports DMA) */
 369         uint8_t bdma_no_post_sync:1;    /* set if the USB callback wrapper
 370                                          * should not do the BUS-DMA post sync
 371                                          * operation */
 372         uint8_t bdma_setup:1;           /* set if BUS-DMA has been setup */
 373 #endif
 374         uint8_t isochronous_xfr:1;      /* set if isochronous transfer */
 375         uint8_t curr_dma_set:1;         /* used by USB HC/DC driver */
 376         uint8_t can_cancel_immed:1;     /* set if USB transfer can be
 377                                          * cancelled immediately */
 378 };
 379
 380 /*
 381  * The following structure define an USB configuration, that basically
 382  * is used when setting up an USB transfer.
 383  */
 384 struct usb_config {
 385         usb_callback_t *callback;       /* USB transfer callback */
 386         usb_frlength_t bufsize; /* total pipe buffer size in bytes */
 387         usb_frcount_t frames;           /* maximum number of USB frames */
 388         usb_timeout_t interval; /* interval in milliseconds */
 389 #define USB_DEFAULT_INTERVAL    0
 390         usb_timeout_t timeout;          /* transfer timeout in milliseconds */
 391         struct usb_xfer_flags flags;    /* transfer flags */
 392         enum usb_hc_mode usb_mode;      /* host or device mode */
 393         uint8_t type;                   /* pipe type */
 394         uint8_t endpoint;               /* pipe number */
 395         uint8_t direction;              /* pipe direction */
 396         uint8_t ep_index;               /* pipe index match to use */
 397         uint8_t if_index;               /* "ifaces" index to use */
 398 };
 399
 400 /*
 401  * The following structure defines an USB transfer.
 402  */
 403 struct usb_xfer {
 404         struct usb_callout timeout_handle;
 405         TAILQ_ENTRY(usb_xfer) wait_entry;       /* used at various places */
 406
 407         struct usb_page_cache *buf_fixup;       /* fixup buffer(s) */
 408         struct usb_xfer_queue *wait_queue;      /* pointer to queue that we
 409                                                  * are waiting on */
 410         struct usb_page *dma_page_ptr;
 411         struct usb_pipe *pipe;          /* our USB pipe */
 412         struct usb_xfer_root *xroot;    /* used by HC driver */
 413         void   *qh_start[2];            /* used by HC driver */
 414         void   *td_start[2];            /* used by HC driver */
 415         void   *td_transfer_first;      /* used by HC driver */
 416         void   *td_transfer_last;       /* used by HC driver */
 417         void   *td_transfer_cache;      /* used by HC driver */
 418         void   *priv_sc;                /* device driver data pointer 1 */
 419         void   *priv_fifo;              /* device driver data pointer 2 */
 420         void   *local_buffer;
 421         usb_frlength_t *frlengths;
 422         struct usb_page_cache *frbuffers;
 423         usb_callback_t *callback;
 424
 425         usb_frlength_t max_hc_frame_size;
 426         usb_frlength_t max_data_length;
 427         usb_frlength_t sumlen;          /* sum of all lengths in bytes */
 428         usb_frlength_t actlen;          /* actual length in bytes */
 429         usb_timeout_t timeout;          /* milliseconds */
 430 #define USB_NO_TIMEOUT 0
 431 #define USB_DEFAULT_TIMEOUT 5000        /* 5000 ms = 5 seconds */
 432
 433         usb_frcount_t max_frame_count;  /* initial value of "nframes" after
 434                                          * setup */
 435         usb_frcount_t nframes;          /* number of USB frames to transfer */
 436         usb_frcount_t aframes;          /* actual number of USB frames
 437                                          * transferred */
 438
 439         uint16_t max_packet_size;
 440         uint16_t max_frame_size;
 441         uint16_t qh_pos;
 442         uint16_t isoc_time_complete;    /* in ms */
 443         usb_timeout_t interval; /* milliseconds */
 444
 445         uint8_t address;                /* physical USB address */
 446         uint8_t endpoint;               /* physical USB endpoint */
 447         uint8_t max_packet_count;
 448         uint8_t usb2_smask;
 449         uint8_t usb2_cmask;
 450         uint8_t usb2_uframe;
 451         uint8_t usb2_state;
 452
 453         usb_error_t error;
 454
 455         struct usb_xfer_flags flags;
 456         struct usb_xfer_flags_int flags_int;
 457 };
 458
 459 /*
 460  * The following structure keeps information that is used to match
 461  * against an array of "usb_device_id" elements.
 462  */
 463 struct usb_lookup_info {
 464         uint16_t idVendor;
 465         uint16_t idProduct;
 466         uint16_t bcdDevice;
 467         uint8_t bDeviceClass;
 468         uint8_t bDeviceSubClass;
 469         uint8_t bDeviceProtocol;
 470         uint8_t bInterfaceClass;
 471         uint8_t bInterfaceSubClass;
 472         uint8_t bInterfaceProtocol;
 473         uint8_t bIfaceIndex;
 474         uint8_t bIfaceNum;
 475         uint8_t bConfigIndex;
 476         uint8_t bConfigNum;
 477 };
 478
 479 /* Structure used by probe and attach */
 480
 481 struct usb_attach_arg {
 482         struct usb_lookup_info info;
 483         device_t temp_dev;              /* for internal use */
 484         const void *driver_info;        /* for internal use */
 485         struct usb_device *device;      /* current device */
 486         struct usb_interface *iface;    /* current interface */
 487         enum usb_hc_mode usb_mode;      /* host or device mode */
 488         uint8_t port;
 489         uint8_t use_generic;            /* hint for generic drivers */
 490 };
 491
 492 /* external variables */
 493
 494 MALLOC_DECLARE(M_USB);
 495 MALLOC_DECLARE(M_USBDEV);
 496 MALLOC_DECLARE(M_USBHC);
 497
 498 extern struct mtx usb2_ref_lock;
 499
 500 /* prototypes */
 501
 502 const char *usb2_errstr(usb_error_t error);
 503 const char *usb2_statestr(enum usb_dev_state state);
 504 struct usb_config_descriptor *usb2_get_config_descriptor(
 505             struct usb_device *udev);
 506 struct usb_device_descriptor *usb2_get_device_descriptor(
 507             struct usb_device *udev);
 508 struct usb_interface *usb2_get_iface(struct usb_device *udev,
 509             uint8_t iface_index);
 510 struct usb_interface_descriptor *usb2_get_interface_descriptor(
 511             struct usb_interface *iface);
 512 uint8_t usb2_clear_stall_callback(struct usb_xfer *xfer1,
 513             struct usb_xfer *xfer2);
 514 uint8_t usb2_get_interface_altindex(struct usb_interface *iface);
 515 usb_error_t usb2_set_alt_interface_index(struct usb_device *udev,
 516             uint8_t iface_index, uint8_t alt_index);
 517 enum usb_hc_mode        usb2_get_mode(struct usb_device *udev);
 518 enum usb_dev_speed      usb2_get_speed(struct usb_device *udev);
 519 uint32_t usb2_get_isoc_fps(struct usb_device *udev);
 520 usb_error_t usb2_transfer_setup(struct usb_device *udev,
 521             const uint8_t *ifaces, struct usb_xfer **pxfer,
 522             const struct usb_config *setup_start, uint16_t n_setup,
 523             void *priv_sc, struct mtx *priv_mtx);
 524 void    usb2_set_frame_data(struct usb_xfer *xfer, void *ptr,
 525             usb_frcount_t frindex);
 526 void    usb2_set_frame_offset(struct usb_xfer *xfer, usb_frlength_t offset,
 527             usb_frcount_t frindex);
 528 void    usb2_start_hardware(struct usb_xfer *xfer);
 529 void    usb2_transfer_clear_stall(struct usb_xfer *xfer);
 530 void    usb2_transfer_drain(struct usb_xfer *xfer);
 531 void    usb2_transfer_set_stall(struct usb_xfer *xfer);
 532 uint8_t usb2_transfer_pending(struct usb_xfer *xfer);
 533 void    usb2_transfer_start(struct usb_xfer *xfer);
 534 void    usb2_transfer_stop(struct usb_xfer *xfer);
 535 void    usb2_transfer_unsetup(struct usb_xfer **pxfer, uint16_t n_setup);
 536 void    usb2_set_parent_iface(struct usb_device *udev, uint8_t iface_index,
 537             uint8_t parent_index);
 538 uint8_t usb2_get_bus_index(struct usb_device *udev);
 539 uint8_t usb2_get_device_index(struct usb_device *udev);
 540 void    usb2_set_power_mode(struct usb_device *udev, uint8_t power_mode);
 541 uint8_t usb2_device_attached(struct usb_device *udev);
 542
 543 #endif                                  /* _USB2_CORE_H_ */