usb_core.h revision 184824
1169689Skan/* $FreeBSD: head/sys/dev/usb2/core/usb2_core.h 184824 2008-11-10 20:54:31Z thompsa $ */ 2169689Skan/*- 3169689Skan * Copyright (c) 2008 Hans Petter Selasky. All rights reserved. 4169689Skan * 5169689Skan * Redistribution and use in source and binary forms, with or without 6169689Skan * modification, are permitted provided that the following conditions 7169689Skan * are met: 8169689Skan * 1. Redistributions of source code must retain the above copyright 9169689Skan * notice, this list of conditions and the following disclaimer. 10169689Skan * 2. Redistributions in binary form must reproduce the above copyright 11169689Skan * notice, this list of conditions and the following disclaimer in the 12169689Skan * documentation and/or other materials provided with the distribution. 13169689Skan * 14169689Skan * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15169689Skan * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16169689Skan * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17169689Skan * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 18169689Skan * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19169689Skan * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20169689Skan * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21169689Skan * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22169689Skan * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23169689Skan * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24169689Skan * SUCH DAMAGE. 25169689Skan */ 26169689Skan 27169689Skan/* 28169689Skan * Including this file is mandatory for all USB related c-files in the 29169689Skan * kernel. 30169689Skan */ 31169689Skan 32169689Skan#ifndef _USB2_CORE_H_ 33169689Skan#define _USB2_CORE_H_ 34169689Skan 35169689Skan/* Default USB configuration */ 36169689Skan 37169689Skan#ifndef USB_NO_POLL 38169689Skan#define USB_NO_POLL 0 39169689Skan#endif 40169689Skan 41169689Skan#ifndef USB_USE_CONDVAR 42169689Skan#define USB_USE_CONDVAR 0 43169689Skan#endif 44169689Skan 45169689Skan#ifndef USB_TD_GET_PROC 46169689Skan#define USB_TD_GET_PROC(td) (td)->td_proc 47169689Skan#endif 48169689Skan 49169689Skan#ifndef USB_PROC_GET_GID 50169689Skan#define USB_PROC_GET_GID(td) (td)->p_pgid 51169689Skan#endif 52169689Skan 53169689Skan#ifndef USB_VNOPS_FO_CLOSE 54169689Skan#define USB_VNOPS_FO_CLOSE(fp, td, perr) do { \ 55169689Skan (td)->td_fpop = (fp); \ 56169689Skan *(perr) = vnops.fo_close(fp, td); \ 57169689Skan (td)->td_fpop = NULL; \ 58169689Skan} while (0) 59169689Skan#endif 60169689Skan 61169689Skan#ifndef USB_VNOPS_FO_STAT 62169689Skan#define USB_VNOPS_FO_STAT(fp, sb, cred, td) \ 63169689Skan vnops.fo_stat(fp, sb, cred, td) 64169689Skan#endif 65169689Skan 66169689Skan#ifndef USB_VNOPS_FO_TRUNCATE 67169689Skan#define USB_VNOPS_FO_TRUNCATE(fp, length, cred, td) \ 68169689Skan vnops.fo_truncate(fp, length, cred, td) 69169689Skan#endif 70169689Skan 71169689Skan/* Include files */ 72169689Skan 73169689Skan#include <sys/stdint.h> 74169689Skan#include <sys/stddef.h> 75169689Skan#include <sys/param.h> 76169689Skan#include <sys/queue.h> 77169689Skan#include <sys/types.h> 78169689Skan#include <sys/systm.h> 79169689Skan#include <sys/kernel.h> 80169689Skan#include <sys/bus.h> 81169689Skan#include <sys/linker_set.h> 82169689Skan#include <sys/module.h> 83169689Skan#include <sys/lock.h> 84169689Skan#include <sys/mutex.h> 85169689Skan#include <sys/condvar.h> 86169689Skan#include <sys/sysctl.h> 87169689Skan#include <sys/sx.h> 88169689Skan#include <sys/unistd.h> 89169689Skan#include <sys/callout.h> 90169689Skan#include <sys/malloc.h> 91169689Skan#include <sys/priv.h> 92169689Skan 93169689Skan#include <dev/usb2/include/usb2_mfunc.h> 94169689Skan#include <dev/usb2/include/usb2_revision.h> 95169689Skan 96169689Skan#include "usb2_if.h" 97169689Skan#include "opt_usb.h" 98169689Skan#include "opt_bus.h" 99169689Skan 100169689Skan#define USB_STACK_VERSION 2000 /* 2.0 */ 101169689Skan 102169689Skan#define USB_HOST_ALIGN 8 /* bytes, must be power of two */ 103169689Skan 104169689Skan#define USB_ROOT_HUB_ADDR 1 /* value */ 105169689Skan 106169689Skan#define USB_ISOC_TIME_MAX 128 /* ms */ 107169689Skan#define USB_FS_ISOC_UFRAME_MAX 4 /* exclusive unit */ 108169689Skan 109169689Skan#if (USB_FS_ISOC_UFRAME_MAX > 6) 110169689Skan#error "USB_FS_ISOC_UFRAME_MAX cannot be set higher than 6" 111169689Skan#endif 112169689Skan 113169689Skan#define USB_MAX_FS_ISOC_FRAMES_PER_XFER (120) /* units */ 114169689Skan#define USB_MAX_HS_ISOC_FRAMES_PER_XFER (8*120) /* units */ 115169689Skan 116169689Skan#define USB_MAX_IPACKET 8 /* maximum size of the initial USB 117169689Skan * data packet */ 118169689Skan#ifndef USB_VERBOSE 119169689Skan#define USB_VERBOSE 1 120169689Skan#endif 121169689Skan 122169689Skan#define USB_HUB_MAX_DEPTH 5 123169689Skan 124169689Skan/* USB transfer states */ 125169689Skan 126169689Skan#define USB_ST_SETUP 0 127169689Skan#define USB_ST_TRANSFERRED 1 128169689Skan#define USB_ST_ERROR 2 129169689Skan 130169689Skan/* 131169689Skan * The following macro will return the current state of an USB 132169689Skan * transfer like defined by the "USB_ST_XXX" enums. 133169689Skan */ 134169689Skan#define USB_GET_STATE(xfer) ((xfer)->usb2_state) 135169689Skan 136169689Skan/* 137169689Skan * The following macro will tell if an USB transfer is currently 138169689Skan * receiving or transferring data. 139169689Skan */ 140169689Skan#define USB_GET_DATA_ISREAD(xfer) (((xfer)->flags_int.usb2_mode == \ 141169689Skan USB_MODE_DEVICE) ? ((xfer->endpoint & UE_DIR_IN) ? 0 : 1) : \ 142169689Skan ((xfer->endpoint & UE_DIR_IN) ? 1 : 0)) 143169689Skan 144169689Skan/* 145169689Skan * The following macros are used used to convert milliseconds into 146169689Skan * HZ. We use 1024 instead of 1000 milliseconds per second to save a 147169689Skan * full division. 148169689Skan */ 149169689Skan#define USB_MS_HZ 1024 150169689Skan 151169689Skan#define USB_MS_TO_TICKS(ms) \ 152169689Skan (((uint32_t)((((uint32_t)(ms)) * ((uint32_t)(hz))) + USB_MS_HZ - 1)) / USB_MS_HZ) 153169689Skan 154169689Skan/* macros */ 155169689Skan 156169689Skan#define usb2_callout_init_mtx(c,m,f) callout_init_mtx(&(c)->co,m,f) 157169689Skan#define usb2_callout_reset(c,t,f,d) callout_reset(&(c)->co,t,f,d) 158169689Skan#define usb2_callout_stop(c) callout_stop(&(c)->co) 159169689Skan#define usb2_callout_drain(c) callout_drain(&(c)->co) 160169689Skan#define usb2_callout_pending(c) callout_pending(&(c)->co) 161169689Skan 162169689Skan#define USB_BUS_LOCK(_b) mtx_lock(&(_b)->bus_mtx) 163169689Skan#define USB_BUS_UNLOCK(_b) mtx_unlock(&(_b)->bus_mtx) 164169689Skan#define USB_BUS_LOCK_ASSERT(_b, _t) mtx_assert(&(_b)->bus_mtx, _t) 165169689Skan#define USB_XFER_LOCK(_x) mtx_lock((_x)->xfer_mtx) 166169689Skan#define USB_XFER_UNLOCK(_x) mtx_unlock((_x)->xfer_mtx) 167169689Skan#define USB_XFER_LOCK_ASSERT(_x, _t) mtx_assert((_x)->xfer_mtx, _t) 168169689Skan/* structure prototypes */ 169169689Skan 170169689Skanstruct file; 171169689Skanstruct usb2_bus; 172169689Skanstruct usb2_device; 173169689Skanstruct usb2_page; 174169689Skanstruct usb2_page_cache; 175169689Skanstruct usb2_xfer; 176169689Skanstruct usb2_xfer_root; 177169689Skan 178169689Skan/* typedefs */ 179169689Skan 180169689Skantypedef uint8_t usb2_error_t; 181169689Skan 182169689Skantypedef void (usb2_callback_t)(struct usb2_xfer *); 183169689Skan 184169689Skan/* structures */ 185169689Skan 186169689Skan/* 187169689Skan * This structure contains permissions. 188169689Skan */ 189169689Skan 190169689Skanstruct usb2_perm { 191169689Skan uint32_t uid; 192169689Skan uint32_t gid; 193169689Skan uint16_t mode; 194169689Skan}; 195169689Skan 196169689Skan/* 197169689Skan * Common queue structure for USB transfers. 198169689Skan */ 199169689Skanstruct usb2_xfer_queue { 200169689Skan TAILQ_HEAD(, usb2_xfer) head; 201169689Skan struct usb2_xfer *curr; /* current USB transfer processed */ 202169689Skan void (*command) (struct usb2_xfer_queue *pq); 203169689Skan uint8_t recurse_1:1; 204169689Skan uint8_t recurse_2:1; 205169689Skan}; 206169689Skan 207169689Skan/* 208169689Skan * The following is a wrapper for the callout structure to ease 209169689Skan * porting the code to other platforms. 210169689Skan */ 211169689Skanstruct usb2_callout { 212169689Skan struct callout co; 213169689Skan}; 214169689Skan 215169689Skan/* 216169689Skan * The following structure defines a set of USB transfer flags. 217169689Skan */ 218169689Skanstruct usb2_xfer_flags { 219169689Skan uint8_t force_short_xfer:1; /* force a short transmit transfer 220169689Skan * last */ 221169689Skan uint8_t short_xfer_ok:1; /* allow short receive transfers */ 222169689Skan uint8_t short_frames_ok:1; /* allow short frames */ 223169689Skan uint8_t pipe_bof:1; /* block pipe on failure */ 224169689Skan uint8_t proxy_buffer:1; /* makes buffer size a factor of 225169689Skan * "max_frame_size" */ 226169689Skan uint8_t ext_buffer:1; /* uses external DMA buffer */ 227 uint8_t manual_status:1; /* non automatic status stage on 228 * control transfers */ 229 uint8_t no_pipe_ok:1; /* set if "USB_ERR_NO_PIPE" error can 230 * be ignored */ 231 uint8_t stall_pipe:1; /* set if the endpoint belonging to 232 * this USB transfer should be stalled 233 * before starting this transfer! */ 234}; 235 236/* 237 * The following structure defines a set of internal USB transfer 238 * flags. 239 */ 240struct usb2_xfer_flags_int { 241 uint16_t control_rem; /* remainder in bytes */ 242 243 uint8_t open:1; /* set if USB pipe has been opened */ 244 uint8_t transferring:1; /* set if an USB transfer is in 245 * progress */ 246 uint8_t did_dma_delay:1; /* set if we waited for HW DMA */ 247 uint8_t did_close:1; /* set if we closed the USB transfer */ 248 uint8_t draining:1; /* set if we are draining an USB 249 * transfer */ 250 uint8_t started:1; /* keeps track of started or stopped */ 251 uint8_t bandwidth_reclaimed:1; 252 uint8_t control_xfr:1; /* set if control transfer */ 253 uint8_t control_hdr:1; /* set if control header should be 254 * sent */ 255 uint8_t control_act:1; /* set if control transfer is active */ 256 257 uint8_t short_frames_ok:1; /* filtered version */ 258 uint8_t short_xfer_ok:1; /* filtered version */ 259 uint8_t bdma_enable:1; /* filtered version (only set if 260 * hardware supports DMA) */ 261 uint8_t bdma_no_post_sync:1; /* set if the USB callback wrapper 262 * should not do the BUS-DMA post sync 263 * operation */ 264 uint8_t bdma_setup:1; /* set if BUS-DMA has been setup */ 265 uint8_t isochronous_xfr:1; /* set if isochronous transfer */ 266 uint8_t usb2_mode:1; /* shadow copy of "udev->usb2_mode" */ 267 uint8_t curr_dma_set:1; /* used by USB HC/DC driver */ 268 uint8_t can_cancel_immed:1; /* set if USB transfer can be 269 * cancelled immediately */ 270}; 271 272/* 273 * The following structure defines the symmetric part of an USB config 274 * structure. 275 */ 276struct usb2_config_sub { 277 usb2_callback_t *callback; /* USB transfer callback */ 278 uint32_t bufsize; /* total pipe buffer size in bytes */ 279 uint32_t frames; /* maximum number of USB frames */ 280 uint16_t interval; /* interval in milliseconds */ 281#define USB_DEFAULT_INTERVAL 0 282 uint16_t timeout; /* transfer timeout in milliseconds */ 283 struct usb2_xfer_flags flags; /* transfer flags */ 284}; 285 286/* 287 * The following structure define an USB configuration, that basically 288 * is used when setting up an USB transfer. 289 */ 290struct usb2_config { 291 struct usb2_config_sub mh; /* parameters for USB_MODE_HOST */ 292 struct usb2_config_sub md; /* parameters for USB_MODE_DEVICE */ 293 uint8_t type; /* pipe type */ 294 uint8_t endpoint; /* pipe number */ 295 uint8_t direction; /* pipe direction */ 296 uint8_t ep_index; /* pipe index match to use */ 297 uint8_t if_index; /* "ifaces" index to use */ 298}; 299 300/* 301 * The following structure defines an USB transfer. 302 */ 303struct usb2_xfer { 304 struct usb2_callout timeout_handle; 305 TAILQ_ENTRY(usb2_xfer) wait_entry; /* used at various places */ 306 307 struct usb2_page_cache *buf_fixup; /* fixup buffer(s) */ 308 struct usb2_xfer_queue *wait_queue; /* pointer to queue that we 309 * are waiting on */ 310 struct usb2_page *dma_page_ptr; 311 struct usb2_pipe *pipe; /* our USB pipe */ 312 struct usb2_device *udev; 313 struct mtx *xfer_mtx; /* cannot be changed during operation */ 314 struct usb2_xfer_root *usb2_root; /* used by HC driver */ 315 void *usb2_sc; /* used by HC driver */ 316 void *qh_start[2]; /* used by HC driver */ 317 void *td_start[2]; /* used by HC driver */ 318 void *td_transfer_first; /* used by HC driver */ 319 void *td_transfer_last; /* used by HC driver */ 320 void *td_transfer_cache; /* used by HC driver */ 321 void *priv_sc; /* device driver data pointer 1 */ 322 void *priv_fifo; /* device driver data pointer 2 */ 323 void *local_buffer; 324 uint32_t *frlengths; 325 struct usb2_page_cache *frbuffers; 326 usb2_callback_t *callback; 327 328 uint32_t max_usb2_frame_size; 329 uint32_t max_data_length; 330 uint32_t sumlen; /* sum of all lengths in bytes */ 331 uint32_t actlen; /* actual length in bytes */ 332 uint32_t timeout; /* milliseconds */ 333#define USB_NO_TIMEOUT 0 334#define USB_DEFAULT_TIMEOUT 5000 /* 5000 ms = 5 seconds */ 335 336 uint32_t max_frame_count; /* initial value of "nframes" after 337 * setup */ 338 uint32_t nframes; /* number of USB frames to transfer */ 339 uint32_t aframes; /* actual number of USB frames 340 * transferred */ 341 342 uint16_t max_packet_size; 343 uint16_t max_frame_size; 344 uint16_t qh_pos; 345 uint16_t isoc_time_complete; /* in ms */ 346 uint16_t interval; /* milliseconds */ 347 348 uint8_t address; /* physical USB address */ 349 uint8_t endpoint; /* physical USB endpoint */ 350 uint8_t max_packet_count; 351 uint8_t usb2_smask; 352 uint8_t usb2_cmask; 353 uint8_t usb2_uframe; 354 uint8_t usb2_state; 355 356 usb2_error_t error; 357 358 struct usb2_xfer_flags flags; 359 struct usb2_xfer_flags_int flags_int; 360}; 361 362/* 363 * The following structure keeps information that is used to match 364 * against an array of "usb2_device_id" elements. 365 */ 366struct usb2_lookup_info { 367 uint16_t idVendor; 368 uint16_t idProduct; 369 uint16_t bcdDevice; 370 uint8_t bDeviceClass; 371 uint8_t bDeviceSubClass; 372 uint8_t bDeviceProtocol; 373 uint8_t bInterfaceClass; 374 uint8_t bInterfaceSubClass; 375 uint8_t bInterfaceProtocol; 376 uint8_t bIfaceIndex; 377 uint8_t bIfaceNum; 378 uint8_t bConfigIndex; 379 uint8_t bConfigNum; 380}; 381 382/* Structure used by probe and attach */ 383 384struct usb2_attach_arg { 385 struct usb2_lookup_info info; 386 device_t temp_dev; /* for internal use */ 387 const void *driver_info; /* for internal use */ 388 struct usb2_device *device; /* current device */ 389 struct usb2_interface *iface; /* current interface */ 390 uint8_t usb2_mode; /* see USB_MODE_XXX */ 391 uint8_t port; 392 uint8_t use_generic; /* hint for generic drivers */ 393}; 394 395/* Structure used when referring an USB device */ 396 397struct usb2_location { 398 struct usb2_bus *bus; 399 struct usb2_device *udev; 400 struct usb2_interface *iface; 401 struct usb2_fifo *rxfifo; 402 struct usb2_fifo *txfifo; 403 uint32_t devloc; /* original devloc */ 404 uint16_t bus_index; 405 uint8_t dev_index; 406 uint8_t iface_index; 407 uint8_t ep_index; 408 uint8_t is_read; 409 uint8_t is_write; 410 uint8_t is_uref; 411}; 412 413/* external variables */ 414 415MALLOC_DECLARE(M_USB); 416MALLOC_DECLARE(M_USBDEV); 417MALLOC_DECLARE(M_USBHC); 418 419extern struct mtx usb2_ref_lock; 420 421/* typedefs */ 422 423typedef struct malloc_type *usb2_malloc_type; 424 425/* prototypes */ 426 427const char *usb2_errstr(usb2_error_t error); 428struct usb2_config_descriptor *usb2_get_config_descriptor(struct usb2_device *udev); 429struct usb2_device_descriptor *usb2_get_device_descriptor(struct usb2_device *udev); 430struct usb2_interface *usb2_get_iface(struct usb2_device *udev, uint8_t iface_index); 431struct usb2_interface_descriptor *usb2_get_interface_descriptor(struct usb2_interface *iface); 432uint8_t usb2_clear_stall_callback(struct usb2_xfer *xfer1, struct usb2_xfer *xfer2); 433uint8_t usb2_get_interface_altindex(struct usb2_interface *iface); 434usb2_error_t usb2_set_alt_interface_index(struct usb2_device *udev, uint8_t iface_index, uint8_t alt_index); 435uint8_t usb2_get_speed(struct usb2_device *udev); 436usb2_error_t usb2_transfer_setup(struct usb2_device *udev, const uint8_t *ifaces, struct usb2_xfer **pxfer, const struct usb2_config *setup_start, uint16_t n_setup, void *priv_sc, struct mtx *priv_mtx); 437void usb2_set_frame_data(struct usb2_xfer *xfer, void *ptr, uint32_t frindex); 438void usb2_set_frame_offset(struct usb2_xfer *xfer, uint32_t offset, uint32_t frindex); 439void usb2_start_hardware(struct usb2_xfer *xfer); 440void usb2_transfer_clear_stall(struct usb2_xfer *xfer); 441void usb2_transfer_drain(struct usb2_xfer *xfer); 442void usb2_transfer_set_stall(struct usb2_xfer *xfer); 443void usb2_transfer_start(struct usb2_xfer *xfer); 444void usb2_transfer_stop(struct usb2_xfer *xfer); 445void usb2_transfer_unsetup(struct usb2_xfer **pxfer, uint16_t n_setup); 446usb2_error_t usb2_ref_device(struct file *fp, struct usb2_location *ploc, uint32_t devloc); 447void usb2_unref_device(struct usb2_location *ploc); 448void usb2_set_parent_iface(struct usb2_device *udev, uint8_t iface_index, uint8_t parent_index); 449void usb2_set_iface_perm(struct usb2_device *udev, uint8_t iface_index, uint32_t uid, uint32_t gid, uint16_t mode); 450uint8_t usb2_get_bus_index(struct usb2_device *udev); 451uint8_t usb2_get_device_index(struct usb2_device *udev); 452 453#endif /* _USB2_CORE_H_ */ 454