PIC

OpenCore

Reference Manual (0.7.5.6)

[2021.12.01]

Copyright ©2018-2021 vit9696

MacPro5,1 as well as on certain Insyde firmware without garbage collection or with defective garbage collection.

  • ProtectUefiServices
    Type: plist boolean
    Failsafe: false
    Description: Protect UEFI services from being overridden by the firmware.

    Some modern firmware, including on virtual machines such as VMware, may update pointers to UEFI services during driver loading and related actions. Consequently, this directly obstructs other quirks that affect memory management, such as DevirtualiseMmio, ProtectMemoryRegions, or RebuildAppleMemoryMap, and may also obstruct other quirks depending on the scope of such.

    GRUB shim makes similar on-the-fly changes to various UEFI image services, which are also protected against by this quirk.

    Note 1: On VMware, the need for this quirk may be determined by the appearance of the “Your Mac OS guest might run unreliably with more than one virtual core.” message.

    Note 2: This quirk is needed for correct operation if OpenCore is chainloaded from GRUB with BIOS Secure Boot enabled.

  • ProvideCustomSlide
    Type: plist boolean
    Failsafe: false
    Description: Provide custom KASLR slide on low memory.

    This option performs memory map analysis of the firmware and checks whether all slides (from 1 to 255) can be used. As boot.efi generates this value randomly with rdrand or pseudo randomly rdtsc, there is a chance of boot failure when it chooses a conflicting slide. In cases where potential conflicts exist, this option forces macOS to select a pseudo random value from the available values. This also ensures that the slide= argument is never passed to the operating system (for security reasons).

    Note: The need for this quirk is determined by the OCABC: Only N/256 slide values are usable! message in the debug log.

  • ProvideMaxSlide
    Type: plist integer
    Failsafe: 0
    Description: Provide maximum KASLR slide when higher ones are unavailable.

    This option overrides the maximum slide of 255 by a user specified value between 1 and 254 (inclusive) when ProvideCustomSlide is enabled. It is assumed that modern firmware allocates pool memory from top to bottom, effectively resulting in free memory when slide scanning is used later as temporary memory during kernel loading. When such memory is not available, this option stops the evaluation of higher slides.

    Note: The need for this quirk is determined by random boot failures when ProvideCustomSlide is enabled and the randomized slide falls into the unavailable range. When AppleDebug is enabled, the debug log typically contains messages such as AAPL: [EB|‘LD:LKC] } Err(0x9). To find the optimal value, append slide=X, where X is the slide value, to the boot-args and select the largest one that does not result in boot failures.

  • RebuildAppleMemoryMap
    Type: plist boolean
    Failsafe: false
    Description: Generate macOS compatible Memory Map.

    The Apple kernel has several limitations on parsing the UEFI memory map:

    To workaround these limitations, this quirk applies memory attribute table permissions to the memory map passed to the Apple kernel and optionally attempts to unify contiguous slots of similar types if the resulting memory map exceeds 4 KB.

    Note 1: Since several types of firmware come with incorrect memory protection tables, this quirk often comes paired with SyncRuntimePermissions.

    Note 2: The need for this quirk is determined by early boot failures. This quirk replaces EnableWriteUnprotector on firmware supporting Memory Attribute Tables (MAT). This quirk is typically unnecessary when using OpenDuetPkg but may be required to boot macOS 10.6, and earlier, for reasons that are as yet unclear.

  • ResizeAppleGpuBars
    Type: plist integer
    Failsafe: -1
    Description: Reduce GPU PCI BAR sizes for compatibility with macOS.

    This quirk reduces GPU PCI BAR sizes for Apple macOS up to the specified value or lower if it is unsupported. The specified value follows PCI Resizable BAR spec. Use 0 for 1 MB, 1 for 2 MB, 2 for 4 MB, and so on up to 19 for 512 GB. While Apple macOS supports a theoretical 1 GB maximum, which is 10.in practice all non-default values may not work correctly. For this reason the only supported value for this quirk is the minimal supported BAR size, i.e. 0. Use -1 to disable this quirk.

    For development purposes one may take risks and try other values. Consider a GPU with 2 BARs:

    Example 1: Setting ResizeAppleGpuBars to 1 GB will change BAR0 to 1 GB and leave BAR1 unchanged.
    Example 2: Setting ResizeAppleGpuBars to 1 MB will change BAR0 to 256 MB and BAR0 to 2 MB.
    Example 3: Setting ResizeAppleGpuBars to 16 GB will make no changes.

    Note1: See ResizeGpuBars quirk for general GPU PCI BAR size configuration and more details about the technology.

    Note 2: Certain GPU drivers do not support non-standard BAR sizes, causing sleep wake issues, for this reason for macOS it is recommended to use minimal supported BAR sizes, i.e. specify 0 (1 MB).

  • SetupVirtualMap
    Type: plist boolean
    Failsafe: false
    Description: Setup virtual memory at SetVirtualAddresses.

    Some types of firmware access memory by virtual addresses after a SetVirtualAddresses call, resulting in early boot crashes. This quirk workarounds the problem by performing early boot identity mapping of assigned virtual addresses to physical memory.

    Note: The need for this quirk is determined by early boot failures.

  • SignalAppleOS
    Type: plist boolean
    Failsafe: false
    Description: Report macOS being loaded through OS Info for any OS.

    This quirk is useful on Mac firmware, which loads different operating systems with different hardware configurations. For example, it is supposed to enable Intel GPU in Windows and Linux in some dual-GPU MacBook models.

  • 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 (note: includes halt at black screen as well as more obvious crash). Particularly likely to affect early boot of Windows or Linux (but not always both) on affected systems. Only firmware released after 2017 is typically affected.

    8.5 Security Properties

    1. AllowNvramReset
      Type: plist boolean
      Failsafe: false
      Description: Allow CMD+OPT+P+R handling and enable showing NVRAM Reset entry in OpenCore picker.

      Note 1: It is known that some Lenovo laptops have a firmware bug, which makes them unbootable after performing NVRAM reset. Refer to acidanthera/bugtracker#995 for details.

      Note 2: Resetting NVRAM will also erase any boot options not backed up using the bless command. For example, Linux installations to custom locations not specified in BlessOverride

    2. AllowSetDefault
      Type: plist boolean
      Failsafe: false
      Description: Allow CTRL+Enter and CTRL+Index handling to set the default boot option in the OpenCore picker.

      Note 1: May be used in combination with Shift+Enter or Shift+Index when PollAppleHotKeys is enabled.

      Note 2: In order to support systems with unresponsive modifiers during preboot (which includes V1 and V2 KeySupport mode on some firmware) OpenCore also allows holding the =/+ key in order to trigger ‘set default’ mode.

    3. AllowToggleSip
      Type: plist boolean
      Failsafe: false
      Description: Enable entry for disabling and enabling System Integrity Protection in OpenCore picker.

      This will toggle Apple NVRAM variable csr-active-config between 0 for SIP Enabled and a practical default value for SIP Disabled (currently 0x26F).

      Note 1: It is strongly recommended not to make a habit of running macOS with SIP disabled. Use of this boot option may make it easier to quickly disable SIP protection when genuinely needed - it should be re-enabled again afterwards.

      Note 2: OC OpenCore uses 0x26F even though csrutil disable on Big Sur sets 0x7F. To explain the choice:

      • csrutil disable --no-internal actually sets 0x6F, and this is preferable because CSR_ALLOW_APPLE_INTERNAL (0x10) prevents updates (unless you are running an internal build of macOS).

      • CSR_ALLOW_UNAPPROVED_KEXTS (0x200) is generally useful, in the case where you do need to have SIP disabled, as it allows installing unsigned kexts without manual approval in System Preferences.

      • CSR_ALLOW_UNAUTHENTICATED_ROOT (0x800) is not practical as it prevents incremental (non-full) OTA

        Note: This functionality is still under development and is not ready for production environments.

      • ExposeSensitiveData
        Type: plist integer
        Failsafe: 0x6
        Description: Sensitive data exposure bitmask (sum) to operating system.

        • 0x01 — Expose the printable booter path as an a UEFI variable.

        • 0x02 — Expose the OpenCore version as an a UEFI variable.

        • 0x04 — Expose the OpenCore version in the OpenCore picker menu title.

        • 0x08 — Expose OEM information as a set of UEFI variables.

        The exposed booter path points to OpenCore.efi or its booter depending on the load order. To obtain the booter path, use the following command in macOS:

        nvram 4D1FDA02-38C7-4A6A-9CC6-4BCCA8B30102:boot-path

        To use a booter path to mount a booter volume, use the following command in macOS:

        u=$(nvram 4D1FDA02-38C7-4A6A-9CC6-4BCCA8B30102:boot-path | sed 's/.*GPT,\([^,]*\),.*/\1/'); \ 
          if [ "$u" != "" ]; then sudo diskutil mount $u ; fi

        To obtain the current OpenCore version, use the following command in macOS:

        nvram 4D1FDA02-38C7-4A6A-9CC6-4BCCA8B30102:opencore-version

        If the OpenCore version is not exposed the variable will contain UNK-000-0000-00-00 sequence.

        To obtain OEM information, use the following commands in macOS:

        nvram 4D1FDA02-38C7-4A6A-9CC6-4BCCA8B30102:oem-product # SMBIOS Type1 ProductName 
        nvram 4D1FDA02-38C7-4A6A-9CC6-4BCCA8B30102:oem-vendor  # SMBIOS Type2 Manufacturer 
        nvram 4D1FDA02-38C7-4A6A-9CC6-4BCCA8B30102:oem-board   # SMBIOS Type2 ProductName
      • HaltLevel
        Type: plist integer, 64 bit
        Failsafe: 0x80000000 (DEBUG_ERROR)
        Description: EDK II debug level bitmask (sum) causing CPU to halt (stop execution) after obtaining a message of HaltLevel. Possible values match DisplayLevel values.