Re: [PATCH proxmox-perl-rs v2 5/9] pve: add bindings for `pve-qemu-server-pci` crate

[Wolfgang Bumiller <w.bumiller@proxmox.com>]

On Thu, Oct 15, 2026 at 10:10:27AM +0200, Dominik Csapak wrote:
> These provide bindings for using the rust pci code in PVE's qemu-server
> perl code. This exposes 'PVE::RS::PCI::HardwareConfig' which provides an
> object that can be used to query the pci addresses of qemu vms.
> 
> Signed-off-by: Dominik Csapak <d.csapak@proxmox.com>
> ---
>  pve-rs/Cargo.toml                          |   1 +
>  pve-rs/Makefile                            |   1 +
>  pve-rs/src/bindings/mod.rs                 |   3 +
>  pve-rs/src/bindings/pci/hardware_config.rs | 150 +++++++++++++++++++++
>  pve-rs/src/bindings/pci/mod.rs             |   2 +
>  5 files changed, 157 insertions(+)
>  create mode 100644 pve-rs/src/bindings/pci/hardware_config.rs
>  create mode 100644 pve-rs/src/bindings/pci/mod.rs
> 
> diff --git a/pve-rs/Cargo.toml b/pve-rs/Cargo.toml
> index 5ae9082..0c4a47e 100644
> --- a/pve-rs/Cargo.toml
> +++ b/pve-rs/Cargo.toml
> @@ -52,6 +52,7 @@ proxmox-tfa = { version = "6.0.3", features = ["api"] }
>  proxmox-time = "2"
>  proxmox-ve-config = { version = "0.10.4", features = [ "frr" ] }
>  proxmox-wireguard = { version = "0.1.2" }
> +pve-qemu-server-pci = "0.1"
>  
>  # [patch.crates-io]
>  # pbs-api-types = { path = "../../proxmox/pbs-api-types" }
> diff --git a/pve-rs/Makefile b/pve-rs/Makefile
> index bb1cd2d..c239f2a 100644
> --- a/pve-rs/Makefile
> +++ b/pve-rs/Makefile
> @@ -29,6 +29,7 @@ PERLMOD_PACKAGES := \
>  	  PVE::RS::Firewall::SDN \
>  	  PVE::RS::NVML \
>  	  PVE::RS::OCI \
> +	  PVE::RS::PCI::HardwareConfig \
>  	  PVE::RS::OpenId \
>  	  PVE::RS::ResourceScheduling::Static \
>  	  PVE::RS::ResourceScheduling::Dynamic \
> diff --git a/pve-rs/src/bindings/mod.rs b/pve-rs/src/bindings/mod.rs
> index f922982..b26c602 100644
> --- a/pve-rs/src/bindings/mod.rs
> +++ b/pve-rs/src/bindings/mod.rs
> @@ -6,6 +6,9 @@ pub use nvml::pve_rs_nvml;
>  mod oci;
>  pub use oci::pve_rs_oci;
>  
> +mod pci;
> +pub use pci::pve_rs_pci_hardware_config;
> +
>  pub mod resource_scheduling;
>  
>  mod tfa;
> diff --git a/pve-rs/src/bindings/pci/hardware_config.rs b/pve-rs/src/bindings/pci/hardware_config.rs
> new file mode 100644
> index 0000000..44e9d03
> --- /dev/null
> +++ b/pve-rs/src/bindings/pci/hardware_config.rs
> @@ -0,0 +1,150 @@
> +#[perlmod::package(name = "PVE::RS::PCI::HardwareConfig", lib = "pve_rs")]
> +pub mod pve_rs_pci_hardware_config {
> +    //! The `PVE::RS::PCI::HardwareConfig` package.
> +    //!
> +    //! Provides bindings for the `HardwareConfig` struct of the [`pve-qemu-server-pci`] crate.
> +
> +    use std::ops::Deref;
> +    use std::rc::Rc;
> +
> +    use anyhow::Error;
> +
> +    use perlmod::Value;
> +
> +    use pve_qemu_server_pci::{HostpcieDevice, LayoutError, address};
> +
> +    perlmod::declare_magic!(Box<HardwareConfig>: &HardwareConfig as "PVE::RS::PCI::HardwareConfig");
> +
> +    /// Wrapper for [`pve_qemu_server_pci::HardwareConfig`].
> +    pub struct HardwareConfig {
> +        inner: Rc<pve_qemu_server_pci::HardwareConfig>,
> +    }
> +
> +    impl Deref for HardwareConfig {
> +        type Target = pve_qemu_server_pci::HardwareConfig;
> +
> +        fn deref(&self) -> &Self::Target {
> +            &self.inner
> +        }
> +    }
> +
> +    #[export(raw_return)]
> +    #[allow(clippy::too_many_arguments)]

I think a struct parameter might make more sense here.
(A strict one with `#[serde(deny_unknown_fields)]`)

> +    /// Create an instance of the `HardwareConfig` struct.

As per the `README.md` the method here *should* include a
`Class method: ` prefix in its documentation.
(And the rest of them a `Method: ` prefix.)

> +    ///
> +    /// `hostpcie` lists the indices of the `hostpci` devices with `pcie` enabled.
> +    pub fn new(
> +        #[raw] class: Value,
> +        arch: String,
> +        machine_type: String,
> +        scsihw: Option<String>,
> +        max_scsihw: u8,
> +        legacy_igd: bool,
> +        ostype: Option<String>,
> +        major: u16,
> +        minor: u16,
> +        pve: Option<u16>,
> +        layout: &str,
> +        hostpcie: Vec<u8>,
> +    ) -> Result<Value, Error> {
> +        let mut hw_config = pve_qemu_server_pci::HardwareConfig::new(
> +            &arch,
> +            machine_type,
> +            scsihw,
> +            max_scsihw,
> +            legacy_igd,
> +            ostype,
> +            major,
> +            minor,
> +            pve,
> +            layout,
> +        );
> +        hw_config.hostpcie_devices = hostpcie
> +            .into_iter()
> +            .map(|index| (index, HostpcieDevice::default()))
> +            .collect();
> +        Ok(
> +            perlmod::instantiate_magic!(&class, MAGIC => Box::new(HardwareConfig { inner: Rc::new(hw_config) })),
> +        )
> +    }
> +
> +    #[export]
> +    /// Returns the PCI or PCIe address of the chosen device on the given machine if the device
> +    /// exists on the layout.
> +    pub fn addr(
> +        #[try_from_ref] this: &HardwareConfig,

Uses `this` for the parameter (as every other module does).

> +        id: &str,
> +    ) -> Result<Option<String>, LayoutError> {
> +        match address(this, id) {
> +            Ok(addr) => Ok(Some(addr.to_qemu_addr())),
> +            Err(LayoutError::NoAddressFound(_)) => Ok(None),
> +            Err(other) => Err(other),
> +        }
> +    }
> +
> +    #[export]
> +    /// Get the `-device` arguments of all bridges, root ports and chipset devices forming the
> +    /// buses of the guest, which have to come before any device on them.
> +    pub fn pci_bus_devices(
> +        #[try_from_ref] machine: &HardwareConfig,

But from here on out it's always `machine`.

We should stick to `this` for the perl "self" parameter name.

> +    ) -> Result<Vec<String>, LayoutError> {
> +        pve_qemu_server_pci::pci_bus_devices(machine)
> +    }
> +
> +    #[export]
> +    /// Whether the q35 chipset devices still have to be loaded from `pve-q35-4.0.cfg`.
> +    pub fn uses_q35_config_file(#[try_from_ref] machine: &HardwareConfig) -> bool {
> +        machine.uses_q35_config_file()
> +    }
> +
> +    #[export]
> +    /// Get the architecture of the machine
> +    pub fn arch(#[try_from_ref] machine: &HardwareConfig) -> String {
> +        machine.arch.to_string()
> +    }
> +
> +    #[export]
> +    /// Get the machines mainboard model
> +    pub fn machine_type(#[try_from_ref] machine: &HardwareConfig) -> String {
> +        machine.mainboard.to_string()
> +    }
> +
> +    #[export]
> +    /// Get the layout of the given machine.
> +    pub fn layout(#[try_from_ref] machine: &HardwareConfig) -> String {
> +        machine.layout.to_string()
> +    }
> +
> +    #[export]
> +    /// Checks if the given machine is at least the given version
> +    pub fn version_at_least(
> +        #[try_from_ref] machine: &HardwareConfig,
> +        major: u16,
> +        minor: u16,
> +        pve: Option<u16>,
> +    ) -> bool {
> +        machine.version_at_least(major, minor, pve)
> +    }
> +
> +    #[export]
> +    /// returns the windows version (if any)

^ s/r/R/

> +    pub fn windows_version(#[try_from_ref] machine: &HardwareConfig) -> u8 {
> +        machine.windows_version()
> +    }
> +
> +    #[export]
> +    /// Returns the bus the given device sits on, if it is a known device.
> +    pub fn pci_bridge_for_device(
> +        #[try_from_ref] machine: &HardwareConfig,
> +        device: &str,
> +    ) -> Option<String> {
> +        let bus = pve_qemu_server_pci::pci_bridge_for_device(machine, device)?;
> +        Some(bus.to_string())
> +    }
> +
> +    #[export]
> +    /// Returns the required '+pveX' version of the machine.
> +    pub fn required_pve_version(#[try_from_ref] machine: &HardwareConfig) -> u16 {
> +        machine.required_pve_version()
> +    }
> +}
> diff --git a/pve-rs/src/bindings/pci/mod.rs b/pve-rs/src/bindings/pci/mod.rs
> new file mode 100644
> index 0000000..d1b00dd
> --- /dev/null
> +++ b/pve-rs/src/bindings/pci/mod.rs
> @@ -0,0 +1,2 @@
> +mod hardware_config;
> +pub use hardware_config::pve_rs_pci_hardware_config;
> -- 
> 2.47.3
> 
> 
> 
> 
> 

--