将 USB 应用移植到 Web 中。第 1 部分：libusb

了解如何使用 WebAssembly 和 Fugu API 将与外部设备交互的代码移植到 Web 上。

在上一篇博文中，我介绍了如何使用 File System Access API、WebAssembly 和 Asyncify 将使用文件系统 API 的应用移植到 Web 上。现在，我想继续探讨同一主题，即将 Fugu API 与 WebAssembly 集成，并在不丢失重要功能的情况下将应用移植到 Web 上。

我将介绍如何通过将 libusb（一种用 C 语言编写的热门 USB 库）移植到 WebAssembly（通过 Emscripten）、Asyncify 和 WebUSB，将与 USB 设备通信的应用移植到 Web 平台。

先解决重点问题：演示

在移植库时，最重要的是选择合适的演示版，该演示版应能展示移植的库的功能，让您能够以多种方式对其进行测试，同时具有出色的视觉效果。

我选择的方案是数码单反遥控器。特别是，开源项目 gPhoto2 已在此领域深耕多年，能够对各种数字相机进行逆向工程并实现对它们的支持。它支持多种协议，但我最感兴趣的是 USB 支持，它通过 libusb 执行此操作。

我将分两个部分介绍构建此演示的步骤。在本博文中，我将介绍如何移植 libusb 本身，以及可能需要使用哪些技巧才能将其他常用库移植到 Fugu API。在第二篇博文中，我将详细介绍如何移植和集成 gPhoto2 本身。

最后，我获得了一个可用的 Web 应用，该应用可以预览来自 DSLR 的实时画面，并可以通过 USB 控制其设置。在了解技术细节之前，您可以随时观看直播或预录制的演示：

关于相机专用问题的说明

您可能已经注意到，视频中更改设置需要一段时间。与您可能会遇到的大多数其他问题一样，此问题并非由 WebAssembly 或 WebUSB 的性能导致，而是由 gPhoto2 与为演示选择的特定相机的互动方式导致。

Sony a6600 未公开用于直接设置 ISO、光圈或快门速度等值的 API，而是仅提供按指定步数增减这些值的命令。更复杂的是，它也不会返回实际支持的值的列表，返回的列表似乎在许多索尼相机型号中都硬编码了。

设置其中一个值时，gPhoto2 别无选择，只能执行以下操作：

1. 朝着所选值的方向迈出一步（或几步）。
2. 请稍等片刻，让摄像头更新设置。
3. 读回相机实际停留的值。
4. 检查上一步是否跳过了所需值，也未绕过列表的开头或结尾。
5. 重复。

这可能需要一些时间，但如果相机实际支持该值，则会达到该值；如果不支持，则会在最接近的支持值处停止。

其他摄像头可能具有不同的设置、底层 API 和怪癖。请注意，gPhoto2 是一个开源项目，我们根本无法对所有摄像头型号进行自动或手动测试，因此我们非常欢迎您提供详细的问题报告和 PR（但请务必先使用官方 gPhoto2 客户端重现问题）。

关于跨平台兼容性的重要说明

遗憾的是，在 Windows 上，所有“众所周知”的设备（包括数码单反相机）都会分配一个系统驱动程序，该驱动程序与 WebUSB 不兼容。如果您想在 Windows 上试用此演示版，则必须使用 Zadig 等工具将已连接的 DSLR 的驱动程序替换为 WinUSB 或 libusb。此方法对我和许多其他用户都很有效，但您在使用时需自行承担风险。

在 Linux 上，您可能需要设置自定义权限，才能允许通过 WebUSB 访问您的 DSLR，但这取决于您的发行版本。

在 macOS 和 Android 上，该演示应该开箱即用。如果您是在 Android 手机上试用，请务必切换到横屏模式，因为我没有花太多精力来提高其响应能力（欢迎提交 PR！）：

如需有关跨平台使用 WebUSB 的更深入指南，请参阅“构建适用于 WebUSB 的设备”的“平台专用注意事项”部分。

向 libusb 添加了新后端

接下来介绍一些技术细节。虽然可以提供类似于 libusb 的 shim API（之前有人这样做过），并将其他应用与其关联，但这种方法容易出错，并且会增加进一步扩展或维护的难度。我希望以正确的方式处理问题，以便将来能够贡献回上游并合并到 libusb 中。

幸运的是，libusb README 中指出：

“libusb 在内部进行了抽象化处理，以便有望移植到其他操作系统。如需了解详情，请参阅 PORTING 文件。”

libusb 的结构使公共 API 与“后端”分离。这些后端负责列出、打开、关闭设备，以及通过操作系统的低级 API 与设备实际通信。正是如此，libusb 已经抽象化了 Linux、macOS、Windows、Android、OpenBSD/NetBSD、Haiku 和 Solaris 之间的差异，并可在所有这些平台上运行。

我不得不为 Emscripten+WebUSB“操作系统”添加另一个后端。这些后端的实现位于 libusb/os 文件夹中：

~/w/d/libusb $ ls libusb/os
darwin_usb.c           haiku_usb_raw.h  threads_posix.lo
darwin_usb.h           linux_netlink.c  threads_posix.o
events_posix.c         linux_udev.c     threads_windows.c
events_posix.h         linux_usbfs.c    threads_windows.h
events_posix.lo        linux_usbfs.h    windows_common.c
events_posix.o         netbsd_usb.c     windows_common.h
events_windows.c       null_usb.c       windows_usbdk.c
events_windows.h       openbsd_usb.c    windows_usbdk.h
haiku_pollfs.cpp       sunos_usb.c      windows_winusb.c
haiku_usb_backend.cpp  sunos_usb.h      windows_winusb.h
haiku_usb.h            threads_posix.c
haiku_usb_raw.cpp      threads_posix.h

每个后端都包含包含常用类型和帮助程序的 libusbi.h 标头，并且需要公开类型为 usbi_os_backend 的 usbi_backend 变量。例如，Windows 后端如下所示：

const struct usbi_os_backend usbi_backend = {
  "Windows",
  USBI_CAP_HAS_HID_ACCESS,
  windows_init,
  windows_exit,
  windows_set_option,
  windows_get_device_list,
  NULL,   /* hotplug_poll */
  NULL,   /* wrap_sys_device */
  windows_open,
  windows_close,
  windows_get_active_config_descriptor,
  windows_get_config_descriptor,
  windows_get_config_descriptor_by_value,
  windows_get_configuration,
  windows_set_configuration,
  windows_claim_interface,
  windows_release_interface,
  windows_set_interface_altsetting,
  windows_clear_halt,
  windows_reset_device,
  NULL,   /* alloc_streams */
  NULL,   /* free_streams */
  NULL,   /* dev_mem_alloc */
  NULL,   /* dev_mem_free */
  NULL,   /* kernel_driver_active */
  NULL,   /* detach_kernel_driver */
  NULL,   /* attach_kernel_driver */
  windows_destroy_device,
  windows_submit_transfer,
  windows_cancel_transfer,
  NULL,   /* clear_transfer_priv */
  NULL,   /* handle_events */
  windows_handle_transfer_completion,
  sizeof(struct windows_context_priv),
  sizeof(union windows_device_priv),
  sizeof(struct windows_device_handle_priv),
  sizeof(struct windows_transfer_priv),
};

查看这些属性，我们可以看到该结构体包含后端名称、一组功能、各种低级别 USB 操作的处理程序（以函数指针的形式），以及用于存储私密设备级/上下文级/传输级数据的大小。

私有数据字段至少对于存储所有这些内容的操作系统句柄很有用，因为没有句柄，我们就不知道任何给定操作适用于哪个项。在 Web 实现中，操作系统句柄将是底层 WebUSB JavaScript 对象。在 Emscripten 中表示和存储它们的自然方式是通过 emscripten::val 类，该类是 Embind（Emscripten 的绑定系统）的一部分。

该文件夹中的大多数后端都是用 C 实现的，但少数后端是用 C++ 实现的。Embind 仅适用于 C++，因此我选择了后者，并添加了具有所需结构的 libusb/libusb/os/emscripten_webusb.cpp，以及用于私有数据字段的 sizeof(val)：

#include <emscripten.h>
#include <emscripten/val.h>

#include "libusbi.h"

using namespace emscripten;

// …function implementations

const usbi_os_backend usbi_backend = {
  .name = "Emscripten + WebUSB backend",
  .caps = LIBUSB_CAP_HAS_CAPABILITY,
  // …handlers—function pointers to implementations above
  .device_priv_size = sizeof(val),
  .transfer_priv_size = sizeof(val),
};

将 WebUSB 对象存储为设备句柄

libusb 提供了指向分配给私有数据的区域的现成指针。为了将这些指针用作 val 实例，我添加了一些小型辅助程序，用于就地构建这些指针、将其检索为引用，以及移出值：

// We store an Embind handle to WebUSB USBDevice in "priv" metadata of
// libusb device, this helper returns a pointer to it.
struct ValPtr {
 public:
  void init_to(val &&value) { new (ptr) val(std::move(value)); }

  val &get() { return *ptr; }
  val take() { return std::move(get()); }

 protected:
  ValPtr(val *ptr) : ptr(ptr) {}

 private:
  val *ptr;
};

struct WebUsbDevicePtr : ValPtr {
 public:
  WebUsbDevicePtr(libusb_device *dev)
      : ValPtr(static_cast<val *>(usbi_get_device_priv(dev))) {}
};

val &get_web_usb_device(libusb_device *dev) {
  return WebUsbDevicePtr(dev).get();
}

struct WebUsbTransferPtr : ValPtr {
 public:
  WebUsbTransferPtr(usbi_transfer *itransfer)
      : ValPtr(static_cast<val *>(usbi_get_transfer_priv(itransfer))) {}
};

同步 C 情境中的异步 Web API

现在，需要一种处理异步 WebUSB API 的方法，因为 libusb 期望同步操作。为此，我可以使用 Asyncify，或者更具体地说，可以使用其通过 val::await() 进行的 Embind 集成。

我还想正确处理 WebUSB 错误并将其转换为 libusb 错误代码，但 Embind 目前无法从 C++ 端处理 JavaScript 异常或 Promise 拒绝。您可以通过在 JavaScript 端捕获拒绝并将结果转换为 { error, value } 对象来解决此问题，现在可以从 C++ 端安全地解析该对象。我通过结合使用 EM_JS 宏和 Emval.to{Handle, Value} API 来实现此目的：

EM_JS(EM_VAL, em_promise_catch_impl, (EM_VAL handle), {
  let promise = Emval.toValue(handle);
  promise = promise.then(
    value => ({error : 0, value}),
    error => {
      const ERROR_CODES = {
        // LIBUSB_ERROR_IO
        NetworkError : -1,
        // LIBUSB_ERROR_INVALID_PARAM
        DataError : -2,
        TypeMismatchError : -2,
        IndexSizeError : -2,
        // LIBUSB_ERROR_ACCESS
        SecurityError : -3,
        …
      };
      console.error(error);
      let errorCode = -99; // LIBUSB_ERROR_OTHER
      if (error instanceof DOMException)
      {
        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);
});

val em_promise_catch(val &&promise) {
  EM_VAL handle = promise.as_handle();
  handle = em_promise_catch_impl(handle);
  return val::take_ownership(handle);
}

// C++ struct representation for {value, error} object from above
// (performs conversion in the constructor).
struct promise_result {
  libusb_error error;
  val value;

  promise_result(val &&result)
      : error(static_cast<libusb_error>(result["error"].as<int>())),
        value(result["value"]) {}

  // C++ counterpart of the promise helper above that takes a promise, catches
  // its error, converts to a libusb status and returns the whole thing as
  // `promise_result` struct for easier handling.
  static promise_result await(val &&promise) {
    promise = em_promise_catch(std::move(promise));
    return {promise.await()};
  }
};

现在，我可以对从 WebUSB 操作返回的任何 Promise 使用 promise_result::await()，并单独检查其 error 和 value 字段。

例如，从 libusb_device_handle 检索表示 USBDevice 的 val，调用其 open() 方法，等待其结果，并将错误代码作为 libusb 状态代码返回，如下所示：

int em_open(libusb_device_handle *handle) {
  auto web_usb_device = get_web_usb_device(handle->dev);
  return promise_result::await(web_usb_device.call<val>("open")).error;
}

设备枚举

当然，在我可以打开任何设备之前，libusb 需要检索可用设备的列表。后端必须通过 get_device_list 处理程序实现此操作。

难点在于，与其他平台不同，出于安全考虑，您无法在 Web 上枚举所有已连接的 USB 设备。而是将流程拆分为两部分。首先，Web 应用会通过 navigator.usb.requestDevice() 请求具有特定属性的设备，然后用户手动选择要公开哪些设备，或拒绝权限提示。之后，应用会通过 navigator.usb.getDevices() 列出已获批准且已连接的设备。

起初，我尝试在 get_device_list 处理程序的实现中直接使用 requestDevice()。不过，显示包含已连接设备列表的权限提示被视为敏感操作，并且必须由用户互动（例如点击网页上的按钮）触发，否则始终会返回被拒绝的 promise。libusb 应用可能经常需要在应用启动时列出已连接的设备，因此无法使用 requestDevice()。

相反，我不得不将 navigator.usb.requestDevice() 的调用交给最终开发者，并仅通过 navigator.usb.getDevices() 公开已获批准的设备：

// Store the global `navigator.usb` once upon initialisation.
thread_local const val web_usb = val::global("navigator")["usb"];

int em_get_device_list(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 result = promise_result::await(web_usb.call<val>("getDevices"));
  if (result.error) {
    return result.error;
  }
  auto &web_usb_devices = result.value;
  // Iterate over the exposed devices.
  uint8_t devices_num = web_usb_devices["length"].as<uint8_t>();
  for (uint8_t i = 0; i < devices_num; i++) {
    auto web_usb_device = web_usb_devices[i];
    // …
    *devs = discovered_devs_append(*devs, dev);
  }
  return LIBUSB_SUCCESS;
}

大多数后端代码使用 val 和 promise_result 的方式与上文中所述类似。数据传输处理代码中还有一些有趣的黑客技巧，但这些实现细节对本文而言不太重要。如果您对此感兴趣，请务必查看 GitHub 上的代码和评论。

将事件循环移植到 Web

我还想讨论 libusb 端口的另一个部分，即事件处理。如上一篇文章所述，C 等系统语言中的大多数 API 都是同步的，事件处理也不例外。它通常通过无限循环实现，该循环会从一组外部 I/O 源“轮询”（尝试读取数据或阻塞执行，直到有数据可用），并且当其中至少有一个源响应时，将其作为事件传递给相应的处理脚本。处理程序完成后，控制会返回到循环，并暂停以进行另一次轮询。

在网络上，这种方法存在几个问题。

首先，WebUSB 不会也不得公开底层设备的原始句柄，因此无法直接轮询这些句柄。其次，libusb 使用 eventfd 和 pipe API 处理其他事件，以及在没有原始设备句柄的操作系统上处理传输，但 Emscripten 目前不支持 eventfd，虽然 pipe 受支持，但目前不符合规范，无法等待事件。

最后，最大的问题是，Web 有自己的事件循环。此全局事件循环用于任何外部 I/O 操作（包括 fetch()、计时器或在本例中为 WebUSB），并且每当相应操作完成时，都会调用事件或 Promise 处理脚本。执行另一个嵌套的无限事件循环将阻止浏览器的事件循环继续进行，这意味着界面不仅会变得无响应，而且代码也永远不会收到它正在等待的 I/O 事件的通知。这通常会导致死锁，当我尝试在演示中使用 libusb 时，也发生了这种情况。页面卡住了。

与其他阻塞 I/O 一样，如需将此类事件循环移植到 Web，开发者需要找到一种在不阻塞主线程的情况下运行这些循环的方法。一种方法是重构应用，以便在单独的线程中处理 I/O 事件，并将结果传回主线程。另一种方法是使用 Asyncify 暂停循环并以非阻塞方式等待事件。

我不想对 libusb 或 gPhoto2 进行重大更改，并且我已经使用 Asyncify 进行 Promise 集成，因此我选择了这种方式。为了模拟 poll() 的阻塞变体，在初始概念验证中，我使用了一个循环，如下所示：

#ifdef __EMSCRIPTEN__
  // TODO: optimize this. Right now it will keep unwinding-rewinding the stack
  // on each short sleep until an event comes or the timeout expires.
  // We should probably create an actual separate thread that does signaling
  // or come up with a custom event mechanism to report events from
  // `usbi_signal_event` and process them here.
  double until_time = emscripten_get_now() + timeout_ms;
  do {
    // Emscripten `poll` ignores timeout param, but pass 0 explicitly just
    // in case.
    num_ready = poll(fds, nfds, 0);
    if (num_ready != 0) break;
    // Yield to the browser event loop to handle events.
    emscripten_sleep(0);
  } while (emscripten_get_now() < until_time);
#else
  num_ready = poll(fds, nfds, timeout_ms);
#endif

其作用如下：

1. 调用 poll() 以检查后端是否已报告任何事件。如果有，循环会停止。否则，Emscripten 对 poll() 的实现将立即返回 0。
2. 调用 emscripten_sleep(0)。此函数在后台使用 Asyncify 和 setTimeout()，在这里用于将控制权交还给主浏览器事件循环。这样，浏览器便可以处理任何用户互动和 I/O 事件，包括 WebUSB。
3. 检查指定的超时时间是否已过，如果未过，则继续循环。

正如评论中所提到的，这种方法并不理想，因为即使没有要处理的 USB 事件（大多数情况下），它也会一直使用 Asyncify 保存-恢复整个调用堆栈，并且 setTimeout() 本身在现代浏览器中的最短时长为 4 毫秒。不过，在概念验证中，它还是能从 DSLR 生成 13-14 FPS 的直播。

后来，我决定利用浏览器事件系统对其进行改进。此实现可以通过多种方式进一步改进，但目前我选择直接在全局对象上发出自定义事件，而不将其与特定的 libusb 数据结构相关联。我通过基于 EM_ASYNC_JS 宏的以下等待和通知机制实现了这一点：

EM_JS(void, em_libusb_notify, (void), {
  dispatchEvent(new Event("em-libusb"));
});

EM_ASYNC_JS(int, em_libusb_wait, (int timeout), {
  let onEvent, timeoutId;

  try {
    return await new Promise(resolve => {
      onEvent = () => resolve(0);
      addEventListener('em-libusb', onEvent);

      timeoutId = setTimeout(resolve, timeout, -1);
    });
  } finally {
    removeEventListener('em-libusb', onEvent);
    clearTimeout(timeoutId);
  }
});

每当 libusb 尝试报告事件（例如数据传输完成）时，都会使用 em_libusb_notify() 函数：

void usbi_signal_event(usbi_event_t *event)
{
  uint64_t dummy = 1;
  ssize_t r;

  r = write(EVENT_WRITE_FD(event), &dummy, sizeof(dummy));
  if (r != sizeof(dummy))
    usbi_warn(NULL, "event write failed");
#ifdef __EMSCRIPTEN__
  em_libusb_notify();
#endif
}

同时，em_libusb_wait() 部分用于在收到 em-libusb 事件或超时期限已过时从 Asyncify 休眠状态“唤醒”：

double until_time = emscripten_get_now() + timeout_ms;
for (;;) {
  // Emscripten `poll` ignores timeout param, but pass 0 explicitly just
  // in case.
  num_ready = poll(fds, nfds, 0);
  if (num_ready != 0) break;
  int timeout = until_time - emscripten_get_now();
  if (timeout <= 0) break;
  int result = em_libusb_wait(timeout);
  if (result != 0) break;
}

由于显著减少了休眠和唤醒次数，此机制解决了之前基于 emscripten_sleep() 的实现的效率问题，并将 DSLR 演示的吞吐量从 13-14 FPS 提高到了稳定的 30+ FPS，足以实现流畅的实时画面。

构建系统和第一个测试

后端完成后，我必须将其添加到 Makefile.am 和 configure.ac。这里唯一有趣的部分是 Emscripten 专用标志修改：

emscripten)
  AC_SUBST(EXEEXT, [.html])
  # Note: LT_LDFLAGS is not enough here because we need link flags for executable.
  AM_LDFLAGS="${AM_LDFLAGS} --bind -s ASYNCIFY -s ASSERTIONS -s ALLOW_MEMORY_GROWTH -s INVOKE_RUN=0 -s EXPORTED_RUNTIME_METHODS=['callMain']"
  ;;

首先，Unix 平台上的可执行文件通常没有文件扩展名。不过，Emscripten 会根据您请求的扩展程序生成不同的输出。我使用 AC_SUBST(EXEEXT, …) 将可执行文件扩展名更改为 .html，以便软件包中的任何可执行文件（测试和示例）都变成 HTML，并使用 Emscripten 的默认 shell 加载和实例化 JavaScript 和 WebAssembly。

其次，由于我使用的是 Embind 和 Asyncify，因此需要通过链接器参数启用这些功能 (--bind -s ASYNCIFY) 以及允许动态内存增长 (-s ALLOW_MEMORY_GROWTH)。遗憾的是，库无法向链接器报告这些标志，因此使用此 libusb 端口的每个应用都必须将相同的链接器标志添加到其构建配置中。

最后，如前所述，WebUSB 要求通过用户手势完成设备枚举。libusb 示例和测试假定它们可以在启动时枚举设备，如果不进行更改，则会失败并出现错误。我不得不停用自动执行 (-s INVOKE_RUN=0) 并公开手动 callMain() 方法 (-s EXPORTED_RUNTIME_METHODS=...)。

完成所有这些操作后，我就可以使用静态 Web 服务器提供生成的文件、初始化 WebUSB，并借助 DevTools 手动运行这些 HTML 可执行文件。

这看起来没什么特别的，但将库移植到新平台时，首次看到库生成有效输出时，还是很令人兴奋的！

使用该充电桩

如上文所述，该移植依赖于一些 Emscripten 功能，这些功能目前需要在应用的链接阶段启用。如果您想在自己的应用中使用此 libusb 端口，则需要执行以下操作：

1. 将最新的 libusb 作为 build 的一部分下载为归档文件，或将其作为 git 子模块添加到项目中。
2. 在 libusb 文件夹中运行 autoreconf -fiv。
3. 运行 emconfigure ./configure –host=wasm32 –prefix=/some/installation/path 以初始化项目以进行交叉编译，并设置要放置已构建工件的路径。
4. 运行 emmake make install。
5. 将应用或更高级别的库指向先前选择的路径下搜索 libusb。
6. 将以下标志添加到应用的链接参数中：--bind -s ASYNCIFY -s ALLOW_MEMORY_GROWTH。

该库目前存在一些限制：

• 不支持取消转移。这是 WebUSB 的局限性，而这又源于 libusb 本身缺少跨平台传输取消功能。
• 不支持异步传输。按照现有传输模式的实现作为示例，添加该模式应该不难，但这也是一个比较少见的模式，我没有任何设备可以用于对其进行测试，因此目前将其设为不受支持。如果您有此类设备，并且希望为该库做出贡献，欢迎提交 PR！
• 前面提到的跨平台限制。这些限制是由操作系统强加的，因此我们除了要求用户替换驱动程序或权限之外，无法做太多事情。不过，如果您要移植 HID 或串行设备，可以按照 libusb 示例将其他库移植到其他 Fugu API。例如，您可以将 C 库 hidapi 移植到 WebHID，从而完全规避与低级别 USB 访问相关的问题。

总结

在本文中，我展示了如何借助 Emscripten、Asyncify 和 Fugu API 通过一些集成技巧将 libusb 等低级库移植到 Web 上。

移植这些必不可少且广泛使用的低级库特别有益，因为这反过来又可以将更高级别的库或甚至整个应用引入到 Web 中。这让之前仅限于一两个平台的用户体验面向各种设备和操作系统开放，用户只需点击一个链接即可获得这些体验。

在下一篇博文中，我将详细介绍构建 Web gPhoto2 演示的步骤，该演示不仅会检索设备信息，还会广泛使用 libusb 的传输功能。与此同时，希望 libusb 示例对您有所启发，并希望您试用演示版、玩转该库本身，或者甚至继续将另一个广泛使用的库移植到某个 Fugu API。