PIC

OpenCore

Reference Manual (0.6.3.4)

[2020.11.24]

Copyright ©2018-2020 vit9696

loaded by the firmware by default according to UEFI specification, and Bootstrap.efi can be registered as a custom option to let OpenCore coexist with operating systems using BOOTx64.efi as their own loaders (e.g. Windows), see BootProtect for more details.
  • boot
    Duet bootstrap loader, which initialises UEFI environment on legacy BIOS firmware and loads OpenCore.efi similarly to other bootstrap loaders. Modern Duet bootstrap loader will default to OpenCore.efi on the same partition when present.
  • ACPI
    Directory used for storing supplemental ACPI information for ?? section.
  • Drivers
    Directory used for storing supplemental UEFI drivers for ?? section.
  • Kexts
    Directory used for storing supplemental kernel information for ?? section.
  • Resources
    Directory used for storing media resources, such as audio files for screen reader support. See ?? section for more details. This directory also contains image files for graphical user interface. See ?? section for more details.
  • Tools
    Directory used for storing supplemental tools.
  • OpenCore.efi
    Main booter driver responsible for operating system loading. The directory OpenCore.efi resides is called the root directory. By default root directory is set to EFI\OC, however, when launching OpenCore.efi directly or through Bootstrap.efi, other directories containing OpenCore.efi can also be supported.
  • config.plist
    OC Config.
  • vault.plist
    Hashes for all files potentially loadable by OC Config.
  • vault.sig
    Signature for vault.plist.
  • SysReport
    Directory containing system reports generated by SysReport option.
  • 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
    0-terminator) will be accessible within OpenCore.

    3.2 Installation and Upgrade

    To install OpenCore reflect the ?? described in the previous section on a EFI volume of a GPT partition. While corresponding

    When debugging sleep issues Power Nap and automatic power off may be (temporarily) disabled, which appear to sometimes cause wake to black screen or boot loop issues on older platforms. The particular issues may vary, but in general ACPI tables should be looked up first. Here is an example of a bug found in 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 reset at hardware change and in certain other circumstances. To view their current state use pmset -g command in Terminal.

    5.2 Properties

    1. MmioWhitelist
      Type: plist array
      Description: Designed to be filled with plist dict values, describing addresses critical for particular firmware functioning when DevirtualiseMmio quirk is in use. See MmioWhitelist Properties section below.
    2. Quirks
      Type: plist dict
      Description: Apply individual booter quirks described in Quirks Properties section below.

    5.3 MmioWhitelist Properties

    1. Address
      Type: plist integer
      Failsafe: 0
      Description: Exceptional MMIO address, which memory descriptor should be left virtualised (unchanged) by DevirtualiseMmio. This means that the firmware will be able to directly communicate with this memory region during operating system functioning, because the region this value is in will be assigned a virtual address.

      The addresses written here must be part of the memory map, have EfiMemoryMappedIO type and EFI_MEMORY_RUNTIME attribute (highest bit) set. To find the list of the candidates the debug log can be used.

    2. Comment
      Type: plist string
      Failsafe: Empty string
      Description: Arbitrary ASCII string used to provide human readable reference for the entry. It is implementation defined whether this value is used.
    3. Enabled
      Type: plist boolean
      Failsafe: false
      Description: This address will be devirtualised unless set to true.

    5.4 Quirks Properties

    1. AllowRelocationBlock
      Type: plist boolean
      Failsafe: false
      Description: Allows booting macOS through a relocation block.

      Relocation block is a scratch buffer allocated in lower 4 GB to be used for loading the kernel and related structures by EfiBoot on firmwares where lower memory is otherwise occupied by the (assumed to be) non-runtime data. Right before kernel startup the relocation block is copied back to lower addresses. Similarly all the other addresses pointing to relocation block are also carefully adjusted. Relocation block can be used when:

      This quirk requires ProvideCustomSlide to also be enabled and generally needs AvoidRuntimeDefrag to work correctly. Hibernation is not supported when booting with a relocation block (but relocation block is not always used when the quirk is enabled).

      Note: While this quirk is required to run older macOS versions on platforms with used lower memory it is not compatible with some hardware and macOS 11. In this case you may try to use EnableSafeModeSlide instead.

    2. AvoidRuntimeDefrag
      Type: plist boolean
      Failsafe: false
      Description: Protect from boot.efi runtime memory defragmentation.

      This option fixes UEFI runtime services (date, time, NVRAM, power control, etc.) support on firmware that uses SMM backing for select services such as variable storage. SMM may try to access physical addresses, but they get moved by boot.efi.

      Note: Most types of firmware, apart from Apple and VMware, need this quirk.

    3. DevirtualiseMmio
      Type: plist boolean
      Failsafe: false
      Description: Remove runtime attribute from select MMIO regions.

      This option reduces stolen memory footprint from the memory map by removing runtime bit for known memory regions. This quirk may result in the increase of KASLR slides available, but is not necessarily compatible with the target board without additional measures. In general this frees from 64 to 256 megabytes of memory (present in the debug log), and on some platforms it is the only way to boot macOS, which otherwise fails with allocation error at bootloader stage.

      This option is generally useful on all types of firmware, except some very old ones such as Sandy Bridge. On some types of firmware, a list of addresses that need virtual addresses for proper NVRAM and hibernation functionality may be required. Use the MmioWhitelist section for this.

    4. DisableSingleUser
      Type: plist boolean
      Failsafe: false
      Description: Disable single user mode.

      This is a security option that restricts the activation of single user mode by ignoring CMD+S hotkey and -s boot argument. The behaviour with this quirk enabled is supposed to match T2-based model behaviour. Refer to this archived article to understand how to use single user mode with this quirk enabled.

    5.          









      macOS

      i386 NCi386 MKi386 PKx86_64 NCx86_64 MKx86_64 PKx86_64 KC








      10.4

      YES YES (V1) NO (V1)








      10.5

      YES YES (V1) NO (V1)








      10.6

      YES YES (V2)YES (V2) YES YES (V2) YES (V2)








      10.7

      YES YES (V3) YES YES (V3)








      10.8-10.9

      YES YES (V3)








      10.10-10.15

      YES (V3)








      11.011+

      YES (V3) YES








      Note: First version (V1) of 32-bit prelinkedkernel is unsupported due to kext symbol tables being corrupted by the tools. On these versions Auto will block prelinkedkernel booting. This also makes keepsyms=1 for kext frames broken on these systems.

    8 Misc

    8.1 Introduction

    This section contains miscellaneous configuration affecting OpenCore operating system loading behaviour as well as other entries, which do not go to any other section.

    OpenCore tries to follow “bless” model also known as “Apple Boot Policy”. The primary specialty of “bless” model is to allow embedding boot options within the file system (and be accessible through a specialised driver) as well as supporting a broader range of predefined boot paths compared to the removable media list found in the UEFI specification.

    Each partition will only be used for booting when it corresponds to “Scan policy”: a set of restrictions to only use partitions with specific file systems and from specific device types. Scan policy behaviour is discussed in ScanPolicy property description.

    Scan process starts with obtaining all the partitions filtered with “Scan policy”. Each partition may produce multiple primary and alternate options. Primary options describe operating systems installed on this media. Alternate options describe recovery options for the operating systems on the media. It is possible for alternate options to exist without primary options and vice versa. Be warned that the options may not necessarily describe the operating systems on the same partition. Each primary and alternate option can be an auxiliary option or not, refer to HideAuxiliary for more details. Algorithm to determine boot options behaves as follows:

    1. Obtain all available partition handles filtered by “Scan policy” (and driver availability).
    2. Obtain all available boot options from BootOrder UEFI variable.
    3. For each found boot option:

      Apple Secure Boot appeared in macOS 10.13 on models with T2 chips. Since PlatformInfo and SecureBootModel are independent, Apple Secure Boot can be used with any SMBIOS with and without T2. Setting SecureBootModel to any valid value but Disabled is equivalent to Medium Security of Apple Secure Boot. The ApECID value must also be specified to achieve Full Security. Check ForceSecureBootScheme when using Apple Secure Boot on a virtual machine.

      Enabling Apple Secure Boot is more demanding to incorrect configurations, buggy macOS installations, and unsupported setups. Things to consider:

      1. As with T2 Macs, unsigned kernel drivers and several signed kernel drivers, including NVIDIA Web Drivers, cannot be installed.
      2. The list of cached drivers may be different, resulting in the need to change the list of Added or Forced kernel drivers. For example, IO80211Family cannot be injected in this case.
      3. System volume alterations on operating systems with sealing, such as macOS 11, may result in the operating system being unbootable. Do not try to disable system volume encryption unless Apple Secure Boot is disabled.
      4. If the platform requires certain settings, but they were not enabled, because the obvious issues did not trigger before, boot failure might occur. Be extra careful with IgnoreInvalidFlexRatio or HashServices.
      5. Operating systems released before Apple Secure Boot landed (e.g. macOS 10.12 or earlier) will still boot until UEFI Secure Boot is enabled. This is so, because from Apple Secure Boot point they are treated as incompatible and are assumed to be handled by the firmware as Microsoft Windows is.
      6. On older CPUs (e.g. before Sandy Bridge) enabling Apple Secure Boot might cause slightly slower loading by up to 1 second.
      7. Since Default value will increase with time to support the latest major release operating system, it is not recommended to use ApECID and Default value together.

      Sometimes the already installed operating system may have outdated Apple Secure Boot manifests on the Preboot partition causing boot failure. If there is “OCB: Apple Secure Boot prohibits this boot entry, enforcing!” message, it is likely the case. When this happens, either reinstall the operating system or copy the manifests (files with .im4m extension, such as boot.efi.j137.im4m) from /usr/standalone/i386 to /Volumes/Preboot/<UUID>/System/Library/CoreServices. Here <UUID> is the system volume identifier. On HFS+ installations the manifests should be copied to /System/Library/CoreServices on the system volume.

      For more details on how to configure Apple Secure Boot with UEFI Secure Boot refer to ?? section.

    8.6 Entry Properties

    1. Arguments
      Type: plist string
      Failsafe: Empty string
      Description: Arbitrary ASCII string used as boot arguments (load options) of the specified entry.
    2. Auxiliary
      Type: plist boolean
      Failsafe: false
      Description: This entry will not be listed by default when HideAuxiliary is set to true.
    3. Comment
      Type: plist string
      Failsafe: Empty string
      Description: Arbitrary ASCII string used to provide human readable reference for the entry. It is implementation defined whether this value is used.
    4. Enabled
      Type: plist boolean
      Failsafe: false
      Description: This entry will not be listed unless set to true.
    5. Name
      Type: plist string
      Failsafe: Empty string
      Description: Human readable entry name displayed in boot picker.
    6. Path
      Type: plist string
      Failsafe: Empty string
      Description: Entry location depending on entry type.
    7. RealPath
      Type: plist boolean
      Failsafe: false
      Description: Pass full path to the tool when launching.

      Passing tool directory may be unsafe for tool accidentally trying to access files without checking their integrity and thus should generally be disabled. Reason to enable this property may include cases where tools cannot work without external files or may need them for better function (e.g. memtest86 for logging and configuration or Shell for automatic script execution).

      Note: This property is only valid for Tools. For Entries this property cannot be specified and is always true.

    8. TextMode
      Type: plist boolean
      Failsafe: false
      Description: Run the entry in text mode instead of graphics mode.

      This setting may be benefitial to some older tools that require text output. By default all the tools are launched in graphics mode. Read more about text modes in ?? section below.

    9 NVRAM

    9.1 Introduction

    Has plist dict type and allows to set volatile UEFI variables commonly referred as NVRAM variables. Refer to man nvram for more details. macOS extensively uses NVRAM variables for OS — Bootloader — Firmware intercommunication, and thus supplying several NVRAM is required for proper macOS functioning.

    Each NVRAM variable consists of its name, value, attributes (refer to UEFI specification), and its GUID, representing which ‘section’ NVRAM variable belongs to. macOS uses several GUIDs, including but not limited to:

    Note: Some of the variables may be added by ?? or ?? subsections of ?? section. Please ensure that variables of this section never collide with them, as behaviour is undefined otherwise.

    For proper macOS functioning it is often required to use OC_FIRMWARE_RUNTIME protocol implementation currently offered as a part of OpenRuntime driver. While it brings any benefits, there are certain limitations which arise depending on the use.

    1. Not all tools may be aware of protected namespaces.
      When RequestBootVarRouting is used Boot-prefixed variable access is restricted and protected in a separate namespace. To access the original variables tools have to be aware of OC_FIRMWARE_RUNTIME logic.

    9.2 Properties

    1. Add
      Type: plist dict
      Description: Sets NVRAM variables from a map (plist dict) of GUIDs to a map (plist dict) of variable names and their values in plist metadata format. GUIDs must be provided in canonic string format in upper or lower case (e.g. 8BE4DF61-93CA-11D2-AA0D-00E098032B8C). decoded keyboard list from AppleKeyboardLayouts-L.dat can be found here. Using non-latin keyboard on 10.14 will not enable ABC keyboard, unlike previous and subsequent macOS versions, and is thus not recommended in case 10.14 is needed.
    2. 7C436110-AB2A-4BBB-A880-FE41995C9F82:security-mode ASCII string defining FireWire security mode. Legacy, can be found in IOFireWireFamily source code in IOFireWireController.cpp. It is recommended not to set this variable, which may speedup system startup. Setting to full is equivalent to not setting the variable and none disables FireWire security.
    3. 4D1EDE05-38C7-4A6A-9CC6-4BCCA8B38C14:UIScale One-byte data defining boot.efi user interface scaling. Should be 01 for normal screens and 02 for HiDPI screens.
    4. 4D1EDE05-38C7-4A6A-9CC6-4BCCA8B38C14:DefaultBackgroundColor Four-byte BGRA data defining boot.efi user interface background colour. Standard colours include BF BF BF 00 (Light Gray) and 00 00 00 00 (Syrah Black). Other colours may be set at user’s preference.
    5. 9.5 Other Variables

      The following variables may be useful for certain configurations or troubleshooting: