PIC

OpenCore

Reference Manual (0.6.90.7.0)

[2021.06.17]

Copyright ©2018-2021 vit9696

  • Identifier
    Type: plist string
    Failsafe: Empty
    Description: Kext bundle identifier (e.g. com.apple.driver.AppleTyMCEDriver).
  • MaxKernel
    Type: plist string
    Failsafe: Empty
    Description: Blocks kernel extension on specified macOS version or older.

    Note: Refer to the Add MaxKernel description for matching logic.

  • MinKernel
    Type: plist string
    Failsafe: Empty
    Description: Blocks kernel extension on specified macOS version or newer.

    Note: Refer to the Add MaxKernel description for matching logic.

  • 7.5 Emulate Properties

    1. Cpuid1Data
      Type: plist data, 16 bytes
      Failsafe: All zero
      Description: Sequence of EAX, EBX, ECX, EDX values to replace CPUID (1) call in XNU kernel.

      This property primarily meets three requirements:

      Note 1: It may also be the case that the CPU model is supported but there is no power management supported (e.g. virtual machines). In this case, MinKernel and MaxKernel can be set to restrict CPU virtualisation and dummy power management patches to the particular macOS kernel version.

      Note 2: Only the value of EAX, which represents the full CPUID, typically needs to be accounted for and remaining bytes should be left as zeroes. The byte order is Little Endian. For example, C3 06 03 00 stands for CPUID 0x0306C3 (Haswell).

      Note 3: For XCPM support it is recommended to use the following combinations.

      Note 4: Be aware that the following configurations are unsupported by XCPM (at least out of the box):

    2. Cpuid1Mask
      Type: plist data, 16 bytes
      Failsafe: All zero
      Description: Bit mask of active bits in Cpuid1Data.

      When each Cpuid1Mask bit is set to 0, the original CPU bit is used, otherwise set bits take the value of Cpuid1Data.

    3. DummyPowerManagement
      Type: plist boolean
      Failsafe: false
      Requirement: 10.4
      Description: Disables AppleIntelCpuPowerManagement.

      Note 1: This option is a preferred alternative to NullCpuPowerManagement.kext for CPUs without native power management driver in macOS.

      Note 2: While this option is typically needed to disable AppleIntelCpuPowerManagement on unsupported platforms, it can also be used to disable this kext in other situations (e.g. with Cpuid1Data left blank).

    4. MaxKernel
      Type: plist string
      Failsafe: Empty
      Description: Emulates CPUID and applies DummyPowerManagement on specified macOS version or older.

      Note: Refer to the Add MaxKernel description for matching logic.

    5. MinKernel
      Type: plist string
      Failsafe: Empty
      Description: Emulates CPUID and applies DummyPowerManagement on specified macOS version or newer.

      Note: Refer to the Add MaxKernel description for matching logic.

  • IncreasePciBarSize
    Type: plist boolean
    Failsafe: false
    Requirement: 10.10
    Description: Increases 32-bit PCI bar size in IOPCIFamily from 1 to 4 GBs.

    Note: This option should be avoided whenever possible. A need for this option indicates misconfigured or defective firmware.

  • LapicKernelPanic
    Type: plist boolean
    Failsafe: false
    Requirement: 10.6 (64-bit)
    Description: Disables kernel panic on LAPIC interrupts.
  • LegacyCommpage
    Type: plist boolean
    Failsafe: false
    Requirement: 10.4 - 10.6
    Description: Replaces the default 64-bit commpage bcopy implementation with one that does not require SSSE3, useful for legacy platforms. This prevents a commpage no match for last panic due to no available 64-bit bcopy functions that do not require SSSE3.
  • PanicNoKextDump
    Type: plist boolean
    Failsafe: false
    Requirement: 10.13 (not required for older)
    Description: Prevent kernel from printing kext dump in the panic log preventing from observing panic details. Affects 10.13 and above.
  • PowerTimeoutKernelPanic
    Type: plist boolean
    Failsafe: false
    Requirement: 10.15 (not required for older)
    Description: Disables kernel panic on setPowerState timeout.

    An additional security measure was added to macOS Catalina (10.15) causing kernel panic on power change timeout for Apple drivers. Sometimes it may cause issues on misconfigured hardware, notably digital audio, which sometimes fails to wake up. For debug kernels setpowerstate_panic=0 boot argument should be used, which is otherwise equivalent to this quirk.

  • ProvideCurrentCpuInfo
    Type: plist boolean
    Failsafe: false
    Requirement: 10.8
    Description: Provides current CPU info to the kernel.

    This quirk currently provides the correct TSC and FSB values to the kernel, as well as disables CPU topology validation.

    Note: These patches currently target Microsoft Hyper-V and may need to be extended for other purposes.

  • SetApfsTrimTimeout
    Type: plist integer
    Failsafe: -1
    Description: Register the launcher option in the firmware preferences for persistence.

    Valid values:

    This option allows integration with third-party operating system installation and upgrades (which may overwrite the \EFI\BOOT\BOOTx64.efi file). The BOOTx64.efi file is no longer used for bootstrapping OpenCore if a custom option is created. The custom path used for bootstrapping can be specified by using the LauncherPath option.

    Note 1: Some types of firmware may have NVRAM implementation flaws, no boot option support, or other incompatibilities. While unlikely, the use of this option may result in boot failures and should only be used exclusively on boards known to be compatible. Refer to acidanthera/bugtracker#1222 for some known issues affecting Haswell and other boards.

    Note 2: While NVRAM resets executed from OpenCore would not typically erase the boot option created in Bootstrap, executing NVRAM resets prior to loading OpenCore will erase the boot option. Therefore, for significant implementation updates, such as was the case with OpenCore 0.6.4, an NVRAM reset should be executed with Bootstrap disabled, after which it can be re-enabled.

  • LauncherPath
    Type: plist string
    Failsafe: Default
    Description: Launch path for the LauncherOption property.

    Default points to OpenCore.efi. User specified paths, e.g. \EFI\SomeLauncher.efi, can be used to provide custom loaders, which are supposed to load OpenCore.efi themselves.

  • PickerAttributes
    Type: plist integer
    Failsafe: 0
    Description: Sets specific attributes for the OpenCore picker.

    Different OpenCore pickers may be configured through the attribute mask containing OpenCore-reserved (BIT0~BIT15) and OEM-specific (BIT16~BIT31) values.

    Current OpenCore values include:

  • PickerAudioAssist
    Type: plist boolean
    Failsafe: false
    Description: Enable screen reader by default in the OpenCore picker.

    For the macOS bootloader, screen reader preference is set in the preferences.efires archive in the isVOEnabled.int32 file and is controlled by the operating system. For OpenCore screen reader support, this option is an independent equivalent. Toggling screen reader support in both the OpenCore picker and the macOS bootloader FileVault 2 login window can also be done by using the Command + F5 key combination.

  • PickerVariant
    Type: plist string
    Failsafe: Auto
    Description: Choose specific icon set to be used for boot management.

    The following values are supportedAn icon set is a directory path relative to Resources\Image, where the icons and an optional manifest are located. It is recommended for the artists to use provide their sets in the Vendor\Set format, e.g. Acidanthera\GoldenGate.

    Sample resources provided as a part of OcBinaryData repository provide the following icon set:

    For convenience purposes there also are predefined aliases:

  • 8.4 Debug Properties

    1. AppleDebug
      Type: plist boolean
      Failsafe: false
      Description: Enable writing the boot.efi debug log to the OpenCore log.

      Note: This option only applies to 10.15.4 and newer.

    2. ApplePanic
      Type: plist boolean
      Failsafe: false
      Description: 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 the keepsyms=1 boot argument to see debug symbols in the panic log. In cases where it is not present, the kpdescribe.sh utility (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 KernelDebugKit from developer.apple.com when debugging a problem. To activate a development kernel, the boot argument kcsuffix=development should be added. Use the uname -a command 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/DiagnosticReports directory.

      Starting with macOS Catalina, kernel panics are stored in JSON format and thus need to be preprocessed before passing to kpdescribe.sh:

      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 that DisableWatchDog is set to true when 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.

      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:

      Libraries:

    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).

      Note1: 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.

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

      Note3: For any other value which you may need to use, it is possible to configure CsrUtil.efi as a TextMode Tools entry to configure a different value, e.g. use toggle 0x6F in Arguments to toggle the SIP disabled value set by default by csrutil disable --no-internal in Big Sur.

    4. ApECID
      Type: plist integer, 64 bit
      Failsafe: 0
      Description: Apple Enclave Identifier.

      Setting this value to any non-zero 64-bit integer will allow using personalised Apple Secure Boot identifiers. To use this setting, generate a random 64-bit number with a cryptographically secure random number generator. As an alternative, the first 8 bytes of SystemUUID can be used for ApECID, this is found in macOS 11 for Macs without the T2 chip.

      With this value set and SecureBootModel valid (and not Disabled), it is possible to achieve Full Security of Apple Secure Boot.

      To start using personalised Apple Secure Boot, the operating system must be reinstalled or personalised. Unless the operating system is personalised, macOS DMG recovery cannot be loaded. In cases where DMG recovery is missing, it can be downloaded by using the macrecovery utility and saved in com.apple.recovery.boot as explained in the ?? section. Note that ?? needs to be set to Signed to use any DMG with Apple Secure Boot.

      To personalise an existing operating system, use the bless command after loading to macOS DMG recovery. Mount the system volume partition, unless it has already been mounted, and execute the following command:

      bless bless --folder "/Volumes/Macintosh HD/System/Library/CoreServices" \ 
        --bootefi --personalize

      On macOS versions before macOS 11, which introduced a dedicated x86legacy model for models without the T2 chip, personalised Apple Secure Boot may not work as expected. When reinstalling the operating system, the macOS Installer from macOS 10.15 and older will often run out of free memory on the /var/tmp partition when trying to install macOS with the personalised Apple Secure Boot. Soon after downloading the macOS installer image, an Unable to verify macOS error message will appear.

      To workaround this issue, allocate a dedicated RAM disk of 2 MBs for macOS personalisation by entering the following commands in the macOS recovery terminal before starting the installation:

      disk=$(hdiutil attach -nomount ram://4096) 
      diskutil erasevolume HFS+ SecureBoot $disk 
      diskutil unmount $disk 
      mkdir /var/tmp/OSPersonalizationTemp 
      diskutil mount -mountpoint /var/tmp/OSPersonalizationTemp $disk
    5. AuthRestart
      Type: plist boolean                              
       escription: To be filled with plist dict values, describing memory areas exclusive to specific firmware and hardware functioning, which should not be used by the operating system. Examples of such memory regions could be the second 256 MB corrupted by the Intel HD 3000 or an area with faulty RAM. Refer to the ?? section below for details.

    11.7 APFS Properties

    1. EnableJumpstart
      Type: plist boolean
      Failsafe: false
      Description: Load embedded APFS drivers from APFS containers.

      An APFS EFI driver is bundled in all bootable APFS containers. This option performs the loading of signed APFS drivers (consistent with the ScanPolicy). Refer to the “EFI Jumpstart” section of the Apple File System Reference for details.

    2. GlobalConnect
      Type: plist boolean
      Failsafe: false
      Description: Perform full device connection during APFS loading.

      Every handle is connected recursively instead of the partition handle connection typically used for APFS driver loading. This may result in additional time being taken but can sometimes be the only way to access APFS partitions on certain firmware, such as those on older HP laptops.

    3. HideVerbose
      Type: plist boolean
      Failsafe: false
      Description: Hide verbose output from APFS driver.

      APFS verbose output can be useful for debugging.

    4. JumpstartHotPlug
      Type: plist boolean
      Failsafe: false
      Description: Load APFS drivers for newly connected devices.

      Permits APFS USB hot plug which enables loading APFS drivers, both at OpenCore startup and during OpenCore picker dusplaydisplay. Disable if not required.

    5. MinDate
      Type: plist integer
      Failsafe: 0
      Description: Minimal allowed APFS driver date.

      The APFS driver date connects the APFS driver with the calendar release date. Apple ultimately drops support for older macOS releases and APFS drivers from such releases may contain vulnerabilities that can be used to compromise a computer if such drivers are used after support ends. This option permits restricting APFS drivers to current macOS versions.

    11.12 ProtocolOverrides Properties

    1. AppleAudio
      Type: plist boolean
      Failsafe: false
      Description: Replaces Apple audio protocols with builtin versions.

      Apple audio protocols allow OpenCore and the macOS bootloader to play sounds and signals for screen reading or audible error reporting. Supported protocols are beep generation and VoiceOver. The VoiceOver protocol is specific to Gibraltar machines (T2) and is not supported before macOS High Sierra (10.13). Older macOS versions use the AppleHDA protocol (which is not currently implemented) instead.

      Only one set of audio protocols can be available at a time, so this setting should be enabled in order to enable audio playback in the OpenCore user interface on Mac systems implementing some of these protocols.

      Note: The backend audio driver needs to be configured in UEFI Audio section for these protocols to be able to stream audio.

    2. AppleBootPolicy
      Type: plist boolean
      Failsafe: false
      Description: Replaces the Apple Boot Policy protocol with a builtin version. This may be used to ensure APFS compatibility on VMs and legacy Macs.

      Note: This option is advisable on certain Macs, such as the MacPro5,1, that are APFS compatible but on which the Apple Boot Policy protocol has recovery detection issues.

    3. AppleDebugLog
      Type: plist boolean
      Failsafe: false
      Description: Replaces the Apple Debug Log protocol with a builtin version.
    4. AppleEg2Info
      Type: plist boolean
      Failsafe: false
      Description: Replaces the Apple EFI Graphics 2 protocol with a builtin version.

      Note: This protocol allows newer EfiBoot versions (at least 10.15) to expose screen rotation to macOS. Refer to ForceDisplayRotationInEFI variable description on how to set screen rotation angle.

    5. AppleFramebufferInfo