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
  29  * kernel.
  30  */
  31
  32 #ifndef _USB2_CORE_H_
  33 #define _USB2_CORE_H_
  34
  35 /* Allow defines in "opt_usb.h" to override configuration */
  36
  37 #include "opt_usb.h"
  38 #include "opt_bus.h"
  39
  40 /* Default USB configuration */
  41
  42 /*
  43  * The following macro defines if the code shall use cv_xxx() instead
  44  * of msleep() and wakeup().
  45  */
  46 #ifndef USB_HAVE_CONDVAR
  47 #define USB_HAVE_CONDVAR 0
  48 #endif
  49
  50 /*
  51  * The following macro defines if the code shall support
  52  * /dev/usb/x.y.z.
  53  */
  54 #ifndef USB_HAVE_UGEN
  55 #define USB_HAVE_UGEN 1
  56 #endif
  57
  58 /*
  59  * The following macro defines if the code shall support any forms of
  60  * ASCII strings.
  61  */
  62 #ifndef USB_HAVE_STRINGS
  63 #define USB_HAVE_STRINGS 1
  64 #endif
  65
  66 /*
  67  * The following macro defines if the code shall support BUS-DMA.
  68  */
  69 #ifndef USB_HAVE_BUSDMA
  70 #define USB_HAVE_BUSDMA 1
  71 #endif
  72
  73 /*
  74  * The following macro defines if the code shall support the Linux
  75  * compatibility layer.
  76  */
  77 #ifndef USB_HAVE_COMPAT_LINUX
  78 #define USB_HAVE_COMPAT_LINUX 1
  79 #endif
  80
  81 /*
  82  * The following macro defines if the code shall support
  83  * userland data transfer via copyin() and copyout()
  84  */
  85 #ifndef USB_HAVE_USER_IO
  86 #define USB_HAVE_USER_IO 1
  87 #endif
  88
  89 /*
  90  * The following macro defines if the code shall support copy in via
  91  * bsd-mbufs to USB.
  92  */
  93 #ifndef USB_HAVE_MBUF
  94 #define USB_HAVE_MBUF 1
  95 #endif
  96
  97 /*
  98  * The following macro defines if the code shall compile a table
  99  * describing USB vendor and product IDs.
 100  */
 101 #ifndef USB_VERBOSE
 102 #define USB_VERBOSE 1
 103 #endif
 104
 105 /*
 106  * The following macro defines if USB debugging support shall be
 107  * compiled for the USB core and all drivers.
 108  */
 109 #ifndef USB_DEBUG
 110 #define USB_DEBUG 1
 111 #endif
 112
 113 #ifndef USB_TD_GET_PROC
 114 #define USB_TD_GET_PROC(td) (td)->td_proc
 115 #endif
 116
 117 #ifndef USB_PROC_GET_GID
 118 #define USB_PROC_GET_GID(td) (td)->p_pgid
 119 #endif
 120
 121 /* Include files */
 122
 123 #include <sys/stdint.h>
 124 #include <sys/stddef.h>
 125 #include <sys/param.h>
 126 #include <sys/queue.h>
 127 #include <sys/types.h>
 128 #include <sys/systm.h>
 129 #include <sys/kernel.h>
 130 #include <sys/bus.h>
 131 #include <sys/linker_set.h>
 132 #include <sys/module.h>
 133 #include <sys/lock.h>
 134 #include <sys/mutex.h>
 135 #include <sys/condvar.h>
 136 #include <sys/sysctl.h>
 137 #include <sys/sx.h>
 138 #include <sys/unistd.h>
 139 #include <sys/callout.h>
 140 #include <sys/malloc.h>
 141 #include <sys/priv.h>
 142
 143 #include <dev/usb/usb_mfunc.h>
 144 #include <dev/usb/usb_revision.h>
 145
 146 #include "usb_if.h"
 147
 148 #define USB_STACK_VERSION 2000          /* 2.0 */
 149
 150 #define USB_HOST_ALIGN    8             /* bytes, must be power of two */
 151
 152 #define USB_ISOC_TIME_MAX 128           /* ms */
 153 #define USB_FS_ISOC_UFRAME_MAX 4        /* exclusive unit */
 154
 155 #if (USB_FS_ISOC_UFRAME_MAX > 6)
 156 #error "USB_FS_ISOC_UFRAME_MAX cannot be set higher than 6"
 157 #endif
 158
 159 #define USB_MAX_FS_ISOC_FRAMES_PER_XFER (120)   /* units */
 160 #define USB_MAX_HS_ISOC_FRAMES_PER_XFER (8*120) /* units */
 161
 162 #define USB_MAX_IPACKET         8       /* maximum size of the initial USB
 163                                          * data packet */
 164 #define USB_HUB_MAX_DEPTH 5
 165
 166 /* USB transfer states */
 167
 168 #define USB_ST_SETUP       0
 169 #define USB_ST_TRANSFERRED 1
 170 #define USB_ST_ERROR       2
 171
 172 /*
 173  * The following macro will return the current state of an USB
 174  * transfer like defined by the "USB_ST_XXX" enums.
 175  */
 176 #define USB_GET_STATE(xfer) ((xfer)->usb2_state)
 177
 178 /*
 179  * The following macro will tell if an USB transfer is currently
 180  * receiving or transferring data.
 181  */
 182 #define USB_GET_DATA_ISREAD(xfer) (((xfer)->flags_int.usb2_mode == \
 183         USB_MODE_DEVICE) ? ((xfer->endpoint & UE_DIR_IN) ? 0 : 1) : \
 184         ((xfer->endpoint & UE_DIR_IN) ? 1 : 0))
 185
 186 /*
 187  * The following macros are used used to convert milliseconds into
 188  * HZ. We use 1024 instead of 1000 milliseconds per second to save a
 189  * full division.
 190  */
 191 #define USB_MS_HZ 1024
 192
 193 #define USB_MS_TO_TICKS(ms) \
 194   (((uint32_t)((((uint32_t)(ms)) * ((uint32_t)(hz))) + USB_MS_HZ - 1)) / USB_MS_HZ)
 195
 196 /* macros */
 197
 198 #define usb2_callout_init_mtx(c,m,f) callout_init_mtx(&(c)->co,m,f)
 199 #define usb2_callout_reset(c,t,f,d) callout_reset(&(c)->co,t,f,d)
 200 #define usb2_callout_stop(c) callout_stop(&(c)->co)
 201 #define usb2_callout_drain(c) callout_drain(&(c)->co)
 202 #define usb2_callout_pending(c) callout_pending(&(c)->co)
 203
 204 #define USB_BUS_LOCK(_b)                mtx_lock(&(_b)->bus_mtx)
 205 #define USB_BUS_UNLOCK(_b)              mtx_unlock(&(_b)->bus_mtx)
 206 #define USB_BUS_LOCK_ASSERT(_b, _t)     mtx_assert(&(_b)->bus_mtx, _t)
 207 #define USB_XFER_LOCK(_x)               mtx_lock((_x)->xroot->xfer_mtx)
 208 #define USB_XFER_UNLOCK(_x)             mtx_unlock((_x)->xroot->xfer_mtx)
 209 #define USB_XFER_LOCK_ASSERT(_x, _t)    mtx_assert((_x)->xroot->xfer_mtx, _t)
 210 /* structure prototypes */
 211
 212 struct file;
 213 struct usb2_bus;
 214 struct usb2_device;
 215 struct usb2_page;
 216 struct usb2_page_cache;
 217 struct usb2_xfer;
 218 struct usb2_xfer_root;
 219
 220 /* typedefs */
 221
 222 typedef void (usb2_callback_t)(struct usb2_xfer *);
 223
 224 #ifndef USB_HAVE_USB_ERROR_T
 225 typedef uint8_t usb2_error_t;           /* see "USB_ERR_XXX" */
 226 #endif
 227
 228 #ifndef USB_HAVE_TIMEOUT_T
 229 typedef uint32_t usb2_timeout_t;        /* milliseconds */
 230 #endif
 231
 232 #ifndef USB_HAVE_LENGTH_T
 233 typedef uint32_t usb2_length_t;         /* bytes */
 234 #endif
 235
 236 #ifndef USB_HAVE_FRAMES_T
 237 typedef uint32_t usb2_frames_t;         /* units */
 238 #endif
 239
 240 #ifndef USB_HAVE_INTERVAL_T
 241 typedef uint32_t usb2_interval_t;       /* milliseconds */
 242 #endif
 243
 244 #ifndef USB_HAVE_SIZE_T
 245 typedef uint32_t usb2_size_t;           /* bytes */
 246 #endif
 247
 248 #ifndef USB_HAVE_REFS_T
 249 typedef uint32_t usb2_refs_t;           /* units */
 250 #endif
 251
 252 #ifndef USB_HAVE_TICKS_T
 253 typedef uint32_t usb2_ticks_t;          /* system defined */
 254 #endif
 255
 256 /* structures */
 257
 258 /*
 259  * Common queue structure for USB transfers.
 260  */
 261 struct usb2_xfer_queue {
 262         TAILQ_HEAD(, usb2_xfer) head;
 263         struct usb2_xfer *curr;         /* current USB transfer processed */
 264         void    (*command) (struct usb2_xfer_queue *pq);
 265         uint8_t recurse_1:1;
 266         uint8_t recurse_2:1;
 267 };
 268
 269 /*
 270  * The following is a wrapper for the callout structure to ease
 271  * porting the code to other platforms.
 272  */
 273 struct usb2_callout {
 274         struct callout co;
 275 };
 276
 277 /*
 278  * The following structure defines a set of USB transfer flags.
 279  */
 280 struct usb2_xfer_flags {
 281         uint8_t force_short_xfer:1;     /* force a short transmit transfer
 282                                          * last */
 283         uint8_t short_xfer_ok:1;        /* allow short receive transfers */
 284         uint8_t short_frames_ok:1;      /* allow short frames */
 285         uint8_t pipe_bof:1;             /* block pipe on failure */
 286         uint8_t proxy_buffer:1;         /* makes buffer size a factor of
 287                                          * "max_frame_size" */
 288         uint8_t ext_buffer:1;           /* uses external DMA buffer */
 289         uint8_t manual_status:1;        /* non automatic status stage on
 290                                          * control transfers */
 291         uint8_t no_pipe_ok:1;           /* set if "USB_ERR_NO_PIPE" error can
 292                                          * be ignored */
 293         uint8_t stall_pipe:1;           /* set if the endpoint belonging to
 294                                          * this USB transfer should be stalled
 295                                          * before starting this transfer! */
 296 };
 297
 298 /*
 299  * The following structure defines a set of internal USB transfer
 300  * flags.
 301  */
 302 struct usb2_xfer_flags_int {
 303         uint16_t control_rem;           /* remainder in bytes */
 304
 305         uint8_t open:1;                 /* set if USB pipe has been opened */
 306         uint8_t transferring:1;         /* set if an USB transfer is in
 307                                          * progress */
 308         uint8_t did_dma_delay:1;        /* set if we waited for HW DMA */
 309         uint8_t did_close:1;            /* set if we closed the USB transfer */
 310         uint8_t draining:1;             /* set if we are draining an USB
 311                                          * transfer */
 312         uint8_t started:1;              /* keeps track of started or stopped */
 313         uint8_t bandwidth_reclaimed:1;
 314         uint8_t control_xfr:1;          /* set if control transfer */
 315         uint8_t control_hdr:1;          /* set if control header should be
 316                                          * sent */
 317         uint8_t control_act:1;          /* set if control transfer is active */
 318
 319         uint8_t short_frames_ok:1;      /* filtered version */
 320         uint8_t short_xfer_ok:1;        /* filtered version */
 321 #if USB_HAVE_BUSDMA
 322         uint8_t bdma_enable:1;          /* filtered version (only set if
 323                                          * hardware supports DMA) */
 324         uint8_t bdma_no_post_sync:1;    /* set if the USB callback wrapper
 325                                          * should not do the BUS-DMA post sync
 326                                          * operation */
 327         uint8_t bdma_setup:1;           /* set if BUS-DMA has been setup */
 328 #endif
 329         uint8_t isochronous_xfr:1;      /* set if isochronous transfer */
 330         uint8_t usb2_mode:1;            /* shadow copy of "udev->usb2_mode" */
 331         uint8_t curr_dma_set:1;         /* used by USB HC/DC driver */
 332         uint8_t can_cancel_immed:1;     /* set if USB transfer can be
 333                                          * cancelled immediately */
 334 };
 335
 336 /*
 337  * The following structure defines the symmetric part of an USB config
 338  * structure.
 339  */
 340 struct usb2_config_sub {
 341         usb2_callback_t *callback;      /* USB transfer callback */
 342         uint32_t bufsize;               /* total pipe buffer size in bytes */
 343         uint32_t frames;                /* maximum number of USB frames */
 344         uint16_t interval;              /* interval in milliseconds */
 345 #define USB_DEFAULT_INTERVAL    0
 346         uint16_t timeout;               /* transfer timeout in milliseconds */
 347         struct usb2_xfer_flags flags;   /* transfer flags */
 348 };
 349
 350 /*
 351  * The following structure define an USB configuration, that basically
 352  * is used when setting up an USB transfer.
 353  */
 354 struct usb2_config {
 355         struct usb2_config_sub mh;      /* parameters for USB_MODE_HOST */
 356         struct usb2_config_sub md;      /* parameters for USB_MODE_DEVICE */
 357         uint8_t type;                   /* pipe type */
 358         uint8_t endpoint;               /* pipe number */
 359         uint8_t direction;              /* pipe direction */
 360         uint8_t ep_index;               /* pipe index match to use */
 361         uint8_t if_index;               /* "ifaces" index to use */
 362 };
 363
 364 /*
 365  * The following structure defines an USB transfer.
 366  */
 367 struct usb2_xfer {
 368         struct usb2_callout timeout_handle;
 369         TAILQ_ENTRY(usb2_xfer) wait_entry;      /* used at various places */
 370
 371         struct usb2_page_cache *buf_fixup;      /* fixup buffer(s) */
 372         struct usb2_xfer_queue *wait_queue;     /* pointer to queue that we
 373                                                  * are waiting on */
 374         struct usb2_page *dma_page_ptr;
 375         struct usb2_pipe *pipe;         /* our USB pipe */
 376         struct usb2_xfer_root *xroot;   /* used by HC driver */
 377         void   *qh_start[2];            /* used by HC driver */
 378         void   *td_start[2];            /* used by HC driver */
 379         void   *td_transfer_first;      /* used by HC driver */
 380         void   *td_transfer_last;       /* used by HC driver */
 381         void   *td_transfer_cache;      /* used by HC driver */
 382         void   *priv_sc;                /* device driver data pointer 1 */
 383         void   *priv_fifo;              /* device driver data pointer 2 */
 384         void   *local_buffer;
 385         uint32_t *frlengths;
 386         struct usb2_page_cache *frbuffers;
 387         usb2_callback_t *callback;
 388
 389         uint32_t max_usb2_frame_size;
 390         uint32_t max_data_length;
 391         uint32_t sumlen;                /* sum of all lengths in bytes */
 392         uint32_t actlen;                /* actual length in bytes */
 393         uint32_t timeout;               /* milliseconds */
 394 #define USB_NO_TIMEOUT 0
 395 #define USB_DEFAULT_TIMEOUT 5000        /* 5000 ms = 5 seconds */
 396
 397         uint32_t max_frame_count;       /* initial value of "nframes" after
 398                                          * setup */
 399         uint32_t nframes;               /* number of USB frames to transfer */
 400         uint32_t aframes;               /* actual number of USB frames
 401                                          * transferred */
 402
 403         uint16_t max_packet_size;
 404         uint16_t max_frame_size;
 405         uint16_t qh_pos;
 406         uint16_t isoc_time_complete;    /* in ms */
 407         uint16_t interval;              /* milliseconds */
 408
 409         uint8_t address;                /* physical USB address */
 410         uint8_t endpoint;               /* physical USB endpoint */
 411         uint8_t max_packet_count;
 412         uint8_t usb2_smask;
 413         uint8_t usb2_cmask;
 414         uint8_t usb2_uframe;
 415         uint8_t usb2_state;
 416
 417         usb2_error_t error;
 418
 419         struct usb2_xfer_flags flags;
 420         struct usb2_xfer_flags_int flags_int;
 421 };
 422
 423 /*
 424  * The following structure keeps information that is used to match
 425  * against an array of "usb2_device_id" elements.
 426  */
 427 struct usb2_lookup_info {
 428         uint16_t idVendor;
 429         uint16_t idProduct;
 430         uint16_t bcdDevice;
 431         uint8_t bDeviceClass;
 432         uint8_t bDeviceSubClass;
 433         uint8_t bDeviceProtocol;
 434         uint8_t bInterfaceClass;
 435         uint8_t bInterfaceSubClass;
 436         uint8_t bInterfaceProtocol;
 437         uint8_t bIfaceIndex;
 438         uint8_t bIfaceNum;
 439         uint8_t bConfigIndex;
 440         uint8_t bConfigNum;
 441 };
 442
 443 /* Structure used by probe and attach */
 444
 445 struct usb2_attach_arg {
 446         struct usb2_lookup_info info;
 447         device_t temp_dev;              /* for internal use */
 448         const void *driver_info;        /* for internal use */
 449         struct usb2_device *device;     /* current device */
 450         struct usb2_interface *iface;   /* current interface */
 451         uint8_t usb2_mode;              /* see USB_MODE_XXX */
 452         uint8_t port;
 453         uint8_t use_generic;            /* hint for generic drivers */
 454 };
 455
 456 /* external variables */
 457
 458 MALLOC_DECLARE(M_USB);
 459 MALLOC_DECLARE(M_USBDEV);
 460 MALLOC_DECLARE(M_USBHC);
 461
 462 extern struct mtx usb2_ref_lock;
 463
 464 /* typedefs */
 465
 466 typedef struct malloc_type *usb2_malloc_type;
 467
 468 /* prototypes */
 469
 470 const char *usb2_errstr(usb2_error_t error);
 471 struct usb2_config_descriptor *usb2_get_config_descriptor(
 472             struct usb2_device *udev);
 473 struct usb2_device_descriptor *usb2_get_device_descriptor(
 474             struct usb2_device *udev);
 475 struct usb2_interface *usb2_get_iface(struct usb2_device *udev,
 476             uint8_t iface_index);
 477 struct usb2_interface_descriptor *usb2_get_interface_descriptor(
 478             struct usb2_interface *iface);
 479 uint8_t usb2_clear_stall_callback(struct usb2_xfer *xfer1,
 480             struct usb2_xfer *xfer2);
 481 uint8_t usb2_get_interface_altindex(struct usb2_interface *iface);
 482 usb2_error_t usb2_set_alt_interface_index(struct usb2_device *udev,
 483             uint8_t iface_index, uint8_t alt_index);
 484 uint8_t usb2_get_mode(struct usb2_device *udev);
 485 uint8_t usb2_get_speed(struct usb2_device *udev);
 486 uint32_t usb2_get_isoc_fps(struct usb2_device *udev);
 487 usb2_error_t usb2_transfer_setup(struct usb2_device *udev,
 488             const uint8_t *ifaces, struct usb2_xfer **pxfer,
 489             const struct usb2_config *setup_start, uint16_t n_setup,
 490             void *priv_sc, struct mtx *priv_mtx);
 491 void    usb2_set_frame_data(struct usb2_xfer *xfer, void *ptr,
 492             uint32_t frindex);
 493 void    usb2_set_frame_offset(struct usb2_xfer *xfer, uint32_t offset,
 494             uint32_t frindex);
 495 void    usb2_start_hardware(struct usb2_xfer *xfer);
 496 void    usb2_transfer_clear_stall(struct usb2_xfer *xfer);
 497 void    usb2_transfer_drain(struct usb2_xfer *xfer);
 498 void    usb2_transfer_set_stall(struct usb2_xfer *xfer);
 499 uint8_t usb2_transfer_pending(struct usb2_xfer *xfer);
 500 void    usb2_transfer_start(struct usb2_xfer *xfer);
 501 void    usb2_transfer_stop(struct usb2_xfer *xfer);
 502 void    usb2_transfer_unsetup(struct usb2_xfer **pxfer, uint16_t n_setup);
 503 void    usb2_set_parent_iface(struct usb2_device *udev, uint8_t iface_index,
 504             uint8_t parent_index);
 505 uint8_t usb2_get_bus_index(struct usb2_device *udev);
 506 uint8_t usb2_get_device_index(struct usb2_device *udev);
 507 void    usb2_set_power_mode(struct usb2_device *udev, uint8_t power_mode);
 508
 509 #endif                                  /* _USB2_CORE_H_ */