How to Create or Add New Hardware Variant Definitions to OCLP-Mod: A Complete Developer's Guide

Adding a new hardware variant to OCLP-Mod requires creating a Python class that inherits from BaseHardware in the oclp_mod/sys_patch/patchsets/hardware/ directory, implementing six required methods including name(), present(), and patches(), and placing the file in the appropriate category subdirectory to enable automatic discovery.

OCLP-Mod uses a plugin-based architecture to support diverse hardware configurations on macOS. Creating or adding new hardware variant definitions to OCLP-Mod involves extending the BaseHardware abstract base class to define detection logic and patch sets for unsupported GPUs, network cards, or audio devices. This guide walks through the exact file locations, method signatures, and implementation patterns used in the laobamac/oclp-mod repository.

Create a New Subclass File in the Hardware Patchsets Directory

Place your new hardware definition in the appropriate subdirectory under oclp_mod/sys_patch/patchsets/hardware/. The repository organizes variants by category:

• graphics/ — For GPU architectures (Intel, AMD, NVIDIA)
• networking/ — For Wi-Fi and Ethernet controllers
• audio/ — For sound cards and audio codecs
• misc/ — For other hardware types

Name the file descriptively, such as my_new_gpu.py or broadcom_wifi.py. As a reference implementation, examine intel_skylake.py located at oclp_mod/sys_patch/patchsets/hardware/graphics/intel_skylake.py, which demonstrates the standard structure for graphics variants.

Inherit from BaseHardware and Import Required Modules

Every hardware variant must subclass BaseHardware and import the core dependencies used for detection and patching. The standard import pattern mirrors existing variants in the repository.

from ..base import BaseHardware, HardwareVariant, HardwareVariantGraphicsSubclass
from ...base import PatchType
from .....constants import Constants
from .....detections import device_probe
from .....datasets.os_data import os_data

These imports provide access to the abstract base class, hardware category enumerations, patch type definitions, system constants, device detection utilities, and macOS version data.

Implement the Required Abstract Interface

The BaseHardware class in oclp_mod/sys_patch/patchsets/hardware/base.py defines six abstract methods that every subclass must implement. These methods enable OCLP-Mod to detect hardware presence, determine compatibility, and apply appropriate patches.

• name(self) -> str — Returns a human-readable identifier displayed in the UI. Typical implementation: return f"{self.hardware_variant()}: MyNew GPU".

• present(self) -> bool — Detects whether the hardware exists on the current machine using device_probe helpers. For GPUs, use self._is_gpu_architecture_present([device_probe.Intel.Archs.YourArch]).

• native_os(self) -> bool — Determines if macOS natively supports this hardware on the current version by comparing self._xnu_major against values in os_data.

• hardware_variant(self) -> HardwareVariant — Returns the high-level category: HardwareVariant.GRAPHICS, HardwareVariant.NETWORKING, HardwareVariant.AUDIO, or HardwareVariant.MISCELLANEOUS.

• hardware_variant_graphics_subclass(self) -> HardwareVariantGraphicsSubclass — Required only for graphics variants. Specifies the Metal support level, such as HardwareVariantGraphicsSubclass.METAL_31001_GRAPHICS.

• patches(self) -> dict — Returns a dictionary of patch operations required for this hardware. Combine shared patches (like MontereyOpenCL) with model-specific overrides following the PatchType schema.

Define Model-Specific Patches

If your hardware requires file overrides beyond shared patches, implement a helper method commonly named _model_specific_patches(). This method returns a nested dictionary following the PatchType structure defined in the base classes.

def _model_specific_patches(self) -> dict:
    return {
        "MyNew GPU": {
            PatchType.OVERWRITE_SYSTEM_VOLUME: {
                "/System/Library/Extensions": {
                    "AppleMyNewGPU.kext": "12.5",
                },
            },
        },
    }

Reference the _model_specific_patches implementation in intel_skylake.py to see how model-specific kext overrides integrate with the broader patch dictionary.

Extend Hardware Enums for New Categories

If your variant introduces a completely new hardware category not covered by existing enumerations, you must extend the base definitions in oclp_mod/sys_patch/patchsets/hardware/base.py.

• Add new HardwareVariant enum members for novel categories (e.g., a new storage controller type)
• Add new HardwareVariantGraphicsSubclass members for new GPU Metal support tiers

Most implementations will reuse existing enum values rather than creating new ones.

Enable Automatic Discovery

OCLP-Mod discovers hardware variants automatically through Python's pkgutil.iter_modules. The patchset loader scans all .py files in the patchsets/hardware/ tree at runtime. Simply placing your new file in the correct subdirectory makes it discoverable without explicit registration.

If the project maintains an explicit __all__ list in __init__.py files, ensure you import your class there to maintain compatibility.

Document and Test the New Variant

Add a docstring to your module explaining the hardware support and update the project README to list the new compatibility. Test your implementation by running the detection logic directly:

python -c "from oclp_mod.sys_patch import PatchsetLoader; print(PatchsetLoader().list_active())"

Verify that your class instantiates only when the target hardware is present and that patches() returns the correct dictionary structure for non-native macOS versions.

Complete Implementation Example

The following skeleton demonstrates a complete new graphics variant implementation. Save this as oclp_mod/sys_patch/patchsets/hardware/graphics/my_new_gpu.py:

"""
my_new_gpu.py – detection and patching for "MyNew GPU"
"""

from ..base import BaseHardware, HardwareVariant, HardwareVariantGraphicsSubclass
from ...base import PatchType
from .....constants import Constants
from .....detections import device_probe
from .....datasets.os_data import os_data


class MyNewGPU(BaseHardware):

    def __init__(self, xnu_major, xnu_minor, os_build, global_constants: Constants):
        super().__init__(xnu_major, xnu_minor, os_build, global_constants)

    def name(self) -> str:
        return f"{self.hardware_variant()}: MyNew GPU"

    def present(self) -> bool:
        # Detect the GPU by its PCI class/code or architecture

        return self._is_gpu_architecture_present(
            gpu_architectures=[device_probe.Intel.Archs.MyNewArch]
        )

    def native_os(self) -> bool:
        # Assume support up to macOS Ventura

        return self._xnu_major < os_data.ventura.value

    def hardware_variant(self) -> HardwareVariant:
        return HardwareVariant.GRAPHICS

    def hardware_variant_graphics_subclass(self) -> HardwareVariantGraphicsSubclass:
        return HardwareVariantGraphicsSubclass.METAL_31001_GRAPHICS

    def _model_specific_patches(self) -> dict:
        return {
            "MyNew GPU": {
                PatchType.OVERWRITE_SYSTEM_VOLUME: {
                    "/System/Library/Extensions": {
                        "AppleMyNewGPU.kext": "12.5",
                    },
                },
            },
        }

    def patches(self) -> dict:
        if self.native_os():
            return {}
        # Merge shared OpenCL patches with GPU-specific ones

        from ...shared_patches.monterey_opencl import MontereyOpenCL
        return {
            **MontereyOpenCL(self._xnu_major, self._xnu_minor,
                             self._constants.detected_os_version).patches(),
            **self._model_specific_patches(),
        }

Key Files Reference

Understanding these core files ensures your implementation aligns with the OCLP-Mod architecture:

• oclp_mod/sys_patch/patchsets/hardware/base.py — Defines BaseHardware, HardwareVariant, and HardwareVariantGraphicsSubclass. This is the core abstract API that all hardware variants must implement.

• oclp_mod/sys_patch/patchsets/hardware/graphics/intel_skylake.py — Concrete reference implementation showing how Intel Skylake graphics detection and patching works in practice.

• oclp_mod/sys_patch/patchsets/hardware/<category>/<your_file>.py — The destination path for your new variant, where <category> is graphics, networking, audio, or misc.

• oclp_mod/datasets/os_data.py (or constants file) — Contains macOS version constants used by native_os() checks to determine support ceilings.

Summary

• Create a new Python file in the appropriate oclp_mod/sys_patch/patchsets/hardware/ subdirectory (graphics, networking, audio, or misc).
• Subclass BaseHardware and import required modules following the pattern in intel_skylake.py.
• Implement six required methods: name(), present(), native_os(), hardware_variant(), hardware_variant_graphics_subclass() (for GPUs), and patches().
• Define optional _model_specific_patches() for hardware-specific kext overrides using the PatchType schema.
• Extend HardwareVariant or HardwareVariantGraphicsSubclass enums in base.py only if introducing entirely new categories.
• Place the file in the directory tree to enable automatic discovery via pkgutil.iter_modules—no explicit registration required.
• Test using PatchsetLoader().list_active() to verify detection logic and patch output before submitting.

Frequently Asked Questions

What is the minimum number of methods I must implement to create a valid hardware variant?

You must implement six methods defined in BaseHardware: name(), present(), native_os(), hardware_variant(), patches(), and for graphics hardware, hardware_variant_graphics_subclass(). The present() method is critical as it determines whether your patch set applies to the current machine using device_probe detection logic.

Do I need to register my new hardware variant in an __init__.py or configuration file?

No explicit registration is required. OCLP-Mod uses pkgutil.iter_modules to automatically discover all Python files in the oclp_mod/sys_patch/patchsets/hardware/ directory tree at runtime. Simply placing your file in the correct subdirectory makes it available to the patchset loader.

How do I determine which HardwareVariant enum value to return?

Return HardwareVariant.GRAPHICS for GPUs, HardwareVariant.NETWORKING for Wi-Fi/Ethernet controllers, HardwareVariant.AUDIO for sound devices, or HardwareVariant.MISCELLANEOUS for other hardware types. These values are defined in oclp_mod/sys_patch/patchsets/hardware/base.py and control how the UI categorizes your patch set.

Can I reuse existing patch sets like Monterey OpenCL in my new hardware variant?

Yes. Import shared patch classes from oclp_mod/sys_patch/patchsets/shared_patches/ (such as MontereyOpenCL) and merge their patches() dictionary with your _model_specific_patches() output in your patches() method implementation. This follows the DRY principle used throughout the laobamac/oclp-mod codebase.

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