docs: fill in missing gaps for dfx-mgr changes

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

Author: artiepoole

daemon/src/platforms/platform.rs

@@ -266,8 +266,39 @@ pub trait Platform: Any {
     /// * `Err(FpgadError::Argument)` - Invalid overlay handle or configfs not available
     fn overlay_handler(&self, overlay_handle: &str) -> Result<&dyn OverlayHandler, FpgadError>;
 
+    /// Get a formatted status message for this platform.
+    ///
+    /// Returns a human-readable status message containing information about devices,
+    /// overlays, and platform-specific state. The format and content are platform-specific.
+    ///
+    /// # Returns: `Result<String, FpgadError>`
+    /// * `Ok(String)` - Formatted status message
+    /// * `Err(FpgadError)` - Failed to gather status information
+    ///
+    /// # Examples
+    ///
+    /// For the Universal platform, this returns a table of devices and overlays.
+    /// For Xilinx DFX Manager, this returns the output of `dfx-mgr-client -listPackage`.
     fn status_message(&self) -> Result<String, FpgadError>;
 
+    /// Get the platform compatibility string.
+    ///
+    /// Returns the compatibility string that this platform implementation is registered
+    /// with. This string matches against device tree compatible properties to determine
+    /// which platform to use for a device.
+    ///
+    /// # Returns: `String`
+    /// * The platform compatibility string (e.g., "universal", "xlnx,zynqmp-pcap-fpga")
+    ///
+    /// # Examples
+    ///
+    /// ```rust,no_run
+    /// # use daemon::platforms::platform::Platform;
+    /// # fn example(platform: &dyn Platform) {
+    /// let compat = platform.platform_compat_string();
+    /// println!("Platform: {}", compat);
+    /// # }
+    /// ```
     fn platform_compat_string(&self) -> String;
 }
 

daemon/src/softeners/xilinx_dfx_mgr.rs

@@ -10,6 +10,51 @@
 //
 // You should have received a copy of the GNU General Public License along with this program.  If not, see http://www.gnu.org/licenses/.
 
+//! Xilinx DFX Manager platform implementation.
+//!
+//! This module provides the Xilinx DFX Manager (dfx-mgr) platform, which is a vendor-specific
+//! "softener" implementation for managing Xilinx FPGA devices. It wraps the Xilinx dfx-mgr-client
+//! command-line tool to provide enhanced functionality for Xilinx devices including:
+//! - Dynamic function exchange (DFX) / partial reconfiguration
+//! - Accelerator package management
+//! - Multi-slot FPGA management
+//! - UIO (User I/O) interface management
+//! - Inter-region buffer management
+//!
+//! # Platform Support
+//!
+//! This platform registers itself for Xilinx device compatibility strings:
+//! - `xlnx,zynqmp-pcap-fpga` - Zynq UltraScale+ MPSoC
+//! - `versal-fpga` - Versal ACAP devices
+//! - `zynq-devcfg-1.0` - Zynq-7000 devices
+//!
+//! # DFX Manager Integration
+//!
+//! The platform communicates with the dfx-mgrd daemon (started via snap daemon wrapper)
+//! through the dfx-mgr-client CLI tool. The dfx-mgr-client binary must be available at
+//! `$SNAP/usr/bin/dfx-mgr-client`.
+//!
+//! # Architecture
+//!
+//! The platform uses lazy initialization via `OnceLock` to create component instances:
+//! - [`XilinxDfxMgrFPGA`] - Manages FPGA device operations via dfx-mgr
+//! - [`XilinxDfxMgrOverlayHandler`] - Manages overlay operations with bitstream coordination
+//!
+//! # Feature Flag
+//!
+//! This module is only compiled when the `xilinx-dfx-mgr` feature is enabled.
+//!
+//! # Examples
+//!
+//! ```rust,no_run
+//! # use daemon::platforms::platform::platform_for_known_platform;
+//! # fn example() -> Result<(), daemon::error::FpgadError> {
+//! let platform = platform_for_known_platform("xlnx,zynqmp-pcap-fpga")?;
+//! let fpga = platform.fpga("fpga0")?;
+//! # Ok(())
+//! # }
+//! ```
+
 use std::env;
 use std::path::Path;
 use std::sync::OnceLock;
@@ -22,6 +67,25 @@ use crate::softeners::xilinx_dfx_mgr_overlay_handler::XilinxDfxMgrOverlayHandler
 use fpgad_macros::platform;
 use log::trace;
 
+/// Xilinx DFX Manager platform implementation for managing Xilinx FPGA devices.
+///
+/// This struct provides the platform implementation for Xilinx devices using the
+/// dfx-mgr backend. It uses lazy initialization to create FPGA and overlay handler
+/// instances on first access.
+///
+/// The `#[platform]` macro automatically registers this platform with the Xilinx-specific
+/// compatibility strings, making it available for matching against Xilinx device tree
+/// compatible properties.
+///
+/// # Fields
+///
+/// * `fpga` - Lazily initialized Xilinx FPGA device instance
+/// * `overlay_handler` - Lazily initialized Xilinx overlay handler instance
+///
+/// # Thread Safety
+///
+/// This struct is thread-safe thanks to `OnceLock`, which ensures that initialization
+/// happens exactly once even with concurrent access.
 #[platform(compat_string = "xlnx,zynqmp-pcap-fpga,versal-fpga,zynq-devcfg-1.0")]
 pub struct XilinxDfxMgrPlatform {
     fpga: OnceLock<XilinxDfxMgrFPGA>,
@@ -35,6 +99,22 @@ impl Default for XilinxDfxMgrPlatform {
 }
 
 impl XilinxDfxMgrPlatform {
+    /// Create a new Xilinx DFX Manager platform instance.
+    ///
+    /// Creates an empty platform with uninitialized FPGA and overlay handler instances.
+    /// The actual components will be lazily initialized on first access through the
+    /// [`Platform`] trait methods.
+    ///
+    /// # Returns: `Self`
+    /// * New XilinxDfxMgrPlatform instance ready for use
+    ///
+    /// # Examples
+    ///
+    /// ```rust,no_run
+    /// use daemon::softeners::xilinx_dfx_mgr::XilinxDfxMgrPlatform;
+    ///
+    /// let platform = XilinxDfxMgrPlatform::new();
+    /// ```
     pub fn new() -> Self {
         trace!("creating new XilinxDfxMgrPlatform");
         XilinxDfxMgrPlatform {

daemon/src/softeners/xilinx_dfx_mgr_fpga.rs

@@ -10,6 +10,33 @@
 //
 // You should have received a copy of the GNU General Public License along with this program.  If not, see http://www.gnu.org/licenses/.
 
+//! Xilinx DFX Manager FPGA device implementation.
+//!
+//! This module provides the [`XilinxDfxMgrFPGA`] struct, which implements the [`Fpga`] trait
+//! for Xilinx FPGA devices using the dfx-mgr backend. It provides a hybrid approach that:
+//! - Uses standard sysfs for reading flags
+//! - Uses dfx-mgr-client for bitstream loading and package management
+//! - Supports dfx-mgr's slot-based management
+//!
+//! # Key Differences from Universal Platform
+//!
+//! - **State Query**: Returns dfx-mgr package listing instead of simple sysfs state
+//! - **Bitstream Loading**: Uses `dfx-mgr-client -b` instead of direct firmware loading due to snap confinement
+//!   limitations (temporary?)
+//! - **Firmware Removal**: Supports slot-based removal via `dfx-mgr-client -remove`
+//!
+//! # Examples
+//!
+//! ```rust,no_run
+//! # use daemon::platforms::platform::platform_for_known_platform;
+//! # fn example() -> Result<(), daemon::error::FpgadError> {
+//! let platform = platform_for_known_platform("xlnx,zynqmp-pcap-fpga")?;
+//! let fpga = platform.fpga("fpga0")?;
+//! let state = fpga.state()?;  // Returns dfx-mgr package listing
+//! # Ok(())
+//! # }
+//! ```
+
 use crate::config;
 use crate::error::FpgadError;
 use crate::platforms::platform::Fpga;
@@ -18,11 +45,46 @@ use crate::system_io::{fs_read, fs_write};
 use log::{error, trace};
 use std::path::Path;
 
+/// Xilinx DFX Manager FPGA device implementation.
+///
+/// This struct represents a Xilinx FPGA device and provides methods to interact
+/// with it through the dfx-mgr backend. It stores only the device handle and
+/// uses dfx-mgr-client for most operations.
+///
+/// # Fields
+///
+/// * `device_handle` - The device identifier (e.g., "fpga0") used to locate the device in sysfs.
+///   Only used for sysfs backed functions e.g. flags
+///
+/// # Implementation Notes
+///
+/// While this implementation uses the dfx-mgr backend, it still reads flags directly
+/// from sysfs for consistency with the standard FPGA subsystem interface.
 pub struct XilinxDfxMgrFPGA {
     device_handle: String,
 }
 
 impl XilinxDfxMgrFPGA {
+    /// Create a new XilinxDfxMgrFPGA instance for the specified device.
+    ///
+    /// This constructor simply stores the device handle. It does not verify that
+    /// the device exists or that dfx-mgrd is running - validation occurs when
+    /// methods are called.
+    ///
+    /// # Arguments
+    ///
+    /// * `device_handle` - The device handle (e.g., "fpga0")
+    ///
+    /// # Returns: `Self`
+    /// * New XilinxDfxMgrFPGA instance
+    ///
+    /// # Examples
+    ///
+    /// ```rust,no_run
+    /// use daemon::softeners::xilinx_dfx_mgr_fpga::XilinxDfxMgrFPGA;
+    ///
+    /// let fpga = XilinxDfxMgrFPGA::new("fpga0");
+    /// ```
     pub(crate) fn new(device_handle: &str) -> Self {
         XilinxDfxMgrFPGA {
             device_handle: device_handle.to_owned(),

daemon/src/softeners/xilinx_dfx_mgr_helpers.rs

@@ -10,6 +10,33 @@
 //
 // You should have received a copy of the GNU General Public License along with this program.  If not, see http://www.gnu.org/licenses/.
 
+//! Helper functions for Xilinx DFX Manager operations.
+//!
+//! This module provides utility functions for working with Xilinx device tree overlay
+//! files and extracting information needed for dfx-mgr operations.
+//!
+//! # Key Functions
+//!
+//! - [`extract_firmware_name`] - Parses .dtbo files to extract the firmware-name property
+//!
+//! # Device Tree Parsing
+//!
+//! The module uses the `fdt` crate to parse flattened device tree binary (.dtbo) files
+//! and extract properties. This is essential for coordinating bitstream and overlay loading
+//! in the Xilinx dfx-mgr workflow.
+//!
+//! # Examples
+//!
+//! ```rust,no_run
+//! # use std::path::Path;
+//! # use daemon::softeners::xilinx_dfx_mgr_helpers::extract_firmware_name;
+//! # fn example() -> Result<(), daemon::error::FpgadError> {
+//! let firmware = extract_firmware_name(Path::new("/lib/firmware/design.dtbo"))?;
+//! println!("Bitstream file: {}", firmware);
+//! # Ok(())
+//! # }
+//! ```
+
 use crate::error::FpgadError;
 use crate::softeners::error::FpgadSoftenerError;
 use log::trace;

daemon/src/softeners/xilinx_dfx_mgr_overlay_handler.rs

@@ -10,6 +10,38 @@
 //
 // You should have received a copy of the GNU General Public License along with this program.  If not, see http://www.gnu.org/licenses/.
 
+//! Xilinx DFX Manager overlay handler implementation.
+//!
+//! This module provides the [`XilinxDfxMgrOverlayHandler`] struct, which implements the
+//! [`OverlayHandler`] trait for managing device tree overlays on Xilinx FPGA devices
+//! using the dfx-mgr backend.
+//!
+//! # Key Features
+//!
+//! - **Slot-based Management**: Uses dfx-mgr's slot system for overlay tracking and removal
+//!
+//! # Overlay Loading Process
+//!
+//! 1. Parse the .dtbo file to extract the `firmware-name` property
+//! 2. Locate the bitstream file in the same directory as the .dtbo
+//! 3. Call `dfx-mgr-client -o <dtbo_path> -b <bitstream_path>` to load both
+//!
+//! This ensures the bitstream and overlay are applied together, which is required
+//! as a temporary workaround while `-load` is not supported due to snap confinement limitations
+//!
+//! # Examples
+//!
+//! ```rust,no_run
+//! # use daemon::platforms::platform::platform_for_known_platform;
+//! # use std::path::Path;
+//! # fn example() -> Result<(), daemon::error::FpgadError> {
+//! let platform = platform_for_known_platform("xlnx,zynqmp-pcap-fpga")?;
+//! let handler = platform.overlay_handler("my_overlay")?;
+//! handler.apply_overlay(Path::new("/lib/firmware/design.dtbo"), Path::new(""))?;
+//! # Ok(())
+//! # }
+//! ```
+
 use crate::error::FpgadError;
 use crate::platforms::platform::OverlayHandler;
 use crate::softeners::error::FpgadSoftenerError;
@@ -19,9 +51,35 @@ use log::{debug, trace};
 use std::option::Option;
 use std::path::Path;
 
+/// Xilinx DFX Manager overlay handler implementation.
+///
+/// This struct provides overlay management for Xilinx FPGA devices using the
+/// dfx-mgr backend. Unlike the universal overlay handler, it doesn't directly
+/// manage configfs overlay directories since dfx-mgr handles that internally.
+///
+/// # Implementation Notes
+///
+/// The overlay handle parameter is currently unused since dfx-mgr manages
+/// overlay lifecycle internally through its slot system.
 pub struct XilinxDfxMgrOverlayHandler {}
 
 impl XilinxDfxMgrOverlayHandler {
+    /// Create a new XilinxDfxMgrOverlayHandler instance.
+    ///
+    /// # Arguments
+    ///
+    /// * `_overlay_handle` - Overlay handle (currently unused, slot management WIP)
+    ///
+    /// # Returns: `Self`
+    /// * New XilinxDfxMgrOverlayHandler instance
+    ///
+    /// # Examples
+    ///
+    /// ```rust,no_run
+    /// use daemon::softeners::xilinx_dfx_mgr_overlay_handler::XilinxDfxMgrOverlayHandler;
+    ///
+    /// let handler = XilinxDfxMgrOverlayHandler::new("");
+    /// ```
     pub(crate) fn new(_: &str) -> Self {
         XilinxDfxMgrOverlayHandler {}
     }