Skip to content

Latest commit

 

History

History
90 lines (57 loc) · 3.07 KB

debug.md

File metadata and controls

90 lines (57 loc) · 3.07 KB
Raw

OpenCore Debugging

  • Supported version: 0.5.9

Needing to figure out why you're getting issues or stalling? Well, you've come to the right place.

To start, make sure you're using either the DEBUG or NOOPT versions of OpenCore. This will provide much more info than the RELEASE version, the specific files that need to be swapped:

  • EFI/BOOT/
    • BOOTx64.efi
  • EFI/OC/Bootstrap/
    • Bootstrap.efi
  • EFI/OC/Drivers/
    • OpenRuntime.efi
    • OpenCanopy.efi(if you're using it)
  • EFI/OC/
    • OpenCore.efi

  • Note: Generally best to debug systems without OpenCanopy, if required make sure this file is from DEBUG else there will be virtually no debug information.

Next, head to your config.plist and locate the Misc section, we have a couple entries we'll want to play with here:

AppleDebug: YES

Provides much more debugging information, specifically relating to boot.efi and will also store the log to disk.

ApplePanic: YES

This will allow kernel panics to be stored to disk, highly recommend keeping keepsyms=1 in boot-args to preserve as much info as possible.

DisableWatchdog: YES

Disables the UEFI watchdog, used for when OpenCore is stalling on something non-critical.

Target: 67(or calculate one below)

Used for enabling different levels of debugging

  • 0x01 — Enable Logging
  • 0x02 — Enable Onscreen debug
  • 0x04 — Enable logging to Data Hub.
  • 0x08 — Enable serial port logging.
  • 0x10 — Enable UEFI variable logging.
  • 0x20 — Enable non-volatile UEFI variable logging.
  • 0x40 — Enable logging to file.

To calculate the target, we can use a HEX calculator and then convert it to decimal. For us we want to have our values on stored onto a .txt file for later viewing:

  • 0x01 — Enable Logging
  • 0x02 — Enable Onscreen debug
    • Note this can heavily increase boot times on firmwares with poor GOP implementations
  • 0x10 — Enable UEFI variable logging.
  • 0x40 — Enable logging to file.

0x01 + 0x02 + 0x10 + 0x40 = 0x53

0x53 converted to decimal becomes 83

So we can set Misc -> Debug -> Target -> 83

DisplayLevel: 2147483714(or calculate one below)

Used for setting what is logged

  • 0x00000002 — DEBUG_WARN in DEBUG, NOOPT, RELEASE.

  • 0x00000040 — DEBUG_INFO in DEBUG, NOOPT.

  • 0x00400000 — DEBUG_VERBOSE in custom builds.

  • 0x80000000 — DEBUG_ERROR in DEBUG, NOOPT, RELEASE.

    A full list can be found in DebugLib.h.

For us we just want the following:

  • 0x00000002 — DEBUG_WARN in DEBUG, NOOPT, RELEASE.
  • 0x00000040 — DEBUG_INFO in DEBUG, NOOPT.
  • 0x80000000 — DEBUG_ERROR in DEBUG, NOOPT, RELEASE.

Just like with Target, we use a HEX calculator then convert to decimal:

0x80000042 Converted to decimal Misc -> Debug -> DisplayLevel -> 2147483714

Once done, your config.plist should look like this:

Disabling logging

To remove all file logging, set Target to 0