Skip to content

A rootless Android app that boots Alpine Linux: run containers (Podman/Docker/LXC) and GUI desktop apps.

fix(usb): keep input devices with Android during passthrough

ExTv1d3763943aa1
diff --git a/app/src/main/java/com/excp/podroid/engine/usb/UsbPassthroughManager.kt b/app/src/main/java/com/excp/podroid/engine/usb/UsbPassthroughManager.kt
index 2504bec..38f6b21 100644
--- a/app/src/main/java/com/excp/podroid/engine/usb/UsbPassthroughManager.kt
+++ b/app/src/main/java/com/excp/podroid/engine/usb/UsbPassthroughManager.kt
@@ -24,6 +24,7 @@ import android.content.BroadcastReceiver
import android.content.Context
import android.content.Intent
import android.content.IntentFilter
+import android.hardware.usb.UsbConstants
import android.hardware.usb.UsbDevice
import android.hardware.usb.UsbDeviceConnection
import android.hardware.usb.UsbManager
@@ -137,6 +138,11 @@ class UsbPassthroughManager @Inject constructor(
private fun requestAndAttach(device: UsbDevice) {
if (active.containsKey(device.deviceName)) return
+ val interfaceClasses = (0 until device.interfaceCount).map { device.getInterface(it).interfaceClass }
+ if (!isPassthroughCandidate(device.deviceClass, interfaceClasses)) {
+ Log.i(TAG, "Keeping input device ${device.deviceName} with Android (HID interface)")
+ return
+ }
if (usbManager.hasPermission(device)) {
scope.launch { attach(device) }
} else {
@@ -237,5 +243,16 @@ class UsbPassthroughManager @Inject constructor(
companion object {
private const val TAG = "UsbPassthrough"
private const val ACTION_USB_PERMISSION = "com.excp.podroid.action.USB_PERMISSION"
+
+ /**
+ * Whether a device may be handed to the guest. usb-host takes the whole
+ * device, so anything exposing a HID interface (keyboard, mouse,
+ * trackpad, touchscreen, often bundled in a dock alongside other
+ * functions) is kept with Android: passing it through would leave the
+ * phone with no input.
+ */
+ fun isPassthroughCandidate(deviceClass: Int, interfaceClasses: List<Int>): Boolean =
+ deviceClass != UsbConstants.USB_CLASS_HID &&
+ interfaceClasses.none { it == UsbConstants.USB_CLASS_HID }
}
}
diff --git a/app/src/main/res/values-zh/strings.xml b/app/src/main/res/values-zh/strings.xml
index 0930269..384829d 100644
--- a/app/src/main/res/values-zh/strings.xml
+++ b/app/src/main/res/values-zh/strings.xml
@@ -352,10 +352,10 @@
<string name="usb_passthrough_description">可选。在虚拟机运行时热插拔外部 USB 设备(Wi-Fi、存储、串口等)。</string>
<string name="enable_usb_passthrough">启用 USB 设备直通</string>
<string name="usb_devices_section">设备</string>
- <string name="usb_passthrough_available">插入设备时会询问您的许可。为虚拟机添加 USB 控制器,会带来少量模拟开销,如果不需要可保持关闭。您可在设置中随时更改。</string>
+ <string name="usb_passthrough_available">插入设备时会询问您的许可。键盘、鼠标、触控板和触摸屏保留给手机使用。为虚拟机添加 USB 控制器,会带来少量模拟开销,如果不需要可保持关闭。您可在设置中随时更改。</string>
<string name="usb_passthrough_unavailable">此后端不可用:USB 设备直通需要 QEMU 控制套接字,而 AVF 后端不提供此功能。您可在设置中随时更改。</string>
<string name="usb_passthrough_settings_label">USB 设备直通</string>
- <string name="usb_passthrough_settings_description_available">在虚拟机中热插拔外部 USB 设备(Wi-Fi、存储、串口等)。设备连接时会询问许可。启动时添加 USB 控制器,因此需要重启虚拟机以应用更改。</string>
+ <string name="usb_passthrough_settings_description_available">在虚拟机中热插拔外部 USB 设备(Wi-Fi、存储、串口等)。设备连接时会询问许可;键盘、鼠标等输入设备保留给手机使用。启动时添加 USB 控制器,因此需要重启虚拟机以应用更改。</string>
<string name="usb_passthrough_settings_description_unavailable">%1$s 后端不可用:USB 设备直通需要 QEMU 的 QMP 控制套接字,而 AVF 后端不提供此功能。</string>
<string name="server_mode">服务器模式</string>
<string name="server_mode_desc">在屏幕变黑的情况下保持虚拟机运行以省电。应用会保持在前台,因此虚拟机不会被停止。要退出,请在任意位置长按 3 秒。</string>
diff --git a/app/src/main/res/values/strings.xml b/app/src/main/res/values/strings.xml
index fc35ae0..d1fbff2 100644
--- a/app/src/main/res/values/strings.xml
+++ b/app/src/main/res/values/strings.xml
@@ -351,10 +351,10 @@
<string name="usb_passthrough_description">Optional. Hot-plug external USB devices (Wi-Fi, storage, serial, etc.) into the VM at runtime.</string>
<string name="enable_usb_passthrough">Enable USB passthrough</string>
<string name="usb_devices_section">Devices</string>
- <string name="usb_passthrough_available">Each device asks for permission when you plug it in. Adds a USB controller to the VM, which costs a little emulation overhead, so leave it off if you do not need it. You can change this later in Settings.</string>
+ <string name="usb_passthrough_available">Each device asks for permission when you plug it in. Keyboards, mice, trackpads and touchscreens stay with the phone. Adds a USB controller to the VM, which costs a little emulation overhead, so leave it off if you do not need it. You can change this later in Settings.</string>
<string name="usb_passthrough_unavailable">Not available on this backend: USB passthrough needs QEMU control socket, which the AVF backend does not provide. You can change this later in Settings.</string>
<string name="usb_passthrough_settings_label">USB passthrough</string>
- <string name="usb_passthrough_settings_description_available">Hot-plugs external USB devices (Wi-Fi, storage, serial, etc.) into the VM. Each device asks for permission when attached. Adds a USB controller at boot, so restart the VM to apply.</string>
+ <string name="usb_passthrough_settings_description_available">Hot-plugs external USB devices (Wi-Fi, storage, serial, etc.) into the VM. Each device asks for permission when attached; keyboards, mice and other input devices stay with the phone. Adds a USB controller at boot, so restart the VM to apply.</string>
<string name="usb_passthrough_settings_description_unavailable">Not available on the %1$s backend: USB passthrough rides QEMU\'s QMP control socket, which the AVF backend doesn\'t provide.</string>
<string name="server_mode">Server mode</string>
<string name="server_mode_desc">Keeps the VM running with the screen blacked out to save power. The app stays in the foreground so the VM is never stopped. To exit, press and hold anywhere for 3 seconds.</string>
diff --git a/app/src/test/java/com/excp/podroid/engine/usb/UsbPassthroughFilterTest.kt b/app/src/test/java/com/excp/podroid/engine/usb/UsbPassthroughFilterTest.kt
new file mode 100644
index 0000000..98b45a0
--- /dev/null
+++ b/app/src/test/java/com/excp/podroid/engine/usb/UsbPassthroughFilterTest.kt
@@ -0,0 +1,41 @@
+package com.excp.podroid.engine.usb
+
+import android.hardware.usb.UsbConstants
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertTrue
+import org.junit.Test
+
+class UsbPassthroughFilterTest {
+
+ @Test
+ fun `wifi adapter passes through`() {
+ assertTrue(UsbPassthroughManager.isPassthroughCandidate(0, listOf(UsbConstants.USB_CLASS_VENDOR_SPEC)))
+ }
+
+ @Test
+ fun `mass storage passes through`() {
+ assertTrue(UsbPassthroughManager.isPassthroughCandidate(0, listOf(UsbConstants.USB_CLASS_MASS_STORAGE)))
+ }
+
+ @Test
+ fun `keyboard stays with Android`() {
+ assertFalse(UsbPassthroughManager.isPassthroughCandidate(0, listOf(UsbConstants.USB_CLASS_HID)))
+ }
+
+ @Test
+ fun `composite device with any HID interface stays with Android`() {
+ // A dock exposing keyboard + trackpad alongside audio: passing it through
+ // would take the dock's input away from Android.
+ assertFalse(
+ UsbPassthroughManager.isPassthroughCandidate(
+ 0,
+ listOf(UsbConstants.USB_CLASS_AUDIO, UsbConstants.USB_CLASS_HID, UsbConstants.USB_CLASS_AUDIO),
+ )
+ )
+ }
+
+ @Test
+ fun `device-level HID class stays with Android`() {
+ assertFalse(UsbPassthroughManager.isPassthroughCandidate(UsbConstants.USB_CLASS_HID, emptyList()))
+ }
+}
diff --git a/docs/guide/limitations.html b/docs/guide/limitations.html
index b34aaa3..0bdad18 100644
--- a/docs/guide/limitations.html
+++ b/docs/guide/limitations.html
@@ -95,7 +95,7 @@
<tr>
<td>USB passthrough</td>
<td>QEMU backend only</td>
- <td>Passing a physical USB device into the VM works only on the QEMU backend, which streams the open device handle to the emulator over QMP. The AVF backend has no equivalent channel, so USB passthrough is unavailable there. It is also opt-in and adds a USB controller at boot, so it must be enabled while the VM is stopped.</td>
+ <td>Passing a physical USB device into the VM works only on the QEMU backend, which streams the open device handle to the emulator over QMP. The AVF backend has no equivalent channel, so USB passthrough is unavailable there. It is also opt-in and adds a USB controller at boot, so it must be enabled while the VM is stopped. Input devices (keyboards, mice, trackpads, touchscreens, including the ones built into a dock) are never passed through, so the phone keeps its input.</td>
</tr>
<tr>
<td>Storage</td>