usb_gadget/

lib.rs

//! This library allows implementation of USB peripherals, so called **USB gadgets**,
//! on Linux devices that have a USB device controller (UDC).
//! Both, pre-defined USB functions and fully custom implementations of the USB
//! interface are supported.
//!
//! The following pre-defined USB functions, implemented by kernel drivers, are supported:
//!
//! * [network interface]: CDC ECM, ECM subset, EEM, NCM, RNDIS
//! * [serial port]: CDC ACM, generic
//! * [human interface device (HID)]
//! * [mass-storage device (MSD)]
//! * [printer device]
//! * [musical instrument digital interface (MIDI)]
//! * [audio device]: UAC1 and UAC2
//! * [video device] (UVC)
//!
//! In addition fully [custom USB functions] can be implemented in user-mode Rust code.
//!
//! [network interface]: function::net
//! [serial port]: function::serial
//! [human interface device (HID)]: function::hid
//! [mass-storage device (MSD)]: function::msd
//! [printer device]: function::printer
//! [musical instrument digital interface (MIDI)]: function::midi
//! [audio device]: function::audio
//! [video device]: function::video
//! [custom USB functions]: function::custom
//!
//! Support for OS-specific descriptors and WebUSB is also provided.
//!
//! ### Requirements
//!
//! A USB device controller (UDC) supported by Linux is required.
//!
//! The Linux kernel configuration options `CONFIG_USB_GADGET` and `CONFIG_USB_CONFIGFS`
//! need to be enabled.
//!
//! root permissions are required to configure USB gadgets and
//! the `configfs` filesystem needs to be mounted.
//!
//! Some settings are only supported by newer kernels.
//! Optional settings are only written when set; if left at `None`, the kernel default is used.
//! Setting an option that is unsupported by the running kernel makes registration
//! fail with an error of kind [`ErrorKind::Unsupported`].
//! The exceptions are OS descriptors and WebUSB, which are skipped with a warning.
//!
//! ### Usage
//!
//! Start defining a USB gadget by calling [`Gadget::new`].
//! When the gadget is fully specified, call [`Gadget::bind`] to register it with
//! a [USB device controller (UDC)](Udc).

#![warn(missing_docs)]
#![cfg_attr(docsrs, feature(doc_cfg))]

#[cfg(not(target_os = "linux"))]
compile_error!("usb_gadget only supports Linux");

use proc_mounts::MountIter;
use std::{
    ffi::OsStr,
    fs,
    io::{Error, ErrorKind, Result},
    os::unix::prelude::OsStrExt,
    path::{Path, PathBuf},
    process::Command,
    sync::OnceLock,
};

pub mod function;

mod ioctl;

mod gadget;
pub use gadget::*;

mod udc;
pub use udc::*;

mod lang;
pub use lang::*;

/// USB speed.
#[derive(
    Default, Debug, strum::Display, strum::EnumString, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash,
)]
#[non_exhaustive]
pub enum Speed {
    /// Unknown speed.
    #[default]
    #[strum(serialize = "UNKNOWN")]
    Unknown,
    /// USB 1.0: 1.5 Mbit/s.
    #[strum(serialize = "low-speed")]
    LowSpeed,
    /// USB 1.0: 12 Mbit/s.
    #[strum(serialize = "full-speed")]
    FullSpeed,
    /// USB 2.0: 480 Mbit/s.
    #[strum(serialize = "high-speed")]
    HighSpeed,
    /// USB 3.0: 5 Gbit/s.
    #[strum(serialize = "super-speed")]
    SuperSpeed,
    /// USB 3.1: 10 Gbit/s.
    #[strum(serialize = "super-speed-plus")]
    SuperSpeedPlus,
}

/// 8-bit value to hexadecimal notation.
fn hex_u8(value: u8) -> String {
    format!("0x{:02x}", value)
}

/// 8-bit value to hexadecimal notation without 0x prefix.
fn hex_u8_noprefix(value: u8) -> String {
    format!("{:02x}", value)
}

/// 16-bit value to hexadecimal notation.
fn hex_u16(value: u16) -> String {
    format!("0x{:04x}", value)
}

/// Writes a configfs attribute.
///
/// Fails with [`ErrorKind::Unsupported`] if the attribute does not exist,
/// i.e. it is not supported by the running kernel.
fn write_attr(path: &Path, value: impl AsRef<[u8]>) -> Result<()> {
    fs::write(path, value).map_err(|err| match path.try_exists() {
        Ok(false) => Error::new(
            ErrorKind::Unsupported,
            format!("attribute {} is not supported by the kernel", path.display()),
        ),
        _ => err,
    })
}

/// Returns where configfs is mounted.
fn configfs_dir() -> Result<PathBuf> {
    for mount in MountIter::new()? {
        let Ok(mount) = mount else { continue };
        if mount.fstype == "configfs" {
            return Ok(mount.dest);
        }
    }

    Err(Error::new(ErrorKind::NotFound, "configfs is not mounted"))
}

/// Trims an OsStr.
fn trim_os_str(value: &OsStr) -> &OsStr {
    let mut value = value.as_bytes();

    while value.first() == Some(&b'\n') || value.first() == Some(&b' ') || value.first() == Some(&b'\0') {
        value = &value[1..];
    }

    while value.last() == Some(&b'\n') || value.last() == Some(&b' ') || value.last() == Some(&b'\0') {
        value = &value[..value.len() - 1];
    }

    OsStr::from_bytes(value)
}

/// Request a kernel module to be loaded.
fn request_module(name: impl AsRef<OsStr>) -> Result<()> {
    let mut res = Command::new("modprobe").arg("-q").arg(name.as_ref()).output();

    match res {
        Err(err) if err.kind() == ErrorKind::NotFound => {
            res = Command::new("/sbin/modprobe").arg("-q").arg(name.as_ref()).output();
        }
        _ => (),
    }

    match res {
        Ok(out) if out.status.success() => Ok(()),
        Ok(_) => Err(Error::other("modprobe failed")),
        Err(err) => Err(err),
    }
}

/// Gets the Linux kernel version.
fn linux_version() -> Option<(u16, u16)> {
    static VERSION: OnceLock<Result<(u16, u16)>> = OnceLock::new();
    let version = VERSION.get_or_init(|| {
        let uts = rustix::system::uname();

        let release =
            uts.release().to_str().map_err(|_| Error::new(ErrorKind::InvalidData, "invalid release string"))?;

        let parts: Vec<&str> = release.split('.').collect();
        if parts.len() < 2 {
            return Err(Error::new(ErrorKind::InvalidData, "invalid kernel version"));
        }

        let major = parts[0].parse().map_err(|e| Error::new(ErrorKind::InvalidData, e))?;
        let minor = parts[1].parse().map_err(|e| Error::new(ErrorKind::InvalidData, e))?;

        Ok((major, minor))
    });

    match version {
        Ok(version) => Some(*version),
        Err(err) => {
            log::warn!("failed to obtain Linux version: {err}");
            None
        }
    }
}

#[cfg(test)]
mod test {
    #[test]
    fn linux_version() {
        let (major, minor) = super::linux_version().expect("failed to get Linux version");
        println!("Linux {major}.{minor}");
    }
}