Debug
-
AppleDebugType:plist booleanFailsafe:falseDescription: Enable writing theboot.efidebug log to the OpenCore log.Note: This option only applies to 10.15.4 and newer.
-
ApplePanicType:plist booleanFailsafe:falseDescription: Save macOS kernel panic output to the OpenCore root partition.The file is saved as
panic-YYYY-MM-DD-HHMMSS.txt. It is strongly recommended to set thekeepsyms=1boot argument to see debug symbols in the panic log. In cases where it is not present, thekpdescribe.shutility (bundled with OpenCore) may be used to partially recover the stacktrace.Development and debug kernels produce more useful kernel panic logs. Consider downloading and installing the
KernelDebugKitfrom developer.apple.com when debugging a problem. To activate a development kernel, the boot argumentkcsuffix=developmentshould be added. Use theuname -acommand to ensure that the current loaded kernel is a development (or a debug) kernel.In cases where the OpenCore kernel panic saving mechanism is not used, kernel panic logs may still be found in the
/Library/Logs/DiagnosticReportsdirectory.Starting with macOS Catalina, kernel panics are stored in JSON format and thus need to be preprocessed before passing to
kpdescribe.sh:cat Kernel.panic | grep macOSProcessedStackshotData | python3 -c 'import json,sys;print(json.load(sys.stdin)["macOSPanicString"])' -
DisableWatchDogType:plist booleanFailsafe:falseDescription: Some types of firmware may not succeed in booting the operating system quickly, especially in debug mode. This results in the watchdog timer aborting the process. This option turns off the watchdog timer. -
DisplayDelayType:plist integerFailsafe:0Description: Delay in microseconds executed after every printed line visible onscreen (i.e. console). -
DisplayLevelType:plist integer, 64 bit Failsafe:0Description: EDK II debug level bitmask (sum) showed onscreen. UnlessTargetenables console (onscreen) printing, onscreen debug output will not be visible. The following levels are supported (discover more in DebugLib.h):0x00000002(bit1) —DEBUG_WARNinDEBUG,NOOPT,RELEASE.0x00000040(bit6) —DEBUG_INFOinDEBUG,NOOPT.0x00400000(bit22) —DEBUG_VERBOSEin custom builds.0x80000000(bit31) —DEBUG_ERRORinDEBUG,NOOPT,RELEASE.
-
LogModulesType:plist stringFailsafe:*Description: Filter log entries by module.This option filters logging generated by specific modules, both in the log and onscreen. Two modes are supported:
+- Positive filtering: Only present selected modules.-- Negative filtering: Exclude selected modules.
When multiple ones are selected, comma (
,) should be used as the splitter. For instance,+OCCPU,OCA,OCBmeans onlyOCCPU,OCA,OCBbeing printed, while-OCCPU,OCA,OCBindicates these modules being filtered out (i.e. not logged). When no symbol is specified, positive filtering (+) will be used.*indicates all modules being logged.Note 1: Acronyms of libraries can be found in the Libraries section below.
Note 2: Messages printed before the configuration of log protocol cannot be filtered.
-
SysReportType:plist booleanFailsafe:falseDescription: Produce system report on ESP folder.This option will create a
SysReportdirectory in the ESP partition unless already present. The directory will contain ACPI, SMBIOS, and audio codec dumps. Audio codec dumps require an audio backend driver to be loaded.Note: To maintain system integrity, the
SysReportoption is not available inRELEASEbuilds. Use aDEBUGbuild if this option is required. -
TargetType:plist integerFailsafe:0Description: A bitmask (sum) of enabled logging targets. Logging output is hidden by default and this option must be set when such output is required, such as when debugging.The following logging targets are supported:
0x01(bit0) — Enable logging, otherwise all log is discarded. - 0x02 (bit 1) — Enable basic console (onscreen) logging.0x04(bit2) — Enable logging to Data Hub.0x08(bit3) — Enable serial port logging.0x10(bit4) — Enable UEFI variable logging.0x20(bit5) — Enablenon-volatileUEFI variable logging.0x40(bit6) — Enable logging to file.0x80(bit7) — In combination with0x40, enable faster but unsafe (see Warning 2 below) file logging.
Console logging prints less than the other variants. Depending on the build type (
RELEASE,DEBUG, orNOOPT) different amount of logging may be read (from least to most).To obtain Data Hub logs, use the following command in macOS (Note that Data Hub logs do not log kernel and kext patches):
ioreg -lw0 -p IODeviceTree | grep boot-log | sort | sed 's/.*<\(.*\)>.*/\1/' | xxd -r -pUEFI variable log does not include some messages and has no performance data. To maintain system integrity, the log size is limited to 32 kilobytes. Some types of firmware may truncate it much earlier or drop completely if they have no memory. Using the
non-volatileflag will cause the log to be written to NVRAM flash after every printed line.To obtain UEFI variable logs, use the following command in macOS:
nvram 4D1FDA02-38C7-4A6A-9CC6-4BCCA8B30102:boot-log | awk '{gsub(/%0d%0a%00/,"");gsub(/%0d%0a/,"\n")}1'Warning 1: Certain firmware appear to have defective NVRAM garbage collection. As a result, they may not be able to always free space after variable deletion. Do not enable non-volatile NVRAM logging on such devices unless specifically required.
While the OpenCore boot log already contains basic version information including build type and date, this information may also be found in the opencore-version NVRAM variable even when boot logging is disabled.
File logging will create a file named
opencore-YYYY-MM-DD-HHMMSS.txt(in UTC) under the EFI volume root with log contents (the upper case letter sequence is replaced with date and time from the firmware). Please be warned that some file system drivers present in firmware are not reliable and may corrupt data when writing files through UEFI. Log writing is attempted in the safest manner and thus, is very slow. Ensure thatDisableWatchDogis set totruewhen a slow drive is used. Try to avoid frequent use of this option when dealing with flash drives as large I/O amounts may speed up memory wear and render the flash drive unusable quicker.Warning 2: It is possible to enable fast file logging, which requires a fully compliant firmware FAT32 driver. On drivers with incorrect FAT32 write support (e.g. APTIO IV, but maybe others) this setting can result in corruption up to and including an unusable ESP filesystem, therefore be prepared to recreate the ESP partition and all of its contents if testing this option. This option can increase logging speed significantly on some suitable firmware, but may make little speed difference on some others.
When interpreting the log, note that the lines are prefixed with a tag describing the relevant location (module) of the log line allowing better attribution of the line to the functionality.
The list of currently used tags is as follows.
### Drivers and tools
BMF— OpenCanopy, bitmap fontBS— BootstrapGSTT— GoptStopHDA— AudioDxeKKT— KeyTesterLNX— OpenLinuxBootMMDD— MmapDumpOCPAVP— PavpProvisionOCRST— ResetSystemOCUI— OpenCanopyOC— OpenCore main, also OcMainLibVMOPT— VerifyMemOpt
### Libraries
AAPL— OcLogAggregatorLib, Apple EfiBoot loggingOCABC— OcAfterBootCompatLibOCAE— OcAppleEventLibOCAK— OcAppleKernelLibOCAU— OcAudioLibOCA—- OcAcpiLibOCBP— OcAppleBootPolicyLibOCB— OcBootManagementLibOCLBT— OcBlitLibOCCL— OcAppleChunkListLibOCCPU— OcCpuLibOCC— OcConsoleLibOCDC— OcDriverConnectionLibOCDH— OcDataHubLibOCDI— OcAppleDiskImageLibOCDM— OcDeviceMiscLibOCFS— OcFileLibOCFV— OcFirmwareVolumeLibOCHS— OcHashServicesLibOCI4— OcAppleImg4LibOCIC— OcImageConversionLibOCII— OcInputLibOCJS— OcApfsLibOCKM— OcAppleKeyMapLibOCL— OcLogAggregatorLibOCM— OcMiscLibOCMCO— OcMachoLibOCME— OcHeciLibOCMM— OcMemoryLibOCPE— OcPeCoffLib, OcPeCoffExtLibOCPI— OcFileLib, partition infoOCPNG— OcPngLibOCRAM— OcAppleRamDiskLibOCRTC— OcRtcLibOCSB— OcAppleSecureBootLibOCSMB— OcSmbiosLibOCSMC— OcSmcLibOCST— OcStorageLibOCS— OcSerializedLibOCTPL— OcTemplateLibOCUC— OcUnicodeCollationLibOCUT— OcAppleUserInterfaceThemeLibOCVAR— OcVariableLibOCXML— OcXmlLib