How OCLP-Mod Handles GPU Architecture Patching for Legacy GCN and NVIDIA GPUs

OCLP-Mod employs a modular, detection-driven architecture that uses hardware-variant classes to identify GPU families, filters incompatible hardware combinations, and constructs specific patchsets of kexts and bundles tailored to AMD Legacy GCN and NVIDIA GPUs.

OCLP-Mod (OpenCore Legacy Patcher Mod) is an open-source tool that extends macOS compatibility to unsupported hardware. When patching different GPU architectures, including Legacy GCN and NVIDIA, the tool relies on a sophisticated detection and filtering pipeline implemented in the laobamac/oclp-mod repository.

Hardware Detection and Hardware-Variant Classes

The detection layer in oclp_mod/sys_patch/patchsets/detect.py instantiates hardware-variant classes that implement standardized introspection methods including present(), native_os(), and patches(). Each GPU architecture maps to a specific class responsible for identifying its presence and defining compatible patchsets.

AMD Legacy GCN Detection

AMD Legacy GCN detection resides in oclp_mod/sys_patch/patchsets/hardware/graphics/amd_legacy_gcn.py. The implementation checks for three distinct GCN generations: Legacy_GCN_7000, Legacy_GCN_8000, and Legacy_GCN_9000. The detection logic queries device_probe and includes safeguards against false positives, specifically verifying that Rosetta 2 is not masquerading as an AMD GPU during the enumeration process.

NVIDIA GPU Detection

NVIDIA architectures are handled by dedicated classes in separate modules. oclp_mod/sys_patch/patchsets/hardware/graphics/nvidia_kepler.py implements NvidiaKepler detection by querying device_probe.NVIDIA.Archs.Kepler, while nvidia_tesla.py handles NvidiaTesla through device_probe.NVIDIA.Archs.Tesla. Each class isolates architecture-specific logic, allowing the patcher to distinguish between Metal-capable Kepler cards and legacy Tesla architectures requiring different driver bundles.

Compatibility Filtering and Hardware Coexistence

After initial detection, Detect._strip_incompatible_hardware() in detect.py performs compatibility filtering to resolve conflicts when multiple GPUs are present. The method enforces hierarchy rules: Metal 31001 GPUs take precedence over all non-Metal GPUs. On macOS Sequoia and later, Metal 3802 GPUs are stripped when a Metal 31001 GPU is detected, with a specific exception carved out for AMD Legacy GCN hardware (see lines 35-42 of detect.py) to ensure these cards remain eligible for patching even in mixed-GPU configurations.

Patchset Construction and Application

Each hardware-variant class supplies a patches() method returning a dictionary that maps patch types to file operations. The patcher aggregates these dictionaries during HardwarePatchsetDetection and applies them through PatchSysVolume.start_patch() in sys_patch.py.

AMD Legacy GCN Patchsets

The _model_specific_patches() method in amd_legacy_gcn.py (lines 92-108) constructs a comprehensive patchset including AMD7000Controller.kext, AMD8000Controller.kext, or AMD9000Controller.kext depending on the detected generation, alongside AMDMTLBronzeDriver.bundle for Metal support. The source versions for these kexts are selected dynamically based on the host OS version and CPU generation, ensuring compatibility across different macOS releases.

NVIDIA Kepler and Tesla Patchsets

NVIDIA Kepler patching in nvidia_kepler.py (lines 98-112) supplies both Metal 3802 compatibility patches (LegacyMetal3802) and legacy driver bundles such as GeForce.kext and NVDAGK100Hal.kext. For Tesla architectures, nvidia_tesla.py provides non-Metal patches utilizing older driver bundles that predate Apple's Metal framework, ensuring these legacy cards remain functional on unsupported macOS versions.

Kernel Debug Kit and Metallib Dependencies

Certain legacy GPU architectures require kernel extensions or Metal libraries that depend on symbols only present in Apple's Kernel Debug Kit (KDK). Hardware classes implement requires_kernel_debug_kit() and requires_metallib_support_pkg() to flag these requirements. During patching, PatchSysVolume.start_patch() invokes _merge_kdk_with_root() to download and integrate the KDK into the target volume before applying GPU-specific patches, ensuring driver compatibility.

The Complete Patching Workflow

The orchestration layer resides in PatchSysVolume.start_patch() (lines 62-70 of sys_patch.py). This method mounts the root volume, performs sanity checks, instantiates HardwarePatchsetDetection to collect the final patch dictionary, and executes the patch sequence. The process handles file removal, system volume overwrites, and KDK merging, then triggers auxiliary kernel-cache rebuilding and creates a new APFS snapshot to ensure atomic, recoverable changes.

Code Examples

The following examples demonstrate practical interaction with OCLP-Mod's GPU detection and patching pipeline.

Detecting the GPU set and retrieving the final patch dictionary:

from oclp_mod.sys_patch.detect import HardwarePatchsetDetection
from oclp_mod.constants import Constants

constants = Constants()
detector = HardwarePatchsetDetection(constants)
detector._detect()                     # runs detection, filtering and requirement checks

print(detector.patch_set_dictionary)   # final dict of patches to apply

Running a full patch on the current machine via CLI:

# Activate the virtual environment that ships with OCLP-Mod

source venv/bin/activate

# Trigger the patcher (requires sudo because it mounts the system volume)

sudo python -m oclp_mod.sys_patch.sys_patch

Adding a custom patch for a new GPU by extending a hardware class:

# my_gpu.py

from ..base import BaseHardware, HardwareVariant, HardwareVariantGraphicsSubclass
from ...base import PatchType

class MyCustomGPU(BaseHardware):
    def present(self):
        return self._is_gpu_architecture_present([device_probe.AMD.Archs.Custom])

    def hardware_variant(self):
        return HardwareVariant.GRAPHICS

    def hardware_variant_graphics_subclass(self):
        return HardwareVariantGraphicsSubclass.METAL_31001_GRAPHICS

    def patches(self):
        return {
            "MyCustomGPU": {
                PatchType.OVERWRITE_SYSTEM_VOLUME: {
                    "/System/Library/Extensions": {
                        "MyGPU.kext": "12.5"
                    }
                }
            }
        }

Add MyCustomGPU to the HardwarePatchsetDetection._hardware_variants list, and OCLP-Mod will automatically include it in the detection pipeline.

Summary

• Modular Detection: Hardware-variant classes in amd_legacy_gcn.py and nvidia_kepler.py isolate architecture-specific logic for AMD Legacy GCN and NVIDIA GPUs.
• Compatibility Filtering: The Detect._strip_incompatible_hardware() method resolves GPU conflicts, prioritizing Metal 31001 devices while preserving AMD Legacy GCN exceptions on macOS Sequoia.
• Dynamic Patchsets: GPU classes return dictionaries mapping kexts and bundles (e.g., AMD7000Controller.kext, GeForce.kext) with version-specific sources based on OS and CPU generation.
• Dependency Management: Automatic detection of Kernel Debug Kit and MetalLib requirements ensures prerequisite packages are merged before patching via _merge_kdk_with_root().
• Atomic Application: The PatchSysVolume.start_patch() workflow mounts volumes, applies patches, rebuilds kernel caches, and creates APFS snapshots for recoverable changes.

Frequently Asked Questions

What GPU architectures does OCLP-Mod support for patching?

OCLP-Mod supports AMD Legacy GCN (7000, 8000, and 9000 series), NVIDIA Kepler, and NVIDIA Tesla architectures. Each family has dedicated detection classes in the oclp_mod/sys_patch/patchsets/hardware/graphics/ directory that query PCI devices and match against specific architecture constants defined in device_probe.py.

How does OCLP-Mod handle multiple GPUs with different Metal capabilities?

When multiple GPUs are present, Detect._strip_incompatible_hardware() in detect.py filters the hardware set based on Metal support levels. Metal 31001 GPUs take precedence over non-Metal devices. On macOS Sequoia and later, Metal 3802 GPUs are removed when a Metal 31001 GPU is detected, with a specific exception for AMD Legacy GCN cards that allows them to remain in the patch set.

Why does OCLP-Mod require the Kernel Debug Kit for some GPUs?

Certain legacy GPU architectures require kernel extensions or Metal libraries that depend on symbols only present in Apple's Kernel Debug Kit (KDK). Hardware classes implement requires_kernel_debug_kit() to flag this requirement. During patching, PatchSysVolume.start_patch() invokes _merge_kdk_with_root() to download and integrate the KDK into the target volume before applying GPU-specific patches.

Can I add support for a custom or unsupported GPU to OCLP-Mod?

Yes, OCLP-Mod's modular architecture allows extending support by subclassing BaseHardware and implementing the required interface methods (present(), patches(), hardware_variant()). You must query device_probe for your specific PCI IDs, return a dictionary mapping patch types to file operations in patches(), and register the new class in HardwarePatchsetDetection._hardware_variants. The detection pipeline will automatically include your GPU in subsequent patching operations.

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