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