mfd-hyperv 2.1.0__py3-none-any.whl

mfd_hyperv/__init__.py

@@ -0,0 +1,4 @@
+# Copyright (C) 2025 Intel Corporation
+# SPDX-License-Identifier: MIT
+"""Module for Hyperv."""
+from .base import HyperV

mfd_hyperv/attributes/__init__.py

@@ -0,0 +1,3 @@
+# Copyright (C) 2025 Intel Corporation
+# SPDX-License-Identifier: MIT
+"""Module for attributes of Hyper-V objects."""

mfd_hyperv/attributes/vm_network_interface_attributes.py

@@ -0,0 +1,62 @@
+# Copyright (C) 2025 Intel Corporation
+# SPDX-License-Identifier: MIT
+"""VMNetworkInterfaceAttributes class."""
+from enum import Enum
+
+
+class VMNetworkInterfaceAttributes(str, Enum):
+    """Attributes of VM network interface."""
+
+    def __str__(self) -> str:
+        return str.__str__(self)
+
+    DynamicMacAddressEnabled = "dynamicmacaddressenabled"
+    AllowPacketDirect = "allowpacketdirect"
+    NumaAwarePlacement = "numaawareplacement"
+    MacAddressSpoofing = "macaddressspoofing"
+    AllowTeaming = "allowteaming"
+    RouterGuard = "routerguard"
+    DhcpGuard = "dhcpguard"
+    StormLimit = "stormlimit"
+    PortMirroringMode = "portmirroringmode"
+    IeeePriorityTag = "ieeeprioritytag"
+    VirtualSubnetId = "virtualsubnetid"
+    DynamicIPAddressLimit = "dynamicipaddresslimit"
+    DeviceNaming = "devicename"
+    VmqWeight = "vmqweight"
+    VmqUsage = "vmqusage"
+    IovWeight = "iovweight"
+    IovUsage = "iovusage"
+    IovQueuePairsRequested = "iovqueuepairsrequested"
+    IovQueuePairsAssigned = "iovqueuepairsassigned"
+    IovInterruptModeration = "iovinterruptmoderation"
+    PacketDirectNumProcs = "packetdirectnumprocs"
+    PacketDirectModerationCount = "packetdirectmoderationcount"
+    PacketDirectModerationInterval = "packetdirectmoderationinterval"
+    VrssEnabledRequested = "vrssenabledrequested"
+    VrssEnabled = "vrssenabled"
+    VmmqEnabledRequested = "vmmqenabledrequested"
+    VmmqEnabled = "vmmqenabled"
+    VrssMaxQueuePairsRequested = "vrssmaxqueuepairsrequested"
+    VrssMaxQueuePairs = "vrssmaxqueuepairs"
+    VrssMinQueuePairsRequested = "vrssminqueuepairsrequested"
+    VrssMinQueuePairs = "vrssminqueuepairs"
+    VrssQueueSchedulingModeRequested = "vrssqueueschedulingmoderequested"
+    VrssQueueSchedulingMode = "vrssqueueschedulingmode"
+    VrssExcludePrimaryProcessorRequested = "vrssexcludeprimaryprocessorrequested"
+    VrssExcludePrimaryProcessor = "vrssexcludeprimaryprocessor"
+    VrssIndependentHostSpreadingRequested = "vrssindependenthostspreadingrequested"
+    VrssIndependentHostSpreading = "vrssindependenthostspreading"
+    VrssVmbusChannelAffinityPolicyRequested = "vrssvmbuschannelaffinitypolicyrequested"
+    VrssVmbusChannelAffinityPolicy = "vrssvmbuschannelaffinitypolicy"
+    RscEnabledRequested = "rscenabledrequested"
+    RscEnabled = "rscenabled"
+    IPsecOffloadMaxSA = "ipsecoffloadmaxsa"
+    IPsecOffloadSAUsage = "ipsecoffloadsausage"
+    VFDataPathActive = "vfdatapathactive"
+    MaximumBandwidth = "maximumbandwidth"
+    MinimumBandwidthAbsolute = "minimumbandwidthabsolute"
+    MinimumBandwidthWeight = "minimumbandwidthweight"
+    BandwidthPercentage = "bandwidthpercentage"
+    VmmqQueuePairs = "vmmqqueuepairs"
+    StaticMacAddress = "staticmacaddress"

mfd_hyperv/attributes/vm_params.py

@@ -0,0 +1,41 @@
+# Copyright (C) 2025 Intel Corporation
+# SPDX-License-Identifier: MIT
+"""VMParams class."""
+from dataclasses import dataclass, fields
+from typing import Optional, Union
+
+from mfd_typing import MACAddress
+from mfd_typing.dataclass_utils import convert_value_field_to_typehint_type
+
+
+@dataclass
+class VMParams:
+    """Configuration for VM.
+
+    name: Name of VM
+    cpu_count: Count of CPUs
+    hw_threads_per_core: number of virtual SMT threads exposed to the virtual machine
+    memory: Memory value in MB
+    generation: Generation of VM
+    vm_dir_path: Path to directory where VM will be stored
+    img_file_name: Name of VM image used for VM
+    mng_interface_name: Name of management vSwitch
+    mng_mac_address: Mac address for management vSwitch
+    vswitch_name: Name of management vSwitch used
+    """
+
+    name: str = "vm"
+    cpu_count: int = 2
+    hw_threads_per_core: int = 0
+    memory: int = 2048
+    generation: int = 2
+    vm_dir_path: Optional[str] = None
+    diff_disk_path: Optional[str] = None
+    mng_interface_name: str = "mng"
+    mng_mac_address: Optional[Union[MACAddress, str]] = None
+    mng_ip: Optional[str] = None
+    vswitch_name: Optional[str] = None
+
+    def __post_init__(self):
+        for field in fields(self):
+            convert_value_field_to_typehint_type(self, field)

mfd_hyperv/attributes/vm_processor_attributes.py

@@ -0,0 +1,14 @@
+# Copyright (C) 2025 Intel Corporation
+# SPDX-License-Identifier: MIT
+"""VMProcessorAttributes class."""
+from enum import Enum
+
+
+class VMProcessorAttributes(str, Enum):
+    """Enum for VM processor attributes."""
+
+    def __str__(self) -> str:
+        return str.__str__(self)
+
+    Count: str = "count"
+    HWThreadCountPerCore: str = "hwthreadcountpercore"

mfd_hyperv/attributes/vswitchattributes.py

@@ -0,0 +1,26 @@
+# Copyright (C) 2025 Intel Corporation
+# SPDX-License-Identifier: MIT
+"""VSwitchAttributes class."""
+from enum import Enum
+
+
+class VSwitchAttributes(str, Enum):
+    """Enum of attributes that can be set on vSwitch."""
+
+    def __str__(self) -> str:
+        return str.__str__(self)
+
+    DefaultQueueVmmqEnabled: str = "defaultqueuevmmqenabled"
+    DefaultQueueVmmqQueuePairs: str = "defaultqueuevmmqqueuepairs"
+    EmbeddedTeamingEnabled: str = "embeddedteamingenabled"
+    EnableSoftwareRsc: str = "enablesoftwarersc"
+    EnableRscOffload: str = "enablerscoffload"
+    IovEnabled: str = "iovenabled"
+    IovQueuePairsInUse: str = "iovqueuepairsinuse"
+    IovSupport: str = "iovsupport"
+    IovVirtualFunctionCount: str = "iovvirtualfunctioncount"
+    IovVirtualFunctionsInUse: str = "iovvirtualfunctionsinuse"
+    NumberVmqAllocated: str = "numbervmqallocated"
+    RscOffloadEnabled: str = "rscoffloadenabled"
+    SoftwareRscEnabled: str = "softwarerscenabled"
+    SwitchType: str = "switchtype"

mfd_hyperv/base.py

@@ -0,0 +1,31 @@
+# Copyright (C) 2025 Intel Corporation
+# SPDX-License-Identifier: MIT
+"""Main module."""
+
+from typing import TYPE_CHECKING
+
+from mfd_common_libs import os_supported
+from mfd_typing import OSName
+
+from mfd_hyperv.hw_qos import HWQoS
+from mfd_hyperv.hypervisor import HypervHypervisor
+from mfd_hyperv.vm_network_interface_manager import VMNetworkInterfaceManager
+from mfd_hyperv.vswitch_manager import VSwitchManager
+
+if TYPE_CHECKING:
+    from mfd_connect import Connection
+
+
+class HyperV:
+    """Module for HyperV."""
+
+    @os_supported(OSName.WINDOWS)
+    def __init__(self, *, connection: "Connection"):
+        """Class constructor.
+
+        :param connection: connection instance of MFD connect class.
+        """
+        self.hw_qos = HWQoS(connection)
+        self.hypervisor = HypervHypervisor(connection=connection)
+        self.vswitch_manager = VSwitchManager(connection=connection)
+        self.vm_network_interface_manager = VMNetworkInterfaceManager(connection=connection)

mfd_hyperv/exceptions.py

@@ -0,0 +1,12 @@
+# Copyright (C) 2025 Intel Corporation
+# SPDX-License-Identifier: MIT
+"""Module for exceptions."""
+import subprocess
+
+
+class HyperVException(Exception):
+    """Handle HyperV module exceptions."""
+
+
+class HyperVExecutionException(subprocess.CalledProcessError):
+    """Handle execution exceptions."""

mfd_hyperv/helpers.py

@@ -0,0 +1,13 @@
+# Copyright (C) 2025 Intel Corporation
+# SPDX-License-Identifier: MIT
+"""Module for helper functions."""
+from typing import Union
+
+
+def standardise_value(value: Union[int, str, bool]) -> str:
+    """Make input value standardised, no matter it's type to make comparisons more easily."""
+    value = str(value)
+    value = value.lower()
+    if value in ["true", "false"]:
+        return f"${value}"
+    return value

mfd_hyperv/hw_qos.py

@@ -0,0 +1,282 @@
+# Copyright (C) 2025 Intel Corporation
+# SPDX-License-Identifier: MIT
+"""Main module."""
+
+import logging
+import re
+
+from typing import TYPE_CHECKING
+from mfd_common_libs import log_levels, add_logging_level
+
+from mfd_hyperv.exceptions import HyperVExecutionException, HyperVException
+
+if TYPE_CHECKING:
+    from mfd_connect import Connection
+
+logger = logging.getLogger(__name__)
+add_logging_level(level_name="MODULE_DEBUG", level_value=log_levels.MODULE_DEBUG)
+
+
+class HWQoS:
+    """Class for Hyper-V Hardware QoS Offload functionality."""
+
+    def __init__(self, connection: "Connection") -> None:
+        """
+        Class constructor.
+
+        :param connection: connection instance.
+        """
+        self._connection = connection
+
+    def create_scheduler_queue(
+        self, vswitch_name: str, sq_id: str, sq_name: str, limit: bool, tx_max: str, tx_reserve: str, rx_max: str
+    ) -> None:
+        """
+        Create scheduler queue.
+
+        :param vswitch_name: name of the virtual switch.
+        :param sq_id: ID for new scheduler queue.
+        :param sq_name: name for new scheduler queue.
+        :param limit: determine if enforcing infra-host limits.
+        :param tx_max: transmit limit.
+        :param tx_reserve: transmit reservation.
+        :param rx_max: receive limit.
+        :raises HyperVExecutionException: when command execution fails.
+        """
+        limit = str(limit).lower()
+        cmd = (
+            f"vfpctrl /switch {vswitch_name} /add-queue " f'"{sq_id} {sq_name} {limit} {tx_max} {tx_reserve} {rx_max}"'
+        )
+        self._connection.execute_powershell(command=cmd, custom_exception=HyperVExecutionException)
+
+    def update_scheduler_queue(
+        self, vswitch_name: str, limit: bool, tx_max: str, tx_reserve: str, rx_max: str, sq_id: str
+    ) -> None:
+        """
+        Update existing scheduler queue.
+
+        :param vswitch_name: name of the virtual switch.
+        :param limit: determine if enforcing infra-host limits.
+        :param tx_max: queue configuration value which determines transmit limit.
+        :param tx_reserve: transmit reservation.
+        :param rx_max: receive limit.
+        :param sq_id: ID of existing scheduler queue.
+        :raises HyperVExecutionException: when command execution fails.
+        """
+        limit = str(limit).lower()
+        cmd = (
+            f"vfpctrl /switch {vswitch_name} /set-queue-config "
+            f'"{limit} {tx_max} {tx_reserve} {rx_max}" /queue "{sq_id}"'
+        )
+        self._connection.execute_powershell(command=cmd, custom_exception=HyperVExecutionException)
+
+    def delete_scheduler_queue(self, vswitch_name: str, sq_id: str) -> None:
+        """
+        Delete existing scheduler queue.
+
+        :param vswitch_name: name of the virtual switch.
+        :param sq_id: ID of existing scheduler queue.
+        :raises HyperVExecutionException: when command execution fails.
+        """
+        cmd = f'vfpctrl /switch {vswitch_name} /remove-queue /queue "{sq_id}"'
+        self._connection.execute_powershell(command=cmd, custom_exception=HyperVExecutionException)
+
+    def get_qos_config(self, vswitch_name: str) -> dict[str, str | bool]:
+        """
+        Get current QoS configuration for the vSwitch.
+
+        :param vswitch_name: name of the virtual switch.
+        :return: config from parsed command output, for example:
+        {'hw_caps': False, 'hw_reserv': False, 'sw_reserv': True, flags: 0x0}
+        :raises HyperVExecutionException: when command execution fails.
+        """
+        cmd = f"vfpctrl /switch {vswitch_name} /get-qos-config"
+        result = self._connection.execute_powershell(command=cmd, custom_exception=HyperVExecutionException)
+
+        pattern = (
+            r"Caps:+\s(?P<hw_caps>\S+)[\s\S]*?"
+            r"Hardware Reservations:+\s(?P<hw_reserv>\S+)[\s\S]*?"
+            r"Software Reservations:+\s(?P<sw_reserv>\S+)[\s\S]*?"
+            r"Flags:+\s(?P<flags>\S+)"
+        )
+        parsed_config = {}
+        matches = re.finditer(pattern, result.stdout)
+        params = ["hw_caps", "hw_reserv", "sw_reserv", "flags"]
+
+        for match in matches:
+            for param in params:
+                if param == "flags":
+                    parsed_config[param] = match.group(param)
+                else:
+                    parsed_config[param] = True if match.group(param) == "TRUE" else False
+
+        return parsed_config
+
+    def set_qos_config(self, vswitch_name: str, hw_caps: bool, hw_reserv: bool, sw_reserv: bool, flags: str) -> None:
+        """
+        Set QoS configuration on the vSwitch.
+
+        :param vswitch_name: name of the virtual switch.
+        :param hw_caps: determine if enable hardware caps.
+        :param hw_reserv: determine if enable hardware reservations.
+        :param sw_reserv: determine if enable software reservations.
+        :param flags: flags.
+        :raises HyperVExecutionException: when command execution fails.
+        """
+        hw_caps = str(hw_caps).lower()
+        hw_reserv = str(hw_reserv).lower()
+        sw_reserv = str(sw_reserv).lower()
+        cmd = f'vfpctrl /switch {vswitch_name} /set-qos-config "{hw_caps} {hw_reserv} {sw_reserv} {flags}"'
+        self._connection.execute_powershell(command=cmd, custom_exception=HyperVExecutionException)
+
+    def disassociate_scheduler_queues_with_vport(self, vswitch_name: str, vport: str) -> None:
+        """
+        Disassociate scheduler queues with virtual port.
+
+        :param vswitch_name: name of the virtual switch.
+        :param vport: virtual port.
+        :raises HyperVExecutionException: when command execution fails.
+        """
+        cmd = f"vfpctrl /switch {vswitch_name} /port {vport} /clear-port-queue"
+        self._connection.execute_powershell(command=cmd, custom_exception=HyperVExecutionException)
+
+    def list_scheduler_queues_with_vport(self, vswitch_name: str, vport: str) -> list[str]:
+        """
+        List scheduler queues associated with virtual port.
+
+        :param vswitch_name: name of the virtual switch.
+        :param vport: virtual port.
+        :return: list of SQ IDs associated with given port, eg. ["1", "5", "2"]
+        :raises HyperVExecutionException: when command execution fails.
+        """
+        cmd = f"vfpctrl /switch {vswitch_name} /port {vport} /get-port-queue"
+        result = self._connection.execute_powershell(command=cmd, custom_exception=HyperVExecutionException)
+        pattern = r"(?<=QOS QUEUE: ).*"
+        return re.findall(pattern, result.stdout)
+
+    def associate_scheduler_queues_with_vport(
+        self, vswitch_name: str, vport: str, sq_id: str, lid: int, lname: str
+    ) -> None:
+        """
+        Associate scheduler queues with virtual port.
+
+        :param vswitch_name: name of the virtual switch.
+        :param vport: virtual port.
+        :param sq_id: ID of existing scheduler queue.
+        :param lid: layer ID
+        :param lname: layer name
+        :raises HyperVExecutionException: when any command execution fails.
+        """
+        base_cmd = f"vfpctrl /switch {vswitch_name} /port {vport}"
+        params = [
+            "/enable-port",
+            "/unblock-port",
+            f"/add-layer '{lid} {lname} stateless 100 1'",
+            f"/set-port-queue {sq_id}",
+        ]
+        for param in params:
+            cmd = f"{base_cmd} {param}"
+            self._connection.execute_powershell(command=cmd, custom_exception=HyperVExecutionException)
+
+    def get_vmswitch_port_name(self, switch_friendly_name: str, vm_name: str) -> str:
+        """
+        Get vmswitch port name.
+
+        :param switch_friendly_name: switch friendly name.
+        :param vm_name: vm name.
+        :return: vmswitch port name.
+        :raises HyperVExecutionException: when command execution fails.
+        :raises HyperVException: when no vmswitch port name found.
+        """
+        cmd = "vfpctrl /list-vmswitch-port"
+
+        result = self._connection.execute_powershell(command=cmd, custom_exception=HyperVExecutionException)
+
+        pattern = (
+            r"Port\sname\s+:+\s(?P<port_name>\S+)[\s\S]*?"
+            r"Switch\sFriendly\sname\s+:+\s(?P<friendly_name>\S+)[\s\S]*?"
+            r"VM\sname\s+:+\s(?P<vm_name>\S+)"
+        )
+
+        matches = re.finditer(pattern, result.stdout)
+
+        for match in matches:
+            if match.group("friendly_name") == switch_friendly_name and match.group("vm_name") == vm_name:
+                return match.group("port_name")
+
+        raise HyperVException(
+            f"Couldn't find VM Switch port name for Switch Friendly name: {switch_friendly_name} and "
+            f"VM name: {vm_name} in output: {result.stdout}"
+        )
+
+    def is_scheduler_queues_created(self, vswitch_name: str, sq_id: int, sq_name: str, tx_max: str) -> bool:
+        """
+        Verify that scheduler queues with provided name was created.
+
+        :param vswitch_name: name of vswitch.
+        :param sq_id: scheduler queues for verification.
+        :param sq_name: name of scheduler queues.
+        :param tx_max: transmit limit value
+        :return: True if SQ found, False otherwise.
+        :raises HyperVExecutionException: when command execution fails.
+        """
+        pattern = (
+            r"(?<=QOS QUEUE: )(?P<sq_id>.*)\s+"
+            r"Friendly\sname\s+:+\s(?P<friendly_name>\S+)[\s\S]*?\s+.+"
+            r"Transmit\sLimit:+\s(?P<tx_max>\S+)"
+        )
+
+        listed_queue = self.list_queue(vswitch_name=vswitch_name)
+        all_info = self.get_queue_all_info(vswitch_name=vswitch_name)
+        offload_info = self.get_queue_offload_info(vswitch_name=vswitch_name, sq_id=sq_id)
+
+        for result in [listed_queue, all_info, offload_info]:
+            matches = re.finditer(pattern, result)
+            for match in matches:
+                if (
+                    match.group("friendly_name") == sq_name
+                    and match.group("sq_id") == str(sq_id)
+                    and match.group("tx_max") == str(tx_max)
+                ):
+                    is_scheduler_queues_created = True
+                    break
+            else:
+                is_scheduler_queues_created = False
+
+        return is_scheduler_queues_created
+
+    def list_queue(self, vswitch_name: str) -> str:
+        """
+        List quested scheduler queues on a vswitch.
+
+        :param vswitch_name: name of vswitch.
+        :return: output from command.
+        :raises HyperVExecutionException: when command execution fails.
+        """
+        cmd = f"vfpctrl /switch {vswitch_name} /list-queue"
+        return self._connection.execute_powershell(command=cmd, custom_exception=HyperVExecutionException).stdout
+
+    def get_queue_all_info(self, vswitch_name: str) -> str:
+        """
+        List quested scheduler queues on a vswitch.
+
+        :param vswitch_name: name of vswitch.
+        :return: output from command.
+        :raises HyperVExecutionException: when command execution fails.
+        """
+        cmd = f'vfpctrl /switch {vswitch_name} /get-queue-info "all"'
+
+        return self._connection.execute_powershell(command=cmd, custom_exception=HyperVExecutionException).stdout
+
+    def get_queue_offload_info(self, vswitch_name: str, sq_id: int) -> str:
+        """
+        List quested scheduler queues on a vswitch.
+
+        :param vswitch_name: name of vswitch.
+        :param sq_id: number of scheduler queues.
+        :return: output from command.
+        :raises HyperVExecutionException: when command execution fails.
+        """
+        cmd = f'vfpctrl /switch {vswitch_name} /get-queue-info "offload" /queue "{sq_id}"'
+
+        return self._connection.execute_powershell(command=cmd, custom_exception=HyperVExecutionException).stdout