blob: 8b7341871fca918ae60139043365fe79d967b22f [file]
// Copyright 2023 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
use futures::stream::Stream;
use thiserror::Error;
#[cfg_attr(target_os = "linux", path = "usb_linux/mod.rs")]
mod usb_plat;
pub mod bulk_interface;
pub use usb_plat::{
BulkInEndpoint, BulkOutEndpoint, ControlEndpoint, Interface, InterruptEndpoint,
IsochronousEndpoint,
};
/// Controls whether a zero-length packet (ZLP) is sent to terminate an OUT transfer
/// that ends on a packet boundary.
#[derive(Copy, Clone, PartialEq, Eq, Debug)]
pub enum ZeroPacket {
/// Send a zero-length packet if the transfer length is an exact multiple of the endpoint max packet size.
Send,
/// Do not send a zero-length packet.
DoNotSend,
}
/// Selects the bit in USB endpoint addresses that tells us whether it is an in or and out endpoint.
pub(crate) const USB_ENDPOINT_DIR_MASK: u8 = 0x80;
pub struct DeviceHandle(usb_plat::DeviceHandleInner);
impl From<usb_plat::DeviceHandleInner> for DeviceHandle {
fn from(inner: usb_plat::DeviceHandleInner) -> DeviceHandle {
DeviceHandle(inner)
}
}
#[cfg(target_os = "linux")]
impl DeviceHandle {
pub fn from_path(path: impl AsRef<std::path::Path>) -> Self {
DeviceHandle(usb_plat::DeviceHandleInner::new(path.as_ref().to_string_lossy().into_owned()))
}
/// Resolves a USB [`DeviceHandle`] directly from a known sysfs device directory and serial number.
pub fn from_sysfs_path(sysfs_path: std::path::PathBuf, serial: String) -> Result<Option<Self>> {
usb_plat::device_from_sysfs_path(sysfs_path, serial)
}
}
impl DeviceHandle {
/// A printable name for this device.
pub fn debug_name(&self) -> String {
self.0.debug_name()
}
/// The serial number for the device (if any)
pub fn serial(&self) -> Option<String> {
self.0.serial()
}
/// Returns the sysfs path for this device if available on the platform.
pub fn sysfs_path(&self) -> Option<std::path::PathBuf> {
self.0.sysfs_path()
}
/// Returns the negotiated USB connection speed for this device, if available from sysfs.
pub fn speed(&self) -> Option<UsbSpeed> {
self.0.speed()
}
}
/// Negotiated USB connection speed.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum UsbSpeed {
/// Low speed (1.5 Mbps, USB 1.0)
Low,
/// Full speed (12 Mbps, USB 1.1)
Full,
/// High speed (480 Mbps, USB 2.0)
High,
/// SuperSpeed (5 Gbps, USB 3.0)
Super,
/// SuperSpeed+ (10 Gbps, USB 3.1)
SuperPlus,
/// SuperSpeed+ Gen 2x2 (20 Gbps, USB 3.2)
SuperPlusBy2,
/// Other or unknown speed
Other(String),
}
impl UsbSpeed {
pub fn from_sysfs_str(s: &str) -> Self {
match s {
"1.5" => Self::Low,
"12" => Self::Full,
"480" => Self::High,
"5000" => Self::Super,
"10000" => Self::SuperPlus,
"20000" => Self::SuperPlusBy2,
other => Self::Other(other.to_string()),
}
}
/// Theoretical maximum bus bandwidth in megabytes per second (MB/s).
pub fn theoretical_max_mbps(&self) -> u32 {
match self {
Self::Low => 0,
Self::Full => 1,
Self::High => 60,
Self::Super => 625,
Self::SuperPlus => 1250,
Self::SuperPlusBy2 => 2500,
Self::Other(_) => 0,
}
}
/// Returns true if this connection speed is at least SuperSpeed (USB 3.0, >= 5 Gbps).
pub fn is_superspeed(&self) -> bool {
matches!(self, Self::Super | Self::SuperPlus | Self::SuperPlusBy2)
}
}
impl std::fmt::Display for UsbSpeed {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
Self::Low => write!(f, "LowSpeed (1.5 Mbps)"),
Self::Full => write!(f, "FullSpeed (12 Mbps)"),
Self::High => write!(f, "HighSpeed (480 Mbps, USB 2.0)"),
Self::Super => write!(f, "SuperSpeed (5 Gbps, USB 3.0)"),
Self::SuperPlus => write!(f, "SuperSpeed+ (10 Gbps, USB 3.1)"),
Self::SuperPlusBy2 => write!(f, "SuperSpeed+ (20 Gbps, USB 3.2)"),
Self::Other(s) => write!(f, "{} Mbps", s),
}
}
}
impl DeviceHandle {
/// Given a path to a USB device, scan each interface available on the device. Each interface's
/// descriptor is passed to the given callback, and the first descriptor for which the callback
/// returns `true` will be opened and returned.
pub fn scan_interfaces(
&self,
urb_pool_size: usize,
f: impl Fn(&DeviceDescriptor, &InterfaceDescriptor) -> bool,
) -> Result<Interface> {
self.0.scan_interfaces(urb_pool_size, f)
}
}
impl std::fmt::Debug for DeviceHandle {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> Result<(), std::fmt::Error> {
f.debug_tuple("DeviceHandle").field(&self.debug_name()).field(&self.serial()).finish()
}
}
/// Device discovery events. See `wait_for_devices`.
#[derive(Debug)]
pub enum DeviceEvent {
/// Indicates a new USB device has been plugged in.
Added(DeviceHandle),
/// Indicates a USB device has been unplugged.
Removed(DeviceHandle),
}
/// Errors emitted by USB operations.
#[derive(Error, Debug)]
pub enum Error {
#[error("Could not write all data (had {0} wrote {1})")]
ShortWrite(usize, usize),
#[error("Buffer of size {0} too large for USB API")]
BufferTooBig(usize),
#[error("Malformed descriptor table")]
MalformedDescriptor,
#[error("Could not find appropriate interface")]
InterfaceNotFound,
#[error("IO Error: {0:?}")]
IOError(#[from] std::io::Error),
#[error("Discovered device with malformed name: {0}")]
BadDeviceName(String),
#[error("Error watching device folder: {0:?}")]
NotifyError(#[from] notify::Error),
}
/// Descriptive information about a USB device.
#[derive(Copy, Clone, PartialEq, Eq, Debug)]
pub struct DeviceDescriptor {
pub vendor: u16,
pub product: u16,
pub class: u8,
pub subclass: u8,
pub protocol: u8,
}
/// Type of an endpoint on a USB interface.
#[derive(Copy, Clone, PartialEq, Eq, Debug)]
pub enum EndpointType {
Control,
Interrupt,
Isochronous,
Bulk,
}
/// Direction an Endpoint flows on a USB interface.
#[derive(Copy, Clone, PartialEq, Eq, Debug)]
pub enum EndpointDirection {
In,
Out,
}
#[derive(Clone, PartialEq, Eq, Debug)]
pub struct InterfaceDescriptor {
pub id: u8,
pub class: u8,
pub subclass: u8,
pub protocol: u8,
pub alternate: u8,
pub endpoints: Vec<EndpointDescriptor>,
}
#[derive(Copy, Clone, PartialEq, Eq, Debug)]
pub struct EndpointDescriptor {
pub ty: EndpointType,
pub address: u8,
}
impl EndpointDescriptor {
pub fn direction(&self) -> EndpointDirection {
if (self.address & USB_ENDPOINT_DIR_MASK) != 0 {
EndpointDirection::In
} else {
EndpointDirection::Out
}
}
}
/// A USB endpoint. Wraps the four types of endpoint for easy carry.
pub enum Endpoint {
BulkIn(BulkInEndpoint),
BulkOut(BulkOutEndpoint),
Isochronous(IsochronousEndpoint),
Interrupt(InterruptEndpoint),
Control(ControlEndpoint),
}
/// Waits for USB devices to appear on the bus.
pub fn wait_for_devices(
notify_added: bool,
notify_removed: bool,
) -> Result<impl Stream<Item = Result<DeviceEvent>>> {
usb_plat::wait_for_devices(notify_added, notify_removed)
}
/// Lists all USB devices currently on the bus.
pub fn enumerate_devices() -> Result<Vec<DeviceHandle>> {
usb_plat::enumerate_devices()
}
/// Directly finds the USB DeviceHandle for a specific serial number by querying sysfs.
pub fn find_device_by_serial(serial: &str) -> Result<Option<DeviceHandle>> {
usb_plat::find_device_by_serial(serial)
}
pub type Result<T, E = Error> = std::result::Result<T, E>;