GUIDE How to Create OpenCore config.plist file for booting macOS on Desktops and Laptops [Intel/AMD] - OpenCore config.plist Guide

EliteMacx86

Administrator
Staff member
Joined
Jul 22, 2018
Messages
3,858
Motherboard
Supermicro X11SPA-T
CPU
Intel Xeon W-3275 28 Core
Graphics
2xAMD RX 580 8GB
OS X/macOS
11.0.x
Bootloader
  1. OpenCore
Mac
  1. Mac mini
  2. MacBook Pro
Mobile Phone
  1. Android
  2. iOS
How to Create OpenCore config.plist file for booting macOS on Desktops and Laptops [Intel/AMD] - OpenCore config.plist Guide

By following this guide, you'll be able to create a config.plist for booting macOS on a Desktop or Laptop. This guide is meant for macOS compatible hardware and will not work if your hardware isn't compatible, regardless of the platform.

This guide provides the required information for setting up config.plist which is only valid for OpenCore and is applicable for the following
  • Desktops [Intel/AMD]
  • Laptops [Intel Only]
  • HEDT [Intel/AMD]
Please note that this guide does not provide a step-by-step guide configuration for an end user hardware as the hardware specifications may vary from user to user and this guide only provides a sample configuration for the following



config.plist Limitations


The OpenCore config.plist file has restrictions on size, nesting levels, and number of keys:

• The config.plist file size shall not exceed 32 MBs.
• The config.plist file shall not have more than 32 nesting levels.
• The config.plist file may have up to 32,768 XML nodes within each plist object. – One plist dictionary item is counted as a pair of nodes

Configuration Structure


The config.plist is structured to group related elements in subsections as follows:

FunctionPurpose
AddProvides support for data addition. Existing data will not be overridden, and needs to be handled separately with Delete if necessary.
DeleteProvides support for data removal
PatchProvides support for data modification
QuirksProvides support for specific workarounds

config.plist Sections

The config.plist consist of the following sections. All of these sections must be defined under config.plist, according to the OpenCore version.

SectionPurpose
ACPI
Booter
DeviceProperties
Kernel
Misc
NVRAM
PlatformInfo
UEFI

Obtaining config.plist File


Editing config.plist File
The OpenCore config.plist file can be edited with any text editor. However, specialized software is highly recommended for a better experience. Please note that config.plist created for a specific hardware configuration should never be used on the different hardware configurations.
 

EliteMacx86

Administrator
Staff member
Joined
Jul 22, 2018
Messages
3,858
Motherboard
Supermicro X11SPA-T
CPU
Intel Xeon W-3275 28 Core
Graphics
2xAMD RX 580 8GB
OS X/macOS
11.0.x
Bootloader
  1. OpenCore
Mac
  1. Mac mini
  2. MacBook Pro
Mobile Phone
  1. Android
  2. iOS
OpenCore Configuration

ACPI



The ACPI section is not only first in the list but also the most important. This section is for loading, blocking, and patching the ACPI tables. The sub-sections are explained below.

Add
This section is for adding the DSDT and SSDT files for your system which will allow booting macOS. This can include the mandatory SSDTs from the OpenCore package as well as any add-on SSDTs for specific purposes such as USB and Thunderbolt.

QUICK INFO:
  • The ACPI table loading depends on the order of the items in the list. Therefore, the mandatory SSDTs should always load first. Usually, the mandatory ACPI loading order should be SSDT-EC-USBX, SSDT-AWAC-DISABLE, SSDT-PLUG, SSDT-PNLF, etc.
  • The dependencies SSDTs should load first before the SSDTs that depend on them (e.g. SSDT-DTGP should always load first before the Thunderbolt SSDT)
  • When adding DSDT.aml, the DSDT.aml should be added first followed by the rest of the SSDTs.
  • ACPI Tables defined here must exist in EFI/OC/ACPI directory.


Add Properties
PropertiesDescription
PathDefines ACPI Tables path.
CommentUsed to provide a reference for the ACPI Table
EnabledUsed to Enable or Disable the ACPI Tables
Enables ACPI Tables when set to true.

Delete
This section allows blocking the ACPI tables from loading.

Delete Properties
PropertiesDescription
TableSignatureDefines Table Signature
Match Table size equal to the value defined here
OemTableIdDefines ACPI Table's OEM ID.
Match table OEM ID equal to the value defined here
TabeLengthDefines Table Size
Match table size equal to the value defined here.
CommentUsed to provide a reference for the ACPI Table
AllDeletes all ACPI Tables matching the condition when set to true.
EnabledUsed to Enable or Disable the ACPI Tables
Removes particular ACPI Table when set to true.


Patch
This section is used for device renames such as USB, Graphics, Brightness and Audio. You can implement the necessary ACPI patches for optimizing the ACPI system components with DSDT and SSDT. This section is important when doing Hot-patch.

QUICK INFO:
  • In most cases, ACPI renaming is not required. This may fail or perform improper renaming of unrelated devices. WhateverGreen applies the ACPI renames automatically. However, in some cases, a rename can be required (such as I2C Trackpad), HPET, Brightness Hotkeys, or Shut Down Fix.
  • Cosmetic ACPI Renames such as PCI0 to PC00 should be ignored.
  • Duplicate renames may result the system in a non-bootable state. Especially, if the rename is done by WhaterGreen.
  • Find and Replace Value must be HEX values and of the same length. Patches of different Find and Replace lengths are unsupported as they may corrupt ACPI tables and make the system unstable due to area relocation.

Patch Properties
PropertiesDescription
BaseSelects ACPI path base for patch lookup (or immediate replacement) by obtaining the offset to the provided path.
Only fully-qualified absolute paths are supported (e.g. \_SB.PCI0.LPCB.HPET). Currently supported object types are: Device, Field, Method.
TableSignatureDefines Table Signature
Match Table size equal to the value defined here
OemTableIdDefines ACPI Table's OEM ID.
Match table OEM ID equal to the value defined here
TableLengthDefines Table Size
Match table size equal to the value defined here.
FindData to find. Must be equal to Replace in size if set.
Can be empty, when Base is specified, immediate replacement after Base lookup happens in this case.
ReplaceReplacement data of one or more bytes.
CommentUsed to provide a reference for the ACPI Renames
MaskData bitwise mask used during find comparison. Allows fuzzy search by ignoring not masked (set to zero) bits. Must be equal to Replace in size if set.
ReplaceMaskData bitwise mask used during replacement. Allows fuzzy replacement by updating masked (set to non-zero) bits. Must be equal to Replace in size if set.
BaseSkipNumber of found Base occurrences to skip before finds and replacements are applied
CountNumber of occurrences to patch.
LimitMaximum number of bytes to search for.
SkipNumber of found occurrences to skip before replacements are applied.
EnabledUsed to Enable or Disable the ACPI Renames
Enables particular ACPI Rename when set to true.


Quirks
This section allows to apply certain ACPI Quirks. The Quirks consist of the following:

QuirksDescription
FadEnableReset
  • Provide reset register and flag in FADT table to enable reboot and shutdown.
  • Mainly required on legacy hardware and a few newer laptops.
  • Can also fix power-button shortcuts. Not recommended unless required.
NormalizeHeaders
  • Clean up ACPI header fields to workaround macOS ACPI implementation flaws that result in boot crashes.
RebaseRegions
  • Attempt to heuristically relocate ACPI memory regions.
  • When nothing else helps, this option could be tried to avoid stalls at PCI Configuration Begin phase when booting macOS by attempting to fix the ACPI addresses. It is not a magic bullet however and only works with the most typical cases.
  • Do not use it unless absolutely required as it can have the opposite effect on certain platforms and result in boot failures.
ResetHwSig
  • Reset FACS table HardwareSignature value to 0.
  • This works around firmware that fail to maintain hardware signature across the reboots and cause issues with waking from hibernation.
ResetLogoStatus
  • Reset BGRT table Displayed status field to false.
  • This works around firmware that provide a BGRT table but fail to handle screen updates afterwards.
SyncTableIds
  • Sync table identifiers with the SLIC table.
  • This works around patched tables becoming incompatible with the SLIC table causing licensing issues in older Windows operating systems.


Booter


This section is used for booting and

This section is used for different UEFI modifications and provides firmware fixes in relation to the Apple bootloader (boot.efi). The modifications currently provide various patches and environment alterations for different firmware types. The sub-sections are explained below.

MmioWhitelist
Designed to be filled with plist dict values, describing addresses critical for particular firmware functioning when DevirtualiseMmio quirk is in use.

MmioWhitelist Properties
PropertiesDescription
AddressExceptional 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. The debug log can be used to find the list of the candidates.
CommentUsed to provide a reference for the MMIO address
EnabledUsed to Enable or Disable the MMIO address
Exclude MMIO address from the devirtualization procedure

Patch
Performs binary patching in booter. To be filled with plist dictionary values, describing each patch.

Patch Properties
PropertiesDescription
ArchDefines Booter patch architecture (i386, x86_64).
IdentifierApple for macOS booter (typically boot.efi); or a name with a suffix, such as bootmgfw.efi, for a specific booter.
CommentUsed to provide a reference for the Patches
FindData to find. Must be equal to Replace in size if set.
ReplaceReplacement data of one or more bytes.
MaskData bitwise mask used during find comparison. Allows fuzzy search by ignoring not masked (set to zero) bits. Must be equal to Find in size if set.
ReplaceMaskData bitwise mask used during replacement. Allows fuzzy replacement by updating masked (set to non-zero) bits. Must be equal to Replace in size if set.
CountNumber of patch occurrences to apply
LimitThe maximum number of bytes to search for.
SkipNumber of found occurrences to skip before replacements are applied.
EnabledUsed to Enable or Disable the booter patch.
Enables particular booter patch when set to true.

Quirks
This section allows to apply certain Booter quirks. The Quirks consist of the following:

QuirksNotes
AllowRelocationBlock
  • Allows booting macOS through a relocation block.
  • The relocation block is a scratch buffer allocated in the lower 4 GB used for loading the kernel and related structures by EfiBoot on firmware where the lower memory region is otherwise occupied by (assumed) non-runtime data. Right before kernel startup, the relocation block is copied back to lower addresses. Similarly, all the other addresses pointing to the relocation block are also carefully adjusted. The relocation block can be used when:
    • No better slide exists (all the memory is used)
    • slide=0 is forced (by an argument or safe mode)
    • KASLR (slide) is unsupported (this is macOS 10.7 or older)
  • This quirk requires ProvideCustomSlide to be enabled and typically also requires enabling AvoidRuntimeDefrag Quirk to function correctly. Hibernation is not supported when booting with a relocation block, which will only be used if required when the quirk is enabled. 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 such cases, consider using EnableSafeModeSlide Quirk instead.
AvoidRunTimeDefrag
  • Protect from boot.efi runtime memory defragmentation
  • Fixes certain UEFI runtime services such as date time, NVRAM, power control, etc.
  • Apart from Apple and VMware, this quirk is required by the rest of the firmware
  • Required for every platform.
DevirtualiseMmio
  • Remove runtime attribute from select MMIO regions.
  • This option reduces the stolen memory footprint from the memory map by removing the runtime bit for known memory regions.
  • This quirk may result in an increase of KASLR slides available but without additional measures, it is not necessarily compatible with the target board. This quirk typically frees between 64 and 256 megabytes of memory, present in the debug log, and on some platforms, is the only way to boot macOS, which otherwise fails with allocation errors at the bootloader stage.
  • This option is useful on all types of firmware, except for some very old ones such as Sandy Bridge. On certain firmware, a list of addresses that need virtual addresses for proper NVRAM and hibernation functionality may be required. Use the MmioWhitelist section for this.
  • Required for Coffee Lake and later.
DisableSingleUser
  • Disables single user mode.
  • This is a security option that restricts the activation of single user mode by ignoring the CMD+S hotkey and the -s boot argument. The behavior with this quirk enabled is supposed to match T2-based model behavior. Refer to this archived article to understand how to use single user mode with this quirk enabled.
DisableVariableWrite
  • Protect from macOS NVRAM write access
  • This is a security option that restricts NVRAM access in macOS. This quirk requires OC_FIRMWARE_RUNTIME protocol implemented in OpenRuntime.efi.
  • This quirk can also be used as an ad hoc workaround for defective UEFI runtime services implementations that are unable to write variables to NVRAM and results in operating system failures.
DiscardHibernateMap
EnableSafeModeSlide
  • Patch bootloader to have KASLR enabled in safe mode.
  • This option is relevant to users with issues booting to safe mode (e.g. by holding shift or with using the -x boot argument). By default, safe mode forces 0 slide as if the system was launched with the slide=0 boot argument.
  • This quirk requires ProvideCustomSlide to be enabled.
  • This quirk can be helpful if you're unable to boot into safe mode.
  • Required for every platform.
EnableWriteUnprotector
  • Allows write access to UEFI runtime services code.
  • This option bypasses WˆX permissions in code pages of UEFI runtime services by removing the write protection (WP) bit from the CR0 register during their execution. This quirk requires OC_FIRMWARE_RUNTIME protocol implemented in OpenRuntime.efi.
  • This Quirk can conflict with RebuildAppleMemoryMap if enabled. It is always recommended to enable RebuildAppleMemoryMap on Coffee Lake and newer platforms. However, a few motherboards will require

  • This quirk may potentially weaken firmware security, please use RebuildAppleMemoryMap if the firmware supports the memory attributes table (MAT)
  • Required for systems up to Kaby Lake
ForceBooterSignatureSet macOS boot-signature to OpenCore launcher.
Booter signature, essentially a SHA-1 hash of the loaded image, is used by Mac EFI to verify the authenticity of the bootloader when waking from hibernation. This option forces macOS to use OpenCore launcher SHA-1 hash as a booter signature to let OpenCore shim hibernation wake on Mac EFI firmware. OpenCore launcher path is determined from the LauncherPath property.
ForceExitBootServices
  • Retry ExitBootServices with a new memory map on failure.
  • Try to ensure that the ExitBootServices call succeeds. If required, an outdated MemoryMap key argument can be used by obtaining the current memory map and retrying the ExitBootServices call.
  • The need for this quirk is determined by early boot crashes of the firmware. Do not use this option without a full understanding of the implications.
ProtectMemoryRegions
  • Protect memory regions from incorrect access.
  • Some types of firmware incorrectly map certain memory regions:
    • The CSM region can be marked as boot services code, or data, which leaves it as free memory for the XNU kernel.
    • MMIO regions can be marked as reserved memory and stay unmapped. They may however be required to be accessible at runtime for NVRAM support.
  • Fixes regions such as ACPI NVS for CSM or MMIO for MMIO.
  • The need for this quirk is determined by artifacts, sleep/wake issues, and boot failures. This quirk is typically only required by very old firmware.
ProtectSecureBoot
  • Protect UEFI Secure Boot variables from being written.
  • Reports security violation during attempts to write to db, dbx, PK, and KEK variables from the operating system.
  • This quirk attempts to avoid issues with NVRAM implementations with fragmentation issues, such as on the MacPro5,1 as well as on certain Insyde firmware without garbage collection or with defective garbage collection.
ProtectUefiServices
  • Protect UEFI services from being overridden by the firmware.
  • 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.
  • This quirk is needed for correct operation if OpenCore is chain loaded from GRUB with BIOS Secure Boot enabled.
  • Required for Coffee Lake and later (including VMware).
ProvideCustomSlide
  • Provide custom KASLR slide on low memory.
  • This option forces macOS to use a pseudo random value among the available ones.
  • Used for Slide variable calculation. However the necessity of this quirk is determined by OCABC: Only N/256 slide values are usable! message in the debug log. If the message OCABC: All slides are usable! You can disable ProvideCustomSlide! is present in your log, you can disable ProvideCustomSlide.
RebuildAppleMemoryMapGenerates Memory Map which is compatible with macOS.
Since several types of firmware come with incorrect memory protection tables, this quirk often comes paired with SyncRuntimePermissions.
SetupVirtualMap
  • Setup virtual memory at SetVirtualAddresses.
  • Fixes several virtual address issues and tends to fix early Kernel Panics.
  • The necessity of this quirk is determined by early boot failures. Currently, new firmware with memory protection support (such as OVMF) do not support this quirk.
SignalAppleOS
  • 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
  • Update memory permissions for runtime environment.
  • The need for this quirk is indicated by early boot failures. Only firmware released after 2017 is typically affected.
ProvideMaxSlide
  • Provide maximum KASLR slide when higher ones are unavailable.
ResizeAppleGpuBars
  • Reduce GPU PCI BAR sizes for compatibility with macOS.
  • If your firmware has Resizable BAR Support Enabled, use 0 to enable Resizable BAR.
  • If your firmware does not have Resizable BAR Support or if the Resizable BAR Support is Disabled, use -1 to disable Resizable BAR.
  • For Resizable BAR Support to be Enabled, both, the GPU and the firmware must support the Resizable BAR. For BIOS (Legacy), and GPUs which does not support Resizable BAR, it is recommended to use -1 to disable this Quirk.
  • Do not Enable the Resizable BAR Support in Firmware if this Quirk is Disabled.
  • Setting other PCI BAR sizes can cause instabilities within macOS.

DeviceProperties


This section is used for adding device properties. This includes PCI Devices information such as Graphics, Audio, WiFi, Ethernet, and other controllers. This section can be also used for PCI Device implementation, Device Spoofing, and EDID injection.

Devices
The PCI Devices

Properties
PropertiesDescription

Kernel


This section is used for different kinds of Kernelspace modifications for Apple Kernel (XNU). This includes Kexts Injection, Kernel and Driver patching, driver blocking, and CPU spoofing. The sub-sections are explained below.

Add
This section is for adding the Kexts files for your system which will allow booting macOS. This can include the mandatory Kexts as well as any add-on Kext(s) for specific purposes such as USB and Card Reader.

QUICK INFO:
  • The Kext loading depends on the order of the items in the list. Therefore, the mandatory Kexts should always load first. Usually, the mandatory kexts loading order should be Lilu, VirtualSMC, WhateverGreen, AppleALC, etc.
  • The dependencies kexts should load first before the kexts that depend on them.
  • To track the dependency order, inspect the OSBundleLibraries key in the Info.plist file of the kext(s) being added. Any kext included under the key is a dependency that must appear before the kext is added.
  • Kexts may have inner kexts (Plugins) included in the bundle. Such Plugins must be added separately and follow the same global ordering rules as other kexts.
  • All the plugins must load after loading their dependencies otherwise the kext will no longer function even when loaded in macOS/OS X.
  • Kexts defined here must exist in EFI/OC/Kexts directory.

Add Properties
PropertiesDescription
Arch
  • Defines Kext Architecture
Any
  • Apply to any supported architecture.
i386
  • (32-bit)
x86_x64
  • (64-bit)
BundlePath
  • Defines Kext name (e.g. Lilu.kext or YourKext.kext/Contents/PlugIns/YourSubKext.kext)
Comment
  • Used to provide a reference for the Kexts.
ExecutablePathKext executable path (e.g. Contents/MacOS/Lilu).
  • The path to the actual executable is hidden within the kext, you can see what path your kext has by right-clicking and selecting Show Package Contents. Generally, they'll be Contents/MacOS/Kext but some have kexts hidden within under Plugin folder.
  • plist only kexts do not need this entry.
PlistPath
  • Kext Info.plist path (e.g. Contents/Info.plist).
MinKernel
  • Minimum Kernel version for the kext injection. See Kernel Support Table for more information.
MaxKernel
  • Maximum Kernel version for the kext injection. See Kernel Support Table for more information.
Enabled
  • Used to Enable or Disable the Kext Injection.
  • Enables particular Kext when set to true.

Block
This section is for blocking the Kext(s) from the prelinked kernel.

Block Properties
PropertiesDescription
Arch
  • Defines Kext Architecture for blocking.
Identifier
  • Defines Kext bundle identifier (e.g. com.apple.driver.AppleTyMCEDriver).
Comment
  • Used to provide a reference for the blocking Kexts.
MinKernel
  • Minimum Kernel version for blocking the Kext. See Kernel Support Table for more information.
MaxKernel
  • Maximum Kernel version for blocking the Kext. See Kernel Support Table for more information.
Strategy
  • Determines the behavior of kernel driver blocking.
  • The possible values include:
    • Disable - Forcibly make the kernel driver kmod startup code return failure
    • Exclude - Remove the kernel driver from the kernel cache by dropping plist entry and filling in zeroes.
  • It is risky to Exclude a kext that is a dependency of others.
  • At this moment Exclude is only applied to prelinkedkernel and newer mechanisms.
  • In most cases strategy Exclude requires the new kext to be injected as a replacement.
Enabled
  • Used to Enable or Disable the Kext Blocking.
  • Blocks particular Kext when set to true.

Force
This section allows forcing kexts to load from the System Volume if they are not cached.

QUICK INFO:
  • This resolves the problem of injecting kexts that depend on other kexts, which are not otherwise cached. The issue typically affects older operating systems, where various dependency kexts, such as IOAudioFamily or IONetworkingFamily may not be present in the kernel cache by default.
  • The Kext loading depends on the order of the items in the list. The dependencies kexts should load first before the kexts that depend on them.
  • Force happens before Add
  • The signature of the “forced” kext is not checked in any way. This makes using this feature extremely dangerous and undesirable for secure boot.
  • This feature may not work on encrypted partitions in newer operating systems.

Force Properties
PropertiesDescription
Arch
  • Defines Kext Architecture for forcing.
BundlePath
  • Kext bundle path (e.g. System\Library \Extensions \IONetworkingFamily.kext).
Identifier
  • Kext identifier to perform presence checking before adding (e.g. com.apple.iokit.IONetworkingFamily).
  • Only drivers whose identifiers are not found in the cache will be added.
Comment
  • Used to provide a reference for the force loading of Kexts.
ExecutablePath
  • Kext executable path (e.g. Contents/MacOS/IONetworkingFamily).
PlistPath
  • Kext Info.plist path (e.g. Contents/Info.plist).
MinKernel
  • Minimum Kernel version to force loading of the Kext. See Kernel Support Table for more information.
MaxKernel
  • Maximum Kernel version to force loading of the Kext. See Kernel Support Table for more information.
Enabled
  • Used to Enable or Disable force loading of the Kext.
  • Forces particular Kext to load when set to true.

Patch
This section allows patching for Kernel and Kexts prior to driver addition and removal.

Patch Properties
PropertiesDescription
ArchDefines Kext patching architecture
Identifier
Base
Comment
Find
Replace
Mask
ReplaceMask
MinKernel
MaxKernel
Count
Limit
Skip
Enabled
  • Used to Enable or Disable the Kernel Patching.
  • Enables particular Kernel Patch when set to true.

Emulate
This section allows spoofing your CPU ID to enable support for an unsupported CPU model (such as Intel Pentium and Celeron) or a CPU which is not yet supported by a specific version of macOS (such as Intel Rocket Lake and Alder Lake). This also enables XCPM support for unsupported CPU models.

Emulate Properties
PropertiesDescription
Cpuid1Data
Cpuid1Mask
MinKernel
MaxKernel
DummyPowerManagement
  • Disables AppleIntelCPUPowerManagement
  • Provides Dummy Power Management. This option is an alternative to NullCPUPowerManagement.kext for CPUs without native power management drivers in macOS.
  • Required for all AMD-based systems as there is no native Power Management.
  • Disabling this option will lead to Kernel Panic for AppleIntelCPUPowerManagement.kext.

Scheme
This section allows settings related to Kernel. These settings are relevant for older Mac Operating Systems.

Scheme Properties
PropertiesDescription
FuzzyMatch
  • Use kernelcache with different checksums when available.
  • On macOS 10.6 and earlier, kernelcache filename has a checksum, which essentially is adler32 from SMBIOS product name and EfiBoot device path. On certain firmware, the EfiBoot device path differs between UEFI and macOS due to ACPI or hardware specifics, rendering kernelcache checksum as always different.
  • Enabling this option ignores kernelcache checksum and uses the latest available cache.
  • This setting allows matching the latest kernelcache with a suitable architecture when the kernelcache without a suffix is unavailable, improving macOS 10.6 boot performance on several platforms.
  • Required for macOS Big Sur and above.
KernelArch
  • Defines Kernel Architecture type.
  • It's recommended to set this option to "Auto" and let macOS/OS X decide the Kernel Architecture.
KernelCache
  • Defines Kernel Cache type.
  • It's recommended to set this option as Auto.
CustomKernel
  • Use customized kernel cache from the Kernels directory located at the root of the ESP partition.
  • Unsupported platforms including Atom and AMD require modified versions of the XNU kernel in order to boot. This option provides the possibility of using a customized kernel cache that contains such modifications from the ESP partition.

Quirks
This section allows to apply certain Kernel quirks. It provides settings related to Kernel and several other options related to BIOS/UEFI and USB ports. The Quirks consist of the following:

QuirksDescription
AppleCpuPmCfgLock
  • Disables PKG_CST_CONFIG_CONTROL (0xE2) MSR modification in AppleIntelCPUPowerManagement.kext, commonly causing early kernel panic, when it is locked from writing.
  • Required for Ivy Bridge and older (any macOS version) and for Haswell (OS X 10.10 and older).
  • Required if MSR 0xE2 is locked or cannot be disabled in BIOS/UEFI (typically, CFG-Lock).
  • Disabling MSR Lock is the preferred option and this Quirk should be avoided whenever possible. See MSR Lock for more information.
  • Do not use this Quirk if MSR 0xE2 register is unlocked.
AppleXcpmCfgLock
  • Disables PKG_CST_CONFIG_CONTROL (0xE2) MSR modification in XNU kernel, commonly causing early kernel panic, when it is locked from writing (XCPM power management).
  • Required for Haswell and newer.
  • Required if MSR 0xE2 is locked or cannot be disabled in BIOS/UEFI (typically, CFG-Lock).
  • Disabling MSR Lock is the preferred option and this Quirk should be avoided whenever possible. See MSR Lock for more information.
  • Do not use this Quirk if MSR 0xE2 register is unlocked.
AppleXcpmExtraMsrs
  • Disables multiple MSR access critical for certain CPUs, which have no native XCPM support.
  • This is typically used in conjunction with the Emulate section on Haswell-E, Broadwell-E, Skylake-SP, and similar CPUs.
AppleXcpmForceBoost
  • Forces maximum performance in XCPM mode.
  • This Quirk is also known as the XCPM performance fix.
  • This patch writes 0xFF00 to MSR_IA32_PERF_CONTROL (0x199), effectively setting the maximum multiplier for all the time.
  • While this may increase the performance, the use of this Quirk is strongly discouraged on all systems except for the systems being used for scientific or media calculations. Only certain Xeon models typically benefit from the patch.
  • Do not use this Quirk whenever possible as it breaks the idea of CPU Power Management.
CustomPciSerialDevicePerforms change of PMIO register base address on a customised PCI serial device.
CustomSMBIOSGuid
  • Performs GUID patching for UpdateSMBIOSMode Custom mode.
  • Required for all Dell Systems.
  • When using this Quirk, you must set UpdateSMBIOSMode to Custom in PlatformInfo section.
DisableIoMapper
  • Disables IOMapper support in XNU (VT-d), which may conflict with the firmware implementation.
  • Enables Apple VTD when disabling this Quirk and enabling VT-d in Firmware Settings. However, this requires fixing of DMAR Table on systems that have VT-d enabled.
  • This Quirk is a much better alternative to dart=0 boot arg, required for disabling VT-d.
  • This option is a preferred alternative to deleting the DMAR ACPItable and/or disabling VT-d in firmware settings, which does not obstruct VT-d support in other Operating Systems if needed.
  • Misconfigured IOMMU in the firmware may result in broken devices such as Ethernet or Wi-Fi Adapters, causing network disruption. For instance, an ethernet adapter may cycle in link-up link-down state infinitely and a Wi-Fi adapter may fail to discover networks. Gigabyte is one of the most common OEMs with these issues. See Fixing DMAR Table on macOS for more information.
  • When utilizing certain Thunderbolt Devices such as Antelope, PreSonus, SlateDigital, Focusrite, and Apogee Audio Interface and NAS under macOS, VT-d must be Enabled in Firmware Settings and this Quirk must be disabled in such case.
  • Required for Network Adapters (including built-in and PCIe) on macOS Ventura.
DisableLinkeditJettison
  • Disables __LINKEDIT jettison code.
  • This Quirk lets Lilu.kext, and possibly other kexts, function in macOS Big Sur at their best performance levels without requiring the keepsyms=1 boot argument.
  • Required for macOS Big Sur and above.
DisableRtcChecksum
  • Disables primary checksum (0x58-0x59) writing in AppleRTC.
  • Required if you have a BIOS Reset issue or if the system enters into Safe Mode issue after Reboot/Shut Down from macOS.
ExtendBTFeatureFlags
  • Set FeatureFlags to 0x0F for full functionality of Bluetooth, including Continuity.
  • Enables Continuity mode.
  • This Quirk is an alternative to BT4LEContinuityFixup.kext, which does not function properly.
ExternalDiskIcons
  • Apply icon type patches to AppleAHCIPort.kext to force internal disk icons for all AHCI disks.
  • This option should be avoided whenever possible. Modern firmware typically have compatible AHCI controllers.
ForceAquantiaEthernet
  • Enables Aquantia AQtion based 10GbE network cards support.
  • In order for Aquantia cards to properly function, DisableIoMapper Quirk must be disabled, DMAR ACPI table must not be dropped, and VT-d must be enabled in BIOS.
  • Required for Aquantia Ethernet Cards. When enabling this Quirk, fixing of DMAR Table is required. See Fixing DMAR Table on macOS for more information.
ForceSecureBootScheme
  • Force x86 scheme for IMG4 verification.
  • This Quirk is required on virtual machines when using SecureBootModel different from x86legacy.
IncreasePciBarSize
  • Allows IOPCIFamily to boot with 2 GB PCI BARs.
  • Normally macOS restricts PCI BARs to 1 GB. Enabling this option (still) does not let macOS actually use PCI devices with larger BARs.
  • This Quirk should be avoided whenever possible. A need for this option indicates misconfigured or defective firmware.
LapicKernelPanic
  • Disables kernel panic on LAPIC interrupts.
  • Equivalent to Clover's Kernel LAPIC.
  • Required for HP Systems.
LegacyComppage
PanicNoKextDump
  • Prevent kernel from printing kext dump in the panic log preventing from observing panic details.
  • Affects 10.13 and above. Not required for older.
PowerTimeoutKernelPanic
  • Disables kernel panic on setPowerState timeout.
  • Prevents Kernel Panics on Power changes timeout for Apple drivers on macOS Catalina (10.15) and above, most notably with digital audio.
ProvideCurrentCpuInfo
  • Provides current CPU info to the kernel.
  • Depending on the CPU, the Quirk performs the following function:
    • Provides the correct TSC and FSB values to the kernel, as well as disables CPU topology validation (10.8+) for Microsoft Hyper-V.
    • Provides precomputed MSR 35h values solving kernel panic with -cpu host for KVM and other hypervisors.
    • Adds support for asymmetrical SMP systems for Intel CPUs (e.g. Intel Alder Lake) by patching core count to thread count along with the supplemental required changes (10.14+).
  • Required for Alder Lake and AMD CPUs and for Hyper-V and KVM.
ThirdPartDrives
  • Applies vendor patches to IOAHCIBlockStorage.kext to enable native features for third-party drives, such as TRIM on SSDs or hibernation support on 10.15 and newer.
  • This Quirk can be avoided for NVMe SSDs and for AHCI SSDs, you can use a built-in tool (trimforce) within macOS. See Enabling TRIM on macOS for more information.
XchiPortLimit
  • Patches various USB Kexts (AppleUSBXHCI.kext, AppleUSBXHCIPCI.kext, IOUSBHostFamily.kext) to remove 15 USB port count limit.
  • This Quirk is broken on macOS Big Sur 11.3 and above and may not function as intended. More details can be found on the USB Mapping thread.
  • This Quirk is a temporary solution and it is advised to map USB Ports instead of using this Quirk. See USB Mapping for more information.
  • This Quirk should be avoided whenever possible due to the chance of data corruption.
SetApfsTrimTimeout
  • Sets TRIM timeout in microseconds for APFS filesystems on SSDs.
  • Only applicable for macOS Mojave 10.14 and above. See macOS and TRIM for more information.
  • The failsafe value -1 indicates that this patch will not be applied, such that apfs.kext will remain untouched.
  • On macOS 12.0 and above, it is no longer possible to specify a trim timeout. However, trim can be disabled by setting 0.
  • Trim operations are only affected at the booting phase when the startup volume is mounted. Either specifying timeout, or completely disabling trim with 0, will not affect normal macOS running.
 
Last edited:

Forum statistics

Threads
749
Messages
7,926
Members
6,855
Latest member
Breakthru81