PIC

OpenCore

Reference Manual (0.7.3.4)

[2021.09.26]

Copyright ©2018-2021 vit9696

nvram.plist
OpenCore variable import file.

  • opencore-YYYY-MM-DD-HHMMSS.txt
    OpenCore log file.

  • panic-YYYY-MM-DD-HHMMSS.txt
    Kernel panic log file.

  • Note: It is not guaranteed that paths longer than OC_STORAGE_SAFE_PATH_MAX (128 characters including the
    0-terminator) will be accessible within OpenCore.

    3.2 Installation and Upgrade

    To install OpenCore, replicate the ?? described in the previous section in the EFI volume of a GPT partition. While corresponding sections of this document provide some information regarding external resources such as ACPI tables, UEFI drivers, or kernel extensions (kexts), completeness of the matter is out of the scope of this document. Information about kernel extensions may be found in a separate Kext List document available in the OpenCore repository. Vaulting information is provided in the ?? section of this document.

    The OC config file, as with any property list file, can be edited with any text editor, such as nano or vim. However, specialised software may provide a better experience. On macOS, the preferred GUI application is Xcode. For a lightweightThe ProperTree editor is a lightweight, cross-platform and open-source alternative, the ProperTree editor can be utilised.

    It is strongly advised not to use any software that is recommended to avoid configuration creation tools that are aware of the internal configration structure as it constantly gets out of date and will cause incorrect configuration to be generated. If it is a must desprite the warning one should make sure to only use configuration structure as this may result in invalid configurations (since the structure gets constantly updated). If such tools are to be used despite this warning, ensure that only stable versions of OpenCore with explicit support for the particular version in the app. The choice explicitly supported by such tools are used. In such cases, the use of open-source implementations with transparent binary generation is encouraged (e.g. (such as OCAT) , since is encouraged, given that other tools may contain malware. Remember that a configuration made for a different hardware setup shall In addition, configurations created for a specific hardware setup should never be used on another hardware setupdifferent hardware setups.

    For BIOS booting, a third-party UEFI environment provider is required and OpenDuetPkg is one such UEFI environment provider for legacy systems. To run OpenCore on such a legacy system, OpenDuetPkg can be installed with a dedicated tool — BootInstall (bundled with OpenCore). Third-party utilities can be used to perform this on systems other than macOS.

    For upgrade purposes, refer to the Differences.pdf document which provides information about changes to the configuration (as compared to the previous release) as well as to the Changelog.md document (which contains a list of modifications across all published updates).

    3.3 Contribution

    OpenCore can be compiled as a standard EDK II package and requires the EDK II Stable package. The currently supported EDK II release is hosted in acidanthera/audk. Required patches for this package can be found in the Patches directory.

    The only officially supported toolchain is XCODE5. Other toolchains might work but are neither supported nor recommended. Contributions of clean patches are welcome. Please do follow EDK II C Codestyle.

    To compile with XCODE5, besides Xcode, users should also install NASM and MTOC. The latest Xcode version is recommended for use despite the toolchain name. An example command sequence is as follows:

  • Above 4G Decoding or similar enabled in firmware settings if present. Note that on some motherboards, notably the ASUS WS-X299-PRO, this option results in adverse effects and must be disabled. While no other motherboards with the same issue are known, this option should be checked first whenever erratic boot failures are encountered.

  • DisableIoMapper quirk enabled, or VT-d disabled in firmware settings if present, or ACPI DMAR table deleted.

  • No ‘slide‘ boot argument present in NVRAM or anywhere else. It is not necessary unless the system cannot be booted at all or No slide values are usable! Use custom slide! message can be seen in the log.

  • CFG Lock (MSR 0xE2 write protection) disabled in firmware settings if present. Refer to the ?? notes for details.

  • CSM (Compatibility Support Module) disabled in firmware settings if present. On NVIDIA 6xx/AMD 2xx or older, GOP ROM may have to be flashed first. Use GopUpdate (see the second post) or AMD UEFI GOP MAKER in case of any potential confusion.

  • EHCI/XHCI Hand-off enabled in firmware settings only if boot stalls unless USB devices are disconnected.

  • VT-x, Hyper Threading, Execute Disable Bit enabled in firmware settings if present.

  • While it may not be required, sometimes Thunderbolt support, Intel SGX, and Intel Platform Trust may have to be disabled in firmware settings present.

  • When debugging sleep issues, Power Nap and automatic power off (which appear to sometimes cause wake to black screen or boot loop issues on older platforms) may be temporarily disabled. The specific issues may vary, but ACPI tables should typically be looked at first.

    Here is an example of a defect found on some Z68 motherboards. To turn Power Nap and the others off, run the following commands in Terminal:

    sudo pmset autopoweroff 0 
    sudo pmset powernap 0 
    sudo pmset standby 0

    Note: These settings may be reset by hardware changes and in certain other circumstances. To view their current state, use the pmset -g command in Terminal.

    5.2 Properties

    1. MmioWhitelist
      Type: plist array
      Failsafe: Empty
      Description: To be filled with plist dict values, describing addresses critical for particular firmware functioning when DevirtualiseMmio quirk is in use. Refer to the ?? section below for details.

    2. SyncRuntimePermissions
      Type: plist boolean
      Failsafe: false
      Description: Update memory permissions for the runtime environment.

      Some types of firmware fail to properly handle runtime permissions:

      This quirk attempts to update the memory map and memory attributes table to correct this.

      Note: The need for this quirk is indicated by early boot failures . (e.g. halts at black screen), particularly in early boot of the Linux kernel. Only firmware released after 2017 is typically affected.

    6 DeviceProperties

    6.1 Introduction

    Device configuration is provided to macOS with a dedicated buffer, called EfiDevicePathPropertyDatabase. This buffer is a serialised map of DevicePaths to a map of property names and their values.

    Property data can be debugged with gfxutil. To obtain current property data, use the following command in macOS:

    ioreg -lw0 -p IODeviceTree -n efi -r -x | grep device-properties | 
      sed 's/.*<//;s/>.*//' > /tmp/device-properties.hex && 
      gfxutil /tmp/device-properties.hex /tmp/device-properties.plist && 
      cat /tmp/device-properties.plist

    Device properties are part of the IODeviceTree (gIODT) plane of the macOS I/O Registry. This plane has several construction stages relevant for the platform initialisation. While the early construction stage is performed by the XNU kernel in the IODeviceTreeAlloc method, the majority of the construction is performed by the platform expert, implemented in AppleACPIPlatformExpert.kext.

    AppleACPIPlatformExpert incorporates two stages of IODeviceTree construction implemented by calling
    AppleACPIPlatformExpert::mergeDeviceProperties:

    1. During ACPI table initialisation through the recursive ACPI namespace scanning by the calls to
      AppleACPIPlatformExpert::createDTNubs.

    2. compromise the operating system, which is undesirable when secure boot is enabled.

      Note 3: Some operating systems, such as Windows, may create a boot option and mark it as the topmost option upon first boot or after NVRAM resets from within OpenCore. When this happens, the default boot entry choice will remain changed until the next manual reconfiguration.

      8.2 Properties

      1. Boot
        Type: plist dict
        Description: Apply the boot configuration described in the ?? section below.

      2. BlessOverride
        Type: plist array
        Failsafe: Empty
        Description: Add custom scanning paths through the bless model.

        To be filled with plist string entries containing absolute UEFI paths to customised bootloaders such as \EFI\debian\grubx64.efi for the Debian bootloader. This allows non-standard boot paths to be automatically discovered by the OpenCore picker. Designwise, they are equivalent to predefined blessed paths, such as \System\Library\CoreServices\boot.efi or \EFI\Microsoft\Boot\bootmgfw.efi, but unlike predefined bless paths, they have the highest priority.

      3. Debug
        Type: plist dict
        Description: Apply debug configuration described in the ?? section below.

      4. Entries
        Type: plist array
        Failsafe: Empty
        Description: Add boot entries to OpenCore picker.

        To be filled with plist dict values, describing each load entry. Refer to the ?? section below for details.

      5. Security
        Type: plist dict
        Description: Apply the security configuration described in the ?? section below.

      6. Tools