fpgad 0.5.1

// This file is part of fpgad, an application to manage FPGA subsystem together with device-tree and kernel modules.
//
// Copyright 2026 Canonical Ltd.
//
// SPDX-License-Identifier: GPL-3.0-only
//
// fpgad is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License version 3, as published by the Free Software Foundation.
//
// fpgad is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranties of MERCHANTABILITY, SATISFACTORY QUALITY, or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more details.
//
// 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 XilinxSys 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 -unload`
//!
//! # 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::error::FpgadError;
use crate::platforms::platform::Fpga;
use crate::softeners::xilinx_dfx_mgr;
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(),
        }
    }
}

impl Fpga for XilinxDfxMgrFPGA {
    /// Get the device handle for this FPGA.
    ///
    /// Returns the device handle (e.g., "fpga0") that identifies this FPGA in sysfs.
    ///
    /// # Returns: `&str`
    /// * The device handle string
    fn device_handle(&self) -> &str {
        self.device_handle.as_str()
    }

    /// Get the current state of the FPGA via dfx-mgr package listing.
    ///
    /// Returns the output of `dfx-mgr-client -listPackage`, which provides a formatted
    /// table showing all available accelerator packages, their types, load status, and
    /// slot assignments.
    ///
    /// # Returns: `Result<String, FpgadError>`
    /// * `Ok(String)` - Formatted package listing from dfx-mgr
    /// * `Err(FpgadSoftenerError)` - Failed to communicate with dfx-mgrd or parse output
    fn state(&self) -> Result<String, FpgadError> {
        Ok(xilinx_dfx_mgr::list_package()?)
    }

    fn load_firmware(&self, firmware_path: &Path, _: &Path) -> Result<String, FpgadError> {
        Ok(xilinx_dfx_mgr::load_bitstream(firmware_path)?)
    }

    fn remove_firmware(&self, slot_handle: Option<&str>) -> Result<String, FpgadError> {
        Ok(xilinx_dfx_mgr::remove(slot_handle)?)
    }
}