fpgad_cli 0.2.0

// This file is part of fpgad, an application to manage FPGA subsystem together with device-tree and kernel modules.
//
// Copyright 2025 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/.

//! DBus proxy for the fpgad control interface.
//!
//! This module provides the auto-generated DBus proxy for the `com.canonical.fpgad.control`
//! interface, which handles all write operations to the FPGA subsystem including:
//! - Loading FPGA bitstreams
//! - Applying device tree overlays
//! - Removing overlays
//! - Writing to FPGA manager properties
//! - Setting FPGA flags
//!
//! The proxy is generated using the `zbus` crate's `#[proxy]` macro and provides
//! type-safe, asynchronous access to the daemon's control interface.
//!
//! # DBus Interface Details
//!
//! - **Service**: `com.canonical.fpgad`
//! - **Interface**: `com.canonical.fpgad.control`
//! - **Object Path**: `/com/canonical/fpgad/control`
//!
//! # Usage
//!
//! ```rust,no_run
//! use zbus::Connection;
//! use crate::control_proxy::ControlProxy;
//!
//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
//! let connection = Connection::system().await?;
//! let proxy = ControlProxy::new(&connection).await?;
//! let result = proxy.write_bitstream_direct(
//!     "",
//!     "fpga0",
//!     "/lib/firmware/design.bit.bin",
//!     ""
//! ).await?;
//! # Ok(())
//! # }
//! ```
//!
//! For detailed method documentation, see the daemon's control interface documentation in the main
//! [fpgad daemon crate](https://docs.rs/crate/fpgad/latest/daemon/comm/dbus/control_interface/index.html)

use zbus::{Result, proxy};

/// DBus proxy trait for the fpgad control interface.
///
/// This trait is auto-generated by the `#[proxy]` macro and provides methods to invoke
/// the control interface methods on the fpgad daemon. All methods return `Result<String>`
/// containing success messages or FpgadError messages.
///
/// See the main [module documentation](index.html) for usage examples.
#[proxy(
    default_service = "com.canonical.fpgad",
    interface = "com.canonical.fpgad.control",
    default_path = "/com/canonical/fpgad/control"
)]
pub trait Control {
    /// Set FPGA programming flags for a device.
    ///
    /// # Arguments
    ///
    /// * `platform_string` - Platform identifier (can be empty for auto-detection)
    /// * `device_handle` - [Device handle](../../index.html#device-handles) (e.g., "fpga0")
    /// * `flags` - Programming flags as a 32-bit unsigned integer
    ///
    /// # Returns: `Result<String>`
    /// * `Ok(String)` - Success message with confirmation of flags set
    /// * `Err(zbus::Error)` - DBus error or FpgadError.
    ///   See [Error Handling](../../index.html#error-handling)
    async fn set_fpga_flags(
        &self,
        platform_string: &str,
        device_handle: &str,
        flags: u32,
    ) -> Result<String>;

    /// Write a bitstream directly to an FPGA device.
    ///
    /// # Arguments
    ///
    /// * `platform_string` - Platform identifier (can be empty for auto-detection)
    /// * `device_handle` - [Device handle](../../index.html#device-handles) (e.g., "fpga0")
    /// * `bitstream_path_str` - Absolute path to the bitstream file
    /// * `firmware_lookup_path` - Optional firmware search path (empty for default)
    ///
    /// # Returns: `Result<String>`
    /// * `Ok(String)` - Success message confirming bitstream loaded
    /// * `Err(zbus::Error)` - DBus error or FpgadError.
    ///   See [Error Handling](../../index.html#error-handling)
    async fn write_bitstream_direct(
        &self,
        platform_string: &str,
        device_handle: &str,
        bitstream_path_str: &str,
        firmware_lookup_path: &str,
    ) -> Result<String>;

    /// Apply a device tree overlay to the system.
    ///
    /// # Arguments
    ///
    /// * `platform_string` - Platform identifier string
    /// * `overlay_handle` - [Overlay handle](../../index.html#overlay-handles) for the overlay directory
    /// * `overlay_source_path` - Absolute path to the overlay file (.dtbo)
    /// * `firmware_lookup_path` - Optional firmware search path (empty for default)
    ///
    /// # Returns: `Result<String>`
    /// * `Ok(String)` - Success message confirming overlay applied
    /// * `Err(zbus::Error)` - DBus error or FpgadError.
    ///   See [Error Handling](../../index.html#error-handling)
    async fn apply_overlay(
        &self,
        platform_string: &str,
        overlay_handle: &str,
        overlay_source_path: &str,
        firmware_lookup_path: &str,
    ) -> Result<String>;

    /// Remove a device tree overlay from the system.
    ///
    /// # Arguments
    ///
    /// * `platform_str` - Platform identifier string
    /// * `overlay_handle` - [Overlay handle](../../index.html#overlay-handles) to remove
    ///
    /// # Returns: `Result<String>`
    /// * `Ok(String)` - Success message confirming overlay removed
    /// * `Err(zbus::Error)` - DBus error or FpgadError.
    ///   See [Error Handling](../../index.html#error-handling)
    async fn remove_overlay(&self, platform_str: &str, overlay_handle: &str) -> Result<String>;

    /// Write a string value to an FPGA manager property.
    ///
    /// # Arguments
    ///
    /// * `property_path_str` - Full sysfs path to the property (must be under `/sys/class/fpga_manager/`)
    /// * `data` - String data to write
    ///
    /// # Returns: `Result<String>`
    /// * `Ok(String)` - Success message confirming write
    /// * `Err(zbus::Error)` - DBus error or FpgadError.
    ///   See [Error Handling](../../index.html#error-handling)
    async fn write_property(&self, property_path_str: &str, data: &str) -> Result<String>;

    /// Write binary data to an FPGA manager property.
    ///
    /// # Arguments
    ///
    /// * `property_path_str` - Full sysfs path to the property (must be under `/sys/class/fpga_manager/`)
    /// * `data` - Binary data to write as a byte slice
    ///
    /// # Returns: `Result<String>`
    /// * `Ok(String)` - Success message confirming write
    /// * `Err(zbus::Error)` - DBus error or FpgadError.
    ///   See [Error Handling](../../index.html#error-handling)
    async fn write_property_bytes(&self, property_path_str: &str, data: &[u8]) -> Result<String>;

    /// Remove a previously loaded bitstream, identifiable by its `bitstream_handle` or `slot`.
    ///
    /// # Arguments
    ///
    /// * `platform_string`: Platform compatibility string.
    /// * `overlay_handle`: Handle of the overlay to remove.
    ///
    /// # Returns: `Result<String, Error>`
    /// *  `Ok(String)` – Confirmation message including overlay filesystem path.
    /// * `Err(fdo::Error)` if overlay or platform cannot be accessed.
    ///
    /// # Examples
    ///
    /// ```
    /// assert!(remove_bitstream("xlnx,zynqmp-pcap-fpga", "").is_ok());
    /// ```
    async fn remove_bitstream(
        &self,
        platform_string: &str,
        device_handle: &str,
        bitstream_handle: &str,
    ) -> Result<String>;
}