fpgad_cli 0.1.1

// 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 status interface.
//!
//! This module provides the auto-generated DBus proxy for the `com.canonical.fpgad.status`
//! interface, which handles all read-only operations for querying FPGA subsystem state:
//! - Querying FPGA device states (operating, unknown, etc.)
//! - Reading FPGA programming flags
//! - Listing loaded device tree overlays
//! - Getting platform compatibility strings
//! - Checking overlay status
//!
//! The proxy is generated using the `zbus` crate's `#[proxy]` macro and provides
//! type-safe, asynchronous access to the daemon's status interface.
//!
//! # DBus Interface Details
//!
//! - **Service**: `com.canonical.fpgad`
//! - **Interface**: `com.canonical.fpgad.status`
//! - **Object Path**: `/com/canonical/fpgad/status`
//!
//! # Usage
//!
//! ```rust,no_run
//! use zbus::Connection;
//! use crate::proxies::status_proxy::StatusProxy;
//!
//! # async fn example() -> Result<(), Box<dyn std::error::Error>> {
//! let connection = Connection::system().await?;
//! let proxy = StatusProxy::new(&connection).await?;
//! let state = proxy.get_fpga_state("", "fpga0").await?;
//! println!("FPGA state: {}", state);
//! # 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 status interface.
///
/// This trait is auto-generated by the `#[proxy]` macro and provides methods to invoke
/// the status interface methods on the fpgad daemon. All methods return `Result<String>`
/// containing requested information or FpgadError messages.
///
/// See the main [module documentation](index.html) for usage examples.
#[proxy(
    default_service = "com.canonical.fpgad",
    interface = "com.canonical.fpgad.status",
    default_path = "/com/canonical/fpgad/status"
)]
pub trait Status {
    /// Get the current state of an FPGA device.
    ///
    /// Returns the device state such as "operating", "unknown", "write init", "write",
    /// "write complete", or "write error".
    ///
    /// # Arguments
    ///
    /// * `platform_string` - Platform identifier (can be empty for auto-detection)
    /// * `device_handle` - [Device handle](../../index.html#device-handles) (e.g., "fpga0")
    ///
    /// # Returns: `Result<String>`
    /// * `Ok(String)` - Current state of the FPGA device
    /// * `Err(zbus::Error)` - DBus error or FpgadError. See [Error Handling](../../index.html#error-handling)
    async fn get_fpga_state(&self, platform_string: &str, device_handle: &str) -> Result<String>;

    /// Get the current programming flags for an FPGA device.
    ///
    /// Returns the flags as a hexadecimal string with no prefix (decimal value of 32 -> "20").
    ///
    /// # Arguments
    ///
    /// * `platform_string` - Platform identifier (can be empty for auto-detection)
    /// * `device_handle` - [Device handle](../../index.html#device-handles) (e.g., "fpga0")
    ///
    /// # Returns: `Result<String>`
    /// * `Ok(String)` - Current flags in hexadecimal format
    /// * `Err(zbus::Error)` - DBus error or FpgadError. See [Error Handling](../../index.html#error-handling)
    async fn get_fpga_flags(&self, platform_string: &str, device_handle: &str) -> Result<String>;

    /// Get the status of a specific device tree overlay.
    ///
    /// # Arguments
    ///
    /// * `platform_string` - Platform identifier string
    /// * `overlay_handle` - [Overlay handle](../../index.html#overlay-handles) to query
    ///
    /// # Returns: `Result<String>`
    /// * `Ok(String)` - Status information for the overlay
    /// * `Err(zbus::Error)` - DBus error or FpgadError. See [Error Handling](../../index.html#error-handling)
    async fn get_overlay_status(
        &self,
        platform_string: &str,
        overlay_handle: &str,
    ) -> Result<String>;

    /// Get a list of all loaded device tree overlays.
    ///
    /// Returns a newline-separated list of overlay handles.
    ///
    /// # Returns: `Result<String>`
    /// * `Ok(String)` - Newline-separated list of overlay handles
    /// * `Err(zbus::Error)` - DBus error or FpgadError. See [Error Handling](../../index.html#error-handling)
    async fn get_overlays(&self) -> Result<String>;

    /// Get the platform compatibility string for an FPGA device.
    ///
    /// Returns the platform/compatibility string that identifies the hardware type
    /// (e.g., "xlnx,zynqmp-pcap-fpga", "universal").
    ///
    /// # Arguments
    ///
    /// * `device_handle` - [Device handle](../../index.html#device-handles) (e.g., "fpga0")
    ///
    /// # Returns: `Result<String>`
    /// * `Ok(String)` - Platform compatibility string
    /// * `Err(zbus::Error)` - DBus error or FpgadError. See [Error Handling](../../index.html#error-handling)
    async fn get_platform_type(&self, device_handle: &str) -> Result<String>;

    /// Get all FPGA devices and their platform strings.
    ///
    /// Returns a newline-separated list where each line is formatted as "device:platform".
    ///
    /// # Returns: `Result<String>`
    /// * `Ok(String)` - Newline-separated list of "device:platform" pairs
    /// * `Err(zbus::Error)` - DBus error or FpgadError. See [Error Handling](../../index.html#error-handling)
    async fn get_platform_types(&self) -> Result<String>;
}