HardwareVariant Enum in OCLP-Mod: Categorizing and Applying Hardware-Specific Patches

The HardwareVariant enum in laobamac/oclp-mod serves as the central taxonomy that classifies every hardware-specific patch into Graphics, Networking, Audio, or Miscellaneous categories, enabling the detection engine to aggregate patches and the GUI to present them in organized sections.

The HardwareVariant enum is the foundational classification system within the OCLP-Mod project (OpenCore Legacy Patcher Mod), a fork designed to extend macOS compatibility to unsupported hardware. Located in oclp_mod/sys_patch/patchsets/hardware/base.py, this string-based enumeration ensures that every hardware patch—whether for legacy GPUs, unsupported Wi-Fi cards, or audio controllers—is categorized correctly for detection, aggregation, and user interface presentation.

What Is the HardwareVariant Enum?

HardwareVariant is implemented as a StrEnum (string enumeration) that defines four top-level hardware categories. Each variant maps to a Chinese label used in the GUI, reflecting the project's internationalization approach. The enum declaration in oclp_mod/sys_patch/patchsets/hardware/base.py is:

class HardwareVariant(StrEnum):
    """
    Hardware variant for patch set
    """
    GRAPHICS:      str = "显卡"
    NETWORKING:    str = "网卡"
    AUDIO:         str = "音频"
    MISCELLANEOUS: str = "杂项"

Every concrete hardware patch class inherits from the abstract BaseHardware class and must implement the hardware_variant() method, returning the appropriate HardwareVariant member. This contract ensures the detection engine can query any patch instance and immediately know its categorical classification.

How HardwareVariant Drives Patch Classification

The enum serves four critical architectural purposes that bridge low-level hardware detection with high-level user interaction.

Classification and Inheritance

Each hardware patch explicitly declares its category. For example, ModernWireless (handling Broadcom Wi-Fi cards) returns HardwareVariant.NETWORKING, while NvidiaWebDriver returns HardwareVariant.GRAPHICS. This declaration resides in the individual patch file within oclp_mod/sys_patch/patchsets/hardware/ subdirectories.

Detection and Aggregation

The HardwarePatchsetDetection class in oclp_mod/sys_patch/patchsets/detect.py orchestrates system scanning. It iterates over all registered hardware patch classes, instantiates them with system parameters (XNU kernel version, OS build), and checks present() and native_os() methods. Crucially, it groups results using the HardwareVariant as a dictionary key:

for hw_cls in self._hardware_variants:
    hw = hw_cls(xnu_major, xnu_minor, os_build, self._constants)
    if hw.present() and hw.native_os():
        category = hw.hardware_variant()
        self.device_properties.setdefault(category, []).append(hw)

This aggregation produces device_properties, a structured dictionary where each key is a HardwareVariant (e.g., "显卡", "网卡") and each value is a list of applicable patch objects for that category.

Graphics Subclassification with HardwareVariantGraphicsSubclass

Graphics patches require finer granularity than the four main categories provide. To address this, OCLP-Mod implements a secondary enum, HardwareVariantGraphicsSubclass, also defined in oclp_mod/sys_patch/patchsets/hardware/base.py.

This subclass enum distinguishes between Non-Metal Graphics, Metal 3802 (for specific AMD GPUs), and other graphics implementations. Patch classes like NvidiaWebDriver or LegacyAMD override the hardware_variant_graphics_subclass() method to return the appropriate subclass value, while still maintaining HardwareVariant.GRAPHICS as their primary category.

This dual-layer taxonomy allows the detection engine to apply graphics-specific logic (such as selecting between Metal and Non-Metal kernel patches) while maintaining consistent top-level categorization for UI presentation.

Practical Usage in GUI and Patch Application

The GUI modules leverage HardwareVariant to create organized, user-friendly patch displays. Files such as oclp_mod/wx_gui/gui_sys_patch_display.py and gui_sys_patch_start.py import the enum and use it to label tree view sections or panel headers.

When rendering available patches, the GUI iterates over the aggregated device_properties dictionary:

# Simplified example from gui_sys_patch_display.py

for variant in HardwareVariant:
    patch_set = patches.get(variant)
    if not patch_set:
        continue
    variant_item = self.tree.AppendItem(root, variant.value)  # Displays "显卡", "网卡", etc.

    for patch in patch_set:
        self.tree.AppendItem(variant_item, patch.name())

This implementation ensures that users see logically grouped options—such as all networking patches under "网卡" (Networking)—rather than an unstructured list of technical patch names.

Creating Custom Hardware Patches with HardwareVariant

Developers extending OCLP-Mod can implement new hardware support by inheriting from BaseHardware and specifying the appropriate HardwareVariant. The contract requires implementing four key methods: name(), present(), native_os(), and hardware_variant().

Here is a complete example for a hypothetical custom audio patch:

from oclp_mod.sys_patch.patchsets.hardware.base import BaseHardware, HardwareVariant

class MyCustomAudioController(BaseHardware):
    def name(self) -> str:
        """Return human-readable patch name"""
        return "Custom Audio Controller Patch"

    def present(self) -> bool:
        """Detection logic: check if hardware is present"""
        return any(
            dev.device_id == 0x1234 
            for dev in self._computer.audio_devices
        )

    def native_os(self) -> bool:
        """Determine if patch applies to current OS version"""
        return self._xnu_major >= 22  # macOS Ventura+

    def hardware_variant(self) -> HardwareVariant:
        """Return the categorical classification"""
        return HardwareVariant.AUDIO

When this class is registered with the patch detection system, it automatically appears under the "音频" (Audio) section in the GUI, grouped with other audio-related patches.

Summary

• HardwareVariant is a StrEnum defined in oclp_mod/sys_patch/patchsets/hardware/base.py that categorizes patches into Graphics ("显卡"), Networking ("网卡"), Audio ("音频"), and Miscellaneous ("杂项").
• The enum enables HardwarePatchsetDetection (detect.py) to aggregate applicable patches by category into the device_properties dictionary.
• Concrete patch classes inherit from BaseHardware and implement hardware_variant() to declare their category, establishing a strict classification contract.
• HardwareVariantGraphicsSubclass provides secondary granularity for graphics patches, distinguishing between Non-Metal and Metal implementations while maintaining the primary Graphics category.
• GUI modules use the enum values to organize patch displays into logical sections, presenting Chinese labels ("显卡", "网卡", etc.) to users for clarity.

Frequently Asked Questions

How does HardwareVariant differ from HardwareVariantGraphicsSubclass?

HardwareVariant provides the top-level categorical taxonomy used across all patch types, while HardwareVariantGraphicsSubclass offers granular classification exclusively for graphics patches. When a patch returns HardwareVariant.GRAPHICS, it may additionally specify a subclass such as NON_METAL_GRAPHICS or METAL_3802 to trigger specific kernel patching logic, while the GUI still groups it under the main "显卡" (Graphics) category.

Where is the HardwareVariant enum defined and what are its values?

The enum is defined in oclp_mod/sys_patch/patchsets/hardware/base.py as a StrEnum with four members: GRAPHICS (value: "显卡"), NETWORKING (value: "网卡"), AUDIO (value: "音频"), and MISCELLANEOUS (value: "杂项"). These Chinese string values are used directly in the GUI to label patch categories.

How does the detection engine use HardwareVariant to organize patches?

The HardwarePatchsetDetection class in oclp_mod/sys_patch/patchsets/detect.py iterates through all hardware patch classes, instantiates them, and checks their applicability. For each patch that passes detection, it calls hardware_variant() to obtain the category enum, then aggregates the patch into a dictionary (device_properties) keyed by that enum. This creates a structured data structure where all networking patches reside under HardwareVariant.NETWORKING, all graphics under HardwareVariant.GRAPHICS, and so on.

Can developers extend HardwareVariant with new categories?

While the enum definition in base.py contains the four canonical categories, the architecture supports extension through the MISCELLANEOUS category for hardware that does not fit Graphics, Networking, or Audio classifications. Developers implementing new patch classes should return HardwareVariant.MISCELLANEOUS for specialized hardware (such as legacy USB controllers or storage controllers) unless the core enum is modified to include a new top-level category. The StrEnum type ensures that any future additions will integrate seamlessly with the existing string-based GUI labels.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}