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