1 /* $FreeBSD$ */ 2 /*- 3 * SPDX-License-Identifier: BSD-2-Clause 4 * 5 * Copyright (c) 2008 Hans Petter Selasky. All rights reserved. 6 * 7 * Redistribution and use in source and binary forms, with or without 8 * modification, are permitted provided that the following conditions 9 * are met: 10 * 1. Redistributions of source code must retain the above copyright 11 * notice, this list of conditions and the following disclaimer. 12 * 2. Redistributions in binary form must reproduce the above copyright 13 * notice, this list of conditions and the following disclaimer in the 14 * documentation and/or other materials provided with the distribution. 15 * 16 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 17 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 19 * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 20 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 21 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 22 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 23 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 24 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 25 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 26 * SUCH DAMAGE. 27 */ 28 29 /* 30 * Including this file is mandatory for all USB related c-files in the kernel. 31 */ 32 33 #ifndef _USB_CORE_H_ 34 #define _USB_CORE_H_ 35 36 /* 37 * The following macro will tell if an USB transfer is currently 38 * receiving or transferring data. 39 */ 40 #define USB_GET_DATA_ISREAD(xfer) ((xfer)->flags_int.usb_mode == \ 41 USB_MODE_DEVICE ? (((xfer)->endpointno & UE_DIR_IN) ? 0 : 1) : \ 42 (((xfer)->endpointno & UE_DIR_IN) ? 1 : 0)) 43 44 /* locking wrappers for BUS lock */ 45 #define USB_BUS_LOCK(_b) USB_MTX_LOCK(&(_b)->bus_mtx) 46 #define USB_BUS_UNLOCK(_b) USB_MTX_UNLOCK(&(_b)->bus_mtx) 47 #define USB_BUS_LOCK_ASSERT(_b, _t) USB_MTX_ASSERT(&(_b)->bus_mtx, _t) 48 49 /* locking wrappers for BUS spin lock */ 50 #define USB_BUS_SPIN_LOCK(_b) USB_MTX_LOCK_SPIN(&(_b)->bus_spin_lock) 51 #define USB_BUS_SPIN_UNLOCK(_b) USB_MTX_UNLOCK_SPIN(&(_b)->bus_spin_lock) 52 #define USB_BUS_SPIN_LOCK_ASSERT(_b, _t) USB_MTX_ASSERT(&(_b)->bus_spin_lock, _t) 53 54 /* locking wrappers for XFER lock */ 55 #define USB_XFER_LOCK(_x) USB_MTX_LOCK((_x)->xroot->xfer_mtx) 56 #define USB_XFER_UNLOCK(_x) USB_MTX_UNLOCK((_x)->xroot->xfer_mtx) 57 #define USB_XFER_LOCK_ASSERT(_x, _t) USB_MTX_ASSERT((_x)->xroot->xfer_mtx, _t) 58 59 /* helper for converting pointers to integers */ 60 #define USB_P2U(ptr) \ 61 ((uintptr_t)(ptr)) 62 63 /* helper for computing offsets */ 64 #define USB_ADD_BYTES(ptr,size) \ 65 ((void *)(__DECONST(char *, (ptr)) + (size))) 66 67 /* debug macro */ 68 #define USB_ASSERT KASSERT 69 70 /* structure prototypes */ 71 72 struct file; 73 struct usb_bus; 74 struct usb_device; 75 struct usb_device_request; 76 struct usb_page; 77 struct usb_page_cache; 78 struct usb_xfer; 79 struct usb_xfer_root; 80 struct usb_string_lang; 81 82 /* typedefs */ 83 84 /* structures */ 85 86 /* 87 * The following structure defines a set of internal USB transfer 88 * flags. 89 */ 90 struct usb_xfer_flags_int { 91 enum usb_hc_mode usb_mode; /* shadow copy of "udev->usb_mode" */ 92 uint16_t control_rem; /* remainder in bytes */ 93 94 uint8_t open:1; /* set if USB pipe has been opened */ 95 uint8_t transferring:1; /* set if an USB transfer is in 96 * progress */ 97 uint8_t did_dma_delay:1; /* set if we waited for HW DMA */ 98 uint8_t did_close:1; /* set if we closed the USB transfer */ 99 uint8_t draining:1; /* set if we are draining an USB 100 * transfer */ 101 uint8_t started:1; /* keeps track of started or stopped */ 102 uint8_t bandwidth_reclaimed:1; 103 uint8_t control_xfr:1; /* set if control transfer */ 104 uint8_t control_hdr:1; /* set if control header should be 105 * sent */ 106 uint8_t control_act:1; /* set if control transfer is active */ 107 uint8_t control_stall:1; /* set if control transfer should be stalled */ 108 uint8_t control_did_data:1; /* set if control DATA has been transferred */ 109 110 uint8_t short_frames_ok:1; /* filtered version */ 111 uint8_t short_xfer_ok:1; /* filtered version */ 112 #if USB_HAVE_BUSDMA 113 uint8_t bdma_enable:1; /* filtered version (only set if 114 * hardware supports DMA) */ 115 uint8_t bdma_no_post_sync:1; /* set if the USB callback wrapper 116 * should not do the BUS-DMA post sync 117 * operation */ 118 uint8_t bdma_setup:1; /* set if BUS-DMA has been setup */ 119 #endif 120 uint8_t isochronous_xfr:1; /* set if isochronous transfer */ 121 uint8_t curr_dma_set:1; /* used by USB HC/DC driver */ 122 uint8_t can_cancel_immed:1; /* set if USB transfer can be 123 * cancelled immediately */ 124 uint8_t doing_callback:1; /* set if executing the callback */ 125 uint8_t maxp_was_clamped:1; /* set if the max packet size 126 * was outside its allowed range */ 127 }; 128 129 /* 130 * The following structure defines an USB transfer. 131 */ 132 struct usb_xfer { 133 struct usb_callout timeout_handle; 134 TAILQ_ENTRY(usb_xfer) wait_entry; /* used at various places */ 135 136 struct usb_page_cache *buf_fixup; /* fixup buffer(s) */ 137 struct usb_xfer_queue *wait_queue; /* pointer to queue that we 138 * are waiting on */ 139 struct usb_page *dma_page_ptr; 140 struct usb_endpoint *endpoint; /* our USB endpoint */ 141 struct usb_xfer_root *xroot; /* used by HC driver */ 142 void *qh_start[2]; /* used by HC driver */ 143 void *td_start[2]; /* used by HC driver */ 144 void *td_transfer_first; /* used by HC driver */ 145 void *td_transfer_last; /* used by HC driver */ 146 void *td_transfer_cache; /* used by HC driver */ 147 void *priv_sc; /* device driver data pointer 1 */ 148 void *priv_fifo; /* device driver data pointer 2 */ 149 void *local_buffer; 150 usb_frlength_t *frlengths; 151 struct usb_page_cache *frbuffers; 152 usb_callback_t *callback; 153 154 usb_frlength_t max_hc_frame_size; 155 usb_frlength_t max_data_length; 156 usb_frlength_t sumlen; /* sum of all lengths in bytes */ 157 usb_frlength_t actlen; /* actual length in bytes */ 158 usb_timeout_t timeout; /* milliseconds */ 159 160 usb_frcount_t max_frame_count; /* initial value of "nframes" after 161 * setup */ 162 usb_frcount_t nframes; /* number of USB frames to transfer */ 163 usb_frcount_t aframes; /* actual number of USB frames 164 * transferred */ 165 usb_stream_t stream_id; /* USB3.0 specific field */ 166 167 uint16_t max_packet_size; 168 uint16_t max_frame_size; 169 uint16_t qh_pos; 170 uint16_t isoc_time_complete; /* in ms */ 171 usb_timeout_t interval; /* milliseconds */ 172 173 uint8_t address; /* physical USB address */ 174 uint8_t endpointno; /* physical USB endpoint */ 175 uint8_t max_packet_count; 176 uint8_t usb_state; 177 uint8_t fps_shift; /* down shift of FPS, 0..3 */ 178 179 usb_error_t error; 180 181 struct usb_xfer_flags flags; 182 struct usb_xfer_flags_int flags_int; 183 }; 184 185 /* external variables */ 186 187 extern struct mtx usb_ref_lock; 188 extern const struct usb_string_lang usb_string_lang_en; 189 190 /* typedefs */ 191 192 typedef struct malloc_type *usb_malloc_type; 193 194 /* prototypes */ 195 196 #endif /* _USB_CORE_H_ */ 197