usb 2.12.1 → 2.13.0

package/libusb/libusb/os/emscripten_webusb.cpp

@@ -0,0 +1,870 @@
+/*
+ * Copyright © 2021 Google LLC
+ * Copyright © 2023 Ingvar Stepanyan <me@rreverser.com>
+ *
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ *
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA
+ *
+ * Authors:
+ *		Ingvar Stepanyan <me@rreverser.com>
+ */
+
+#include <emscripten/version.h>
+
+static_assert((__EMSCRIPTEN_major__ * 100 * 100 + __EMSCRIPTEN_minor__ * 100 +
+			   __EMSCRIPTEN_tiny__) >= 30148,
+			  "Emscripten 3.1.48 or newer is required.");
+
+#include <assert.h>
+#include <emscripten.h>
+#include <emscripten/val.h>
+
+#include <type_traits>
+#include <utility>
+
+#include "libusbi.h"
+
+using namespace emscripten;
+
+#ifdef _REENTRANT
+#include <emscripten/proxying.h>
+#include <emscripten/threading.h>
+#include <pthread.h>
+
+static ProxyingQueue queue;
+#endif
+
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wmissing-prototypes"
+#pragma clang diagnostic ignored "-Wunused-parameter"
+#pragma clang diagnostic ignored "-Wshadow"
+
+namespace {
+
+// clang-format off
+EM_JS(EM_VAL, usbi_em_promise_catch, (EM_VAL handle), {
+	let promise = Emval.toValue(handle);
+	promise = promise.then(
+		value => ({error : 0, value}),
+		error => {
+			console.error(error);
+			let errorCode = -99; // LIBUSB_ERROR_OTHER
+			if (error instanceof DOMException) {
+				const ERROR_CODES = {
+					// LIBUSB_ERROR_IO
+					NetworkError : -1,
+					// LIBUSB_ERROR_INVALID_PARAM
+					DataError : -2,
+					TypeMismatchError : -2,
+					IndexSizeError : -2,
+					// LIBUSB_ERROR_ACCESS
+					SecurityError : -3,
+					// LIBUSB_ERROR_NOT_FOUND
+					NotFoundError : -5,
+					// LIBUSB_ERROR_BUSY
+					InvalidStateError : -6,
+					// LIBUSB_ERROR_TIMEOUT
+					TimeoutError : -7,
+					// LIBUSB_ERROR_INTERRUPTED
+					AbortError : -10,
+					// LIBUSB_ERROR_NOT_SUPPORTED
+					NotSupportedError : -12,
+				};
+				errorCode = ERROR_CODES[error.name] ?? errorCode;
+			} else if (error instanceof RangeError || error instanceof TypeError) {
+				errorCode = -2; // LIBUSB_ERROR_INVALID_PARAM
+			}
+			return {error: errorCode, value: undefined};
+		}
+	);
+	return Emval.toHandle(promise);
+});
+
+EM_JS(void, usbi_em_copy_from_dataview, (void* dst, EM_VAL src), {
+	src = Emval.toValue(src);
+	src = new Uint8Array(src.buffer, src.byteOffset, src.byteLength);
+	HEAPU8.set(src, dst);
+});
+
+// Our implementation proxies operations from multiple threads to the same
+// underlying USBDevice on the main thread. This can lead to issues when
+// multiple threads try to open/close the same device at the same time.
+//
+// First, since open/close operations are asynchronous in WebUSB, we can end up
+// with multiple open/close operations in flight at the same time, which can
+// lead to unpredictable outcome (e.g. device got closed but opening succeeded
+// right before that).
+//
+// Second, since multiple threads are allowed to have their own handles to the
+// same device, we need to keep track of number of open handles and close the
+// device only when the last handle is closed.
+//
+// We fix both of these issues by using a shared promise chain that executes
+// open and close operations sequentially and keeps track of the reference count
+// in each promise's result. This way, we can ensure that only one open/close
+// operation is in flight at any given time. Note that we don't need to worry
+// about all other operations because they're preconditioned on the device being
+// open and having at least 1 reference anyway.
+EM_JS(EM_VAL, usbi_em_device_safe_open_close, (EM_VAL device, bool open), {
+	device = Emval.toValue(device);
+	const symbol = Symbol.for('libusb.open_close_chain');
+	let promiseChain = device[symbol] ?? Promise.resolve(0);
+	device[symbol] = promiseChain = promiseChain.then(async refCount => {
+		if (open) {
+			if (!refCount++) {
+				await device.open();
+			}
+		} else {
+			if (!--refCount) {
+				await device.close();
+			}
+		}
+		return refCount;
+	});
+	return Emval.toHandle(promiseChain);
+});
+// clang-format on
+
+libusb_transfer_status getTransferStatus(const val& transfer_result) {
+	auto status = transfer_result["status"].as<std::string>();
+	if (status == "ok") {
+		return LIBUSB_TRANSFER_COMPLETED;
+	} else if (status == "stall") {
+		return LIBUSB_TRANSFER_STALL;
+	} else if (status == "babble") {
+		return LIBUSB_TRANSFER_OVERFLOW;
+	} else {
+		return LIBUSB_TRANSFER_ERROR;
+	}
+}
+
+// Note: this assumes that `dst` is valid for at least `src.byteLength` bytes.
+// This is true for all results returned from WebUSB as we pass max length to
+// the transfer APIs.
+void copyFromDataView(void* dst, const val& src) {
+	usbi_em_copy_from_dataview(dst, src.as_handle());
+}
+
+auto getUnsharedMemoryView(void* src, size_t len) {
+	auto view = typed_memory_view(len, (uint8_t*)src);
+#ifdef _REENTRANT
+	// Unfortunately, TypedArrays backed by SharedArrayBuffers are not accepted
+	// by most Web APIs, trading off guaranteed thread-safety for performance
+	// loss. The usual workaround is to copy them into a new TypedArray, which
+	// is what we do here via the `.slice()` method.
+	return val(view).call<val>("slice");
+#else
+	// Non-threaded builds can avoid the copy penalty.
+	return view;
+#endif
+}
+
+// A helper that proxies a function call to the main thread if not already
+// there. This is a wrapper around Emscripten's raw proxying API with couple of
+// high-level improvements, namely support for destroying lambda on the target
+// thread as well as custom return types.
+template <typename Func>
+auto runOnMain(Func&& func) {
+#ifdef _REENTRANT
+	if (!emscripten_is_main_runtime_thread()) {
+		if constexpr (std::is_same_v<std::invoke_result_t<Func>, void>) {
+			bool proxied =
+				queue.proxySync(emscripten_main_runtime_thread_id(), [&func] {
+					// Capture func by reference and move into a local variable
+					// to render the captured func inert on the first (and only)
+					// call. This way it can be safely destructed on the main
+					// thread instead of the current one when this call
+					// finishes. TODO: remove this when
+					// https://github.com/emscripten-core/emscripten/issues/20610
+					// is fixed.
+					auto func_ = std::move(func);
+					func_();
+				});
+			assert(proxied);
+			return;
+		} else {
+			// A storage for the result of the function call.
+			// TODO: remove when
+			// https://github.com/emscripten-core/emscripten/issues/20611 is
+			// implemented.
+			std::optional<std::invoke_result_t<Func>> result;
+			runOnMain(
+				[&result, func = std::move(func)] { result.emplace(func()); });
+			return std::move(result.value());
+		}
+	}
+#endif
+	return func();
+}
+
+// C++ struct representation for `{value, error}` object used by `CaughtPromise`
+// below.
+struct PromiseResult {
+	int error;
+	val value;
+
+	PromiseResult() = delete;
+	PromiseResult(PromiseResult&&) = default;
+
+	PromiseResult(val&& result)
+		: error(result["error"].as<int>()), value(result["value"]) {}
+
+	~PromiseResult() {
+		// make sure value is freed on the thread it exists on
+		runOnMain([value = std::move(value)] {});
+	}
+};
+
+struct CaughtPromise : val {
+	CaughtPromise(val&& promise)
+		: val(wrapPromiseWithCatch(std::move(promise))) {}
+
+	using AwaitResult = PromiseResult;
+
+private:
+
+	// Wrap promise with conversion from some value T to `{value: T, error:
+	// number}`.
+	static val wrapPromiseWithCatch(val&& promise) {
+		auto handle = promise.as_handle();
+		handle = usbi_em_promise_catch(handle);
+		return val::take_ownership(handle);
+	}
+};
+
+#define co_await_try(promise)                                   \
+	({                                                          \
+		PromiseResult result = co_await CaughtPromise(promise); \
+		if (result.error) {                                     \
+			co_return result.error;                             \
+		}                                                       \
+		std::move(result.value);                                \
+	})
+
+// A helper that runs an asynchronous callback when the promise is resolved.
+template <typename Promise, typename OnResult>
+val promiseThen(Promise&& promise, OnResult&& onResult) {
+	// Save captures from the callback while we can, or they'll be destructed.
+	// https://devblogs.microsoft.com/oldnewthing/20211103-00/?p=105870
+	auto onResult_ = std::move(onResult);
+	onResult_(co_await promise);
+	co_return val::undefined();
+}
+
+// A helper that runs an asynchronous function on the main thread and blocks the
+// current thread until the promise is resolved (via Asyncify "blocking" if
+// already on the main thread or regular blocking otherwise).
+template <typename Func>
+static std::invoke_result_t<Func>::AwaitResult awaitOnMain(Func&& func) {
+#ifdef _REENTRANT
+	if (!emscripten_is_main_runtime_thread()) {
+		// If we're on a different thread, we can't use main thread's Asyncify
+		// as multiple threads might be fighting for its state; instead, use
+		// proxying to synchronously block the current thread until the promise
+		// is complete.
+		std::optional<typename std::invoke_result_t<Func>::AwaitResult> result;
+		queue.proxySyncWithCtx(
+			emscripten_main_runtime_thread_id(),
+			[&result, &func](ProxyingQueue::ProxyingCtx ctx) {
+				// Same as `func` in `runOnMain`, move to destruct on the first
+				// call.
+				auto func_ = std::move(func);
+				promiseThen(
+					func_(),
+					[&result, ctx = std::move(ctx)](auto&& result_) mutable {
+						result.emplace(std::move(result_));
+						ctx.finish();
+					});
+			});
+		return std::move(result.value());
+	}
+#endif
+	// If we're already on the main thread, use Asyncify to block until the
+	// promise is resolved.
+	return func().await();
+}
+
+// A helper that makes a control transfer given a setup pointer (assumed to be
+// followed by data payload for out-transfers).
+val makeControlTransferPromise(const val& dev, libusb_control_setup* setup) {
+	auto params = val::object();
+
+	const char* request_type = "unknown";
+	// See LIBUSB_REQ_TYPE in windows_winusb.h (or docs for `bmRequestType`).
+	switch (setup->bmRequestType & (0x03 << 5)) {
+		case LIBUSB_REQUEST_TYPE_STANDARD:
+			request_type = "standard";
+			break;
+		case LIBUSB_REQUEST_TYPE_CLASS:
+			request_type = "class";
+			break;
+		case LIBUSB_REQUEST_TYPE_VENDOR:
+			request_type = "vendor";
+			break;
+	}
+	params.set("requestType", request_type);
+
+	const char* recipient = "other";
+	switch (setup->bmRequestType & 0x0f) {
+		case LIBUSB_RECIPIENT_DEVICE:
+			recipient = "device";
+			break;
+		case LIBUSB_RECIPIENT_INTERFACE:
+			recipient = "interface";
+			break;
+		case LIBUSB_RECIPIENT_ENDPOINT:
+			recipient = "endpoint";
+			break;
+	}
+	params.set("recipient", recipient);
+
+	params.set("request", setup->bRequest);
+	params.set("value", setup->wValue);
+	params.set("index", setup->wIndex);
+
+	if (setup->bmRequestType & LIBUSB_ENDPOINT_IN) {
+		return dev.call<val>("controlTransferIn", params, setup->wLength);
+	} else {
+		return dev.call<val>("controlTransferOut", params,
+							 getUnsharedMemoryView(setup + 1, setup->wLength));
+	}
+}
+
+// Smart pointer for managing pointers to places allocated by libusb inside its
+// backend structures.
+template <typename T>
+struct ValPtr {
+	template <typename... Args>
+	void emplace(Args&&... args) {
+		new (ptr) T(std::forward<Args>(args)...);
+	}
+
+	const T& operator*() const { return *ptr; }
+	T& operator*() { return *ptr; }
+
+	const T* operator->() const { return ptr; }
+	T* operator->() { return ptr; }
+
+	void free() { ptr->~T(); }
+
+	T take() {
+		auto value = std::move(*ptr);
+		free();
+		return value;
+	}
+
+protected:
+
+	ValPtr(void* ptr) : ptr(static_cast<T*>(ptr)) {}
+
+private:
+
+	// Note: this is not a heap-allocated pointer, but a pointer to a part
+	// of the backend structure allocated by libusb itself.
+	T* ptr;
+};
+
+struct CachedDevice;
+
+struct WebUsbDevicePtr : ValPtr<CachedDevice> {
+public:
+
+	WebUsbDevicePtr(libusb_device* dev) : ValPtr(usbi_get_device_priv(dev)) {}
+	WebUsbDevicePtr(libusb_device_handle* handle)
+		: WebUsbDevicePtr(handle->dev) {}
+};
+
+struct WebUsbTransferPtr : ValPtr<PromiseResult> {
+public:
+
+	WebUsbTransferPtr(usbi_transfer* itransfer)
+		: ValPtr(usbi_get_transfer_priv(itransfer)) {}
+};
+
+enum class OpenClose : bool {
+	Open = true,
+	Close = false,
+};
+
+struct CachedDevice {
+	CachedDevice() = delete;
+	CachedDevice(CachedDevice&&) = delete;
+
+	// Fill in the device descriptor and configurations by reading them from the
+	// WebUSB device.
+	static val initFromDevice(val&& web_usb_dev, libusb_device* libusb_dev) {
+		auto cachedDevicePtr = WebUsbDevicePtr(libusb_dev);
+		cachedDevicePtr.emplace(std::move(web_usb_dev));
+		bool must_close = false;
+		val result = co_await cachedDevicePtr->initFromDeviceWithoutClosing(
+			libusb_dev, must_close);
+		if (must_close) {
+			co_await_try(cachedDevicePtr->safeOpenCloseAssumingMainThread(
+				OpenClose::Close));
+		}
+		co_return std::move(result);
+	}
+
+	const val& getDeviceAssumingMainThread() const { return device; }
+
+	uint8_t getActiveConfigValue() const {
+		return runOnMain([&] {
+			auto web_usb_config = device["configuration"];
+			return web_usb_config.isNull()
+				? 0
+				: web_usb_config["configurationValue"].as<uint8_t>();
+		});
+	}
+
+	usbi_configuration_descriptor* getConfigDescriptor(uint8_t config_id) {
+		return config_id < configurations.size()
+			? configurations[config_id].get()
+			: nullptr;
+	}
+
+	usbi_configuration_descriptor* findConfigDescriptorByValue(
+		uint8_t config_id) const {
+		for (auto& config : configurations) {
+			if (config->bConfigurationValue == config_id) {
+				return config.get();
+			}
+		}
+		return nullptr;
+	}
+
+	int copyConfigDescriptor(const usbi_configuration_descriptor* config,
+							 void* buf,
+							 size_t buf_len) {
+		auto len = std::min(buf_len, (size_t)config->wTotalLength);
+		memcpy(buf, config, len);
+		return len;
+	}
+
+	template <typename... Args>
+	int awaitOnMain(const char* methodName, Args&&... args) const {
+		return ::awaitOnMain([&] {
+				   return CaughtPromise(device.call<val>(
+					   methodName, std::forward<Args>(args)...));
+			   })
+			.error;
+	}
+
+	~CachedDevice() {
+		runOnMain([device = std::move(device)] {});
+	}
+
+	CaughtPromise safeOpenCloseAssumingMainThread(OpenClose open) {
+		return val::take_ownership(usbi_em_device_safe_open_close(
+			device.as_handle(), static_cast<bool>(open)));
+	}
+
+	int safeOpenCloseOnMain(OpenClose open) {
+		return ::awaitOnMain([this, open] {
+				   return safeOpenCloseAssumingMainThread(open);
+			   })
+			.error;
+	}
+
+private:
+
+	val device;
+	std::vector<std::unique_ptr<usbi_configuration_descriptor>> configurations;
+
+	CaughtPromise requestDescriptor(libusb_descriptor_type desc_type,
+									uint8_t desc_index,
+									uint16_t max_length) const {
+		libusb_control_setup setup = {
+			.bmRequestType = LIBUSB_ENDPOINT_IN,
+			.bRequest = LIBUSB_REQUEST_GET_DESCRIPTOR,
+			.wValue = (uint16_t)((desc_type << 8) | desc_index),
+			.wIndex = 0,
+			.wLength = max_length,
+		};
+		return makeControlTransferPromise(device, &setup);
+	}
+
+	// Implementation of the `CachedDevice::initFromDevice` above. This is a
+	// separate function just because we need to close the device on exit if
+	// we opened it successfully, and we can't use an async operation (`close`)
+	// in RAII destructor.
+	val initFromDeviceWithoutClosing(libusb_device* dev, bool& must_close) {
+		co_await_try(safeOpenCloseAssumingMainThread(OpenClose::Open));
+
+		// Can't use RAII to close on exit as co_await is not permitted in
+		// destructors (yet:
+		// https://github.com/cplusplus/papers/issues/445), so use a good
+		// old boolean + a wrapper instead.
+		must_close = true;
+
+		{
+			auto result = co_await_try(
+				requestDescriptor(LIBUSB_DT_DEVICE, 0, LIBUSB_DT_DEVICE_SIZE));
+			if (auto error = getTransferStatus(result)) {
+				co_return error;
+			}
+			copyFromDataView(&dev->device_descriptor, result["data"]);
+		}
+
+		// Infer the device speed (which is not yet provided by WebUSB) from
+		// the descriptor.
+		if (dev->device_descriptor.bMaxPacketSize0 ==
+			/* actually means 2^9, only valid for superspeeds */ 9) {
+			dev->speed = dev->device_descriptor.bcdUSB >= 0x0310
+				? LIBUSB_SPEED_SUPER_PLUS
+				: LIBUSB_SPEED_SUPER;
+		} else if (dev->device_descriptor.bcdUSB >= 0x0200) {
+			dev->speed = LIBUSB_SPEED_HIGH;
+		} else if (dev->device_descriptor.bMaxPacketSize0 > 8) {
+			dev->speed = LIBUSB_SPEED_FULL;
+		} else {
+			dev->speed = LIBUSB_SPEED_LOW;
+		}
+
+		if (auto error = usbi_sanitize_device(dev)) {
+			co_return error;
+		}
+
+		auto configurations_len = dev->device_descriptor.bNumConfigurations;
+		configurations.reserve(configurations_len);
+		for (uint8_t j = 0; j < configurations_len; j++) {
+			// Note: requesting more than (platform-specific limit) bytes
+			// here will cause the transfer to fail, see
+			// https://crbug.com/1489414. Use the most common limit of 4096
+			// bytes for now.
+			constexpr uint16_t MAX_CTRL_BUFFER_LENGTH = 4096;
+			auto result = co_await_try(
+				requestDescriptor(LIBUSB_DT_CONFIG, j, MAX_CTRL_BUFFER_LENGTH));
+			if (auto error = getTransferStatus(result)) {
+				co_return error;
+			}
+			auto configVal = result["data"];
+			auto configLen = configVal["byteLength"].as<size_t>();
+			auto& config = configurations.emplace_back(
+				(usbi_configuration_descriptor*)::operator new(configLen));
+			copyFromDataView(config.get(), configVal);
+		}
+
+		co_return (int) LIBUSB_SUCCESS;
+	}
+
+	CachedDevice(val device) : device(std::move(device)) {}
+
+	friend struct ValPtr<CachedDevice>;
+};
+
+unsigned long getDeviceSessionId(val& web_usb_device) {
+	thread_local const val SessionIdSymbol =
+		val::global("Symbol")(val("libusb.session_id"));
+
+	val session_id_val = web_usb_device[SessionIdSymbol];
+	if (!session_id_val.isUndefined()) {
+		return session_id_val.as<unsigned long>();
+	}
+
+	// If the device doesn't have a session ID, it means we haven't seen
+	// it before. Generate a new session ID for it. We can associate an
+	// incrementing ID with the `USBDevice` object itself. It's
+	// guaranteed to be alive and, thus, stable as long as the device is
+	// connected, even between different libusb invocations. See
+	// https://github.com/WICG/webusb/issues/241.
+
+	static unsigned long next_session_id = 0;
+
+	web_usb_device.set(SessionIdSymbol, next_session_id);
+	return next_session_id++;
+}
+
+val getDeviceList(libusb_context* ctx, discovered_devs** devs) {
+	// C++ equivalent of `await navigator.usb.getDevices()`. Note: at this point
+	// we must already have some devices exposed - caller must have called
+	// `await navigator.usb.requestDevice(...)` in response to user interaction
+	// before going to LibUSB. Otherwise this list will be empty.
+	auto web_usb_devices =
+		co_await_try(val::global("navigator")["usb"].call<val>("getDevices"));
+	for (auto&& web_usb_device : web_usb_devices) {
+		auto session_id = getDeviceSessionId(web_usb_device);
+
+		auto dev = usbi_get_device_by_session_id(ctx, session_id);
+		if (dev == NULL) {
+			dev = usbi_alloc_device(ctx, session_id);
+			if (dev == NULL) {
+				usbi_err(ctx, "failed to allocate a new device structure");
+				continue;
+			}
+
+			auto statusVal = co_await CachedDevice::initFromDevice(
+				std::move(web_usb_device), dev);
+			if (auto error = statusVal.as<int>()) {
+				usbi_err(ctx, "failed to read device information: %s",
+						 libusb_error_name(error));
+				libusb_unref_device(dev);
+				continue;
+			}
+
+			// We don't have real buses in WebUSB, just pretend everything
+			// is on bus 1.
+			dev->bus_number = 1;
+			// This can wrap around but it's the best approximation of a stable
+			// device address and port number we can provide.
+			dev->device_address = dev->port_number = (uint8_t)session_id;
+		}
+		*devs = discovered_devs_append(*devs, dev);
+		libusb_unref_device(dev);
+	}
+	co_return (int) LIBUSB_SUCCESS;
+}
+
+int em_get_device_list(libusb_context* ctx, discovered_devs** devs) {
+	// No need to wrap into CaughtPromise as we catch all individual ops in the
+	// inner implementation and return just the error code. We do need a custom
+	// promise type to ensure conversion to int happens on the main thread
+	// though.
+	struct IntPromise : val {
+		IntPromise(val&& promise) : val(std::move(promise)) {}
+
+		struct AwaitResult {
+			int error;
+
+			AwaitResult(val&& result) : error(result.as<int>()) {}
+		};
+	};
+
+	return awaitOnMain(
+			   [ctx, devs] { return IntPromise(getDeviceList(ctx, devs)); })
+		.error;
+}
+
+int em_open(libusb_device_handle* handle) {
+	return WebUsbDevicePtr(handle)->safeOpenCloseOnMain(OpenClose::Open);
+}
+
+void em_close(libusb_device_handle* handle) {
+	// LibUSB API doesn't allow us to handle an error here, but we still need to
+	// wait for the promise to make sure that subsequent attempt to reopen the
+	// same device doesn't fail with a "device busy" error.
+	if (auto error =
+			WebUsbDevicePtr(handle)->safeOpenCloseOnMain(OpenClose::Close)) {
+		usbi_err(handle->dev->ctx, "failed to close device: %s",
+				 libusb_error_name(error));
+	}
+}
+
+int em_get_active_config_descriptor(libusb_device* dev, void* buf, size_t len) {
+	auto& cached_device = *WebUsbDevicePtr(dev);
+	auto config_value = cached_device.getActiveConfigValue();
+	if (auto config = cached_device.findConfigDescriptorByValue(config_value)) {
+		return cached_device.copyConfigDescriptor(config, buf, len);
+	} else {
+		return LIBUSB_ERROR_NOT_FOUND;
+	}
+}
+
+int em_get_config_descriptor(libusb_device* dev,
+							 uint8_t config_id,
+							 void* buf,
+							 size_t len) {
+	auto& cached_device = *WebUsbDevicePtr(dev);
+	if (auto config = cached_device.getConfigDescriptor(config_id)) {
+		return cached_device.copyConfigDescriptor(config, buf, len);
+	} else {
+		return LIBUSB_ERROR_NOT_FOUND;
+	}
+}
+
+int em_get_configuration(libusb_device_handle* dev_handle,
+						 uint8_t* config_value) {
+	*config_value = WebUsbDevicePtr(dev_handle)->getActiveConfigValue();
+	return LIBUSB_SUCCESS;
+}
+
+int em_get_config_descriptor_by_value(libusb_device* dev,
+									  uint8_t config_value,
+									  void** buf) {
+	auto& cached_device = *WebUsbDevicePtr(dev);
+	if (auto config = cached_device.findConfigDescriptorByValue(config_value)) {
+		*buf = config;
+		return config->wTotalLength;
+	} else {
+		return LIBUSB_ERROR_NOT_FOUND;
+	}
+}
+
+int em_set_configuration(libusb_device_handle* dev_handle, int config) {
+	return WebUsbDevicePtr(dev_handle)->awaitOnMain("setConfiguration", config);
+}
+
+int em_claim_interface(libusb_device_handle* handle, uint8_t iface) {
+	return WebUsbDevicePtr(handle)->awaitOnMain("claimInterface", iface);
+}
+
+int em_release_interface(libusb_device_handle* handle, uint8_t iface) {
+	return WebUsbDevicePtr(handle)->awaitOnMain("releaseInterface", iface);
+}
+
+int em_set_interface_altsetting(libusb_device_handle* handle,
+								uint8_t iface,
+								uint8_t altsetting) {
+	return WebUsbDevicePtr(handle)->awaitOnMain("selectAlternateInterface",
+												iface, altsetting);
+}
+
+int em_clear_halt(libusb_device_handle* handle, unsigned char endpoint) {
+	std::string direction = endpoint & LIBUSB_ENDPOINT_IN ? "in" : "out";
+	endpoint &= LIBUSB_ENDPOINT_ADDRESS_MASK;
+
+	return WebUsbDevicePtr(handle)->awaitOnMain("clearHalt", direction,
+												endpoint);
+}
+
+int em_reset_device(libusb_device_handle* handle) {
+	return WebUsbDevicePtr(handle)->awaitOnMain("reset");
+}
+
+void em_destroy_device(libusb_device* dev) {
+	WebUsbDevicePtr(dev).free();
+}
+
+int em_submit_transfer(usbi_transfer* itransfer) {
+	return runOnMain([itransfer] {
+		auto transfer = USBI_TRANSFER_TO_LIBUSB_TRANSFER(itransfer);
+		auto& web_usb_device = WebUsbDevicePtr(transfer->dev_handle)
+								   ->getDeviceAssumingMainThread();
+		val transfer_promise;
+		switch (transfer->type) {
+			case LIBUSB_TRANSFER_TYPE_CONTROL: {
+				transfer_promise = makeControlTransferPromise(
+					web_usb_device,
+					libusb_control_transfer_get_setup(transfer));
+				break;
+			}
+			case LIBUSB_TRANSFER_TYPE_BULK:
+			case LIBUSB_TRANSFER_TYPE_INTERRUPT: {
+				auto endpoint =
+					transfer->endpoint & LIBUSB_ENDPOINT_ADDRESS_MASK;
+
+				if (IS_XFERIN(transfer)) {
+					transfer_promise = web_usb_device.call<val>(
+						"transferIn", endpoint, transfer->length);
+				} else {
+					auto data = getUnsharedMemoryView(transfer->buffer,
+													  transfer->length);
+					transfer_promise =
+						web_usb_device.call<val>("transferOut", endpoint, data);
+				}
+
+				break;
+			}
+			// TODO: add implementation for isochronous transfers too.
+			default:
+				return LIBUSB_ERROR_NOT_SUPPORTED;
+		}
+		// Not a coroutine because we don't want to block on this promise, just
+		// schedule an asynchronous callback.
+		promiseThen(CaughtPromise(std::move(transfer_promise)),
+					[itransfer](auto&& result) {
+						WebUsbTransferPtr(itransfer).emplace(std::move(result));
+						usbi_signal_transfer_completion(itransfer);
+					});
+		return LIBUSB_SUCCESS;
+	});
+}
+
+void em_clear_transfer_priv(usbi_transfer* itransfer) {
+	WebUsbTransferPtr(itransfer).free();
+}
+
+int em_cancel_transfer(usbi_transfer* itransfer) {
+	return LIBUSB_SUCCESS;
+}
+
+int em_handle_transfer_completion(usbi_transfer* itransfer) {
+	libusb_transfer_status status = runOnMain([itransfer] {
+		auto transfer = USBI_TRANSFER_TO_LIBUSB_TRANSFER(itransfer);
+
+		// Take ownership of the transfer result, as `em_clear_transfer_priv` is
+		// not called automatically for completed transfers and we must free it
+		// to avoid leaks.
+
+		auto result = WebUsbTransferPtr(itransfer).take();
+
+		if (itransfer->state_flags & USBI_TRANSFER_CANCELLING) {
+			return LIBUSB_TRANSFER_CANCELLED;
+		}
+
+		if (result.error) {
+			return LIBUSB_TRANSFER_ERROR;
+		}
+
+		auto& value = result.value;
+
+		void* dataDest;
+		unsigned char endpointDir;
+
+		if (transfer->type == LIBUSB_TRANSFER_TYPE_CONTROL) {
+			dataDest = libusb_control_transfer_get_data(transfer);
+			endpointDir =
+				libusb_control_transfer_get_setup(transfer)->bmRequestType;
+		} else {
+			dataDest = transfer->buffer;
+			endpointDir = transfer->endpoint;
+		}
+
+		if (endpointDir & LIBUSB_ENDPOINT_IN) {
+			auto data = value["data"];
+			if (!data.isNull()) {
+				itransfer->transferred = data["byteLength"].as<int>();
+				copyFromDataView(dataDest, data);
+			}
+		} else {
+			itransfer->transferred = value["bytesWritten"].as<int>();
+		}
+
+		return getTransferStatus(value);
+	});
+
+	// Invoke user's handlers outside of the main thread to reduce pressure.
+	return status == LIBUSB_TRANSFER_CANCELLED
+		? usbi_handle_transfer_cancellation(itransfer)
+		: usbi_handle_transfer_completion(itransfer, status);
+}
+
+}  // namespace
+
+#pragma clang diagnostic ignored "-Wmissing-field-initializers"
+extern "C" const usbi_os_backend usbi_backend = {
+	.name = "Emscripten + WebUSB backend",
+	.caps = LIBUSB_CAP_HAS_CAPABILITY,
+	.get_device_list = em_get_device_list,
+	.open = em_open,
+	.close = em_close,
+	.get_active_config_descriptor = em_get_active_config_descriptor,
+	.get_config_descriptor = em_get_config_descriptor,
+	.get_config_descriptor_by_value = em_get_config_descriptor_by_value,
+	.get_configuration = em_get_configuration,
+	.set_configuration = em_set_configuration,
+	.claim_interface = em_claim_interface,
+	.release_interface = em_release_interface,
+	.set_interface_altsetting = em_set_interface_altsetting,
+	.clear_halt = em_clear_halt,
+	.reset_device = em_reset_device,
+	.destroy_device = em_destroy_device,
+	.submit_transfer = em_submit_transfer,
+	.cancel_transfer = em_cancel_transfer,
+	.clear_transfer_priv = em_clear_transfer_priv,
+	.handle_transfer_completion = em_handle_transfer_completion,
+	.device_priv_size = sizeof(CachedDevice),
+	.transfer_priv_size = sizeof(PromiseResult),
+};
+
+#pragma clang diagnostic pop