docs: full documentation of universal_overlay_handler.rs

Signed-off-by: Artie Poole <stuart.poole@canonical.com>

Author: artiepoole

daemon/src/platforms/universal_components/universal_overlay_handler.rs

@@ -10,49 +10,154 @@
 //
 // You should have received a copy of the GNU General Public License along with this program.  If not, see http://www.gnu.org/licenses/.
 
+//! Universal device tree overlay handler implementation.
+//!
+//! This module provides the [`UniversalOverlayHandler`] struct, which implements the
+//! [`OverlayHandler`] trait for generic device tree overlay management using the Linux
+//! configfs mechanism. It handles overlay application, removal, and status checking
+//! without vendor-specific logic.
+//!
+//! # Configfs Interface
+//!
+//! ## Overlay Directory Structure
+//!
+//! Overlays are managed in `/sys/kernel/config/device-tree/overlays/<handle>/`:
+//! ```text
+//! /sys/kernel/config/device-tree/overlays/my_overlay/
+//! ├── dtbo       # Device tree blob (appears unused in current implementation)
+//! ├── path       # Write overlay source path here to apply; read to verify application
+//! └── status     # Read to check if overlay was applied successfully
+//!```
+//!
+//! # Overlay Application Flow
+//!
+//! 1. Create overlay directory in configfs
+//! 2. Write overlay source path to the `path` file
+//! 3. Verify overlay applied by checking both `path` and `status` files
+//!
+//! # Examples
+//!
+//! ```rust,no_run
+//! use daemon::platforms::universal_components::universal_overlay_handler::UniversalOverlayHandler;
+//! use daemon::platforms::platform::OverlayHandler;
+//! use std::path::Path;
+//!
+//! # fn example() -> Result<(), daemon::error::FpgadError> {
+//! let handler =  platform_for_known_platform("universal").overlay_handler("my_overlay")?;
+//!
+//! // Apply overlay
+//! handler.apply_overlay(Path::new("/lib/firmware/design.dtbo"))?;
+//!
+//! // Check status
+//! let status = handler.status()?;
+//! println!("Overlay status: {}", status);
+//!
+//! // Remove overlay
+//! handler.remove_overlay()?;
+//! # Ok(())
+//! # }
+//! ```
+
 use crate::config;
 use crate::error::FpgadError;
 use crate::platforms::platform::OverlayHandler;
 use crate::system_io::{fs_create_dir, fs_read, fs_remove_dir, fs_write};
 use log::{info, trace};
 use std::path::{Path, PathBuf};
 
-/// Takes a handle and creates and stores an appropriate overlay_fs_path in this object.
-/// The overlay_fs_path is static apart from the handle associated with each
-/// device, overlay or bitstream, and so the handle is specified by the user here and the rest
-/// is fixed.
+/// Construct the configfs path for an overlay directory.
+///
+/// Creates the full path to an overlay's configfs directory by combining the
+/// base overlay control directory with the provided handle.
+/// See [config::OVERLAY_CONTROL_DIR] for information about the base path.
+///
+/// # Arguments
+///
+/// * `overlay_handle` - The overlay handle (directory name)
+///
+/// # Returns: `PathBuf`
+/// * Full path to overlay directory in configfs
+///
+/// # Examples
+///
+/// ```rust,no_run
+/// # use std::path::PathBuf;
+/// # fn construct_overlay_fs_path(overlay_handle: &str) -> PathBuf {
+/// #     PathBuf::from("/sys/kernel/config/device-tree/overlays").join(overlay_handle)
+/// # }
+/// let path = construct_overlay_fs_path("my_overlay");
+/// assert!(path.to_string_lossy().contains("my_overlay"));
+/// ```
 fn construct_overlay_fs_path(overlay_handle: &str) -> PathBuf {
     let overlay_fs_path = PathBuf::from(config::OVERLAY_CONTROL_DIR).join(overlay_handle);
     trace!("overlay_fs_path will be {overlay_fs_path:?}");
     overlay_fs_path
 }
 
-/// Stores the three relevant paths: source files for dtbo/bitstream and the overlayfs dir to which
-/// the dtbo path was written.
+/// Universal device tree overlay handler using Linux configfs.
+///
+/// This struct manages a single device tree overlay through the Linux configfs
+/// mechanism. It stores the overlay's configfs directory path and provides methods
+/// to apply, remove, and check the status of the overlay.
+///
+/// # Fields
+///
+/// * `overlay_fs_path` - Path to the overlay's directory in configfs
+///   (e.g., `/sys/kernel/config/device-tree/overlays/my_overlay`)
+///
+/// see [config::OVERLAY_CONTROL_DIR] for the base overlay control directory.
 #[derive(Debug)]
 pub struct UniversalOverlayHandler {
     /// The path which points to the overlay virtual filesystem's dir which contains
     /// `path`, `status` and `dtbo` virtual files for overlay control. `dtbo` appears unused?
     overlay_fs_path: PathBuf,
 }
 
+/// Implementation of helper methods for UniversalOverlayHandler.
 impl UniversalOverlayHandler {
+    /// Read the overlay status from the configfs `status` file.
+    ///
+    /// Reads from the `<overlay_fs_path>/status` file and returns
+    /// the status string with trailing newlines removed.
+    ///
+    /// # Returns: `Result<String, FpgadError>`
+    /// * `Ok(String)` - Status string (typically "applied" or empty)
+    /// * `Err(FpgadError::IORead)` - Failed to read status file
     fn get_vfs_status(&self) -> Result<String, FpgadError> {
         let status_path = self.overlay_fs_path()?.join("status");
         trace!("Reading from {status_path:?}");
         fs_read(&status_path).map(|s| s.trim_end_matches('\n').to_string())
     }
-    /// Read path from <overlay_fs_path>/path file and verify that what was meant to be applied
-    /// was applied.
+
+    /// Read the overlay path from the configfs `path` file.
+    ///
+    /// Reads from the  `<overlay_fs_path>/path` file which contains
+    /// the device tree path where the overlay was applied.
+    ///
+    /// # Returns: `Result<PathBuf, FpgadError>`
+    /// * `Ok(PathBuf)` - Device tree path from the path file
+    /// * `Err(FpgadError::IORead)` - Failed to read path file
     fn get_vfs_path(&self) -> Result<PathBuf, FpgadError> {
         let path_path = self.overlay_fs_path()?.join("path");
         trace!("Reading from {path_path:?}");
         let path_string = fs_read(&path_path).map(|s| s.trim_end_matches('\n').to_string())?;
         Ok(PathBuf::from(path_string))
     }
 
-    /// When an overlay fails to be applied, it may show as "applied" status but the path will
-    /// be empty. Therefore, this checks both match what is expected.
+    /// Verify that an overlay was successfully applied.
+    ///
+    /// Checks both the `path` and `status` files within  `overlay_fs_path` to ensure that
+    /// the overlay was correctly applied. Sometimes an overlay may show "applied" status
+    /// but have an empty path, indicating a failure.
+    ///
+    /// # Arguments
+    ///
+    /// * `source_path_rel` - The source path that was written to apply the overlay
+    ///
+    /// # Returns: `Result<(), FpgadError>`
+    /// * `Ok(())` - Overlay successfully applied (path matches and status is "applied")
+    /// * `Err(FpgadError::OverlayStatus)` - Path doesn't match or status not "applied"
+    /// * `Err(FpgadError::IORead)` - Failed to read path or status file
     fn vfs_check_applied(&self, source_path_rel: &Path) -> Result<(), FpgadError> {
         let path_file_contents = &self.get_vfs_path()?;
         if path_file_contents.ends_with(source_path_rel) {
@@ -79,11 +184,32 @@ impl UniversalOverlayHandler {
     }
 }
 
+/// Implementation of the OverlayHandler trait for UniversalOverlayHandler.
 impl OverlayHandler for UniversalOverlayHandler {
-    /// Attempts to apply a device tree overlay which should trigger a firmware load.
-    /// There are multiple ways to trigger a firmware load so this is not valid if the
-    /// dtbo doesn't contain a firmware to load.
-    /// Calls prepare_for_load to ensure paths are valid etc. beforehand.
+    /// Apply a device tree overlay through configfs.
+    ///
+    /// Creates the overlay directory in configfs, writes the overlay source path to the
+    /// `path` file, and verifies successful application. This may trigger automatic
+    /// firmware loading if the overlay specifies a bitstream.
+    ///
+    /// # Arguments
+    ///
+    /// * `source_path_rel` - Path to the overlay file (can be absolute or relative to firmware path)
+    ///
+    /// # Returns: `Result<(), FpgadError>`
+    /// * `Ok(())` - Overlay applied and verified successfully
+    /// * `Err(FpgadError::Argument)` - Overlay with this handle already exists
+    /// * `Err(FpgadError::IOCreate)` - Failed to create overlay directory
+    /// * `Err(FpgadError::Internal)` - configfs didn't create `path` file (not mounted?)
+    /// * `Err(FpgadError::IOWrite)` - Failed to write overlay path
+    /// * `Err(FpgadError::OverlayStatus)` - Overlay didn't apply correctly
+    ///
+    /// # Notes
+    ///
+    /// - There are multiple ways device tree overlays can trigger firmware loading
+    /// - This method is not valid if the dtbo doesn't contain firmware to load
+    /// - The overlay directory must not already exist. [`OverlayHandler::remove_overlay`] can be called
+    ///   to remove it first.
     fn apply_overlay(&self, source_path_rel: &Path) -> Result<(), FpgadError> {
         let overlay_fs_path = self.overlay_fs_path()?;
         if overlay_fs_path.exists() {
@@ -115,20 +241,42 @@ impl OverlayHandler for UniversalOverlayHandler {
         self.vfs_check_applied(source_path_rel)
     }
 
-    /// Attempts to delete overlay_fs_path
+    /// Remove a device tree overlay from configfs.
+    ///
+    /// Removes the overlay directory from configfs, which deactivates the overlay and
+    /// restores the original device tree state.
+    ///
+    /// # Returns: `Result<(), FpgadError>`
+    /// * `Ok(())` - Overlay directory removed successfully
+    /// * `Err(FpgadError::IODelete)` - Failed to remove directory (not empty, doesn't exist, etc.)
     fn remove_overlay(&self) -> Result<(), FpgadError> {
         let overlay_fs_path = self.overlay_fs_path()?;
         fs_remove_dir(overlay_fs_path)
     }
 
-    /// WARNING NOT IMPLEMENTED:
-    /// This is where the required fpga flags will be determined from the dtbo,
-    /// such as compressed or encrypted.
+    /// Get the required FPGA programming flags from the overlay.
+    ///
+    /// # Warning: Not Implemented
+    ///
+    /// This method is intentionally unimplemented for the universal overlay handler.
+    /// In a platform specific implementation (i.e. a softener) this would implement
+    /// logic to parse the overlay/relevant package and determine any required FPGA
+    /// programming flags.
+    ///
+    /// # Returns: `Result<isize, FpgadError>`
+    /// * `Ok(0)` - Always returns 0 (no flags)
     fn required_flags(&self) -> Result<isize, FpgadError> {
         Ok(0)
     }
 
-    /// Read status from <overlay_fs_path>/status file and verify that it is "applied"
+    /// Get the current status of the overlay.
+    ///
+    /// Reads both the `path` and `status` files from configfs and returns a combined
+    /// status string. If the overlay directory doesn't exist, returns "not present".
+    ///
+    /// # Returns: `Result<String, FpgadError>`
+    /// * `Ok(String)` - Status string (e.g., "/path/in/tree applied" or "not present")
+    /// * `Err(FpgadError::IORead)` - Failed to read status or path file
     fn status(&self) -> Result<String, FpgadError> {
         if !self.overlay_fs_path()?.exists() {
             return Ok("not present".into());
@@ -138,14 +286,37 @@ impl OverlayHandler for UniversalOverlayHandler {
         Ok(format!("{path:?} {status}"))
     }
 
-    /// Checks that the overlay_fs_path is stored at time of call and returns it if so (unwraps Option into Result)
+    /// Get the filesystem path to the overlay directory.
+    ///
+    /// Returns the stored overlay configfs path.
+    ///
+    /// # Returns: `Result<&Path, FpgadError>`
+    /// * `Ok(&Path)` - Path to overlay directory in configfs
     fn overlay_fs_path(&self) -> Result<&Path, FpgadError> {
         Ok(self.overlay_fs_path.as_path())
     }
 }
 
 impl UniversalOverlayHandler {
-    /// Scans the package dir for required files
+    /// Create a new UniversalOverlayHandler for the specified overlay.
+    ///
+    /// Constructs the configfs path for the overlay but doesn't create the directory
+    /// or validate its existence. Directory creation happens in [`apply_overlay`](OverlayHandler::apply_overlay).
+    ///
+    /// # Arguments
+    ///
+    /// * `overlay_handle` - The overlay handle (directory name in configfs)
+    ///
+    /// # Returns: `Self`
+    /// * New UniversalOverlayHandler instance
+    ///
+    /// # Examples
+    ///
+    /// ```rust,no_run
+    /// # use daemon::platforms::platform::platform_for_known_platform;
+    ///
+    /// let handler = platform_for_known_platform("universal").overlay_handler("my_overlay")?;
+    /// ```
     pub(crate) fn new(overlay_handle: &str) -> Self {
         UniversalOverlayHandler {
             overlay_fs_path: construct_overlay_fs_path(overlay_handle),