♻️ refactor(device): introduce ProbedDevice enum to distinguish hubs from devices

Add `ProbedDevice` enum with `Device` and `Hub` variants so that callers
of `probe_devices()` can tell apart USB hubs from regular devices without
inspecting descriptors manually.

- Backend: add `ProbedDeviceInfoOp` enum in `ty/mod.rs`, update kmod and
  umod backends to classify devices at probe time
- Public API: expose `ProbedDevice`, `HubDeviceInfo` from `host.rs`
- Tests/examples: use `into_device_info()` to filter out hubs

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: ZR233

test_crates/test_hub/tests/test.rs

@@ -68,8 +68,11 @@ mod tests {
                 sleep(Duration::from_millis(100)).await;
             }
 
-            for info in ls {
-                info!("{info:#x?}");
+            for probed in ls {
+                info!("{probed:#x?}");
+                let Some(info) = probed.into_device_info() else {
+                    continue;
+                };
 
                 let mut interface_desc = None;
                 let mut config_desc: Option<ConfigurationDescriptor> = None;

test_crates/test_hub/tests/test_dwc.rs

@@ -83,8 +83,11 @@ mod tests {
                 sleep(Duration::from_millis(1000)).await;
             }
 
-            for info in ls {
-                info!("{info:#x?}");
+            for probed in ls {
+                info!("{probed:#x?}");
+                let Some(info) = probed.into_device_info() else {
+                    continue;
+                };
 
                 let mut interface_desc = None;
                 let mut config_desc: Option<ConfigurationDescriptor> = None;

test_crates/test_libusb/tests/test.rs

@@ -16,8 +16,11 @@ async fn test() {
 
     let mut info: Option<DeviceInfo> = None;
 
-    for device in ls {
-        println!("{device:?}");
+    'devices: for probed in ls {
+        println!("{probed:?}");
+        let Some(device) = probed.into_device_info() else {
+            continue;
+        };
 
         for iface in device.interface_descriptors().cloned().collect::<Vec<_>>() {
             println!("  Interface: {:?}", iface.class());
@@ -30,7 +33,7 @@ async fn test() {
             if matches!(iface.class(), Class::Video | Class::AudioVideo(_)) {
                 info!("Found video interface: {iface:?}");
                 info = Some(device);
-                break;
+                break 'devices;
             }
         }
     }

test_crates/test_libusb_uvc/src/main.rs

@@ -26,7 +26,10 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
 
     // 查找 UVC 设备
     let mut uvc_device = None;
-    for device_info in devices {
+    for probed in devices {
+        let Some(device_info) = probed.into_device_info() else {
+            continue;
+        };
         info!(
             "Checking device: VID={:04x}, PID={:04x}",
             device_info.vendor_id(),

test_crates/test_xhci_uvc/tests/test.rs

@@ -52,7 +52,10 @@ mod tests {
                 let ls2 = host.probe_devices().await.unwrap();
                 if !ls2.is_empty() {
                     info!("found {} devices", ls2.len());
-                    devices = ls2;
+                    devices = ls2
+                        .into_iter()
+                        .filter_map(|device| device.into_device_info())
+                        .collect();
                     break;
                 }
                 spin_delay(Duration::from_millis(100));

usb-device/hid/keyboard/examples/keyboard.rs

@@ -13,16 +13,19 @@ async fn main() {
 
     let mut info: Option<DeviceInfo> = None;
 
-    for device in ls {
-        println!("{device}");
+    'devices: for probed in ls {
+        println!("{probed}");
+        let Some(device) = probed.into_device_info() else {
+            continue;
+        };
 
         for iface in device.interface_descriptors().cloned().collect::<Vec<_>>() {
             println!("  Interface: {:?}", iface.class());
 
             if KeyBoard::check(&device) {
                 info!("Found video interface: {iface:?}");
                 info = Some(device);
-                break;
+                break 'devices;
             }
         }
     }

usb-host/src/backend/kmod/kcore.rs

@@ -16,7 +16,7 @@ use crate::{
     backend::{
         BackendOp,
         kmod::hub::{Hub, HubDevice, HubInfo, HubOp, PortChangeInfo},
-        ty::{DeviceInfoOp, DeviceOp, EventHandlerOp},
+        ty::{DeviceInfoOp, DeviceOp, EventHandlerOp, ProbedDeviceInfoOp},
     },
 };
 
@@ -62,7 +62,7 @@ impl Core {
         out
     }
 
-    async fn _probe_devices(&mut self) -> Result<(bool, Vec<Box<dyn DeviceInfoOp>>), USBError> {
+    async fn _probe_devices(&mut self) -> Result<(bool, Vec<ProbedDeviceInfoOp>), USBError> {
         let mut is_have_new_hub = false;
         let mut out = Vec::new();
 
@@ -87,6 +87,8 @@ impl Core {
                 if let Some(hub_settings) =
                     HubDevice::is_hub(device.descriptor(), device.configuration_descriptors())
                 {
+                    let desc = device.descriptor().clone();
+                    let configs = device.configuration_descriptors().to_vec();
                     let device_inner: Device = device.into();
 
                     let hub_device = HubDevice::new(
@@ -109,6 +111,10 @@ impl Core {
                     let hub_id = self.hubs.alloc(hub);
                     is_have_new_hub = true;
 
+                    let hub_info = Box::new(DeviceInfo::new(device_id, desc, &configs))
+                        as Box<dyn DeviceInfoOp>;
+                    out.push(ProbedDeviceInfoOp::Hub(hub_info));
+
                     info!("Added new hub with id {:?}", hub_id);
                 } else {
                     let desc = device.descriptor().clone();
@@ -119,7 +125,7 @@ impl Core {
                     let device_info = Box::new(DeviceInfo::new(device_id, desc, &configs))
                         as Box<dyn DeviceInfoOp>;
 
-                    out.push(device_info);
+                    out.push(ProbedDeviceInfoOp::Device(device_info));
                 }
             }
         }
@@ -135,7 +141,7 @@ impl Core {
         hub.backend.changed_ports().await
     }
 
-    async fn probe_devices(&mut self) -> Result<Vec<Box<dyn DeviceInfoOp>>, USBError> {
+    async fn probe_devices(&mut self) -> Result<Vec<ProbedDeviceInfoOp>, USBError> {
         let mut result = Vec::new();
 
         loop {
@@ -164,9 +170,7 @@ impl BackendOp for Core {
         .boxed()
     }
 
-    fn device_list<'a>(
-        &'a mut self,
-    ) -> BoxFuture<'a, Result<Vec<Box<dyn DeviceInfoOp>>, USBError>> {
+    fn device_list<'a>(&'a mut self) -> BoxFuture<'a, Result<Vec<ProbedDeviceInfoOp>, USBError>> {
         self.probe_devices().boxed()
     }
 

usb-host/src/backend/mod.rs

@@ -5,7 +5,7 @@ use alloc::{boxed::Box, vec::Vec};
 use futures::future::{BoxFuture, LocalBoxFuture};
 use usb_if::err::USBError;
 
-use crate::backend::ty::{DeviceInfoOp, DeviceOp};
+use crate::backend::ty::{DeviceInfoOp, DeviceOp, ProbedDeviceInfoOp};
 
 #[cfg(umod)]
 pub mod umod;
@@ -36,8 +36,7 @@ pub(crate) trait BackendOp: Send + Any + 'static {
     fn init<'a>(&'a mut self) -> BoxFuture<'a, Result<(), USBError>>;
 
     /// 探测已连接的设备
-    fn device_list<'a>(&'a mut self)
-    -> BoxFuture<'a, Result<Vec<Box<dyn DeviceInfoOp>>, USBError>>;
+    fn device_list<'a>(&'a mut self) -> BoxFuture<'a, Result<Vec<ProbedDeviceInfoOp>, USBError>>;
 
     fn open_device<'a>(
         &'a mut self,

usb-host/src/backend/ty/mod.rs

@@ -1,3 +1,4 @@
+use alloc::boxed::Box;
 use core::any::Any;
 use core::fmt::Debug;
 
@@ -28,6 +29,11 @@ pub(crate) trait DeviceInfoOp: Send + Sync + Any + Debug + 'static {
     fn configuration_descriptors(&self) -> &[ConfigurationDescriptor];
 }
 
+pub(crate) enum ProbedDeviceInfoOp {
+    Device(Box<dyn DeviceInfoOp>),
+    Hub(Box<dyn DeviceInfoOp>),
+}
+
 /// USB 设备特征（高层抽象）
 pub(crate) trait DeviceOp: Send + Any + 'static {
     fn id(&self) -> usize;

usb-host/src/backend/umod/mod.rs

@@ -3,7 +3,13 @@ use std::{sync::Arc, thread};
 use futures::FutureExt;
 use usb_if::err::USBError;
 
-use crate::{USBHost, backend::BackendOp};
+use crate::{
+    USBHost,
+    backend::{
+        BackendOp,
+        ty::{DeviceInfoOp, ProbedDeviceInfoOp},
+    },
+};
 
 #[macro_use]
 mod err;
@@ -44,13 +50,20 @@ impl Libusb {
         Self { ctx }
     }
 
-    async fn device_list(&mut self) -> Result<Vec<Box<dyn super::ty::DeviceInfoOp>>, USBError> {
+    async fn device_list(&mut self) -> Result<Vec<ProbedDeviceInfoOp>, USBError> {
         let ctx = self.ctx.clone();
         let devices = ctx.device_list()?;
         let mut infos = Vec::new();
         for dev in devices {
             let info = device::DeviceInfo::new(dev)?;
-            infos.push(Box::new(info) as Box<dyn super::ty::DeviceInfoOp>);
+            let is_hub = info.descriptor().class == 0x09;
+            let info = Box::new(info) as Box<dyn super::ty::DeviceInfoOp>;
+            let info = if is_hub {
+                ProbedDeviceInfoOp::Hub(info)
+            } else {
+                ProbedDeviceInfoOp::Device(info)
+            };
+            infos.push(info);
         }
         Ok(infos)
     }
@@ -81,8 +94,7 @@ impl BackendOp for Libusb {
 
     fn device_list<'a>(
         &'a mut self,
-    ) -> futures::future::BoxFuture<'a, Result<Vec<Box<dyn super::ty::DeviceInfoOp>>, USBError>>
-    {
+    ) -> futures::future::BoxFuture<'a, Result<Vec<ProbedDeviceInfoOp>, USBError>> {
         self.device_list().boxed()
     }