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