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