cadmus_core/device/usb/
manager.rs

1//! USB Manager trait definition.
2
3use crate::device::usb::error::UsbError;
4
5/// Trait for USB mass storage gadget management.
6///
7/// This trait abstracts over platform-specific implementations that enable
8/// USB mass storage mode for exposing device storage to a host computer.
9///
10/// # Lifecycle
11///
12/// 1. Call [`enable`](UsbManager::enable) when the user connects to a host
13///    and wants to share storage.
14/// 2. The implementation unmounts the onboard partition, configures the USB
15///    gadget, and exposes the storage to the host.
16/// 3. Call [`disable`](UsbManager::disable) when the user disconnects.
17/// 4. The implementation disables the gadget, runs filesystem checks, and
18///    remounts the partition.
19///
20/// # Example
21///
22/// ```ignore
23/// use cadmus_core::device::usb::{UsbManager, UsbError};
24///
25/// # fn example(usb_manager: &dyn UsbManager) -> Result<(), UsbError> {
26/// // Enable USB sharing
27/// usb_manager.enable()?;
28///
29/// // ... device is now in USB mass storage mode ...
30///
31/// // Disable USB sharing
32/// usb_manager.disable()?;
33/// # Ok(())
34/// # }
35/// ```
36pub trait UsbManager: Send + Sync {
37    /// Enables USB mass storage mode.
38    ///
39    /// This method performs the following operations:
40    ///
41    /// 1. Syncs filesystem buffers and drops caches
42    /// 2. Unmounts `/mnt/onboard` (and `/mnt/sd` if present)
43    /// 3. Configures and enables the USB mass storage gadget
44    ///
45    /// After this call returns successfully, the Kobo's internal storage is
46    /// accessible to the connected USB host.
47    ///
48    /// # Errors
49    ///
50    /// Returns [`UsbError`] if any step fails:
51    /// - [`UsbError::Partition`] if unmounting fails
52    /// - [`UsbError::GadgetConfig`] if USB gadget configuration fails
53    /// - [`UsbError::KernelModule`] if module loading fails
54    ///
55    /// # Example
56    ///
57    /// ```ignore
58    /// use cadmus_core::device::usb::UsbManager;
59    ///
60    /// # fn example(usb_manager: &dyn UsbManager) -> Result<(), cadmus_core::device::usb::UsbError> {
61    /// usb_manager.enable()?;
62    /// # Ok(())
63    /// # }
64    /// ```
65    fn enable(&self) -> Result<(), UsbError>;
66
67    /// Disables USB mass storage mode.
68    ///
69    /// This method performs the following operations:
70    ///
71    /// 1. Disables the USB gadget
72    /// 2. Tears down the USB gadget configuration
73    /// 3. Runs filesystem checks with `dosfsck`
74    /// 4. Remounts `/mnt/onboard` (and `/mnt/sd` if present)
75    ///
76    /// If filesystem corruption is detected and cannot be repaired, this
77    /// method may trigger a reboot by returning an error.
78    ///
79    /// # Errors
80    ///
81    /// Returns [`UsbError`] if any step fails:
82    /// - [`UsbError::KernelModule`] if module unloading fails
83    /// - [`UsbError::Filesystem`] if filesystem check/repair fails
84    /// - [`UsbError::Partition`] if remounting fails
85    ///
86    /// # Example
87    ///
88    /// ```ignore
89    /// use cadmus_core::device::usb::UsbManager;
90    ///
91    /// # fn example(usb_manager: &dyn UsbManager) -> Result<(), cadmus_core::device::usb::UsbError> {
92    /// usb_manager.disable()?;
93    /// # Ok(())
94    /// # }
95    /// ```
96    fn disable(&self) -> Result<(), UsbError>;
97}
cadmus_core/device/usb/manager.rs

cadmus_core/device/usb/
manager.rs
