2 * Windows backend common header for libusb 1.0
4 * This file brings together header code common between
5 * the desktop Windows backends.
6 * Copyright © 2012-2013 RealVNC Ltd.
7 * Copyright © 2009-2012 Pete Batard <pete@akeo.ie>
8 * Copyright © 2014-2020 Chris Dickens <christopher.a.dickens@gmail.com>
9 * With contributions from Michael Plante, Orin Eman et al.
10 * Parts of this code adapted from libusb-win32-v1 by Stephan Meyer
11 * Major code testing contribution by Xiaofan Chen
13 * This library is free software; you can redistribute it and/or
14 * modify it under the terms of the GNU Lesser General Public
15 * License as published by the Free Software Foundation; either
16 * version 2.1 of the License, or (at your option) any later version.
18 * This library is distributed in the hope that it will be useful,
19 * but WITHOUT ANY WARRANTY; without even the implied warranty of
20 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
21 * Lesser General Public License for more details.
23 * You should have received a copy of the GNU Lesser General Public
24 * License along with this library; if not, write to the Free Software
25 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
28 #ifndef LIBUSB_WINDOWS_COMMON_H
29 #define LIBUSB_WINDOWS_COMMON_H
34 * Workaround for the mess that exists with the DWORD and ULONG types.
35 * Visual Studio unconditionally defines these types as 'unsigned long'
36 * and a long is always 32-bits, even on 64-bit builds. GCC on the other
37 * hand varies the width of a long, matching it to the build. To make
38 * matters worse, the platform headers for these GCC builds define a
39 * DWORD/ULONG to be 'unsigned long' on 32-bit builds and 'unsigned int'
40 * on 64-bit builds. This creates a great deal of warnings for compilers
41 * that support printf format checking since it will never actually be
45 #define ULONG_CAST(x) (x)
47 #define ULONG_CAST(x) ((unsigned long)(x))
50 #if defined(__CYGWIN__)
51 #define _stricmp strcasecmp
52 #define _strdup strdup
53 // _beginthreadex is MSVCRT => unavailable for cygwin. Fallback to using CreateThread
54 #define _beginthreadex(a, b, c, d, e, f) CreateThread(a, b, (LPTHREAD_START_ROUTINE)c, d, e, (LPDWORD)f)
59 #define safe_free(p) do {if (p != NULL) {free((void *)p); p = NULL;}} while (0)
62 * API macros - leveraged from libusb-win32 1.x
64 #define DLL_STRINGIFY(s) #s
67 * Macros for handling DLL themselves
69 #define DLL_HANDLE_NAME(name) __dll_##name##_handle
71 #define DLL_DECLARE_HANDLE(name) \
72 static HMODULE DLL_HANDLE_NAME(name)
74 #define DLL_GET_HANDLE(ctx, name) \
76 DLL_HANDLE_NAME(name) = load_system_library(ctx, \
77 DLL_STRINGIFY(name)); \
78 if (!DLL_HANDLE_NAME(name)) \
82 #define DLL_FREE_HANDLE(name) \
84 if (DLL_HANDLE_NAME(name)) { \
85 FreeLibrary(DLL_HANDLE_NAME(name)); \
86 DLL_HANDLE_NAME(name) = NULL; \
91 * Macros for handling functions within a DLL
93 #define DLL_FUNC_NAME(name) __dll_##name##_func_t
95 #define DLL_DECLARE_FUNC_PREFIXNAME(api, ret, prefixname, name, args) \
96 typedef ret (api * DLL_FUNC_NAME(name))args; \
97 static DLL_FUNC_NAME(name) prefixname
99 #define DLL_DECLARE_FUNC(api, ret, name, args) \
100 DLL_DECLARE_FUNC_PREFIXNAME(api, ret, name, name, args)
101 #define DLL_DECLARE_FUNC_PREFIXED(api, ret, prefix, name, args) \
102 DLL_DECLARE_FUNC_PREFIXNAME(api, ret, prefix##name, name, args)
104 #define DLL_LOAD_FUNC_PREFIXNAME(dll, prefixname, name, ret_on_failure) \
106 HMODULE h = DLL_HANDLE_NAME(dll); \
107 prefixname = (DLL_FUNC_NAME(name))GetProcAddress(h, \
108 DLL_STRINGIFY(name)); \
111 prefixname = (DLL_FUNC_NAME(name))GetProcAddress(h, \
112 DLL_STRINGIFY(name) DLL_STRINGIFY(A)); \
115 prefixname = (DLL_FUNC_NAME(name))GetProcAddress(h, \
116 DLL_STRINGIFY(name) DLL_STRINGIFY(W)); \
119 if (ret_on_failure) \
123 #define DLL_LOAD_FUNC(dll, name, ret_on_failure) \
124 DLL_LOAD_FUNC_PREFIXNAME(dll, name, name, ret_on_failure)
125 #define DLL_LOAD_FUNC_PREFIXED(dll, prefix, name, ret_on_failure) \
126 DLL_LOAD_FUNC_PREFIXNAME(dll, prefix##name, name, ret_on_failure)
128 // https://msdn.microsoft.com/en-us/library/windows/hardware/ff539136(v=vs.85).aspx
129 #if !defined(USBD_SUCCESS)
130 typedef LONG USBD_STATUS;
132 #define USBD_SUCCESS(Status) ((USBD_STATUS)(Status) >= 0)
134 #define USBD_STATUS_ENDPOINT_HALTED ((USBD_STATUS)0xC0000030L)
135 #define USBD_STATUS_TIMEOUT ((USBD_STATUS)0xC0006000L)
136 #define USBD_STATUS_DEVICE_GONE ((USBD_STATUS)0xC0007000L)
137 #define USBD_STATUS_CANCELED ((USBD_STATUS)0xC0010000L)
140 // error code added with Windows SDK 10.0.18362
141 #ifndef ERROR_NO_SUCH_DEVICE
142 #define ERROR_NO_SUCH_DEVICE 433L
145 /* Windows versions */
146 enum windows_version {
150 WINDOWS_2003, // Also XP x64
159 extern enum windows_version windows_version;
161 #include <pshpack1.h>
163 typedef struct USB_DEVICE_DESCRIPTOR {
165 UCHAR bDescriptorType;
168 UCHAR bDeviceSubClass;
169 UCHAR bDeviceProtocol;
170 UCHAR bMaxPacketSize0;
177 UCHAR bNumConfigurations;
178 } USB_DEVICE_DESCRIPTOR, *PUSB_DEVICE_DESCRIPTOR;
180 typedef struct USB_CONFIGURATION_DESCRIPTOR {
182 UCHAR bDescriptorType;
184 UCHAR bNumInterfaces;
185 UCHAR bConfigurationValue;
186 UCHAR iConfiguration;
189 } USB_CONFIGURATION_DESCRIPTOR, *PUSB_CONFIGURATION_DESCRIPTOR;
193 #define MAX_DEVICE_ID_LEN 200
195 typedef struct USB_DK_DEVICE_ID {
196 WCHAR DeviceID[MAX_DEVICE_ID_LEN];
197 WCHAR InstanceID[MAX_DEVICE_ID_LEN];
198 } USB_DK_DEVICE_ID, *PUSB_DK_DEVICE_ID;
200 typedef struct USB_DK_DEVICE_INFO {
205 USB_DEVICE_DESCRIPTOR DeviceDescriptor;
206 } USB_DK_DEVICE_INFO, *PUSB_DK_DEVICE_INFO;
208 typedef struct USB_DK_ISO_TRANSFER_RESULT {
209 ULONG64 ActualLength;
210 ULONG64 TransferResult;
211 } USB_DK_ISO_TRANSFER_RESULT, *PUSB_DK_ISO_TRANSFER_RESULT;
213 typedef struct USB_DK_GEN_TRANSFER_RESULT {
214 ULONG64 BytesTransferred;
215 ULONG64 UsbdStatus; // USBD_STATUS code
216 } USB_DK_GEN_TRANSFER_RESULT, *PUSB_DK_GEN_TRANSFER_RESULT;
218 typedef struct USB_DK_TRANSFER_RESULT {
219 USB_DK_GEN_TRANSFER_RESULT GenResult;
220 PVOID64 IsochronousResultsArray; // array of USB_DK_ISO_TRANSFER_RESULT
221 } USB_DK_TRANSFER_RESULT, *PUSB_DK_TRANSFER_RESULT;
223 typedef struct USB_DK_TRANSFER_REQUEST {
224 ULONG64 EndpointAddress;
226 ULONG64 BufferLength;
227 ULONG64 TransferType;
228 ULONG64 IsochronousPacketsArraySize;
229 PVOID64 IsochronousPacketsArray;
230 USB_DK_TRANSFER_RESULT Result;
231 } USB_DK_TRANSFER_REQUEST, *PUSB_DK_TRANSFER_REQUEST;
233 struct usbdk_device_priv {
235 PUSB_CONFIGURATION_DESCRIPTOR *config_descriptors;
236 HANDLE redirector_handle;
237 HANDLE system_handle;
238 uint8_t active_configuration;
241 struct winusb_device_priv {
244 uint8_t active_config;
245 uint8_t depth; // distance to HCD
246 const struct windows_usb_api_backend *apib;
248 char *path; // device interface path
249 int sub_api; // for WinUSB-like APIs
251 char *path; // each interface needs a device interface path,
252 const struct windows_usb_api_backend *apib; // an API backend (multiple drivers support),
254 int8_t nb_endpoints; // and a set of endpoint addresses (USB_MAXENDPOINTS)
256 int current_altsetting;
257 bool restricted_functionality; // indicates if the interface functionality is restricted
258 // by Windows (eg. HID keyboards or mice cannot do R/W)
259 } usb_interface[USB_MAXINTERFACES];
260 struct hid_device_priv *hid;
261 PUSB_CONFIGURATION_DESCRIPTOR *config_descriptor; // list of pointers to the cached config descriptors
264 struct usbdk_device_handle_priv {
265 // Not currently used
269 struct winusb_device_handle_priv {
270 int active_interface;
272 HANDLE dev_handle; // WinUSB needs an extra handle for the file
273 HANDLE api_handle; // used by the API to communicate with the device
274 } interface_handle[USB_MAXINTERFACES];
275 int autoclaim_count[USB_MAXINTERFACES]; // For auto-release
278 struct usbdk_transfer_priv {
279 USB_DK_TRANSFER_REQUEST request;
280 PULONG64 IsochronousPacketsArray;
281 PUSB_DK_ISO_TRANSFER_RESULT IsochronousResultsArray;
284 struct winusb_transfer_priv {
285 uint8_t interface_number;
287 uint8_t *hid_buffer; // 1 byte extended data buffer, required for HID
288 uint8_t *hid_dest; // transfer buffer destination, required for HID
289 size_t hid_expected_size;
291 // For isochronous transfers with LibUSBk driver:
294 // For isochronous transfers with Microsoft WinUSB driver:
295 void *isoch_buffer_handle; // The isoch_buffer_handle to free at the end of the transfer
296 BOOL iso_break_stream; // Whether the isoch. stream was to be continued in the last call of libusb_submit_transfer.
297 // As we this structure is zeroed out upon initialization, we need to use inverse logic here.
298 libusb_transfer_cb_fn iso_user_callback; // Original transfer callback of the user. Might be used for isochronous transfers.
301 struct windows_backend {
302 int (*init)(struct libusb_context *ctx);
303 void (*exit)(struct libusb_context *ctx);
304 int (*get_device_list)(struct libusb_context *ctx,
305 struct discovered_devs **discdevs);
306 int (*open)(struct libusb_device_handle *dev_handle);
307 void (*close)(struct libusb_device_handle *dev_handle);
308 int (*get_active_config_descriptor)(struct libusb_device *device,
309 void *buffer, size_t len);
310 int (*get_config_descriptor)(struct libusb_device *device,
311 uint8_t config_index, void *buffer, size_t len);
312 int (*get_config_descriptor_by_value)(struct libusb_device *device,
313 uint8_t bConfigurationValue, void **buffer);
314 int (*get_configuration)(struct libusb_device_handle *dev_handle, uint8_t *config);
315 int (*set_configuration)(struct libusb_device_handle *dev_handle, uint8_t config);
316 int (*claim_interface)(struct libusb_device_handle *dev_handle, uint8_t interface_number);
317 int (*release_interface)(struct libusb_device_handle *dev_handle, uint8_t interface_number);
318 int (*set_interface_altsetting)(struct libusb_device_handle *dev_handle,
319 uint8_t interface_number, uint8_t altsetting);
320 int (*clear_halt)(struct libusb_device_handle *dev_handle,
321 unsigned char endpoint);
322 int (*reset_device)(struct libusb_device_handle *dev_handle);
323 void (*destroy_device)(struct libusb_device *dev);
324 int (*submit_transfer)(struct usbi_transfer *itransfer);
325 int (*cancel_transfer)(struct usbi_transfer *itransfer);
326 void (*clear_transfer_priv)(struct usbi_transfer *itransfer);
327 enum libusb_transfer_status (*copy_transfer_data)(struct usbi_transfer *itransfer, DWORD length);
330 struct windows_context_priv {
331 const struct windows_backend *backend;
332 HANDLE completion_port;
333 HANDLE completion_port_thread;
336 union windows_device_priv {
337 struct usbdk_device_priv usbdk_priv;
338 struct winusb_device_priv winusb_priv;
341 union windows_device_handle_priv {
342 struct usbdk_device_handle_priv usbdk_priv;
343 struct winusb_device_handle_priv winusb_priv;
346 struct windows_transfer_priv {
347 OVERLAPPED overlapped;
350 struct usbdk_transfer_priv usbdk_priv;
351 struct winusb_transfer_priv winusb_priv;
355 static inline OVERLAPPED *get_transfer_priv_overlapped(struct usbi_transfer *itransfer)
357 struct windows_transfer_priv *transfer_priv = usbi_get_transfer_priv(itransfer);
358 return &transfer_priv->overlapped;
361 static inline void set_transfer_priv_handle(struct usbi_transfer *itransfer, HANDLE handle)
363 struct windows_transfer_priv *transfer_priv = usbi_get_transfer_priv(itransfer);
364 transfer_priv->handle = handle;
367 static inline struct usbdk_transfer_priv *get_usbdk_transfer_priv(struct usbi_transfer *itransfer)
369 struct windows_transfer_priv *transfer_priv = usbi_get_transfer_priv(itransfer);
370 return &transfer_priv->usbdk_priv;
373 static inline struct winusb_transfer_priv *get_winusb_transfer_priv(struct usbi_transfer *itransfer)
375 struct windows_transfer_priv *transfer_priv = usbi_get_transfer_priv(itransfer);
376 return &transfer_priv->winusb_priv;
379 extern const struct windows_backend usbdk_backend;
380 extern const struct windows_backend winusb_backend;
382 HMODULE load_system_library(struct libusb_context *ctx, const char *name);
383 unsigned long htab_hash(const char *str);
384 enum libusb_transfer_status usbd_status_to_libusb_transfer_status(USBD_STATUS status);
385 void windows_force_sync_completion(struct usbi_transfer *itransfer, ULONG size);
387 #if defined(ENABLE_LOGGING)
388 const char *windows_error_str(DWORD error_code);