Add data structure to describe resource requirements

Add DeviceResourceRequest enum to describe a device's resource
requirements, so we could build better flow among the VMM, the device
manager and the device object.

Signed-off-by: Liu Jiang <gerry@linux.alibaba.com>
Signed-off-by: 守情 <liheng.xlh@alibaba-inc.com>

Author: jiangliu

src/resources.rs

@@ -2,6 +2,105 @@
 // SPDX-License-Identifier: Apache-2.0
 
 //! Structs to manage device resources.
+//!
+//! The high level flow of resource management among the VMM, the device manager, and the device
+//! is as below:
+//! 1) the VMM creates a new device object.
+//! 2) the VMM asks the new device object for its resource requirements.
+//! 3) the VMM allocates resources for the device object according to resource requirements.
+//! 4) the VMM passes the allocated resources to the device object.
+//! 5) the VMM registers the new device onto corresponding device managers according the allocated
+//!    resources.
+
+use std::{u16, u32, u64};
+
+/// Enumeration describing a device's resource requirements.
+pub enum ResourceRequest {
+    /// Request for an IO Port address range.
+    PioAddress {
+        /// Allocate resource within the range [`min`, `max`] if `min` is not u16::MAX.
+        min: u16,
+        /// Allocate resource within the range [`min`, `max`] if `max` is not zero.
+        max: u16,
+        /// Alignment for the allocated address.
+        align: u16,
+        /// Size for the allocated address range.
+        size: u16,
+    },
+    /// Request for a Memory Mapped IO address range.
+    MmioAddress {
+        /// Allocate resource within the range [`min`, `max`] if 'min' is not u64::MAX.
+        min: u64,
+        /// Allocate resource within the range [`min`, `max`] if 'max' is not zero.
+        max: u64,
+        /// Alignment for the allocated address.
+        align: u64,
+        /// Size for the allocated address range.
+        size: u64,
+    },
+    /// Request for a legacy IRQ.
+    LegacyIrq {
+        /// Reserve the preallocated IRQ if it's not u32::MAX.
+        fixed: u32,
+    },
+    /// Request for PCI MSI IRQs.
+    PciMsiIrq {
+        /// Number of Irqs to allocate.
+        size: u32,
+    },
+    /// Request for PCI MSIx IRQs.
+    PciMsixIrq {
+        /// Number of Irqs to allocate.
+        size: u32,
+    },
+    /// Request for generic IRQs.
+    GenericIrq {
+        /// Number of Irqs to allocate.
+        size: u32,
+    },
+    /// Request for KVM mem_slot indexes to map memory into the guest.
+    KvmMemSlot {
+        /// Allocate the specified kvm memory slot index if it's not u32::MAX.
+        fixed: u32,
+        /// Number of slots to allocate.
+        size: u32,
+    },
+}
+
+impl ResourceRequest {
+    /// Create a new Mmio address request object with default configuration.
+    pub fn new_pio(size: u16) -> Self {
+        ResourceRequest::PioAddress {
+            min: u16::MAX,
+            max: 0,
+            align: 0x1,
+            size,
+        }
+    }
+
+    /// Create a new Mmio address request object with default configuration.
+    pub fn new_mmio(size: u64) -> Self {
+        ResourceRequest::MmioAddress {
+            min: u64::MAX,
+            max: 0,
+            align: 0x1000,
+            size,
+        }
+    }
+
+    /// Create a new legacy IRQ request object with default configuration.
+    pub fn new_legacy_irq() -> Self {
+        ResourceRequest::LegacyIrq { fixed: u32::MAX }
+    }
+
+    /// Create a new KVM memory slot request object with default configuration.
+    pub fn new_kvm_mem_slot(size: u32) -> Self {
+        ResourceRequest::KvmMemSlot {
+            fixed: u32::MAX,
+            size,
+        }
+    }
+}
 
 /// Type of Message Singaled Interrupt
 #[derive(Copy, Clone, PartialEq)]
@@ -140,3 +239,113 @@ impl DeviceResources {
         &self.0
     }
 }
+
+#[cfg(test)]
+mod test {
+    use super::*;
+
+    const PIO_ADDRESS_SIZE: u16 = 5;
+    const PIO_ADDRESS_BASE: u16 = 0;
+    const MMIO_ADDRESS_SIZE: u64 = 0x8765_4321;
+    const MMIO_ADDRESS_BASE: u64 = 0x1234_5678;
+    const LEGACY_IRQ: u32 = 0x168;
+    const PCI_MSI_IRQ_SIZE: u32 = 0x8888;
+    const PCI_MSI_IRQ_BASE: u32 = 0x6666;
+    const PCI_MSIX_IRQ_SIZE: u32 = 0x16666;
+    const PCI_MSIX_IRQ_BASE: u32 = 0x8888;
+    const GENERIC_MSI_IRQS_SIZE: u32 = 0x16888;
+    const GENERIC_MSI_IRQS_BASE: u32 = 0x16688;
+    const NIC_MAC_ADDRESS: &str = "00:08:63:66:86:88";
+
+    fn get_device_resource() -> DeviceResources {
+        let entry = ResourceEntry::PioAddressRange {
+            base: PIO_ADDRESS_BASE,
+            size: PIO_ADDRESS_SIZE,
+        };
+        let mut resource = DeviceResources::new();
+        resource.append(entry);
+        let entry = ResourceEntry::MmioAddressRange {
+            base: MMIO_ADDRESS_BASE,
+            size: MMIO_ADDRESS_SIZE,
+        };
+        resource.append(entry);
+        let entry = ResourceEntry::LegacyIrq(LEGACY_IRQ);
+        resource.append(entry);
+        let entry = ResourceEntry::PciMsiIrq {
+            base: PCI_MSI_IRQ_BASE,
+            size: PCI_MSI_IRQ_SIZE,
+        };
+        resource.append(entry);
+        let entry = ResourceEntry::PciMsixIrq {
+            base: PCI_MSIX_IRQ_BASE,
+            size: PCI_MSIX_IRQ_SIZE,
+        };
+        resource.append(entry);
+        let entry = ResourceEntry::GenericIrq {
+            base: GENERIC_MSI_IRQS_BASE,
+            size: GENERIC_MSI_IRQS_SIZE,
+        };
+        resource.append(entry);
+        let entry = ResourceEntry::NicMacAddresss(NIC_MAC_ADDRESS.to_string());
+        resource.append(entry);
+
+        resource
+    }
+
+    #[test]
+    fn get_pio_address_ranges() {
+        let resources = get_device_resource();
+        assert!(
+            resources.get_pio_address_ranges()[0].0 == PIO_ADDRESS_BASE
+                && resources.get_pio_address_ranges()[0].1 == PIO_ADDRESS_SIZE
+        );
+    }
+
+    #[test]
+    fn test_get_mmio_address_ranges() {
+        let resources = get_device_resource();
+        assert!(
+            resources.get_mmio_address_ranges()[0].0 == MMIO_ADDRESS_BASE
+                && resources.get_mmio_address_ranges()[0].1 == MMIO_ADDRESS_SIZE
+        );
+    }
+
+    #[test]
+    fn test_get_legacy_irq() {
+        let resources = get_device_resource();
+        assert!(resources.get_legacy_irq().unwrap() == LEGACY_IRQ);
+    }
+
+    #[test]
+    fn test_get_pci_msi_irqs() {
+        let resources = get_device_resource();
+        assert!(
+            resources.get_pci_msi_irqs().unwrap().0 == PCI_MSI_IRQ_BASE
+                && resources.get_pci_msi_irqs().unwrap().1 == PCI_MSI_IRQ_SIZE
+        );
+    }
+
+    #[test]
+    fn test_pci_msix_irqs() {
+        let resources = get_device_resource();
+        assert!(
+            resources.get_pci_msix_irqs().unwrap().0 == PCI_MSIX_IRQ_BASE
+                && resources.get_pci_msix_irqs().unwrap().1 == PCI_MSIX_IRQ_SIZE
+        );
+    }
+
+    #[test]
+    fn test_get_generic_msi_irqs() {
+        let resources = get_device_resource();
+        assert!(
+            resources.get_generic_msi_irqs().unwrap().0 == GENERIC_MSI_IRQS_BASE
+                && resources.get_generic_msi_irqs().unwrap().1 == GENERIC_MSI_IRQS_SIZE
+        );
+    }
+
+    #[test]
+    fn test_get_mac_address() {
+        let resources = get_device_resource();
+        assert_eq!(resources.get_mac_address().unwrap(), NIC_MAC_ADDRESS);
+    }
+}