AGPM Editing for Legacy Hackintosh: A Practical Guide

When a legacy Hackintosh boots into macOS but suffers from choppy graphics, unexpected kernel panics related to GPU power management, or a complete failure to wake from sleep with a black screen, the culprit often lies in AppleGraphicsPowerManagement (AGPM). AGPM is the kernel extension responsible for dynamic GPU frequency scaling and voltage control on genuine Mac hardware. On a custom PC, the GPU is rarely an exact match for a Mac model, so macOS either applies aggressive power-saving that causes instability or leaves the GPU running at full throttle, wasting energy and generating unnecessary heat. Editing the AGPM plist — manually injecting the correct GPU personality — can resolve these issues without resorting to disabling all power management via agdpmod=pikera or similar blunt-force boot arguments.

Understanding AGPM and Its Role

AGPM is located at /System/Library/CoreServices/AGPM.app/Contents/Resources/AGPM.plist. This property list contains a dictionary of GPU personalities keyed by Mac model identifier (e.g., MacPro6,1, iMac14,2). Each personality defines a set of thresholds — temperature, load percentage, memory usage — at which the GPU transitions between performance states (P-states). On genuine hardware, Apple tunes these values for the exact GPU paired with that Mac. On a Hackintosh, the system reads the SMBIOS model you set in your bootloader config and applies the matching AGPM personality, even if your actual GPU is completely different. The result is either overly conservative power management (stuttering, low FPS) or missing keys that cause the kernel extension to fail silently.

For example, using iMac14,2 SMBIOS with a discrete NVIDIA GTX 680 will load the AGPM personality for the iMac’s internal mobile GPU (or no discrete GPU at all), which lacks entries for the GK104 chip. macOS then falls back to a generic, often broken, power management path. Editing AGPM lets you clone a personality from a Mac that originally shipped with a GPU architecturally similar to yours — or create a minimal entry that only defines the required Control-int and Control-ed keys.

Identifying Your GPU and Required Personality

Before editing any system files, you must know your GPU’s device ID and vendor ID. Run system_profiler SPDisplaysDataType in Terminal and note the Vendor (e.g., 0x10de for NVIDIA, 0x1002 for AMD) and Device ID (e.g., 0x1001 for GK104). Then open the stock AGPM.plist in a text editor (Xcode or PlistEdit Pro recommended) and locate the personality that matches your SMBIOS. If you use MacPro6,1, find the MacPro6,1 dictionary. Inside it, look for a sub-dictionary named after your vendor ID, e.g., Vendor10deDevice. If it is missing or contains only a single entry, you need to add your device ID and define the Control-int and Control-ed arrays.

A safer approach is to reference a Mac model that originally used a GPU from the same family. For Kepler-based NVIDIA cards (GTX 6xx/7xx), the iMac13,2 or MacPro6,1 personalities often work. For AMD Radeon HD 7xxx/8xxx (GCN 1.0), the MacPro6,1 personality with the Hawaii or Tahiti keys can be adapted. For older Intel integrated graphics (HD 4000, HD 4600), the MacBookPro11,3 personality is a common reference. Copy the entire VendorXXXXDeviceXXXX dictionary from the reference Mac model into your SMBIOS section, then modify the device ID to match yours.

Editing the AGPM Plist

Because AGPM.plist resides in the read-only system volume on macOS High Sierra and later (SIP must be partially disabled or the file must be replaced from a recovery environment), the safest workflow is to modify the plist on a separate volume or a backup copy, then overwrite the original from a bootable USB installer or single-user mode. On Sierra and earlier, you can directly edit the file with sudo after disabling SIP (csrutil disable).

Open the plist and navigate to Root > [YourSMBIOS] > VendorXXXXDeviceXXXX. If the key does not exist, create it. The minimal working entry requires two arrays:

• Control-int: an array of dictionaries, each containing SP0, SP1, SP2, SP3 keys that define the load thresholds (0.0 to 1.0) and the corresponding P-state index. A typical entry for a desktop GPU might have three states: idle (load 0.0–0.3), medium (0.3–0.7), high (0.7–1.0).
• Control-ed: an array of integers that map each P-state to a specific GPU frequency. These values are hardware-specific. For an NVIDIA Kepler card, common P-state frequencies are 324 MHz (idle), 540 MHz (medium), 1058 MHz (high). You can extract these from the GPU’s VBIOS using tools like NVIDIA Inspector on Windows or by reading ioreg output on a working macOS installation.

A concrete example for a GTX 660 (GK106, device ID 0x11c0) under MacPro6,1 SMBIOS:

<key>Vendor10deDevice11c0</key>
<dict>
    <key>Control-int</key>
    <array>
        <dict>
            <key>SP0</key><real>0.0</real>
            <key>SP1</key><real>0.3</real>
            <key>SP2</key><real>0.7</real>
            <key>SP3</key><real>1.0</real>
        </dict>
    </array>
    <key>Control-ed</key>
    <array>
        <integer>324</integer>
        <integer>540</integer>
        <integer>1058</integer>
    </array>
</dict>

After editing, save the plist and replace the original. On a SIP-enabled system, boot from your macOS installer, open Terminal, mount the system volume, and copy the modified file over. Then rebuild the kernel cache: chown -R 0:0 /System/Library/CoreServices/AGPM.app && kextcache -i /. Reboot and test.

Diagnosing AGPM Loading

After applying the edited plist, verify that AGPM is actually loading your custom personality. Run ioreg -l -w0 | grep AGPM. You should see a line like "AGPM" = <...> with your device ID present. If the output shows AGPMEnabler or AGPMVersion but no device-specific entry, the plist was not read correctly — check for syntax errors (missing semicolons, extra commas).

For deeper verification, enable AGPM logging by adding agpm=debug to your boot-args. Check the system log with log show --predicate 'subsystem == "com.apple.AGPM"' --last boot. Look for messages like AGPM: GPU = Vendor10deDevice11c0 and AGPM: P-state transition. If you see AGPM: Unknown GPU, the personality key does not match your device ID.

Risks and Data Safety

Editing AGPM.plist carries two primary risks. First, a malformed plist can cause the kernel extension to fail to load, resulting in no GPU power management at all — the GPU will run at its highest P-state constantly, increasing power draw and temperature. In severe cases, this can trigger thermal throttling or shutdown on systems with inadequate cooling. Second, if you accidentally corrupt the system volume’s kernel collections, the system may fail to boot until you restore the original AGPM.plist from a backup. Always keep a copy of the stock plist and test the edited version on a non-critical installation or a cloned drive first. For builds running Sierra or High Sierra, refer to the Hackintosh Troubleshooting: ACPI, USB, and Bootloader Fixes for X79/X99 Builds for complementary guidance on power management stability.

If you are using a Broadwell-E platform with an NVIDIA GPU, the interplay between ACPI power states and AGPM can be particularly tricky. The Broadwell-E Hackintosh on High Sierra: Required Kexts, ACPI Patches, and Bootloader Config article covers the broader power management context for that chipset, including SSDT injection for XCPM, which works alongside AGPM to stabilize sleep and wake.

Testing and Validation

After rebooting with the new AGPM, run a GPU stress test (e.g., Unigine Valley or Cinebench) while monitoring clock speeds with iStat Menus or HWMonitor. The GPU should idle at a low frequency (sub-400 MHz) and ramp up under load. If the frequency stays locked at the maximum, your Control-ed values may be incorrect or the personality is not being applied. Check also that the system sleeps and wakes without a black screen — a common symptom of missing AGPM entries is that the GPU fails to reinitialize after sleep. If wake works but the display stays dark, try adding darkwake=0 or darkwake=8 to your boot args as a temporary test, but the real fix is a correct AGPM personality.

For legacy systems with Intel HD Graphics 4000 or 4600, AGPM editing is often unnecessary if you use the correct ig-platform-id and inject Intel via Clover or OpenCore. However, when sleep breaks specifically because the iGPU does not enter its lowest P-state, adding a custom AGPM entry for the Intel vendor ID (0x8086) can help. Use the MacBookPro11,3 personality as a template and adjust the device ID to match your CPU’s graphics (0x0166 for HD 4000, 0x0412 for HD 4600).

If after all edits the system still panics on sleep with a GPU-related backtrace, consider that the problem may not be AGPM alone but a conflict with the ACPI _PS3 method. The guide Fixing Sleep/Wake Issues on Legacy Hackintosh Builds (Sierra & High Sierra) provides a systematic approach to isolating ACPI from power management issues.

One final note: AGPM editing is not a substitute for proper GPU injection via WhateverGreen. Always ensure that WhateverGreen.kext is loaded and that you have set the correct shikigva and radpg boot arguments for your GPU family. AGPM works at a lower level — it tells macOS how to scale voltage and frequency, while WhateverGreen handles connector mapping and board-id validation. Both are needed for a stable, performant system.