How to Save and Use ioreg Dumps for Legacy Hackintosh Debugging

When a legacy Hackintosh refuses to wake from sleep, drops audio after a few minutes, or fails to inject a GPU property, the quickest way to find the root cause is often the ioreg command-line tool. Saving a full registry dump — ioreg -l -w0 > dump.txt — preserves the exact state of your I/O Kit plane at the moment of failure. Unlike a screenshot of IORegistryExplorer, a text dump can be diffed, searched with grep, and shared verbatim on forums without losing nested properties. This guide covers the practical mechanics of saving ioreg output, choosing the right flags, and interpreting the results for common legacy Hackintosh problems.

Why Save ioreg Instead of Relying on IORegistryExplorer

The graphical IORegistryExplorer (versions 2 and 3) is excellent for interactive browsing, but it has limits. It can truncate long property values, it does not always preserve the order of nodes, and it cannot be reused in a scriptable pipeline. A raw ioreg dump, on the other hand, is a plain-text log that you can archive, compress, or attach to a bug report. It also avoids the risk of GUI corruption when the system is already unstable — a kernel panic may occur before the app finishes saving.

For example, when diagnosing a missing USB XHCI controller, you can run ioreg -p IOUSB -l -w0 and grep -i "XHCI" the output. If the controller is absent, the dump shows exactly which ports are missing and which properties (like port-count or usb-connector-type) are not injected. I have archived dozens of such dumps from builds spanning Snow Leopard to Monterey, and they remain the definitive record of what the kernel saw at boot.

Essential ioreg Flags for Diagnostic Saving

The ioreg command offers more than thirty options, but only a handful matter for Hackintosh debugging. The table below summarises the flags you will use most often:

Always combine -l -w0 for a full, parseable dump. Without -w0, long device properties such as acpi-path or built-in data will be truncated, rendering the dump useless for pattern matching.

How to Save a Complete Registry Dump

On a running Hackintosh, open Terminal and navigate to a writable directory (e.g., ~/Desktop/ioreg_dumps). Then run:

ioreg -l -w0 > ioreg_full_$(date +%Y%m%d_%H%M%S).txt

This creates a timestamped file that you can later compare with dumps from other boot sessions. For a focused dump, restrict the plane. For example, to capture only the IOUSBFamily plane:

ioreg -p IOUSB -l -w0 > ioreg_usb_$(date +%Y%m%d_%H%M%S).txt

If you suspect a power management issue, the IOPower plane is more revealing:

ioreg -p IOPower -l -w0 > ioreg_power_$(date +%Y%m%d_%H%M%S).txt

After saving, inspect the file size. A full dump from macOS 10.13 High Sierra on a system with a dozen devices is typically 200–500 KB. If the file is unexpectedly small (under 50 KB), you likely forgot -w0 or the command timed out. Run it again with timeout 30 if necessary, but avoid | less or | head in the save command — those pipe operations can truncate the output before it reaches the file.

Parsing a Saved ioreg Dump

Once you have a dump, open it in a text editor that supports large files (BBEdit, Sublime Text, or Vim). The structure is a tree of nodes, each preceded by a line like +-o <node name> <class>. Properties are indented below. To find a specific device, search for its class name. For instance, to locate the Apple HDA audio device:

grep -n "AppleHDA" ioreg_full.txt

Then open the file at that line number and examine the surrounding properties. A common check is the IOProbeScore property — if it is zero or missing, the driver did not load. For GPU diagnostics, search for @0, @1, or the framebuffer name. The model property should match your injected device ID.

When you suspect an ACPI issue, the acpi-path property tells you the node’s position in the ACPI namespace. A missing acpi-path often indicates that the device was not declared in DSDT or that the SSDT hotpatch did not attach. The SSDT Creation Guide for Legacy Hackintosh: DSDT Disassembly and Hotpatch Basics covers how to use ioreg output to confirm that your hotpatch correctly attached to the intended PCI device.

Common Pitfalls When Saving ioreg

• Missing -w0: The most frequent mistake. Without it, lines wrap and grep returns partial matches that are hard to verify.
• Piping to tee or less: These commands can buffer output and cause the file to be incomplete. Always redirect directly with >.
• Running ioreg as root: While not required, some properties (e.g., under IODeviceTree) are only visible to root. Use sudo ioreg -l -w0 if you suspect missing nodes.
• Ignoring the timestamp: After a warm reboot, the registry may change due to driver loading order. Save a dump immediately after boot and again after triggering the issue to compare.
• Non-ASCII characters in property keys: Some third-party kexts inject strings with Unicode characters. A plain-text dump may render them as escaped codes; use cat -v to see raw bytes if needed.

Using Saved Dumps for Remote Debugging

When you ask for help on a forum, attaching a saved ioreg dump is far more effective than describing symptoms. The dump contains the exact device registry, including injection status, power states, and driver binding. Remove any personally identifiable information (e.g., serial numbers from IOPlatformSerialNumber) before sharing. You can anonymise it with a quick sed command:

sed -i '' 's/IOPlatformSerialNumber = "[^"]*"/IOPlatformSerialNumber = "REDACTED"/g' ioreg_dump.txt

Archiving these dumps alongside your EFI folder and boot log creates a complete snapshot of the system state. Months later, when you revisit the build, you can compare the current ioreg output against the saved dump to detect driver drift or hardware decay.

For a concrete example, consider a legacy Hackintosh with an NVIDIA GeForce 9 series card that fails to output HDMI audio. By saving a full ioreg dump and searching for HDMI or HDAU, you can quickly determine whether the GPU’s audio function is present in the registry. If it is missing, the issue is likely a missing injection property — not a driver problem. The NVIDIA GeForce 9 Series Hackintosh Guide: Compatibility, Setup, and Performance discusses the exact property keys needed, and a saved ioreg dump lets you verify them without rebooting.

I've made it a habit to save an ioreg dump after every build step. Once, after updating my SSDT for a new GPU, the system started crashing under load. A grep through the old and new dumps showed that the new SSDT had omitted a critical power property. Without the archived dump, I'd have been chasing the wrong cause. The file is tiny—typically under 500 KB—and it's saved me hours more times than I can count.