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

> Discover how OCLP-Mod patches GPU architectures for Legacy GCN and NVIDIA. Learn about its modular system for hardware detection and tailored patchset creation.

- Repository: [laobamac/oclp-mod](https://github.com/laobamac/oclp-mod)
- Tags: how-to-guide
- Published: 2026-03-05

---

**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`](https://github.com/laobamac/oclp-mod/blob/main/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`](https://github.com/laobamac/oclp-mod/blob/main/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`](https://github.com/laobamac/oclp-mod/blob/main/oclp_mod/sys_patch/patchsets/hardware/graphics/nvidia_kepler.py) implements `NvidiaKepler` detection by querying `device_probe.NVIDIA.Archs.Kepler`, while [`nvidia_tesla.py`](https://github.com/laobamac/oclp-mod/blob/main/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`](https://github.com/laobamac/oclp-mod/blob/main/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`](https://github.com/laobamac/oclp-mod/blob/main/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`](https://github.com/laobamac/oclp-mod/blob/main/sys_patch.py).

### AMD Legacy GCN Patchsets

The `_model_specific_patches()` method in [`amd_legacy_gcn.py`](https://github.com/laobamac/oclp-mod/blob/main/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`](https://github.com/laobamac/oclp-mod/blob/main/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`](https://github.com/laobamac/oclp-mod/blob/main/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`](https://github.com/laobamac/oclp-mod/blob/main/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:

```python
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:

```bash

# 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:

```python

# 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`](https://github.com/laobamac/oclp-mod/blob/main/amd_legacy_gcn.py) and [`nvidia_kepler.py`](https://github.com/laobamac/oclp-mod/blob/main/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`](https://github.com/laobamac/oclp-mod/blob/main/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`](https://github.com/laobamac/oclp-mod/blob/main/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.