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