1 /*- 2 * SPDX-License-Identifier: BSD-2-Clause 3 * 4 * Copyright (c) 2008 Hans Petter Selasky. All rights reserved. 5 * 6 * Redistribution and use in source and binary forms, with or without 7 * modification, are permitted provided that the following conditions 8 * are met: 9 * 1. Redistributions of source code must retain the above copyright 10 * notice, this list of conditions and the following disclaimer. 11 * 2. Redistributions in binary form must reproduce the above copyright 12 * notice, this list of conditions and the following disclaimer in the 13 * documentation and/or other materials provided with the distribution. 14 * 15 * THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 16 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 17 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 18 * ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 19 * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 20 * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 21 * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 22 * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 23 * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 24 * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 25 * SUCH DAMAGE. 26 */ 27 28 /* 29 * This file describes internal structures. 30 */ 31 32 #ifndef _LIBUSB20_INT_H_ 33 #define _LIBUSB20_INT_H_ 34 35 struct libusb20_device; 36 struct libusb20_backend; 37 struct libusb20_transfer; 38 struct libusb20_quirk; 39 40 union libusb20_session_data { 41 unsigned long session_data; 42 struct timespec tv; 43 uint32_t plugtime; 44 }; 45 46 /* 47 * The backend context holds the file descriptors needed to reach the 48 * USB devices. It is immutable after allocation, so it can be shared 49 * between threads, backends and devices without any locking. Sharing 50 * it between backend allocations keeps enumeration working after the 51 * process has entered capability mode, see capsicum(4). 52 * 53 * The context must stay alive for as long as any backend or device 54 * allocated from it is in use. 55 */ 56 struct libusb20_be_ctx { 57 int ctrl_fd; /* /dev/usbctl */ 58 int usb_dfd; /* /dev/usb directory */ 59 }; 60 61 /* USB backend specific */ 62 typedef const char *(libusb20_get_backend_name_t)(void); 63 typedef int (libusb20_root_get_dev_quirk_t)(struct libusb20_backend *pbe, uint16_t index, struct libusb20_quirk *pq); 64 typedef int (libusb20_root_get_quirk_name_t)(struct libusb20_backend *pbe, uint16_t index, struct libusb20_quirk *pq); 65 typedef int (libusb20_root_add_dev_quirk_t)(struct libusb20_backend *pbe, struct libusb20_quirk *pq); 66 typedef int (libusb20_root_remove_dev_quirk_t)(struct libusb20_backend *pbe, struct libusb20_quirk *pq); 67 typedef int (libusb20_close_device_t)(struct libusb20_device *pdev); 68 typedef int (libusb20_dev_get_info_t)(struct libusb20_device *pdev, struct usb_device_info *pinfo); 69 typedef int (libusb20_dev_get_iface_desc_t)(struct libusb20_device *pdev, uint8_t iface_index, char *buf, uint8_t len); 70 typedef int (libusb20_init_backend_t)(struct libusb20_backend *pbe); 71 typedef int (libusb20_open_device_t)(struct libusb20_device *pdev, uint16_t transfer_count_max); 72 typedef void (libusb20_exit_backend_t)(struct libusb20_backend *pbe); 73 typedef int (libusb20_root_set_template_t)(struct libusb20_backend *pbe, int temp); 74 typedef int (libusb20_root_get_template_t)(struct libusb20_backend *pbe, int *ptemp); 75 76 #define LIBUSB20_DEFINE(n,field) \ 77 libusb20_##field##_t *field; 78 79 #define LIBUSB20_DECLARE(n,field) \ 80 /* .field = */ n##_##field, 81 82 #define LIBUSB20_BACKEND(m,n) \ 83 /* description of this backend */ \ 84 m(n, get_backend_name) \ 85 /* optional backend methods */ \ 86 m(n, init_backend) \ 87 m(n, exit_backend) \ 88 m(n, dev_get_info) \ 89 m(n, dev_get_iface_desc) \ 90 m(n, root_get_dev_quirk) \ 91 m(n, root_get_quirk_name) \ 92 m(n, root_add_dev_quirk) \ 93 m(n, root_remove_dev_quirk) \ 94 m(n, root_set_template) \ 95 m(n, root_get_template) \ 96 /* mandatory device methods */ \ 97 m(n, open_device) \ 98 m(n, close_device) \ 99 100 struct libusb20_backend_methods { 101 LIBUSB20_BACKEND(LIBUSB20_DEFINE,) 102 }; 103 104 /* USB dummy methods */ 105 typedef int (libusb20_dummy_int_t)(void); 106 typedef void (libusb20_dummy_void_t)(void); 107 108 /* USB device specific */ 109 typedef int (libusb20_detach_kernel_driver_t)(struct libusb20_device *pdev, uint8_t iface_index); 110 typedef int (libusb20_attach_kernel_driver_t)(struct libusb20_device *pdev, uint8_t iface_index); 111 typedef int (libusb20_do_request_sync_t)(struct libusb20_device *pdev, struct LIBUSB20_CONTROL_SETUP_DECODED *setup, void *data, uint16_t *pactlen, uint32_t timeout, uint8_t flags); 112 typedef int (libusb20_get_config_desc_full_t)(struct libusb20_device *pdev, uint8_t **ppbuf, uint16_t *plen, uint8_t index); 113 typedef int (libusb20_get_config_index_t)(struct libusb20_device *pdev, uint8_t *pindex); 114 typedef int (libusb20_kernel_driver_active_t)(struct libusb20_device *pdev, uint8_t iface_index); 115 typedef int (libusb20_process_t)(struct libusb20_device *pdev); 116 typedef int (libusb20_reset_device_t)(struct libusb20_device *pdev); 117 typedef int (libusb20_set_power_mode_t)(struct libusb20_device *pdev, uint8_t power_mode); 118 typedef int (libusb20_get_power_mode_t)(struct libusb20_device *pdev, uint8_t *power_mode); 119 typedef int (libusb20_get_power_usage_t)(struct libusb20_device *pdev, uint16_t *power_usage); 120 typedef int (libusb20_get_stats_t)(struct libusb20_device *pdev, struct libusb20_device_stats *pstats); 121 typedef int (libusb20_set_alt_index_t)(struct libusb20_device *pdev, uint8_t iface_index, uint8_t alt_index); 122 typedef int (libusb20_set_config_index_t)(struct libusb20_device *pdev, uint8_t index); 123 typedef int (libusb20_check_connected_t)(struct libusb20_device *pdev); 124 125 126 /* USB transfer specific */ 127 typedef int (libusb20_tr_open_t)(struct libusb20_transfer *xfer, uint32_t MaxBufSize, uint32_t MaxFrameCount, uint8_t ep_no, uint16_t stream_id, uint8_t pre_scale); 128 typedef int (libusb20_tr_close_t)(struct libusb20_transfer *xfer); 129 typedef int (libusb20_tr_clear_stall_sync_t)(struct libusb20_transfer *xfer); 130 typedef void (libusb20_tr_submit_t)(struct libusb20_transfer *xfer); 131 typedef void (libusb20_tr_cancel_async_t)(struct libusb20_transfer *xfer); 132 133 #define LIBUSB20_DEVICE(m,n) \ 134 m(n, detach_kernel_driver) \ 135 m(n, attach_kernel_driver) \ 136 m(n, do_request_sync) \ 137 m(n, get_config_desc_full) \ 138 m(n, get_config_index) \ 139 m(n, kernel_driver_active) \ 140 m(n, process) \ 141 m(n, reset_device) \ 142 m(n, check_connected) \ 143 m(n, set_power_mode) \ 144 m(n, get_power_mode) \ 145 m(n, get_power_usage) \ 146 m(n, get_stats) \ 147 m(n, set_alt_index) \ 148 m(n, set_config_index) \ 149 m(n, tr_cancel_async) \ 150 m(n, tr_clear_stall_sync) \ 151 m(n, tr_close) \ 152 m(n, tr_open) \ 153 m(n, tr_submit) \ 154 155 struct libusb20_device_methods { 156 LIBUSB20_DEVICE(LIBUSB20_DEFINE,) 157 }; 158 159 struct libusb20_backend { 160 TAILQ_HEAD(, libusb20_device) usb_devs; 161 const struct libusb20_backend_methods *methods; 162 163 /* borrowed backend context, owned when "be_ctx_owner" is set */ 164 struct libusb20_be_ctx *be_ctx; 165 uint8_t be_ctx_owner; 166 }; 167 168 struct libusb20_transfer { 169 struct libusb20_device *pdev; /* the USB device we belong to */ 170 libusb20_tr_callback_t *callback; 171 void *priv_sc0; /* private client data */ 172 void *priv_sc1; /* private client data */ 173 /* 174 * Pointer to a list of buffer pointers: 175 */ 176 void **ppBuffer; 177 /* 178 * Pointer to frame lengths, which are updated to actual length 179 * after the USB transfer completes: 180 */ 181 uint32_t *pLength; 182 uint32_t maxTotalLength; 183 uint32_t maxFrames; /* total number of frames */ 184 uint32_t nFrames; /* total number of frames */ 185 uint32_t aFrames; /* actual number of frames */ 186 uint32_t timeout; 187 /* isochronous completion time in milliseconds */ 188 uint16_t timeComplete; 189 uint16_t trIndex; 190 uint16_t maxPacketLen; 191 uint8_t flags; /* see LIBUSB20_TRANSFER_XXX */ 192 uint8_t status; /* see LIBUSB20_TRANSFER_XXX */ 193 uint8_t is_opened; 194 uint8_t is_pending; 195 uint8_t is_cancel; 196 uint8_t is_draining; 197 uint8_t is_restart; 198 }; 199 200 struct libusb20_device { 201 202 /* device descriptor */ 203 struct LIBUSB20_DEVICE_DESC_DECODED ddesc; 204 205 /* device timestamp */ 206 union libusb20_session_data session_data; 207 208 /* our device entry */ 209 TAILQ_ENTRY(libusb20_device) dev_entry; 210 211 /* device methods */ 212 const struct libusb20_device_methods *methods; 213 214 /* backend methods */ 215 const struct libusb20_backend_methods *beMethods; 216 217 /* borrowed backend context */ 218 struct libusb20_be_ctx *be_ctx; 219 220 /* list of USB transfers */ 221 struct libusb20_transfer *pTransfer; 222 223 /* private backend data */ 224 void *privBeData; 225 226 /* libUSB v0.1 and v1.0 compat data */ 227 void *privLuData; 228 229 /* claimed interface */ 230 uint8_t claimed_interface; 231 232 /* auto detach kernel driver */ 233 uint8_t auto_detach; 234 235 /* device file handle */ 236 int file; 237 238 /* device file handle (control transfers only) */ 239 int file_ctrl; 240 241 /* debugging level */ 242 int debug; 243 244 /* number of USB transfers */ 245 uint16_t nTransfer; 246 247 uint8_t bus_number; 248 uint8_t device_address; 249 uint8_t usb_mode; 250 uint8_t usb_speed; 251 uint8_t is_opened; 252 uint8_t parent_address; 253 uint8_t parent_port; 254 uint8_t port_level; 255 256 char usb_desc[96]; 257 #define LIBUSB20_DEVICE_PORT_PATH_MAX 32 258 uint8_t port_path[LIBUSB20_DEVICE_PORT_PATH_MAX]; 259 }; 260 261 extern const struct libusb20_backend_methods libusb20_ugen20_backend; 262 extern const struct libusb20_backend_methods libusb20_linux_backend; 263 264 #endif /* _LIBUSB20_INT_H_ */ 265