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