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