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