Contents

1 Introduction

This document provides information on the format of the OpenCore user configuration file used to set up the correct functioning of the macOS operating system. It is to be read as the official clarification of expected OpenCore behaviour. All deviations, if found in published OpenCore releases, shall be considered to be documentation or implementation issues which should be reported via the Acidanthera Bugtracker. An errata sheet is available in OpenCorePkg repository.

This document is structured as a specification and is not meant to provide a step-by-step guide to configuring an end-user Board Support Package (BSP). The intended audience of the document is anticipated to be programmers and engineers with a basic understanding of macOS internals and UEFI functionality. For these reasons, this document is available exclusively in English, and all other sources or translations of this document are unofficial and may contain errors.

Third-party articles, utilities, books, and similar, may be more useful for a wider audience as they could provide guide-like material. However, they are subject to their authors’ preferences, misinterpretations of this document, and unavoidable obsolescence. In cases of using such sources, such as Dortania’s OpenCore Install Guide and related material, please refer back to this document on every decision made and re-evaluate potential implications.

Please note that regardless of the sources used, users are required to fully understand every OpenCore configuration option, and the principles behind them, before posting issues to the Acidanthera Bugtracker.

Note: Creating this document would not have been possible without the invaluable contributions from other people: Andrey1970, Goldfish64, dakanji, PMheart, and several others, with the full list available in OpenCorePkg history.

1.1 Generic Terms

• plist — Subset of ASCII Property List format written in XML, also know as XML plist format version 1. Uniform Type Identifier (UTI): com.apple.property-list. Plists consist of plist objects, which are combined to form a hierarchical structure. Due to plist format not being well-defined, all the definitions of this document may only be applied after plist is considered valid by running plutil -lint. External references: https://www.apple.com/DTDs/PropertyList-1.0.dtd, man plutil.
• plist type — plist collections (plist array, plist dictionary, plist key) and primitives (plist string, plist data, plist date, plist boolean, plist integer, plist real).
• plist object — definite realisation of plist type, which may be interpreted as value.
• plist array — array-like collection, conforms to array. Consists of zero or more plist objects.
• plist dictionary — map-like (associative array) collection, conforms to dict. Consists of zero or more plist keys.
• plist key — contains one plist object going by the name of plist key, conforms to key. Consists of printable 7-bit ASCII characters.
• plist string — printable 7-bit ASCII string, conforms to string.
• plist data — base64-encoded blob, conforms to data.
• plist date — ISO-8601 date, conforms to date, unsupported.
• plist boolean — logical state object, which is either true (1) or false (0), conforms to true and false.
• plist integer — possibly signed integer number in base 10, conforms to integer. Fits in 64-bit unsigned integer in two’s complement representation, unless a smaller signed or unsigned integral type is explicitly mentioned in specific plist object description.
• plist real — floating point number, conforms to real, unsupported.
• plist multidata — value cast to data by the implementation. Permits passing plist string, in which case the result is represented by a null-terminated sequence of bytes (C string), plist integer, in which case the result is represented by 32-bit little endian sequence of bytes in two’s complement representation, plist boolean, in which case the value is one byte: 01 for true and 00 for false, and plist data itself. All other types or larger integers invoke undefined behaviour.

2 Configuration

2.1 Configuration Terms

• OC config — OpenCore Configuration file in plist format named config.plist. It provides an extensible way to configure OpenCore and is structured to be separated into multiple named sections situated under the root plist dictionary. These sections may have plist array or plist dictionary types and are described in corresponding sections of this document.
• valid key — plist key object of OC config described in this document or its future revisions. Besides explicitly described valid keys, keys starting with the # symbol (e.g. #Hello) are also considered valid keys and while they behave as comments, effectively discarding their values, they are still required to be valid plist objects. All other plist keys are not valid, and their presence results in undefined behaviour.
• valid value — valid plist object of OC config described in this document that matches all the additional requirements in specific plist object descriptions if any.
• invalid value — valid plist object of OC config described in this document that is of other plist type, does not conform to additional requirements found in specific plist object descriptions (e.g. value range), or missing from the corresponding collection. Invalid values are read with or without an error message as any possible value of this plist object in an undetermined manner (i.e. the values may not be same across the reboots). Whilst reading an invalid value is equivalent to reading certain defined valid values, applying incompatible values to the host system may result in undefined behaviour.
• optional value — valid value of OC config described in this document that reads in a certain defined manner provided in specific plist object description (instead of invalid value) when not present in OC config. All other cases of invalid value do still apply. Unless explicitly marked as optional value, any other value is required to be present and reads to invalid value if missing.
• fatal behaviour — behaviour leading to boot termination. Implementations shall prevent the boot process from continuing until the host system is restarted. It is permitted, but not required, to execute cold reboots or to show warning messages in such cases.
• undefined behaviour — behaviour not prescribed by this document. Implementations may take any measures including, but not limited to, measures associated with fatal behaviour, assumptions of any state or value, or disregarding any associated states or values. This is however subject to such measures not negatively impacting upon system integrity.

2.2 Configuration Processing

The OC config file is guaranteed to be processed at least once if found. Subject to the OpenCore bootstrapping mechanism, the presence of multiple OC config files may lead to the reading of any of them. It is permissible for no OC Config file to be present on disk. In such cases, if the implementation does not abort the boot process, all values shall follow the rules of invalid values and optional values.

The OC config file has restrictions on size, nesting levels, and number of keys:

• The OC config file size shall not exceed 32 MBs.
• The OC config file shall not have more than 32 nesting levels.

• The OC config file may have up to 32,768 XML nodes within each plist object.

  • One plist dictionary item is counted as a pair of nodes

Reading malformed OC config files results in undefined behaviour. Examples of malformed OC config files include the following:

• OC config files that do not conform to DTD PLIST 1.0.
• OC config files with unsupported or non-conformant plist objects found in this document.
• OC config files violating restrictions on size, nesting levels, and number of keys.

It is recommended, but not required, to abort loading malformed OC config files and to continue as if an OC config file is not present. For forward compatibility, it is recommended, but not required, for the implementation to warn about the use of invalid values.

The recommended approach to interpreting invalid values is to conform to the following convention where applicable:

2.3 Configuration Structure

The OC config file is separated into subsections, as described in separate sections of this document, and is designed so as to attempt not to enable anything by default as well as to provide kill switches via an Enable property for plist dict entries that represent optional plugins and similar.

The file is structured to group related elements in subsections as follows:

• Add provides support for data addition. Existing data will not be overridden, and needs to be handled separately with Delete if necessary.
• Delete provides support for data removal.
• Patch provides support for data modification.
• Quirks provides support for specific workarounds.

Root configuration entries consist of the following:

• ACPI
• Booter
• DeviceProperties
• Kernel
• Misc
• NVRAM
• PlatformInfo
• UEFI

Basic validation of an OC config file is possible using the ocvalidate utility. Please note that the version of ocvalidate used must match the OpenCore release and that notwithstanding this, it may not detect all configuration issues present in an OC config file.

Note: To maintain system integrity, properties typically have predefined values even when such predefined values are not specified in the OC config file. However, all properties must be explicitly specified in the OC config file and this behaviour should not be relied on.

3 Setup

3.1 Directory Structure

When directory boot is used, the directory structure used should follow the descriptions in the Directory Structure figure. Available entries include:

• BOOTx64.efi or BOOTIa32.efi
  Initial bootstrap loaders, which load OpenCore.efi. BOOTx64.efi is loaded by the firmware by default consistent with the UEFI specification. However, it may also be renamed and put in a custom location to allow OpenCore coexist alongside operating systems, such as Windows, that use BOOTx64.efi files as their loaders. Refer to the LauncherOption property for details.
• boot
  Duet bootstrap loader, which initialises the UEFI environment on legacy BIOS firmware and loads OpenCore.efi similarly to other bootstrap loaders. A modern Duet bootstrap loader will default to OpenCore.efi on the same partition when present.
• ACPI
  Directory used for storing supplemental ACPI information for the ACPI section.
• Drivers
  Directory used for storing supplemental UEFI drivers for UEFI section.
• Kexts
  Directory used for storing supplemental kernel information for the Kernel section.
• Resources
  Directory used for storing media resources such as audio files for screen reader support. Refer to the UEFI Audio Properties section for details. This directory also contains image files for graphical user interface. Refer to the OpenCanopy section for details.
• Tools
  Directory used for storing supplemental tools.
• OpenCore.efi
  Main booter application responsible for operating system loading. The directory OpenCore.efi resides in is called the root directory, which is set to EFI\OC by default. When launching OpenCore.efi directly or through a custom launcher however, other directories containing OpenCore.efi files are also 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.
• nvram.fallback
  OpenCore variable import fallback file.
• nvram.used
  Renamed previous OpenCore variable import file after switch to fallback 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 Configuration Structure 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 Security Properties 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. The ProperTree editor is a lightweight, cross-platform and open-source alternative.

It is strongly recommended to avoid configuration creation tools that are aware of the internal 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 explicitly supported by such tools are used. In such cases, the use of open-source implementations with transparent binary generation (such as OCAT) is encouraged, given that other tools may contain malware. In addition, configurations created for a specific hardware setup should never be used on different 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.

When updating the LaTeX documentation (e.g. Configuration.tex) please do not rebuild the PDF files till merging to master happens. This avoids unnecessary merge conflicts:

• External contributors using the pull-request approach should request the maintainers to handle the PDF rebuild in the pull-request message.
• Internal contributors should rebuild the documentation at merge time in the same or in a separate commit. One can ask another maintainer to rebuild the documentation when lacking the necessary tools in the pull-request message.

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:

git clone --depth=1 https://github.com/acidanthera/audk UDK 
cd UDK 
git submodule update --init --recommend-shallow 
rm -rf OpenCorePkg 
git clone --depth=1 https://github.com/acidanthera/OpenCorePkg 
. ./edksetup.sh 
make -C BaseTools 
build -a X64 -b RELEASE -t XCODE5 -p OpenCorePkg/OpenCorePkg.dsc

For IDE usage Xcode projects are available in the root of the repositories. Another approach could be using Language Server Protocols. For example, Sublime Text with LSP for Sublime Text plugin. Add compile_flags.txt file with similar content to the UDK root:

-I/UefiPackages/MdePkg 
-I/UefiPackages/MdePkg/Include 
-I/UefiPackages/MdePkg/Include/X64 
-I/UefiPackages/MdeModulePkg 
-I/UefiPackages/MdeModulePkg/Include 
-I/UefiPackages/MdeModulePkg/Include/X64 
-I/UefiPackages/OpenCorePkg/Include/AMI 
-I/UefiPackages/OpenCorePkg/Include/Acidanthera 
-I/UefiPackages/OpenCorePkg/Include/Apple 
-I/UefiPackages/OpenCorePkg/Include/Apple/X64 
-I/UefiPackages/OpenCorePkg/Include/Duet 
-I/UefiPackages/OpenCorePkg/Include/Generic 
-I/UefiPackages/OpenCorePkg/Include/Intel 
-I/UefiPackages/OpenCorePkg/Include/Microsoft 
-I/UefiPackages/OpenCorePkg/Include/Nvidia 
-I/UefiPackages/OpenCorePkg/Include/VMware 
-I/UefiPackages/OvmfPkg/Include 
-I/UefiPackages/ShellPkg/Include 
-I/UefiPackages/UefiCpuPkg/Include 
-IInclude 
-include 
/UefiPackages/MdePkg/Include/Uefi.h 
-fshort-wchar 
-Wall 
-Wextra 
-Wno-unused-parameter 
-Wno-missing-braces 
-Wno-missing-field-initializers 
-Wno-tautological-compare 
-Wno-sign-compare 
-Wno-varargs 
-Wno-unused-const-variable 
-DOC_TARGET_NOOPT=1 
-DNO_MSABI_VA_FUNCS=1

Note: /UefiPackages in the sample file denotes an absolute path.

Warning: Tool developers modifying config.plist or any other OpenCore files must ensure that their tools check the opencore-version NVRAM variable (see the Debug Properties section below) and warn users if the version listed is unsupported or prerelease. The OpenCore configuration may change across releases and such tools shall ensure that they carefully follow this document. Failure to do so may result in such tools being considered to be malware and blocked by any means.

3.4 Coding conventions

As with any other project, we have conventions that we follow during development. All third-party contributors are advised to adhere to the conventions listed below before submitting patches. To minimise abortive work and the potential rejection of submissions, third-party contributors should initially raise issues to the Acidanthera Bugtracker for feedback before submitting patches.

Organisation. The codebase is contained in the OpenCorePkg repository, which is the primary EDK II package.

• Whenever changes are required in multiple repositories, separate pull requests should be sent to each.
• Committing the changes should happen firstly to dependent repositories, secondly to primary repositories to avoid automatic build errors.
• Each unique commit should compile with XCODE5 and preferably with other toolchains. In the majority of the cases it can be checked by accessing the CI interface. Ensuring that static analysis finds no warnings is preferred.
• External pull requests and tagged commits must be validated. That said, commits in master may build but may not necessarily work.
• Internal branches should be named as follows: author-name-date, e.g. vit9696-ballooning-20191026.
• Commit messages should be prefixed with the primary module (e.g. library or code module) the changes were made in. For example, OcGuardLib: Add OC_ALIGNED macro. For non-library changes Docs or Build prefixes are used.

Design. The codebase is written in a subset of freestanding C11 (C17) supported by most modern toolchains used by EDK II. Applying common software development practices or requesting clarification is recommended if any particular case is not discussed below.

• Never rely on undefined behaviour and try to avoid implementation defined behaviour unless explicitly covered below (feel free to create an issue when a relevant case is not present).
• Use OcGuardLib to ensure safe integral arithmetics avoiding overflows. Unsigned wraparound should be relied on with care and reduced to the necessary amount.
• Check pointers for correct alignment with OcGuardLib and do not rely on the architecture being able to dereference unaligned pointers.
• Use flexible array members instead of zero-length or one-length arrays where necessary.
• Use static assertions (STATIC_ASSERT) for type and value assumptions, and runtime assertions (ASSERT) for precondition and invariant sanity checking. Do not use runtime assertions to check for errors as they should never alter control flow and potentially be excluded.
• Assume UINT32/INT32 to be int-sized and use %u, %d, and %x to print them.
• Assume UINTN/INTN to be of unspecified size, and cast them to UINT64/INT64 for printing with %Lu, %Ld and so on as normal.
• Do not rely on integer promotions for numeric literals. Use explicit casts when the type is implementation-dependent or suffixes when type size is known. Assume U for UINT32 and ULL for UINT64.
• Do ensure unsigned arithmetics especially in bitwise maths, shifts in particular.
• sizeof operator should take variables instead of types where possible to be error prone. Use ARRAY_SIZE to obtain array size in elements. Use L_STR_LEN and L_STR_SIZE macros from OcStringLib to obtain string literal sizes to ensure compiler optimisation.
• Do not use goto keyword. Prefer early return, break, or continue after failing to pass error checking instead of nesting conditionals.
• Use EFIAPI, force UEFI calling convention, only in protocols, external callbacks between modules, and functions with variadic arguments.
• Provide inline documentation to every added function, at least describing its inputs, outputs, precondition, postcondition, and giving a brief description.
• Do not use RETURN_STATUS. Assume EFI_STATUS to be a matching superset that is to be always used when BOOLEAN is not enough.
• Security violations should halt the system or cause a forced reboot.

Codestyle. The codebase follows the EDK II codestyle with a few changes and clarifications.

• Write inline documentation for the functions and variables only once: in headers, where a header prototype is available, and inline for static variables and functions.
• Use line length of 120 characters or less, preferably 100 characters.
• Use spaces after casts, e.g. (VOID *)(UINTN) Variable.
• Use two spaces to indent function arguments when splitting lines.
• Prefix public functions with either Oc or another distinct name.
• Do not prefix private static functions, but prefix private non-static functions with Internal.
• Use SPDX license headers as shown in acidanthera/bugtracker#483.

3.5 Debugging

The codebase incorporates EDK II debugging and few custom features to improve the experience.

• Use module prefixes, 2-5 letters followed by a colon (:), for debug messages. For OpenCorePkg use OC:, for libraries and drivers use their own unique prefixes.
• Do not use dots (.) in the end of debug messages and separate EFI_STATUS, printed by %r, with a hyphen (e.g. OCRAM: Allocation of %u bytes failed - %r\n).
• Use DEBUG_CODE_BEGIN () and DEBUG_CODE_END () constructions to guard debug checks that may potentially reduce the performance of release builds and are otherwise unnecessary.
• Use DEBUG macro to print debug messages during normal functioning, and RUNTIME_DEBUG for debugging after EXIT_BOOT_SERVICES.
• Use DEBUG_VERBOSE debug level to leave debug messages for future debugging of the code, which are currently not necessary. By default DEBUG_VERBOSE messages are ignored even in DEBUG builds.
• Use DEBUG_INFO debug level for all non critical messages (including errors) and DEBUG_BULK_INFO for extensive messages that should not appear in NVRAM log that is heavily limited in size. These messages are ignored in RELEASE builds.
• Use DEBUG_ERROR to print critical human visible messages that may potentially halt the boot process, and DEBUG_WARN for all other human visible errors, RELEASE builds included.

The git-bisect functionality may be useful when trying to find problematic changes. Unofficial sources of per-commit OpenCore binary builds, such as Dortania, may also be useful.

4 ACPI

4.1 Introduction

ACPI (Advanced Configuration and Power Interface) is an open standard to discover and configure computer hardware. The ACPI specification defines standard tables (e.g. DSDT, SSDT, FACS, DMAR) and various methods (e.g. _DSM, _PRW) for implementation. Modern hardware needs few changes to maintain ACPI compatibility and some options for such changes are provided as part of OpenCore.

To compile and disassemble ACPI tables, the iASL compiler developed by ACPICA can be used. A GUI front-end to iASL compiler can be downloaded from Acidanthera/MaciASL.

ACPI changes apply globally (to every operating system) with the following effective order:

• Delete is processed.
• Quirks are processed.
• Patch is processed.
• Add is processed.

Note: RebaseRegions and SyncTableIds quirks are special and are processed after all other ACPI changes since they can only be applied on the final ACPI configuration including all the patches and added tables.

Applying the changes globally resolves the problems of incorrect operating system detection (consistent with the ACPI specification, not possible before the operating system boots), operating system chainloading, and difficult ACPI debugging. Hence, more attention may be required when writing changes to _OSI.

Applying the patches early makes it possible to write so called “proxy” patches, where the original method is patched in the original table and is implemented in the patched table.

There are several sources of ACPI tables and workarounds. Commonly used ACPI tables are provided with OpenCore, VirtualSMC, VoodooPS2, and WhateverGreen releases. Besides those, several third-party instructions may be found on the AppleLife Laboratory and DSDT subforums (e.g. Battery register splitting guide). A slightly more user-friendly explanation of some tables included with OpenCore can also be found in Dortania’s Getting started with ACPI guide. For more exotic cases, there are several alternatives such as daliansky’s ACPI sample collection ( English Translation by 5T33Z0 et al). Please note however, that suggested solutions from third parties may be outdated or may contain errors.

4.2 Properties

1. Add
   Type: plist array
   Failsafe: Empty
   Description: Load selected tables from the OC/ACPI directory.

   To be filled with plist dict values, describing each add entry. Refer to the Add Properties section below for details.

2. Delete
   Type: plist array
   Failsafe: Empty
   Description: Remove selected tables from the ACPI stack.

   To be filled with plist dict values, describing each delete entry. Refer to the Delete Properties section below for details.

3. Patch
   Type: plist array
   Failsafe: Empty
   Description: Perform binary patches in ACPI tables before table addition or removal.

   To be filled with plist dictionary values describing each patch entry. Refer to the Patch Properties section below for details.

4. Quirks
   Type: plist dict
   Description: Apply individual ACPI quirks described in the Quirks Properties section below.

4.3 Add Properties

1. Comment
   Type: plist string
   Failsafe: Empty
   Description: Arbitrary ASCII string used to provide human readable reference for the entry. Whether this value is used is implementation defined.
2. Enabled
   Type: plist boolean
   Failsafe: false
   Description: Set to true to add this ACPI table.

3. Path
   Type: plist string
   Failsafe: Empty
   Description: File paths meant to be loaded as ACPI tables. Example values include DSDT.aml, SubDir/SSDT-8.aml, SSDT-USBX.aml, etc.

   The ACPI table load order follows the item order in the array. ACPI tables are loaded from the OC/ACPI directory.

   Note: All tables apart from tables with a DSDT table identifier (determined by parsing data, not by filename) insert new tables into the ACPI stack. DSDT tables perform a replacement of DSDT tables instead.

4.4 Delete Properties

1. All
   Type: plist boolean
   Failsafe: false (Only delete the first matched table)
   Description: Set to true to delete all ACPI tables matching the condition.
2. Comment
   Type: plist string
   Failsafe: Empty
   Description: Arbitrary ASCII string used to provide human readable reference for the entry. Whether this value is used is implementation defined.
3. Enabled
   Type: plist boolean
   Failsafe: false
   Description: Set to true to remove this ACPI table.
4. OemTableId
   Type: plist data, 8 bytes
   Failsafe: All zero (Match any table OEM ID)
   Description: Match table OEM ID equal to this value.
5. TableLength
   Type: plist integer
   Failsafe: 0 (Match any table size)
   Description: Match table size equal to this value.

6. TableSignature
   Type: plist data, 4 bytes
   Failsafe: All zero (Match any table signature)
   Description: Match table signature equal to this value.

   Note: Do not use table signatures when the sequence must be replaced in multiple places. This is particularly relevant when performing different types of renames.

4.5 Patch Properties

1. Base
   Type: plist string
   Failsafe: Empty (Ignored)
   Description: Selects 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.

   Note: Use with care, not all OEM tables can be parsed. Use ACPIe utility to debug. ACPIe compiled with DEBUG=1 make command produces helpful ACPI lookup tracing.

2. BaseSkip
   Type: plist integer
   Failsafe: 0 (Do not skip any occurrences)
   Description: Number of found Base occurrences to skip before finds and replacements are applied.
3. Comment
   Type: plist string
   Failsafe: Empty
   Description: Arbitrary ASCII string used to provide human readable reference for the entry. Whether this value is used is implementation defined.
4. Count
   Type: plist integer
   Failsafe: 0 (Apply patch to all occurrences found)
   Description: Number of occurrences to patch.
5. Enabled
   Type: plist boolean
   Failsafe: false
   Description: Set to true to apply this ACPI patch.

6. Find
   Type: plist data
   Failsafe: Empty
   Description: Data to find. Must be equal to Replace in size if set.

   Note: Can be empty, when Base is specified, immediate replacement after Base lookup happens in this case.

7. Limit
   Type: plist integer
   Failsafe: 0 (Search entire ACPI table)
   Description: Maximum number of bytes to search for.
8. Mask
   Type: plist data
   Failsafe: Empty (Ignored)
   Description: Data 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.
9. OemTableId
   Type: plist data, 8 bytes
   Failsafe: All zero (Match any table OEM ID)
   Description: Match table OEM ID equal to this value.
10. Replace
    Type: plist data
    Failsafe: Empty
    Description: Replacement data of one or more bytes.
11. ReplaceMask
    Type: plist data
    Failsafe: Empty (Ignored)
    Description: Data 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.
12. Skip
    Type: plist integer
    Failsafe: 0 (Do not skip any occurrences)
    Description: Number of found occurrences to skip before replacements are applied.
13. TableLength
    Type: plist integer
    Failsafe: 0 (Match any table size)
    Description: Match table size equal to this value.
14. TableSignature
    Type: plist data, 4 bytes
    Failsafe: All zero (Match any table signature)
    Description: Match table signature equal to this value.

In most cases, ACPI patches are not useful and are harmful:

• Avoid renaming devices with ACPI patches. This may fail or perform improper renaming of unrelated devices (e.g. EC and EC0), be unnecessary, or even fail to rename devices in certain tables. For ACPI consistency it is much safer to rename devices at the I/O Registry level, as done by WhateverGreen.
• Avoid patching _OSI to support a higher feature set level whenever possible. While this enables a number of workarounds on APTIO firmware, it typically results in a need for additional patches. These are not usually needed on modern firmware and smaller patches work well on firmware that does. However, laptop vendors often rely on this method to determine the availability of functions such as modern I2C input support, thermal adjustment and custom feature additions.
• Avoid patching embedded controller event _Qxx just to enable brightness keys. The conventional process to find these keys typically involves significant modifications to DSDT and SSDT files and in addition, the debug kext is not stable on newer systems. Please use the built-in brightness key discovery in BrightnessKeys instead.
• Avoid making ad hoc changes such as renaming _PRW or _DSM whenever possible.

Some cases where patching is actually useful include:

• Refreshing HPET (or another device) method header to avoid compatibility checks by _OSI on legacy hardware. _STA method with if ((OSFL () == Zero)) { If (HPTE) ... Return (Zero) content may be forced to always return 0xF by replacing A0 10 93 4F 53 46 4C 00 with A4 0A 0F A3 A3 A3 A3 A3.
• To provide a custom method implementation within an SSDT, to inject shutdown fixes on certain computers for instance, the original method can be replaced with a dummy name by patching _PTS with ZPTS and adding a callback to the original method.

The Tianocore AcpiAml.h source file may help with better understanding ACPI opcodes.

Note: Patches of different Find and Replace lengths are unsupported as they may corrupt ACPI tables and make the system unstable due to area relocation. If such changes are needed, the utilisation of “proxy” patching or the padding of NOP to the remaining area could be considered.

4.6 Quirks Properties

1. FadtEnableReset
   Type: plist boolean
   Failsafe: false
   Description: 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.

2. NormalizeHeaders
   Type: plist boolean
   Failsafe: false
   Description: Cleanup ACPI header fields to workaround macOS ACPI implementation flaws that result in boot crashes. Reference: Debugging AppleACPIPlatform on 10.13 by Alex James (also known as theracermaster). The issue was fixed in macOS Mojave (10.14).

3. RebaseRegions
   Type: plist boolean
   Failsafe: false
   Description: Attempt to heuristically relocate ACPI memory regions. Not recommended.

   ACPI tables are often generated dynamically by the underlying firmware implementation. Among the position-independent code, ACPI tables may contain the physical addresses of MMIO areas used for device configuration, typically grouped by region (e.g. OperationRegion). Changing firmware settings or hardware configuration, upgrading or patching the firmware inevitably leads to changes in dynamically generated ACPI code, which sometimes results in the shift of the addresses in the aforementioned OperationRegion constructions.

   For this reason, the application of modifications to ACPI tables is extremely risky. The best approach is to make as few changes as possible to ACPI tables and to avoid replacing any tables, particularly DSDT tables. When this cannot be avoided, ensure that any custom DSDT tables are based on the most recent DSDT tables or attempt to remove reads and writes for the affected areas.

   When nothing else helps, this option could be tried to avoid stalls at PCI Configuration Begin phase of macOS booting 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 unless absolutely required as it can have the opposite effect on certain platforms and result in boot failures.

4. ResetHwSig
   Type: plist boolean
   Failsafe: false
   Description: 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.

5. ResetLogoStatus
   Type: plist boolean
   Failsafe: false
   Description: Reset BGRT table Displayed status field to false.

   This works around firmware that provide a BGRT table but fail to handle screen updates afterwards.

6. SyncTableIds
   Type: plist boolean
   Failsafe: false
   Description: 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.

5 Booter

5.1 Introduction

This section allows the application of different types of UEFI modifications to operating system bootloaders, primarily the Apple bootloader (boot.efi). The modifications currently provide various patches and environment alterations for different firmware types. Some of these features were originally implemented as part of AptioMemoryFix.efi, which is no longer maintained. Refer to the Tips and Tricks section for instructions on migration.

Booter changes apply with the following effective order:

• Quirks are processed.
• Patch is processed.

If this is used for the first time on customised firmware, the following requirements should be met before starting:

• Most up-to-date UEFI firmware (check the motherboard vendor website).
• Fast Boot and Hardware Fast Boot disabled in firmware settings if present.
• 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 ControlMsrE2 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 MmioWhitelist Properties section below for details.

2. Patch
   Type: plist array
   Failsafe: Empty
   Description: Perform binary patches in booter.

   To be filled with plist dictionary values, describing each patch. Refer to the Patch Properties section below for details.

3. Quirks
   Type: plist dict
   Description: Apply individual booter quirks described in the 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. The debug log can be used to find the list of the candidates.

2. Comment
   Type: plist string
   Failsafe: Empty
   Description: Arbitrary ASCII string used to provide human readable reference for the entry. Whether this value is used is implementation defined.
3. Enabled
   Type: plist boolean
   Failsafe: false
   Description: Exclude MMIO address from the devirtualisation procedure.

5.4 Patch Properties

1. Arch
   Type: plist string
   Failsafe: Any (Apply to any supported architecture)
   Description: Booter patch architecture (i386, x86_64).
2. Comment
   Type: plist string
   Failsafe: Empty
   Description: Arbitrary ASCII string used to provide human readable reference for the entry. Whether this value is used is implementation defined.
3. Count
   Type: plist integer
   Failsafe: 0 (Apply to all occurrences found)
   Description: Number of patch occurrences to apply.
4. Enabled
   Type: plist boolean
   Failsafe: false
   Description: Set to true to activate this booter patch.
5. Find
   Type: plist data
   Failsafe: Empty
   Description: Data to find. Must be equal to Replace in size if set.
6. Identifier
   Type: plist string
   Failsafe: Any (Match any booter)
   Description: Apple for macOS booter (typically boot.efi); or a name with a suffix, such as bootmgfw.efi, for a specific booter.
7. Limit
   Type: plist integer
   Failsafe: 0 (Search the entire booter)
   Description: Maximum number of bytes to search for.
8. Mask
   Type: plist data
   Failsafe: Empty (Ignored)
   Description: Data 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.
9. Replace
   Type: plist data
   Failsafe: Empty
   Description: Replacement data of one or more bytes.
10. ReplaceMask
    Type: plist data
    Failsafe: Empty (Ignored)
    Description: Data 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.
11. Skip
    Type: plist integer
    Failsafe: 0 (Do not skip any occurrences)
    Description: Number of found occurrences to skip before replacements are applied.

5.5 Quirks Properties

1. AllowRelocationBlock
   Type: plist boolean
   Failsafe: false
   Description: 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 Mac OS X 10.7 or older)

   This quirk typically requires ProvideCustomSlide and AvoidRuntimeDefrag to be enabled 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.

   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 such cases, consider using 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 certain services such as variable storage. SMM may try to access memory by physical addresses in non-SMM areas but this may sometimes have been moved by boot.efi. This option prevents boot.efi from moving such data.

   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 certain MMIO regions.

   This quirk reduces the stolen memory footprint in 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.

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 the CMD+S hotkey and the -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.

   Note: When Apple Secure Boot is enabled single user mode is always disabled.

5. DisableVariableWrite
   Type: plist boolean
   Failsafe: false
   Description: 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.

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

6. DiscardHibernateMap
   Type: plist boolean
   Failsafe: false
   Description: Reuse original hibernate memory map.

   This option forces the XNU kernel to ignore a newly supplied memory map and assume that it did not change after waking from hibernation. This behaviour is required by Windows to work. Windows mandates preserving runtime memory size and location after S4 wake.

   Note: This may be used to workaround defective memory map implementations on older, rare legacy hardware. Examples of such hardware are Ivy Bridge laptops with Insyde firmware such as the Acer V3-571G. Do not use this option without a full understanding of the implications.

7. EnableSafeModeSlide
   Type: plist boolean
   Failsafe: false
   Description: 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 attempts to patch the boot.efi file to remove this limitation and to allow using other values (from 1 to 255 inclusive).
   • This quirk requires enabling ProvideCustomSlide.

   Note: The need for this option is dependent on the availability of safe mode. It can be enabled when booting to safe mode fails.

8. EnableWriteUnprotector
   Type: plist boolean
   Failsafe: false
   Description: Permit write access to UEFI runtime services code.

   This option bypasses W^X permissions in code pages of UEFI runtime services by removing write protection (WP) bit from CR0 register during their execution. This quirk requires OC_FIRMWARE_RUNTIME protocol implemented in OpenRuntime.efi.

   Note: This quirk may potentially weaken firmware security. Please use RebuildAppleMemoryMap if the firmware supports memory attributes table (MAT). Refer to the OCABC: MAT support is 1/0 log entry to determine whether MAT is supported.

9. FixupAppleEfiImages
   Type: plist boolean
   Failsafe: false
   Description: Fix permissions and section errors in macOS boot.efi images.

   Mac OS X boot.efi images contain W^X permissions errors in all versions, and 10.4 and 10.5 32-bit versions also contain illegal overlapping sections. Modern, strict PE loaders will refuse to load such images unless additional mitigations are applied. The image loader which matters here is the one provided by the system firmware, or by OpenDuet if OpenDuet is providing the UEFI compatibility layer. Image loaders which enforce these stricter rules include the loader provided with current versions of OpenDuet, the loader in OVMF if compiled from audk, and possibly the image loaders of some very recent 3rd party firmware (e.g. Microsoft).

   This quirk detects these issues and pre-processes such images in memory so that a stricter loader will accept them.

   On a system with such a modern, stricter loader this quirk is required to load Mac OS X 10.4 to macOS 10.12, and is required for all newer macOS when SecureBootModel is set to Disabled.

   Note 1: The quirk is never applied during the Apple secure boot path for newer macOS. The Apple secure boot path in OpenCore includes its own separate mitigations for boot.efi W^X issues.

   Note 2: When enabled, and when not processing for Apple secure boot, this quirk is applied to:

   • All images from Apple Fat binaries (32-bit and 64-bit versions in one image).
   • All Apple-signed images.
   • All images at \System\Library\CoreServices\boot.efi within their filesystem.

   Note 3: Pre-processing in memory is incompatible with UEFI secure boot, as the image loaded is not the image on disk, so you cannot sign files which are loaded in this way based on their original disk image contents. Certain firmware will offer to register the hash of new, unknown images for future secure boot - this would still work. On the other hand, it is not particularly realistic to want to start these early, insecure images with secure boot anyway.

10. ForceBooterSignature
    Type: plist boolean
    Failsafe: false
    Description: Set 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.

    Note: OpenCore launcher path is determined from LauncherPath property.

11. ForceExitBootServices
    Type: plist boolean
    Failsafe: false
    Description: Retry ExitBootServices with 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.

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

12. ProtectMemoryRegions
    Type: plist boolean
    Failsafe: false
    Description: 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.

    This quirk attempts to fix the types of these regions, e.g. ACPI NVS for CSM or MMIO for MMIO.

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

13. ProtectSecureBoot
    Type: plist boolean
    Failsafe: false
    Description: 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.

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

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

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

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

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

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

    • The Memory map size must not exceed 4096 bytes as the Apple kernel maps it as a single 4K page. As some types of firmware can have very large memory maps, potentially over 100 entries, the Apple kernel will crash on boot.
    • The Memory attributes table is ignored. EfiRuntimeServicesCode memory statically gets RX permissions while all other memory types get RW permissions. As some firmware drivers may write to global variables at runtime, the Apple kernel will crash at calling UEFI runtime services unless the driver .data section has a EfiRuntimeServicesData type.

    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 Mac OS X 10.6, and earlier, for reasons that are as yet unclear.

18. 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. While Apple macOS supports a theoretical 1 GB maximum, 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:

    • BAR0 supports sizes from 256 MB to 8 GB. Its value is 4 GB.
    • BAR1 supports sizes from 2 MB to 256 MB. Its value is 256 MB.

    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.

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

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

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

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

    Some types of firmware fail to properly handle runtime permissions:

    • They incorrectly mark OpenRuntime as not executable in the memory map.
    • They incorrectly mark OpenRuntime as not executable in the memory attributes table.
    • They lose entries from the memory attributes table after OpenRuntime is loaded.
    • They mark items in the memory attributes table as read-write-execute.

    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.

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. During IOService registration (IOServices::registerService) callbacks implemented as a part of
   AppleACPIPlatformExpert::platformAdjustService function and its private worker method
   AppleACPIPlatformExpert::platformAdjustPCIDevice specific to the PCI devices.

The application of the stages depends on the device presence in ACPI tables. The first stage applies very early but exclusively to the devices present in ACPI tables. The second stage applies to all devices much later after the PCI configuration and may repeat the first stage if the device was not present in ACPI.

For all kernel extensions that may inspect the IODeviceTree plane without probing, such as Lilu and its plugins (e.g. WhateverGreen), it is especially important to ensure device presence in the ACPI tables. A failure to do so may result in erratic behaviour caused by ignoring the injected device properties as they were not constructed at the first stage. See SSDT-IMEI.dsl and SSDT-BRG0.dsl for an example.

6.2 Properties

1. Add
   Type: plist dict
   Description: Sets device properties from a map (plist dict) of device paths to a map (plist dict) of variable names and their values in plist multidata format.

   Note 1: Device paths must be provided in canonic string format (e.g. PciRoot(0x0)/Pci(0x1,0x0)/Pci(0x0,0x0)).

   Note 2: Existing properties will not be changed unless deleted in the DeviceProperties Delete section.

2. Delete
   Type: plist dict
   Description: Removes device properties from a map (plist dict) of device paths to an array (plist array) of variable names in plist string format.

   Note: Currently, existing properties may only exist on firmware with DeviceProperties drivers (e.g. Apple). Hence, there is typically no reason to delete variables unless a new driver has been installed.

6.3 Common Properties

Some known properties include:

• device-id User-specified device identifier used for I/O Kit matching. Has 4 byte data type.
• vendor-id User-specified vendor identifier used for I/O Kit matching. Has 4 byte data type.
• AAPL,ig-platform-id Intel GPU framebuffer identifier used for framebuffer selection on Ivy Bridge and newer. Has 4 byte data type.
• AAPL,snb-platform-id Intel GPU framebuffer identifier used for framebuffer selection on Sandy Bridge. Has 4 byte data type.
• layout-id Audio layout used for AppleHDA layout selection. Has 4 byte data type.

7 Kernel

7.1 Introduction

This section allows the application of different kinds of kernelspace modifications on Apple Kernel ( XNU). The modifications currently provide driver (kext) injection, kernel and driver patching, and driver blocking.

Kernel and kext changes apply with the following effective order:

• Block is processed.
• Add and Force are processed.
• Emulate and Quirks are processed.
• Patch is processed.

7.2 Properties

1. Add
   Type: plist array
   Failsafe: Empty
   Description: Load selected kernel extensions (kexts) from the OC/Kexts directory.

   To be filled with plist dict values, describing each kext. Refer to the Add Properties section below for details.

   Note 1: The load order is based on the order in which the kexts appear in the array. Hence, dependencies must appear before kexts that depend on them.

   Note 2: To track the dependency order, inspect the OSBundleLibraries key in the Info.plist file of the kext being added. Any kext included under the key is a dependency that must appear before the kext being added.

   Note 3: 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.

2. Block
   Type: plist array
   Failsafe: Empty
   Description: Remove selected kernel extensions (kexts) from the prelinked kernel.

   To be filled with plist dictionary values, describing each blocked kext. Refer to the Block Properties section below for details.

3. Emulate
   Type: plist dict
   Description: Emulate certain hardware in kernelspace via parameters described in the Emulate Properties section below.

4. Force
   Type: plist array
   Failsafe: Empty
   Description: Load kernel extensions (kexts) from the system volume if they are not cached.

   To be filled with plist dict values, describing each kext. Refer to the Force Properties section below for details. This section 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.

   Note 1: The load order is based on the order in which the kexts appear in the array. Hence, dependencies must appear before kexts that depend on them.

   Note 2: Force happens before Add.

   Note 3: The signature of the “forced” kext is not checked in any way. This makes using this feature extremely dangerous and undesirable for secure boot.

   Note 4: This feature may not work on encrypted partitions in newer operating systems.

5. Patch
   Type: plist array
   Failsafe: Empty
   Description: Perform binary patches in kernel and drivers prior to driver addition and removal.

   To be filled with plist dictionary values, describing each patch. Refer to the Patch Properties section below for details.

6. Quirks
   Type: plist dict
   Description: Apply individual kernel and driver quirks described in the Quirks Properties section below.
7. Scheme
   Type: plist dict
   Description: Define kernelspace operation mode via parameters described in the Scheme Properties section below.

7.3 Add Properties

1. Arch
   Type: plist string
   Failsafe: Any (Apply to any supported architecture)
   Description: Kext architecture (i386, x86_64).
2. BundlePath
   Type: plist string
   Failsafe: Empty
   Description: Kext bundle path (e.g. Lilu.kext or MyKext.kext/Contents/PlugIns/MySubKext.kext).
3. Comment
   Type: plist string
   Failsafe: Empty
   Description: Arbitrary ASCII string used to provide human readable reference for the entry. Whether this value is used is implementation defined.
4. Enabled
   Type: plist boolean
   Failsafe: false
   Description: Set to true to add this kernel extension.
5. ExecutablePath
   Type: plist string
   Failsafe: Empty
   Description: Kext executable path relative to bundle (e.g. Contents/MacOS/Lilu).

6. MaxKernel
   Type: plist string
   Failsafe: Empty
   Description: Adds kernel extension on specified macOS version or older.

   Kernel version can be obtained with uname -r command, and should look like 3 numbers separated by dots, for example 18.7.0 is the kernel version for 10.14.6. Kernel version interpretation is implemented as follows:

   ParseDarwinV ersion(κ,λ,μ) = κ ⋅ 10000Where κ ∈ (0,99) is kernel version major + λ ⋅ 100 Where λ ∈ (0,99) is kernel version minor + μ Where μ ∈ (0,99) is kernel version patch

   Kernel version comparison is implemented as follows:

   α	=
   β	=
   γ	=
   	f(α,β,γ) = α ≤ γ ≤ β

   Here ParseDarwinV ersion argument is assumed to be 3 integers obtained by splitting Darwin kernel version string from left to right by the . symbol. FindDarwinV ersion function looks up Darwin kernel version by locating "Darwin Kernel Version κ.λ.μ" string in the kernel image.

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

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

8. PlistPath
   Type: plist string
   Failsafe: Empty
   Description: Kext Info.plist path relative to bundle (e.g. Contents/Info.plist).

7.4 Block Properties

1. Arch
   Type: plist string
   Failsafe: Any (Apply to any supported architecture)
   Description: Kext block architecture (i386, x86_64).
2. Comment
   Type: plist string
   Failsafe: Empty
   Description: Arbitrary ASCII string used to provide human readable reference for the entry. Whether this value is used is implementation defined.
3. Enabled
   Type: plist boolean
   Failsafe: false
   Description: Set to true to block this kernel extension.
4. Identifier
   Type: plist string
   Failsafe: Empty
   Description: Kext bundle identifier (e.g. com.apple.driver.AppleTyMCEDriver).

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

6. 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. Strategy
   Type: plist string
   Failsafe: Disable (Forcibly make the kernel driver kmod startup code return failure)
   Description: Determines the behaviour of kernel driver blocking.

   Valid values:

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

   Note: It is risky to Exclude a kext that is a dependency of others.

   Note 2: At this moment Exclude is only applied to prelinkedkernel and newer mechanisms.

   Note 3: In most cases strategy Exclude requires the new kext to be injected as a replacement.

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:

   • Enabling support for an unsupported CPU model (e.g. Intel Pentium).
   • Enabling support for a CPU model not yet supported by a specific version of macOS (typically old versions).
   • Enabling XCPM support for an unsupported CPU variant.

   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. Be warned that one is required to set the correct frequency vectors matching the installed CPU.

   • Haswell-E (0x0306F2) to Haswell (0x0306C3):
     Cpuid1Data: C3 06 03 00 00 00 00 00 00 00 00 00 00 00 00 00
     Cpuid1Mask: FF FF FF FF 00 00 00 00 00 00 00 00 00 00 00 00
   • Broadwell-E (0x0406F1) to Broadwell (0x0306D4):
     Cpuid1Data: D4 06 03 00 00 00 00 00 00 00 00 00 00 00 00 00
     Cpuid1Mask: FF FF FF FF 00 00 00 00 00 00 00 00 00 00 00 00
   • Comet Lake U62 (0x0A0660) to Comet Lake U42 (0x0806EC):
     Cpuid1Data: EC 06 08 00 00 00 00 00 00 00 00 00 00 00 00 00
     Cpuid1Mask: FF FF FF FF 00 00 00 00 00 00 00 00 00 00 00 00
   • Rocket Lake (0x0A0670) to Comet Lake (0x0A0655):
     Cpuid1Data: 55 06 0A 00 00 00 00 00 00 00 00 00 00 00 00 00
     Cpuid1Mask: FF FF FF FF 00 00 00 00 00 00 00 00 00 00 00 00
   • Alder Lake (0x090672) to Comet Lake (0x0A0655):
     Cpuid1Data: 55 06 0A 00 00 00 00 00 00 00 00 00 00 00 00 00
     Cpuid1Mask: FF FF FF FF 00 00 00 00 00 00 00 00 00 00 00 00

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

   • Consumer Ivy Bridge (0x0306A9) as Apple disabled XCPM for Ivy Bridge and recommends legacy power management for these CPUs. _xcpm_bootstrap should manually be patched to enforce XCPM on these CPUs instead of this option.
   • Low-end CPUs (e.g. Haswell+ Pentium) as they are not supported properly by macOS. Legacy workarounds for older models can be found in the Special NOTES section of acidanthera/bugtracker#365.

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

7.6 Force Properties

1. Arch
   Type: plist string
   Failsafe: Any (Apply to any supported architecture)
   Description: Kext architecture (i386, x86_64).
2. BundlePath
   Type: plist string
   Failsafe: Empty
   Description: Kext bundle path (e.g. System\Library \Extensions \IONetworkingFamily.kext).
3. Comment
   Type: plist string
   Failsafe: Empty
   Description: Arbitrary ASCII string used to provide human readable reference for the entry. Whether this value is used is implementation defined.
4. Enabled
   Type: plist boolean
   Failsafe: false
   Description: Set to true to load this kernel extension from the system volume when not present in the kernel cache.
5. ExecutablePath
   Type: plist string
   Failsafe: Empty
   Description: Kext executable path relative to bundle (e.g. Contents/MacOS/IONetworkingFamily).
6. Identifier
   Type: plist string
   Failsafe: Empty
   Description: Kext identifier to perform presence checking before adding (e.g. com.apple.iokit.IONetworkingFamily). Only drivers which identifiers are not be found in the cache will be added.

7. MaxKernel
   Type: plist string
   Failsafe: Empty
   Description: Adds kernel extension on specified macOS version or older.

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

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

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

9. PlistPath
   Type: plist string
   Failsafe: Empty
   Description: Kext Info.plist path relative to bundle (e.g. Contents/Info.plist).

7.7 Patch Properties

1. Arch
   Type: plist string
   Failsafe: Any (Apply to any supported architecture)
   Description: Kext patch architecture (i386, x86_64).
2. Base
   Type: plist string
   Failsafe: Empty (Ignored)
   Description: Selects symbol-matched base for patch lookup (or immediate replacement) by obtaining the address of the provided symbol name.
3. Comment
   Type: plist string
   Failsafe: Empty
   Description: Arbitrary ASCII string used to provide human readable reference for the entry. Whether this value is used is implementation defined.
4. Count
   Type: plist integer
   Failsafe: 0
   Description: Number of patch occurrences to apply. 0 applies the patch to all occurrences found.
5. Enabled
   Type: plist boolean
   Failsafe: false
   Description: This kernel patch will not be used unless set to true.
6. Find
   Type: plist data
   Failsafe: Empty (Immediate replacement at Base)
   Description: Data to find. Must be equal to Replace in size if set.
7. Identifier
   Type: plist string
   Failsafe: Empty
   Description: Kext bundle identifier (e.g. com.apple.driver.AppleHDA) or kernel for kernel patch.
8. Limit
   Type: plist integer
   Failsafe: 0 (Search entire kext or kernel)
   Description: Maximum number of bytes to search for.
9. Mask
   Type: plist data
   Failsafe: Empty (Ignored)
   Description: Data 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.

10. MaxKernel
    Type: plist string
    Failsafe: Empty
    Description: Patches data on specified macOS version or older.

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

11. MinKernel
    Type: plist string
    Failsafe: Empty
    Description: Patches data on specified macOS version or newer.

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

12. Replace
    Type: plist data
    Failsafe: Empty
    Description: Replacement data of one or more bytes.
13. ReplaceMask
    Type: plist data
    Failsafe: Empty (Ignored)
    Description: Data 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.
14. Skip
    Type: plist integer
    Failsafe: 0 (Do not skip any occurrences)
    Description: Number of found occurrences to skip before replacements are applied.

7.8 Quirks Properties

1. AppleCpuPmCfgLock
   Type: plist boolean
   Failsafe: false
   Requirement: 10.4
   Description: Disables PKG_CST_CONFIG_CONTROL (0xE2) MSR modification in AppleIntelCPUPowerManagement.kext, commonly causing early kernel panic, when it is locked from writing.

   Note: AppleIntelCPUPowerManagement.kext is removed as of macOS 13. However, a legacy version can be injected and thus get patched using this quirk.

   Some types of firmware lock the PKG_CST_CONFIG_CONTROL MSR register and the bundled ControlMsrE2 tool can be used to check its state. Note that some types of firmware only have this register locked on some cores. As modern firmware provide a CFG Lock setting that allows configuring the PKG_CST_CONFIG_CONTROL MSR register lock, this option should be avoided whenever possible.

   On APTIO firmware that do not provide a CFG Lock setting in the GUI, it is possible to access the option directly:

   1. Download UEFITool and IFR-Extractor.
   2. Open the firmware image in UEFITool and find CFG Lock unicode string. If it is not present, the firmware may not have this option and the process should therefore be discontinued.
   3. Extract the Setup.bin PE32 Image Section (the UEFITool found) through the Extract Body menu option.
   4. Run IFR-Extractor on the extracted file (e.g. ./ifrextract Setup.bin Setup.txt).
   5. Find CFG Lock, VarStoreInfo (VarOffset/VarName): in Setup.txt and remember the offset right after it (e.g. 0x123).
   6. Download and run Modified GRUB Shell compiled by brainsucker or use a newer version by datasone.
   7. Enter setup_var 0x123 0x00 command, where 0x123 should be replaced by the actual offset, and reboot.

   Warning: Variable offsets are unique not only to each motherboard but even to its firmware version. Never ever try to use an offset without checking.

   On selected platforms, the ControlMsrE2 tool can also change such hidden options. Pass desired argument: lock, unlock for CFG Lock. Or pass interactive to find and modify other hidden options.

   As a last resort, consider patching the BIOS (for advanced users only).

2. AppleXcpmCfgLock
   Type: plist boolean
   Failsafe: false
   Requirement: 10.8 (not required for older)
   Description: 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).

   Note: This option should be avoided whenever possible. Refer to the AppleCpuPmCfgLock description for details.

3. AppleXcpmExtraMsrs
   Type: plist boolean
   Failsafe: false
   Requirement: 10.8 (not required for older)
   Description: 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. More details on the XCPM patches are outlined in acidanthera/bugtracker#365.

   Note: Additional not provided patches will be required for Ivy Bridge or Pentium CPUs. It is recommended to use AppleIntelCpuPowerManagement.kext for the former.

4. AppleXcpmForceBoost
   Type: plist boolean
   Failsafe: false
   Requirement: 10.8 (not required for older)
   Description: Forces maximum performance in XCPM mode.

   This patch writes 0xFF00 to MSR_IA32_PERF_CONTROL (0x199), effectively setting maximum multiplier for all the time.

   Note: While this may increase the performance, this patch is strongly discouraged on all systems but those explicitly dedicated to scientific or media calculations. Only certain Xeon models typically benefit from the patch.

5. CustomPciSerialDevice
   Type: plist boolean
   Failsafe: false
   Requirement: 10.7
   Description: Performs change of PMIO register base address on a customised PCI serial device.

   The patch changes the PMIO register base address that the XNU kernel uses for serial input and output, from that of the default built-in COM1 serial port 0x3F8, to the base address stored in the first IO BAR of a specified PCI device or to a specific base address (e.g. 0x2F8 for COM2).

   Note: By default, serial logging is disabled. serial=3 boot argument, which enables serial input and output, should be used for XNU to print logs to the serial port.

   Note 2: In addition to this patch, kext Apple16X50PCI0 should be prevented from attaching to have kprintf method working properly. This can be achieved by using PCIeSerialDisable. In addition, for certain Thunderbolt cards the IOKit personality IOPCITunnelCompatible also needs to be set to true, which can be done by the PCIeSerialThunderboltEnable.kext attached at acidanthera/bugtracker#2003.

   Note 3: For this patch to be correctly applied, Override must be enabled with all keys properly set in Custom, under section Misc->Serial.

   Note 4: This patch is for PMIO support and is therefore not applied if UseMmio under section Misc->Serial->Custom is false. For MMIO, there are boot arguments pcie_mmio_uart=ADDRESS and mmio_uart=ADDRESS that allow the kernel to use MMIO for serial port access.

   Note 5: The serial baud rate must be correctly set in both BaudRate under section Misc->Serial->Custom and via serialbaud=VALUE boot argument, both of which should match against each other. The default baud rate is 115200.

6. CustomSMBIOSGuid
   Type: plist boolean
   Failsafe: false
   Requirement: 10.4
   Description: Performs GUID patching for UpdateSMBIOSMode Custom mode. Usually relevant for Dell laptops.

7. DisableIoMapper
   Type: plist boolean
   Failsafe: false
   Requirement: 10.8 (not required for older)
   Description: Disables IOMapper support in XNU (VT-d), which may conflict with the firmware implementation.

   Note 1: This option is a preferred alternative to deleting DMAR ACPI table and disabling VT-d in firmware preferences, which does not obstruct VT-d support in other systems in case they need this.

   Note 2: Misconfigured IOMMU in the firmware may result in broken devices such as ethernet or Wi-Fi adapters. 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.

8. DisableIoMapperMapping
   Type: plist boolean
   Failsafe: false
   Requirement: 13.3 (not required for older)
   Description: Disables mapping PCI bridge device memory in IOMMU (VT-d).

   This option resolves compatibility issues with Wi-Fi, Ethernet and Thunderbolt devices when AppleVTD is enabled on systems where the native DMAR table contains one or more Reserved Memory Regions and more than 16 GB memory is installed. On some systems, this quirk is only needed when iGPU is enabled.

   Note 1: This quirk requires a native DMAR table that does not contain Reserved Memory Regions or a substitute SSDT-DMAR.aml in which Reserved Memory Regions have been removed.

   Note 2: This option is not needed on AMD systems.

9. DisableLinkeditJettison
   Type: plist boolean
   Failsafe: false
   Requirement: 11
   Description: Disables __LINKEDIT jettison code.

   This option lets Lilu.kext, and possibly other kexts, function in macOS Big Sur at their best performance levels without requiring the keepsyms=1 boot argument.

10. DisableRtcChecksum
    Type: plist boolean
    Failsafe: false
    Requirement: 10.4
    Description: Disables primary checksum (0x58-0x59) writing in AppleRTC.

    Note 1: This option will not protect other areas from being overwritten, see RTCMemoryFixup kernel extension if this is desired.

    Note 2: This option will not protect areas from being overwritten at firmware stage (e.g. macOS bootloader), see AppleRtcRam protocol description if this is desired.

11. ExtendBTFeatureFlags
    Type: plist boolean
    Failsafe: false
    Requirement: 10.8-11
    Description: Set FeatureFlags to 0x0F for full functionality of Bluetooth, including Continuity.

    Note: This option is a substitution for BT4LEContinuityFixup.kext, which does not function properly due to late patching progress.

12. ExternalDiskIcons
    Type: plist boolean
    Failsafe: false
    Requirement: 10.4
    Description: Apply icon type patches to AppleAHCIPort.kext to force internal disk icons for all AHCI disks.

    Note: This option should be avoided whenever possible. Modern firmware typically have compatible AHCI controllers.

13. ForceAquantiaEthernet
    Type: plist boolean
    Failsafe: false
    Requirement: 10.15.4
    Description: Enable Aquantia AQtion based 10GbE network cards support.

    This option enables Aquantia AQtion based 10GbE network cards support, which used to work natively before macOS 10.15.4.

    Note: In order for Aquantia cards to properly function, DisableIoMapper must be disabled, DMAR ACPI table must not be dropped, and VT-d must be enabled in BIOS.

    Note 2: While this patch should enable ethernet support for all Aquantia AQtion series, it has only been tested on AQC-107s based 10GbE network cards.

    Note 3: To address AppleVTD incompatibilities after applying this quirk, the Reserved Memory Region section of the corresponding device in the DMAR ACPI table might be removed. This table should be disassembled and edited, then recompiled to AML with tool iASL. For the patched DMAR table to be added, the original one should be deleted. More details can be found at comment on commit 2441455.

14. ForceSecureBootScheme
    Type: plist boolean
    Failsafe: false
    Requirement: 11
    Description: Force x86 scheme for IMG4 verification.

    Note: This option is required on virtual machines when using SecureBootModel different from x86legacy.

15. IncreasePciBarSize
    Type: plist boolean
    Failsafe: false
    Requirement: 10.10
    Description: 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.

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

16. LapicKernelPanic
    Type: plist boolean
    Failsafe: false
    Requirement: 10.6 (64-bit)
    Description: Disables kernel panic on LAPIC interrupts.
17. 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.
18. 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.

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

20. ProvideCurrentCpuInfo
    Type: plist boolean
    Failsafe: false
    Requirement: 10.4 (10.14)
    Description: Provides current CPU info to the kernel.

    This quirk works differently depending on the CPU:

    • For Microsoft Hyper-V it provides the correct TSC and FSB values to the kernel, as well as disables CPU topology validation (10.8+).
    • For KVM and other hypervisors it provides precomputed MSR 35h values solving kernel panic with -cpu host.
    • For Intel CPUs it adds support for asymmetrical SMP systems (e.g. Intel Alder Lake) by patching core count to thread count along with the supplemental required changes (10.14+). Cache size and cache line size are also provided when using 10.4 as Intel Penryn and newer may only have cache information in CPUID leaf 0x4 which is unsupported by 10.4.

21. SetApfsTrimTimeout
    Type: plist integer
    Failsafe: -1
    Requirement: 10.14 (not required for older)
    Description: Set trim timeout in microseconds for APFS filesystems on SSDs.

    The APFS filesystem is designed in a way that the space controlled via the spaceman structure is either used or free. This may be different in other filesystems where the areas can be marked as used, free, and unmapped. All free space is trimmed (unmapped/deallocated) at macOS startup. The trimming procedure for NVMe drives happens in LBA ranges due to the nature of the DSM command with up to 256 ranges per command. The more fragmented the memory on the drive is, the more commands are necessary to trim all the free space.

    Depending on the SSD controller and the level of drive fragmenation, the trim procedure may take a considerable amount of time, causing noticeable boot slowdown. The APFS driver explicitly ignores previously unmapped areas and repeatedly trims them on boot. To mitigate against such boot slowdowns, the macOS driver introduced a timeout (9.999999 seconds) that stops the trim operation when not finished in time.

    On several controllers, such as Samsung, where the deallocation process is relatively slow, this timeout can be reached very quickly. Essentially, it means that the level of fragmentation is high, thus macOS will attempt to trim the same lower blocks that have previously been deallocated, but never have enough time to deallocate higher blocks. The outcome is that trimming on such SSDs will be non-functional soon after installation, resulting in additional wear on the flash.

    One way to workaround the problem is to increase the timeout to an extremely high value, which at the cost of slow boot times (extra minutes) will ensure that all the blocks are trimmed. Setting this option to a high value, such as 4294967295 ensures that all blocks are trimmed. Alternatively, use over-provisioning, if supported, or create a dedicated unmapped partition where the reserve blocks can be found by the controller. Conversely, the trim operation can be mostly disabled by setting a very low timeout value, while 0 entirely disables it. Refer to this article for details.

    Note: The failsafe value -1 indicates that this patch will not be applied, such that apfs.kext will remain untouched.

    Note 2: On macOS 12.0 and above, it is no longer possible to specify trim timeout. However, trim can be disabled by setting 0.

    Note 3: Trim operations are only affected at booting phase when the startup volume is mounted. Either specifying timeout, or completely disabling trim with 0, will not affect normal macOS running.

22. ThirdPartyDrives
    Type: plist boolean
    Failsafe: false
    Requirement: 10.6 (not required for older)
    Description: Apply 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.

    Note: This option may be avoided on user preference. NVMe SSDs are compatible without the change. For AHCI SSDs on modern macOS version there is a dedicated built-in utility called trimforce. Starting from 10.15 this utility creates EnableTRIM variable in APPLE_BOOT_VARIABLE_GUID namespace with 01 00 00 00 value.

23. XhciPortLimit
    Type: plist boolean
    Failsafe: false
    Requirement: 10.11+ (not required for older)
    Description: Patch various kexts (AppleUSBXHCI.kext, AppleUSBXHCIPCI.kext, IOUSBHostFamily.kext) to remove USB port count limit of 15 ports.

    Note: This option should be avoided whenever possible. USB port limit is imposed by the amount of used bits in locationID format and there is no possible way to workaround this without heavy OS modification. The only valid solution is to limit the amount of used ports to 15 (discarding some). More details can be found on AppleLife.ru.

7.9 Scheme Properties

These properties are particularly relevant for older macOS operating systems. Refer to the Legacy Apple OS section for details on how to install and troubleshoot such macOS installations.

1. CustomKernel
   Type: plist boolean
   Failsafe: false
   Description: Use customised kernel cache from the Kernels directory located at the root of the ESP partition.

   Unsupported platforms including Atom and AMD require modified versions of XNU kernel in order to boot. This option provides the possibility to using a customised kernel cache which contains such modifications from ESP partition.

2. FuzzyMatch
   Type: plist boolean
   Failsafe: false
   Description: Use kernelcache with different checksums when available.

   On Mac OS X 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.

   This setting allows matching the latest kernelcache with a suitable architecture when the kernelcache without suffix is unavailable, improving Mac OS X 10.6 boot performance on several platforms.

3. KernelArch
   Type: plist string
   Failsafe: Auto (Choose the preferred architecture automatically)
   Description: Prefer specified kernel architecture (i386, i386-user32, x86_64) when available.

   On Mac OS X 10.7 and earlier, the XNU kernel can boot with architectures different from the usual x86_64. This setting will use the specified architecture to boot macOS when it is supported by the macOS and the configuration:

   • i386 — Use i386 (32-bit) kernel when available.

   • i386-user32 — Use i386 (32-bit) kernel when available and force the use of 32-bit userspace on 64-bit capable processors if supported by the operating system.

     • On macOS, 64-bit capable processors are assumed to support SSSE3. This is not the case for older 64-bit capable Pentium processors, which cause some applications to crash on Mac OS X 10.6. This behaviour corresponds to the -legacy kernel boot argument.
     • This option is unavailable on Mac OS X 10.4 and 10.5 when running on 64-bit firmware due to an uninitialised 64-bit segment in the XNU kernel, which causes AppleEFIRuntime to incorrectly execute 64-bit code as 16-bit code.
   • x86_64 — Use x86_64 (64-bit) kernel when available.

   The algorithm used to determine the preferred kernel architecture is set out below.

   1. arch argument in image arguments (e.g. when launched via UEFI Shell) or in boot-args variable overrides any compatibility checks and forces the specified architecture, completing this algorithm.
   2. OpenCore build architecture restricts capabilities to i386 and i386-user32 mode for the 32-bit firmware variant.

   3. Determined EfiBoot version restricts architecture choice:

      • 10.4-10.5 — i386 or i386-user32 (only on 32-bit firmware)
      • 10.6 — i386, i386-user32, or x86_64
      • 10.7 — i386 or x86_64
      • 10.8 or newer — x86_64
   4. If KernelArch is set to Auto and SSSE3 is not supported by the CPU, capabilities are restricted to i386-user32 if supported by EfiBoot.
   5. Board identifier (from SMBIOS) based on EfiBoot version disables x86_64 support on an unsupported model if any i386 variant is supported. Auto is not consulted here as the list is not overridable in EfiBoot.
   6. KernelArch restricts the support to the explicitly specified architecture (when not set to Auto) if the architecture remains present in the capabilities.
   7. The best supported architecture is chosen in this order: x86_64, i386, i386-user32.

   Unlike Mac OS X 10.7 (where certain board identifiers are treated as i386 only machines), and Mac OS X 10.5 or earlier (where x86_64 is not supported by the macOS kernel), Mac OS X 10.6 is very special. The architecture choice on Mac OS X 10.6 depends on many factors including not only the board identifier, but also the macOS product type (client vs server), macOS point release, and amount of RAM. The detection of all these is complicated and impractical, as several point releases had implementation flaws resulting in a failure to properly execute the server detection in the first place. For this reason when Auto is set, OpenCore on Mac OS X 10.6 falls back to the x86_64 architecture when it is supported by the board, as on Mac OS X 10.7. The 32-bit KernelArch options can still be configured explicitly however.

   A 64-bit Mac model compatibility matrix corresponding to actual EfiBoot behaviour on Mac OS X 10.6.8 and 10.7.5 is outlined below.

   Model	10.6 (minimal)	10.6 (client)	10.6 (server)	10.7 (any)
   Macmini	4,x (Mid 2010)	5,x (Mid 2011)	4,x (Mid 2010)	3,x (Early 2009)
   MacBook	Unsupported	Unsupported	Unsupported	5,x (2009/09)
   MacBookAir	Unsupported	Unsupported	Unsupported	2,x (Late 2008)
   MacBookPro	4,x (Early 2008)	8,x (Early 2011)	8,x (Early 2011)	3,x (Mid 2007)
   iMac	8,x (Early 2008)	12,x (Mid 2011)	12,x (Mid 2011)	7,x (Mid 2007)
   MacPro	3,x (Early 2008)	5,x (Mid 2010)	3,x (Early 2008)	3,x (Early 2008)
   Xserve	2,x (Early 2008)	2,x (Early 2008)	2,x (Early 2008)	2,x (Early 2008)

   Note: 3+2 and 6+4 hotkeys to choose the preferred architecture are unsupported as they are handled by EfiBoot and hence, difficult to detect.

4. KernelCache
   Type: plist string
   Failsafe: Auto
   Description: Prefer specified kernel cache type (Auto, Cacheless, Mkext, Prelinked) when available.

   Different variants of macOS support different kernel caching variants designed to improve boot performance. This setting prevents the use of faster kernel caching variants if slower variants are available for debugging and stability reasons. That is, by specifying Mkext, Prelinked will be disabled for e.g. 10.6 but not for 10.7.

   The list of available kernel caching types and its current support in OpenCore is listed below.

   macOS	i386 NC	i386 MK	i386 PK	x86_64 NC	x86_64 MK	x86_64 PK	x86_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+	—	—	—	—	—	YES (V3)	YES

   Note: The first version (V1) of the 32-bit prelinkedkernel is unsupported due to the corruption of kext symbol tables by the tools. On this version, the Auto setting will block prelinkedkernel booting. This also results in the keepsyms=1 boot argument being non-functional for kext frames on these systems.

8 Misc

8.1 Introduction

This section contains miscellaneous configuration options affecting OpenCore operating system loading behaviour in addition to other options that do not readily fit into other sections.

OpenCore broadly follows the “bless” model, also known as the “Apple Boot Policy”. The primary purpose of the “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 as compared to the removable media list set out in the UEFI specification.

Partitions can only booted by OpenCore when they meet the requirements of a predefined Scan policy. This policy sets out which specific file systems a partition must have, and which specific device types a partition must be located on, to be made available by OpenCore as a boot option. Refer to the ScanPolicy property for details.

The scan process starts with enumerating all available partitions, filtered based on the Scan policy. Each partition may generate multiple primary and alternate options. Primary options represent operating systems installed on the media, while alternate options represent recovery options for the operating systems on the media.

• Alternate options may exist without primary options and vice versa.
• Options may not necessarily represent operating systems on the same partition.

• Each primary and alternate option can be an auxiliary option or not.

  • Refer to the HideAuxiliary section for details.

8.1.1 Boot Algorithm

The algorithm to determine boot options behaves as follows:

1. Obtain all available partition handles filtered based on the Scan policy (and driver availability).
2. Obtain all available boot options from the BootOrder UEFI variable.

3. For each boot option found:

   • Retrieve the device path of the boot option.
   • Perform fixups (e.g. NVMe subtype correction) and expansion (e.g. for Boot Camp) of the device path.
   • On failure, if it is an OpenCore custom entry device path, pre-construct the corresponding custom entry and succeed.
   • Obtain the device handle by locating the device path of the resulting device path (ignore it on failure).
   • Locate the device handle in the list of partition handles (ignore it if missing).
   • For disk device paths (not specifying a bootloader), execute “bless” (may return > 1 entry).
   • For file device paths, check for presence on the file system directly.
   • Exclude entries if there is a .contentVisibility file at a relevant location (see below) with Disabled contents (ASCII) (and if the current InstanceIentifier matches an Instance-List if present, see below).
   • Mark device handle as used in the list of partition handles if any.
   • Register the resulting entries as primary options and determine their types.
     The option will become auxiliary for some types (e.g. Apple HFS recovery) or if its .contentVisibility file contains Auxiliary (and if the current InstanceIentifier matches an Instance-List if present, see below).

4. For each partition handle:

   • If the partition handle is marked as unused, execute “bless” primary option list retrieval.
     In case a BlessOverride list is set, both standard and custom “bless” paths will be found.
   • On the OpenCore boot partition, exclude OpenCore bootstrap files using header checks.
   • Register the resulting entries as primary options and determine their types if found.
     The option will become auxiliary for some types (e.g. Apple HFS recovery).
   • If a partition already has any primary options of the “Apple Recovery” type, proceed to the next handle.
   • Lookup alternate entries by “bless” recovery option list retrieval and predefined paths.
   • Register the resulting entries as alternate auxiliary options and determine their types if found.
5. Custom entries and tools, except such pre-constructed previously, are added as primary options without any checks with respect to Auxiliary.
6. System entries, such as Reset NVRAM, are added as primary auxiliary options.

A .contentVisibility file may be placed next to the bootloader (such as boot.efi), or in the boot folder (for DMG folder based boot items). Example locations, as seen from within macOS, are:

• /System/Volumes/Preboot/{GUID}/System/Library/CoreServices/.contentVisibility
• /Volumes/{ESP}/EFI/BOOT/.contentVisibility

In addition a .contentVisibility file may be placed in the instance-specific (for macOS) or absolute root folders related to a boot entry, for example:

• /System/Volumes/Preboot/{GUID}/.contentVisibility
• /System/Volumes/Preboot/.contentVisibility
• /Volumes/{ESP}/.contentVisibility (not recommended)

These root folder locations are supported specifically for macOS, because non-Apple files next to the Apple bootloader are removed by macOS updates. It is supported but not recommended to place a .contentVisibility file in a non-macOS root location (such as the last location shown above), because it will hide all entries on the drive.

The .contentVisibility file, when present, may optionally target only specific instances of OpenCore. Its contents are [{Instance-List}:](Disabled|Auxiliary). If a colon (:) is present, the preceding Instance-List it is a comma separated list of InstanceIdentifier values (example: OCA,OCB:Disabled). When this list is present, the specified visibility is only applied if the InstanceIdentifier of the current instance of OpenCore is present in the list. When the list is not present, the specified visibility is applied for all instances of OpenCore.

Note 1: For any instance of OpenCore with no InstanceIdentifier value, the specified visibility from a .contentVisibility file with an Instance-List will never be applied.

Note 2: Visibilities with a visibility list will be treated as invalid, and so ignored, in earlier versions of OpenCore - which may be useful when comparing behaviour of older and newer versions.

Note 3: Avoid extraneous spaces in the .contentVisibility file: these will not be treated as whitespace, but as part of the adjacent token.

The display order of the boot options in the OpenCore picker and the boot process are determined separately from the scanning algorithm.

The display order is as follows:

• Alternate options follow corresponding primary options. That is, Apple recovery options will follow the relevant macOS option whenever possible.
• Options will be listed in file system handle firmware order to maintain an established order across reboots regardless of the operating system chosen for loading.
• Custom entries, tools, and system entries will be added after all other options.
• Auxiliary options will only be displayed upon entering “Extended Mode” in the OpenCore picker (typically by pressing the Space key).

The boot process is as follows:

• Look up the first valid primary option in the BootNext UEFI variable.
• On failure, look up the first valid primary option in the BootOrder UEFI variable.
• Mark the option as the default option to boot.
• Boot option through the picker or without it depending on the ShowPicker option.
• Show picker on failure otherwise.

Note 1: This process will only work reliably when the RequestBootVarRouting option is enabled or the firmware does not control UEFI boot options (OpenDuetPkg or custom BDS). When LauncherOption is not enabled, other operating systems may overwrite OpenCore settings and this property should therefore be enabled when planning to use other operating systems.

Note 2: UEFI variable boot options boot arguments will be removed, if present, as they may contain arguments that can 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. 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.

2. Boot
   Type: plist dict
   Description: Apply the boot configuration described in the Boot Properties section below.
3. Debug
   Type: plist dict
   Description: Apply debug configuration described in the Debug Properties 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 Entry Properties section below for details.

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

6. Serial
   Type: plist dict
   Description: Perform serial port initialisation and configure PCD values required by BaseSerialPortLib16550 for serial ports to properly function. Values are listed and described in the Serial Properties and Serial Custom Properties section below.

   By enabling Init, this section ensures that the serial port is initialised when it is not done by firmware. In order for OpenCore to print logs to the serial port, bit 3 (i.e. serial logging) for Target under section Misc->Debug must be set.

   When debugging with serial ports, BaseSerialPortLib16550 only recognises internal ones provided by the motherboard by default. If the option Override is enabled, this section will override the PCD values listed in BaseSerialPortLib16550.inf such that external serial ports (e.g. from a PCI card) will also function properly. Specifically, when troubleshooting macOS, in addition to overriding these PCD values, it is also necessary to turn the CustomPciSerialDevice kernel quirk on in order for the XNU to use such exterior serial ports.

   Refer to MdeModulePkg.dec for the explanations of each key.

7. Tools
   Type: plist array
   Failsafe: Empty
   Description: Add tool entries to the OpenCore picker.

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

   Note: Certain UEFI tools, such as UEFI Shell, can be very dangerous and MUST NOT appear in production configurations, particularly in vaulted configurations as well as those protected by secure boot, as such tools can be used to bypass the secure boot chain. Refer to the UEFI section for examples of UEFI tools.

8.3 Boot Properties

1. ConsoleAttributes
   Type: plist integer
   Failsafe: 0
   Description: Sets specific attributes for the console.

   The text renderer supports colour arguments as a sum of foreground and background colours based on the UEFI specification. The value for black background and for black foreground, 0, is reserved.

   List of colour values and names:

   • 0x00 — EFI_BLACK
   • 0x01 — EFI_BLUE
   • 0x02 — EFI_GREEN
   • 0x03 — EFI_CYAN
   • 0x04 — EFI_RED
   • 0x05 — EFI_MAGENTA
   • 0x06 — EFI_BROWN
   • 0x07 — EFI_LIGHTGRAY
   • 0x08 — EFI_DARKGRAY
   • 0x09 — EFI_LIGHTBLUE
   • 0x0A — EFI_LIGHTGREEN
   • 0x0B — EFI_LIGHTCYAN
   • 0x0C — EFI_LIGHTRED
   • 0x0D — EFI_LIGHTMAGENTA
   • 0x0E — EFI_YELLOW
   • 0x0F — EFI_WHITE
   • 0x00 — EFI_BACKGROUND_BLACK
   • 0x10 — EFI_BACKGROUND_BLUE
   • 0x20 — EFI_BACKGROUND_GREEN
   • 0x30 — EFI_BACKGROUND_CYAN
   • 0x40 — EFI_BACKGROUND_RED
   • 0x50 — EFI_BACKGROUND_MAGENTA
   • 0x60 — EFI_BACKGROUND_BROWN
   • 0x70 — EFI_BACKGROUND_LIGHTGRAY

   Note: This option may not work well with the System text renderer. Setting a background different from black could help with testing GOP functionality.

2. HibernateMode
   Type: plist string
   Failsafe: None
   Description: Hibernation detection mode. The following modes are supported:

   • None — Ignore hibernation state.
   • Auto — Use RTC and NVRAM detection.
   • RTC — Use RTC detection.
   • NVRAM — Use NVRAM detection.

   Note: If the firmware can handle hibernation itself (valid for Mac EFI firmware), then None should be specified to hand-off hibernation state as is to OpenCore.

3. HibernateSkipsPicker
   Type: plist boolean
   Failsafe: false
   Description: Do not show picker if waking from macOS hibernation.

   Limitations:

   • Only supports macOS hibernation wake, Windows and Linux are currently out of scope.
   • Should only be used on systems with reliable hibernation wake in macOS, otherwise users may not be able to visually see boot loops that may occur.
   • Highly recommended to pair this option with PollAppleHotKeys, allows to enter picker in case of issues with hibernation wake.
   • Visual indication for hibernation wake is currently out of scope.

4. HideAuxiliary
   Type: plist boolean
   Failsafe: false
   Description: Set to true to hide auxiliary entries from the picker menu.

   An entry is considered auxiliary when at least one of the following applies:

   • Entry is macOS recovery.
   • Entry is macOS Time Machine.
   • Entry is explicitly marked as Auxiliary.
   • Entry is system (e.g. Reset NVRAM).

   To display all entries, the picker menu can be reloaded into “Extended Mode” by pressing the Spacebar key. Hiding auxiliary entries may increase boot performance on multi-disk systems.

5. InstanceIdentifier
   Type: plist string
   Failsafe: Empty
   Description: An optional identifier for the current instance of OpenCore.

   This should typically be a short alphanumeric string. The current use of this value is to optionally target .contentVisibility files to specific instances of OpenCore, as explained in the Boot Algorithm section.

6. LauncherOption
   Type: plist string
   Failsafe: Disabled
   Description: Register the launcher option in the firmware preferences for persistence.

   Valid values:

   • Disabled — do nothing.

   • Full — create or update the top priority boot option in UEFI variable storage at bootloader startup.

     • For this option to work, RequestBootVarRouting is required to be enabled.

   • Short — create a short boot option instead of a complete one.

     • This variant is useful for some older types of firmware, typically from Insyde, that are unable to manage full device paths.

   • System — create no boot option but assume specified custom option is blessed.

     • This variant is useful when relying on ForceBooterSignature quirk and OpenCore launcher path management happens through bless utilities without involving OpenCore.

   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.

   Note 3: Some versions of Intel Visual BIOS (e.g. on Intel NUC) have an unfortunate bug whereby if any boot option is added referring to a path on a USB drive, from then on that is the only boot option which will be shown when any USB drive is inserted. If OpenCore is started from a USB drive on this firmware with LauncherOption set to Full or Short, this applies and only the OpenCore boot entry will be seen afterwards, when any other USB is inserted (this highly non-standard BIOS behaviour affects other software as well). The best way to avoid this is to leave LauncherOption set to Disabled or System on any version of OpenCore which will be started from a USB drive on this firmware. If the problem has already occurred the quickest reliable fix is:

   • Enable the system UEFI Shell in Intel Visual BIOS
   • With power off, insert an OpenCore USB
   • Power up and select the system UEFI Shell
   • Since the system shell does not include bcfg, use the system shell to start OpenCore’s OpenShell (e.g. by entering the command FS2:\EFI\OC\Tools\OpenShell.efi , but you will need to work out which drive is correct for OpenCore and modify the drive number FS#: accordingly)
   • Within OpenShell, use bcfg boot dump to display the NVRAM boot options and then use bcfg boot rm # (where # is the number of the OpenCore boot entry) to remove the OpenCore entry

   It is alternatively possible to start OpenShell directly from the OpenCore boot menu, if you have a working configured OpenCore for the system. In that case, and if OpenCore has RequestBootVarRouting enabled, it will be necessary to run the command \EFI\OC\Tools\OpenControl.efi disable before using bcfg. (After OpenControl disable, it is necessary to either reboot or run OpenControl restore, before booting an operating system.) It is also possible to use efibootmgr within Linux to remove the offending entry, if you have a working version of Linux on the machine. Linux must be started either not via OpenCore, or via OpenCore with RequestBootVarRouting disabled for this to work.

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

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

   • 0x0001 — OC_ATTR_USE_VOLUME_ICON, provides custom icons for boot entries:

     OpenCore will attempt loading a volume icon by searching as follows, and will fallback to the default icon on failure:

     • .VolumeIcon.icns file at Preboot volume in per-volume directory (/System/Volumes/Preboot/{GUID}/ when mounted at the default location within macOS) for APFS (if present).
     • .VolumeIcon.icns file at the Preboot volume root (/System/Volumes/Preboot/, when mounted at the default location within macOS) for APFS (otherwise).
     • .VolumeIcon.icns file at the volume root for other filesystems.

     Note 1: The Apple picker partially supports placing a volume icon file at the operating system’s Data volume root, /System/Volumes/Data/, when mounted at the default location within macOS. This approach is flawed: the file is neither accessible to OpenCanopy nor to the Apple picker when FileVault 2, which is meant to be the default choice, is enabled. Therefore, OpenCanopy does not attempt supporting Apple’s approach. A volume icon file may be placed at the root of the Preboot volume for compatibility with both OpenCanopy and the Apple picker, or use the Preboot per-volume location as above with OpenCanopy as a preferred alternative to Apple’s approach.

     Note 2: Be aware that using a volume icon on any drive overrides the normal OpenCore picker behaviour for that drive of selecting the appropriate icon depending on whether the drive is internal or external.

   • 0x0002 — OC_ATTR_USE_DISK_LABEL_FILE, use custom prerendered titles for boot entries from .disk_label (.disk_label_2x) file next to the bootloader for all filesystems. These labels can be generated via the disklabel utility or the bless --folder {FOLDER_PATH} --label {LABEL_TEXT} command. When prerendered labels are disabled or missing, use label text in .contentDetails (or .disk_label.contentDetails) file next to bootloader if present instead, otherwise the entry name itself will be rendered.
   • 0x0004 — OC_ATTR_USE_GENERIC_LABEL_IMAGE, provides predefined label images for boot entries without custom entries. This may however give less detail for the actual boot entry.
   • 0x0008 — OC_ATTR_HIDE_THEMED_ICONS, prefers builtin icons for certain icon categories to match the theme style. For example, this could force displaying the builtin Time Machine icon. Requires OC_ATTR_USE_VOLUME_ICON.
   • 0x0010 — OC_ATTR_USE_POINTER_CONTROL, enables pointer control in the OpenCore picker when available. For example, this could make use of mouse or trackpad to control UI elements.
   • 0x0020 — OC_ATTR_SHOW_DEBUG_DISPLAY, enable display of additional timing and debug information, in Builtin picker in DEBUG and NOOPT builds only.
   • 0x0040 — OC_ATTR_USE_MINIMAL_UI, use minimal UI display, no Shutdown or Restart buttons, affects OpenCanopy and builtin picker.

   • 0x0080 — OC_ATTR_USE_FLAVOUR_ICON, provides flexible boot entry content description, suitable for picking the best media across different content sets:

     When enabled, the entry icon in OpenCanopy and the audio assist entry sound in OpenCanopy and builtin boot picker are chosen by something called content flavour. To determine content flavour the following algorithm is used:

     • For a Tool the value is read from Flavour field.
     • For an automatically discovered entry, including for boot entry protocol entries such as those generated by the OpenLinuxBoot driver, it is read from the .contentFlavour file next to the bootloader, if present.
     • For a custom entry specified in the Entries section it is read from the .contentFlavour file next to the bootloader if Flavour is Auto, otherwise it is specified via the Flavour value itself.
     • If read flavour is Auto or there is no .contentFlavour, entry flavour is chosen based on the entry type (e.g. Windows automatically gets Windows flavour).

     The Flavour value is a sequence of : separated names limited to 64 characters of printable 7-bit ASCII. This is designed to support up to approximately five names. Each name refers to a flavour, with the first name having the highest priority and the last name having the lowest priority. Such a structure allows describing an entry in a more specific way, with icons selected flexibly depending on support by the audio-visual pack. A missing audio or icon file means the next flavour should be tried, and if all are missing the choice happens based on the type of the entry. Example flavour values: BigSur:Apple, Windows10:Windows. OpenShell:UEFIShell:Shell.

     Using flavours means that you can switch between icon sets easily, with the flavour selecting the best available icons from each set. E.g. specifying icon flavour Debian:Linux will use the icon Debian.icns if provided, then will try Linux.icns, then will fall back to the default for an OS, which is HardDrive.icns.

     Things to keep in mind:

     • For security reasons Ext<Flavour>.icns and <Flavour>.icns are both supported, and only Ext<Flavour>.icns will be used if the entry is on an external drive (followed by default fallback ExtHardDrive.icns).
     • Where both apply .VolumeIcon.icns takes precedence over .contentFlavour.
     • In order to allow icons and audio assist to work correctly for tools (e.g. for UEFI Shell), system default boot entry icons (see Docs/Flavours.md) specified in the Flavour setting for Tools or Entries will continue to apply even when flavour is disabled. Non-system icons will be ignored in this case. In addition, the flavours UEFIShell and NVRAMReset are given special processing, identifying their respective tools to apply correct audio-assist, default builtin labels, etc.
     • A list of recommended flavours is provided in Docs/Flavours.md.
   • 0x0100 — OC_ATTR_USE_REVERSED_UI, reverse position of Shutdown and Restart buttons, affects OpenCanopy and builtin picker. The reversed setting matches older macOS, and since it was the previous default in OpenCore it may better match some custom backgrounds. Only applicable when OC_ATTR_USE_MINIMAL_UI is not set.

   • 0x0200 — OC_ATTR_REDUCE_MOTION, reduce password and menu animation in OpenCanopy, leaving only animations which communicate information not otherwise provided.

     Note: These same animations, plus additional animations whose information is provided by voice-over, are automatically disabled when PickerAudioAssist is enabled.

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

   Note: The screen reader requires working audio support. Refer to the UEFI Audio Properties section for details.

10. PickerMode
    Type: plist string
    Failsafe: Builtin
    Description: Choose picker used for boot management.

    PickerMode describes the underlying boot management with an optional user interface responsible for handling boot options.

    The following values are supported:

    • Builtin — boot management is handled by OpenCore, a simple text-only user interface is used.
    • External — an external boot management protocol is used if available. Otherwise, the Builtin mode is used.
    • Apple — Apple boot management is used if available. Otherwise, the Builtin mode is used.

    Upon success, the External mode may entirely disable all boot management in OpenCore except for policy enforcement. In the Apple mode, it may additionally bypass policy enforcement. Refer to the OpenCanopy plugin for an example of a custom user interface.

    The OpenCore built-in picker contains a set of actions chosen during the boot process. The list of supported actions is similar to Apple BDS and typically can be accessed by holding action hotkeys during the boot process.

    The following actions are currently considered:

    • Default — this is the default option, and it lets the built-in OpenCore picker load the default boot option as specified in the Startup Disk preference pane.
    • ShowPicker — this option forces the OpenCore picker to be displayed. This can typically be achieved by holding the OPT key during boot. Setting ShowPicker to true will make ShowPicker the default option.
    • BootApple — this options performs booting to the first Apple operating system found unless the chosen default operating system is one from Apple. Hold the X key down to choose this option.
    • BootAppleRecovery — this option performs booting into the Apple operating system recovery partition. This is either that related to the default chosen operating system, or first one found when the chosen default operating system is not from Apple or does not have a recovery partition. Hold the CMD+R hotkey combination down to choose this option.

    Note 1: On non-Apple firmware KeySupport, OpenUsbKbDxe, or similar drivers are required for key handling. However, not all of the key handling functions can be implemented on several types of firmware.

    Note 2: In addition to OPT, OpenCore supports using both the Escape and Zero keys to enter the OpenCore picker when ShowPicker is disabled. Escape exists to support co-existence with the Apple picker (including OpenCore Apple picker mode) and to support firmware that fails to report held OPT key, as on some PS/2 keyboards. In addition, Zero is provided to support systems on which Escape is already assigned to some other pre-boot firmware feature. In systems which do not require KeySupport, pressing and holding one of these keys from after power on until the picker appears should always be successful. The same should apply when using KeySupport mode if it is correctly configured for the system, i.e. with a long enough KeyForgetThreshold. If pressing and holding the key is not successful to reliably enter the picker, multiple repeated keypresses may be tried instead.

    Note 3: On Macs with problematic GOP, it may be difficult to re-bless OpenCore if its bless status is lost. The BootKicker utility can be used to work around this problem, if set up as a Tool in OpenCore with FullNvramAccess enabled. It will launch the Apple picker, which allows selection of an item to boot next (with Enter), or next and from then on until the next change (with CTRL+Enter). Note that after the selection is made, the system will reboot before the chosen entry is booted. While this behaviour might seem surprising, it can be used both to switch which OpenCore installation is blessed, with CTRL+Enter, e.g. from a recovery OpenCore installation on CD (selected with the C key on boot) back to the main installation of OpenCore on the hard drive, if this is lost after an NVRAM reset. It can also be used, even when the native picker cannot be shown normally (unsupported GPU), to do a one-shot boot without OpenCore, e.g. to another OS or tool, or to an earlier version of macOS.

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

    An 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:

    • Acidanthera\GoldenGate — macOS 11 styled icon set.
    • Acidanthera\Syrah — OS X 10.10 styled icon set.
    • Acidanthera\Chardonnay — Mac OS X 10.4 styled icon set.

    For convenience purposes there also are predefined aliases:

    • Auto — Automatically select one set of icons based on the DefaultBackground colour: Acidanthera\GoldenGate for Syrah Black and Acidanthera\Chardonnay for Light Gray.
    • Default — Acidanthera\GoldenGate.

12. PollAppleHotKeys
    Type: plist boolean
    Failsafe: false
    Description: Enable modifier hotkey handling in the OpenCore picker.

    In addition to action hotkeys, which are partially described in the PickerMode section and are typically handled by Apple BDS, modifier keys handled by the operating system bootloader (boot.efi) also exist. These keys allow changing the behaviour of the operating system by providing different boot modes.

    On certain firmware, using modifier keys may be problematic due to driver incompatibilities. To workaround this problem, this option allows registering certain hotkeys in a more permissive manner from within the OpenCore picker. Such extensions include support for tapping on key combinations before selecting the boot item, and for reliable detection of the Shift key when selecting the boot item, in order to work around the fact that hotkeys which are continuously held during boot cannot be reliably detected on many PS/2 keyboards.

    This list of known modifier hotkeys includes:

    • CMD+C+MINUS — disable board compatibility checking.
    • CMD+K — boot release kernel, similar to kcsuffix=release.
    • CMD+S — single user mode.
    • CMD+S+MINUS — disable KASLR slide, requires disabled SIP.
    • CMD+V — verbose mode.
    • Shift+Enter, Shift+Index — safe mode, may be used in combination with CTRL+Enter, CTRL+Index.
13. ShowPicker
    Type: plist boolean
    Failsafe: false
    Description: Show a simple picker to allow boot entry selection.

14. TakeoffDelay
    Type: plist integer, 32 bit
    Failsafe: 0
    Description: Delay in microseconds executed before handling the OpenCore picker startup and action hotkeys.

    Introducing a delay may give extra time to hold the right action hotkey sequence to, for instance, boot into recovery mode. On most systems, the appearance of the initial boot logo is a good indication of the time from which hotkeys can be held down. Earlier than this, the key press may not be registered. On some platforms, setting this option to a minimum of 5000-10000 microseconds is also required to access action hotkeys due to the nature of the keyboard driver.

    If the boot chime is configured (see audio configuration options) then at the expense of slower startup, an even longer delay of half to one second (500000-1000000) may be used to create behaviour similar to a real Mac, where the chime itself can be used as a signal for when hotkeys can be pressed. The boot chime is inevitably later in the boot sequence in OpenCore than on Apple hardware, due to the fact that non-native drivers have to be loaded and connected first. Configuring the boot chime and adding this longer additional delay can also be useful in systems where fast boot time and/or slow monitor signal synchronisation may cause the boot logo not to be shown at all on some boots or reboots.

15. Timeout
    Type: plist integer, 32 bit
    Failsafe: 0
    Description: Timeout in seconds in the OpenCore picker before automatic booting of the default boot entry. Set to 0 to disable.

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:

   cat Kernel.panic | grep macOSProcessedStackshotData | 
     python3 -c 'import json,sys;print(json.load(sys.stdin)["macOSPanicString"])'

3. DisableWatchDog
   Type: plist boolean
   Failsafe: false
   Description: Some types of firmware may not succeed in booting the operating system quickly, especially in debug mode. This results in the watchdog timer aborting the process. This option turns off the watchdog timer.
4. DisplayDelay
   Type: plist integer
   Failsafe: 0
   Description: Delay in microseconds executed after every printed line visible onscreen (i.e. console).

5. DisplayLevel
   Type: plist integer, 64 bit
   Failsafe: 0
   Description: EDK II debug level bitmask (sum) showed onscreen. Unless Target enables console (onscreen) printing, onscreen debug output will not be visible.

   The following levels are supported (discover more in DebugLib.h):

   • 0x00000002 (bit 1) — DEBUG_WARN in DEBUG, NOOPT, RELEASE.
   • 0x00000040 (bit 6) — DEBUG_INFO in DEBUG, NOOPT.
   • 0x00400000 (bit 22) — DEBUG_VERBOSE in custom builds.
   • 0x80000000 (bit 31) — DEBUG_ERROR in DEBUG, NOOPT, RELEASE.

6. LogModules
   Type: plist string
   Failsafe: *
   Description: Filter log entries by module.

   This option filters logging generated by specific modules, both in the log and onscreen. Two modes are supported:

   • + — Positive filtering: Only present selected modules.
   • - — Negative filtering: Exclude selected modules.

   When multiple log line identifiers are selected, comma (,) should be used as the splitter. For instance, +OCCPU,OCA,OCB means only OCCPU, OCA, OCB should be logged, while -OCCPU,OCA,OCB indicates these modules should be filtered out (i.e. not logged). Since there may be lines in the log with no valid prefix (i.e. log lines which are not generated by parts of OpenCore, but by other loaded drivers) then the special module name question mark (?) can be included in the list to include (with positive filtering) or exclude (with negative filtering) these non-standard lines. When no + or - symbol is specified, positive filtering (+) will be used. * alone as the option value indicates all modules being logged.

   Note 1: Acronyms of libraries can be found in the Libraries section below.

   Note 2: Messages printed before the configuration of the log protocol cannot be filtered from the early on screen log, but on being de-buffered from the early log buffer, will be filtered as requested for other log targets.

   Note 3: To avoid missing key issues, warning and error log messages are not filtered.

7. SysReport
   Type: plist boolean
   Failsafe: false
   Description: Produce system report on ESP folder.

   This option will create a SysReport directory in the ESP partition unless already present. The directory will contain ACPI, SMBIOS, and audio codec dumps. Audio codec dumps require an audio backend driver to be loaded.

   Note: To maintain system integrity, the SysReport option is not available in RELEASE builds. Use a DEBUG build if this option is required.

8. Target
   Type: plist integer
   Failsafe: 0
   Description: A bitmask (sum) of enabled logging targets. Logging output is hidden by default and this option must be set when such output is required, such as when debugging.

   The following logging targets are supported:

   • 0x01 (bit 0) — Enable logging, otherwise all log is discarded.
   • 0x02 (bit 1) — Enable basic console (onscreen) logging.
   • 0x04 (bit 2) — Enable logging to Data Hub.
   • 0x08 (bit 3) — Enable serial port logging.
   • 0x10 (bit 4) — Enable UEFI variable logging.
   • 0x20 (bit 5) — Enable non-volatile UEFI variable logging.
   • 0x40 (bit 6) — Enable logging to file.
   • 0x80 (bit 7) — In combination with 0x40, enable faster but unsafe (see Warning 2 below) file logging.

   Console logging prints less than the other variants. Depending on the build type (RELEASE, DEBUG, or NOOPT) different amount of logging may be read (from least to most).

   To obtain Data Hub logs, use the following command in macOS (Note that Data Hub logs do not log kernel and kext patches):

   ioreg -lw0 -p IODeviceTree | grep boot-log | sort | sed 's/.*<\(.*\)>.*/\1/' | xxd -r -p

   UEFI variable log does not include some messages and has no performance data. To maintain system integrity, the log size is limited to 32 kilobytes. Some types of firmware may truncate it much earlier or drop completely if they have no memory. Using the non-volatile flag will cause the log to be written to NVRAM flash after every printed line.

   To obtain UEFI variable logs, use the following command in macOS:

   nvram 4D1FDA02-38C7-4A6A-9CC6-4BCCA8B30102:boot-log | 
     awk '{gsub(/%0d%0a%00/,"");gsub(/%0d%0a/,"\n")}1'

   Warning 1: Certain firmware appear to have defective NVRAM garbage collection. As a result, they may not be able to always free space after variable deletion. Do not enable non-volatile NVRAM logging on such devices unless specifically required.

   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.

   Warning 2: It is possible to enable fast file logging, which requires a fully compliant firmware FAT32 driver. On drivers with incorrect FAT32 write support (e.g. APTIO IV, but maybe others) this setting can result in corruption up to and including an unusable ESP filesystem, therefore be prepared to recreate the ESP partition and all of its contents if testing this option. This option can increase logging speed significantly on some suitable firmware, but may make little speed difference on some others.

   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:

   • BMF — OpenCanopy, bitmap font
   • BS — Bootstrap
   • GSTT — GoptStop
   • HDA — AudioDxe
   • KKT — KeyTester
   • LNX — OpenLinuxBoot
   • NTBT — OpenNetworkBoot
   • MMDD — MmapDump
   • OCPAVP — PavpProvision
   • OCRST — ResetSystem
   • OCUI — OpenCanopy
   • OC — OpenCore main, also OcMainLib
   • OLB — OpenLegacyBoot
   • VMOPT — VerifyMemOpt

   Libraries:

   • AAPL — OcLogAggregatorLib, Apple EfiBoot logging
   • OCABC — OcAfterBootCompatLib
   • OCAE — OcAppleEventLib
   • OCAK — OcAppleKernelLib
   • OCAU — OcAudioLib
   • OCA —- OcAcpiLib
   • OCBP — OcAppleBootPolicyLib
   • OCB — OcBootManagementLib
   • OCLBT — OcBlitLib
   • OCCL — OcAppleChunkListLib
   • OCCPU — OcCpuLib
   • OCC — OcConsoleLib
   • OCDC — OcDriverConnectionLib
   • OCDH — OcDataHubLib
   • OCDI — OcAppleDiskImageLib
   • OCDM — OcDeviceMiscLib
   • OCFS — OcFileLib
   • OCFV — OcFirmwareVolumeLib
   • OCHS — OcHashServicesLib
   • OCI4 — OcAppleImg4Lib
   • OCIC — OcImageConversionLib
   • OCII — OcInputLib
   • OCJS — OcApfsLib
   • OCKM — OcAppleKeyMapLib
   • OCL — OcLogAggregatorLib
   • OCM — OcMiscLib
   • OCMCO — OcMachoLib
   • OCME — OcHeciLib
   • OCMM — OcMemoryLib
   • OCPE — OcPeCoffLib, OcPeCoffExtLib
   • OCPI — OcFileLib, partition info
   • OCPNG — OcPngLib
   • OCRAM — OcAppleRamDiskLib
   • OCRTC — OcRtcLib
   • OCSB — OcAppleSecureBootLib
   • OCSMB — OcSmbiosLib
   • OCSMC — OcSmcLib
   • OCST — OcStorageLib
   • OCS — OcSerializedLib
   • OCTPL — OcTemplateLib
   • OCUC — OcUnicodeCollationLib
   • OCUT — OcAppleUserInterfaceThemeLib
   • OCVAR — OcVariableLib
   • OCXML — OcXmlLib

8.5 Entry Properties

1. Arguments
   Type: plist string
   Failsafe: Empty
   Description: Arbitrary ASCII string used as boot arguments (load options) of the specified entry.
2. Auxiliary
   Type: plist boolean
   Failsafe: false
   Description: Set to true to hide this entry when HideAuxiliary is also set to true. Press the Spacebar key to enter “Extended Mode” and display the entry when hidden.
3. Comment
   Type: plist string
   Failsafe: Empty
   Description: Arbitrary ASCII string used to provide a human readable reference for the entry. Whether this value is used is implementation defined.
4. Enabled
   Type: plist boolean
   Failsafe: false
   Description: Set to true activate this entry.
5. Flavour
   Type: plist string
   Failsafe: Auto
   Description: Specify the content flavour for this entry. See OC_ATTR_USE_FLAVOUR_ICON flag for documentation.

6. FullNvramAccess
   Type: plist boolean
   Failsafe: false
   Description: Disable OpenRuntime NVRAM protection during usage of a tool.

   This disables all of the NVRAM protections provided by OpenRuntime.efi, during the time a tool is in use. It should normally be avoided, but may be required for instance if a tool needs to access NVRAM directly without the redirections put in place by RequestBootVarRouting.

   Note: This option is only valid for Tools and cannot be specified for Entries (is always false).

7. Name
   Type: plist string
   Failsafe: Empty
   Description: Human readable entry name displayed in the OpenCore picker.

8. Path
   Type: plist string
   Failsafe: Empty
   Description: Entry location depending on entry type.

   • Entries specify external boot options, and therefore take device paths in the Path key. Care should be exercised as these values are not checked. Example: PciRoot(0x0)/Pci(0x1,0x1)/.../\EFI\COOL.EFI
   • Tools specify internal boot options, which are part of the bootloader vault, and therefore take file paths relative to the OC/Tools directory. Example: OpenShell.efi.

9. RealPath
   Type: plist boolean
   Failsafe: false
   Description: Pass full path to the tool when launching.

   This should typically be disabled as passing the tool directory may be unsafe with tools that accidentally attempt to access files without checking their integrity. Reasons to enable this property may include cases where tools cannot work without external files or may need them for enhanced functionality such as memtest86 (for logging and configuration), or Shell (for automatic script execution).

   Note: This option is only valid for Tools and cannot be specified for Entries (is always true).

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

    This setting may be beneficial for some older tools that require text output as all the tools are launched in graphics mode by default. Refer to the Output Properties section below for information on text modes.

8.6 Security Properties

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

2. 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. Until the operating system is personalised, only macOS DMG recovery can 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 Tips and Tricks section. Note that DMG loading 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 --folder "/Volumes/Macintosh HD/System/Library/CoreServices" \ 
     --bootefi --personalize

   On macOS 11 and newer the dedicated x86legacy model always uses ApECID. When this configuration setting is left as 0 first 8 bytes of system-id variable are used instead.

   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

3. AuthRestart
   Type: plist boolean
   Failsafe: false
   Description: Enable VirtualSMC-compatible authenticated restart.

   Authenticated restart is a way to reboot FileVault 2 enabled macOS without entering the password. A dedicated terminal command can be used to perform authenticated restarts: sudo fdesetup authrestart. It is also used when installing operating system updates.

   VirtualSMC performs authenticated restarts by splitting and saving disk encryption keys between NVRAM and RTC, which despite being removed as soon as OpenCore starts, may be considered a security risk and thus is optional.

4. BlacklistAppleUpdate
   Type: plist boolean
   Failsafe: false
   Description: Ignore boot options trying to update Apple peripheral firmware (e.g. MultiUpdater.efi).

   Note: Certain operating systems, such as macOS Big Sur, are incapable of disabling firmware updates by using the run-efi-updater NVRAM variable.

5. DmgLoading
   Type: plist string
   Failsafe: Signed
   Description: Define Disk Image (DMG) loading policy used for macOS Recovery.

   Valid values:

   • Disabled — loading DMG images will fail. The Disabled policy will still let the macOS Recovery load in most cases as typically, there are boot.efi files compatible with Apple Secure Boot. Manually downloaded DMG images stored in com.apple.recovery.boot directories will not load, however.
   • Signed — only Apple-signed DMG images will load. Due to the design of Apple Secure Boot, the Signed policy will let any Apple-signed macOS Recovery load regardless of the Apple Secure Boot state, which may not always be desired. While using signed DMG images is more desirable, verifying the image signature may slightly slow the boot time down (by up to 1 second).
   • Any — any DMG images will mount as normal filesystems. The Any policy is strongly discouraged and will result in boot failures when Apple Secure Boot is active.

6. EnablePassword
   Type: plist boolean
   Failsafe: false
   Description: Enable password protection to facilitate sensitive operations.

   Password protection ensures that sensitive operations such as booting a non-default operating system (e.g. macOS recovery or a tool), resetting NVRAM storage, trying to boot into a non-default mode (e.g. verbose mode or safe mode) are not allowed without explicit user authentication by a custom password. Currently, password and salt are hashed with 5000000 iterations of SHA-512.

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

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

   • 0x01 — Expose the printable booter path as a UEFI variable.
   • 0x02 — Expose the OpenCore version as 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

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

   Note 1: A halt will only occur if bit 0 (i.e. enable logging) for Target under section Misc->Debug is set.

   Note 2: A halt will only occur after the configuration is loaded and logging is configured. If any log messages occur at the specified halt level in early log (i.e. before this), they will cause a halt when they are flushed to the log once it has been configured.

9. PasswordHash
   Type: plist data 64 bytes
   Failsafe: all zero
   Description: Password hash used when EnablePassword is set.
10. PasswordSalt
    Type: plist data
    Failsafe: empty
    Description: Password salt used when EnablePassword is set.

11. ScanPolicy
    Type: plist integer, 32 bit
    Failsafe: 0x10F0103
    Description: Define operating system detection policy.

    This value allows preventing scanning (and booting) untrusted sources based on a bitmask (sum) of a set of flags. As it is not possible to reliably detect every file system or device type, this feature cannot be fully relied upon in open environments, and additional measures are to be applied.

    Third party drivers may introduce additional security (and performance) consideratons following the provided scan policy. The active Scan policy is exposed in the scan-policy variable of 4D1FDA02-38C7-4A6A-9CC6-4BCCA8B30102 GUID for UEFI Boot Services only.

    • 0x00000001 (bit 0) — OC_SCAN_FILE_SYSTEM_LOCK, restricts scanning to only known file systems defined as a part of this policy. File system drivers may not be aware of this policy. Hence, to avoid mounting of undesired file systems, drivers for such file systems should not be loaded. This bit does not affect DMG mounting, which may have any file system. Known file systems are prefixed with OC_SCAN_ALLOW_FS_.
    • 0x00000002 (bit 1) — OC_SCAN_DEVICE_LOCK, restricts scanning to only known device types defined as a part of this policy. It is not always possible to detect protocol tunneling, so be aware that on some systems, it may be possible for e.g. USB HDDs to be recognised as SATA instead. Cases like this must be reported. Known device types are prefixed with OC_SCAN_ALLOW_DEVICE_.
    • 0x00000100 (bit 8) — OC_SCAN_ALLOW_FS_APFS, allows scanning of APFS file system.
    • 0x00000200 (bit 9) — OC_SCAN_ALLOW_FS_HFS, allows scanning of HFS file system.
    • 0x00000400 (bit 10) — OC_SCAN_ALLOW_FS_ESP, allows scanning of EFI System Partition file system.
    • 0x00000800 (bit 11) — OC_SCAN_ALLOW_FS_NTFS, allows scanning of NTFS (Msft Basic Data) file system.
    • 0x00001000 (bit 12) — OC_SCAN_ALLOW_FS_LINUX_ROOT, allows scanning of Linux Root file systems.
    • 0x00002000 (bit 13) — OC_SCAN_ALLOW_FS_LINUX_DATA, allows scanning of Linux Data file systems.
    • 0x00004000 (bit 14) — OC_SCAN_ALLOW_FS_XBOOTLDR, allows scanning the Extended Boot Loader Partition as defined by the Boot Loader Specification.
    • 0x00010000 (bit 16) — OC_SCAN_ALLOW_DEVICE_SATA, allow scanning SATA devices.
    • 0x00020000 (bit 17) — OC_SCAN_ALLOW_DEVICE_SASEX, allow scanning SAS and Mac NVMe devices.
    • 0x00040000 (bit 18) — OC_SCAN_ALLOW_DEVICE_SCSI, allow scanning SCSI devices.
    • 0x00080000 (bit 19) — OC_SCAN_ALLOW_DEVICE_NVME, allow scanning NVMe devices.
    • 0x00100000 (bit 20) — OC_SCAN_ALLOW_DEVICE_ATAPI, allow scanning CD/DVD devices and old SATA.
    • 0x00200000 (bit 21) — OC_SCAN_ALLOW_DEVICE_USB, allow scanning USB devices.
    • 0x00400000 (bit 22) — OC_SCAN_ALLOW_DEVICE_FIREWIRE, allow scanning FireWire devices.
    • 0x00800000 (bit 23) — OC_SCAN_ALLOW_DEVICE_SDCARD, allow scanning card reader devices.
    • 0x01000000 (bit 24) — OC_SCAN_ALLOW_DEVICE_PCI, allow scanning devices directly connected to PCI bus (e.g. VIRTIO).

    Note: Given the above description, a value of 0xF0103 is expected to do the following:

    • Permit scanning SATA, SAS, SCSI, and NVMe devices with APFS file systems.
    • Prevent scanning any devices with HFS or FAT32 file systems.
    • Prevent scanning APFS file systems on USB, CD, and FireWire drives.

    The combination reads as:

    • OC_SCAN_FILE_SYSTEM_LOCK
    • OC_SCAN_DEVICE_LOCK
    • OC_SCAN_ALLOW_FS_APFS
    • OC_SCAN_ALLOW_DEVICE_SATA
    • OC_SCAN_ALLOW_DEVICE_SASEX
    • OC_SCAN_ALLOW_DEVICE_SCSI
    • OC_SCAN_ALLOW_DEVICE_NVME

12. SecureBootModel
    Type: plist string
    Failsafe: Default
    Description: Apple Secure Boot hardware model.

    Sets Apple Secure Boot hardware model and policy. Specifying this value defines which operating systems will be bootable. Operating systems shipped before the specified model was released will not boot.

    Valid values:

    • Default — Matching model for current SMBIOS.
    • Disabled — No model, Secure Boot will be disabled.
    • j137 — iMacPro1,1 (December 2017). Minimum macOS 10.13.2 (17C2111)
    • j680 — MacBookPro15,1 (July 2018). Minimum macOS 10.13.6 (17G2112)
    • j132 — MacBookPro15,2 (July 2018). Minimum macOS 10.13.6 (17G2112)
    • j174 — Macmini8,1 (October 2018). Minimum macOS 10.14 (18A2063)
    • j140k — MacBookAir8,1 (October 2018). Minimum macOS 10.14.1 (18B2084)
    • j780 — MacBookPro15,3 (May 2019). Minimum macOS 10.14.5 (18F132)
    • j213 — MacBookPro15,4 (July 2019). Minimum macOS 10.14.5 (18F2058)
    • j140a — MacBookAir8,2 (July 2019). Minimum macOS 10.14.5 (18F2058)
    • j152f — MacBookPro16,1 (November 2019). Minimum macOS 10.15.1 (19B2093)
    • j160 — MacPro7,1 (December 2019). Minimum macOS 10.15.1 (19B88)
    • j230k — MacBookAir9,1 (March 2020). Minimum macOS 10.15.3 (19D2064)
    • j214k — MacBookPro16,2 (May 2020). Minimum macOS 10.15.4 (19E2269)
    • j223 — MacBookPro16,3 (May 2020). Minimum macOS 10.15.4 (19E2265)
    • j215 — MacBookPro16,4 (June 2020). Minimum macOS 10.15.5 (19F96)
    • j185 — iMac20,1 (August 2020). Minimum macOS 10.15.6 (19G2005)
    • j185f — iMac20,2 (August 2020). Minimum macOS 10.15.6 (19G2005)
    • x86legacy — Macs without T2 chip and VMs. Minimum macOS 11.0.1 (20B29)

    Warning: Not all Apple Secure Boot models are supported on all hardware configurations.

    Apple Secure Boot appeared in macOS 10.13 on models with T2 chips. Prior to macOS 12 PlatformInfo and SecureBootModel were independent, allowing Apple Secure Boot can be used with any SMBIOS with and without T2. Starting with macOS 12 SecureBootModel must match the SMBIOS Mac model. Default model derives the model based on SMBIOS board identifier, either set automatically via the Generic section or set manually via the SMBIOS section. If there is no board identifier override the model will be derived heuristically from OEM SMBIOS.

    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.

    Note that enabling Apple Secure Boot is demanding on invalid configurations, faulty macOS installations, and on unsupported setups.

    Things to consider:

    1. As with T2 Macs, all unsigned kernel extensions as well as several signed kernel extensions, including NVIDIA Web Drivers, cannot be installed.
    2. The list of cached kernel extensions may be different, resulting in a need to change the list of Added or Forced kernel extensions. 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. Boot failures might occur when the platform requires certain settings, but they have not been enabled because the associated issues were not discovered earlier. Be extra careful with IgnoreInvalidFlexRatio or HashServices.
    5. Operating systems released before Apple Secure Boot was released (e.g. macOS 10.12 or earlier), will still boot until UEFI Secure Boot is enabled. This is so because Apple Secure Boot treats these as incompatible and they are then 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. As the Default value will increase with time to support the latest major released operating system, it is not recommended to use the ApECID and the Default settings together.
    8. Installing macOS with Apple Secure Boot enabled is not possible while using HFS+ target volumes. This may include HFS+ formatted drives when no spare APFS drive is available.

    The installed operating system may have sometimes outdated Apple Secure Boot manifests on the Preboot partition, resulting in boot failures. This is likely to be the case when an “OCB: Apple Secure Boot prohibits this boot entry, enforcing!” message is logged.

    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 the UEFI Secure Boot section.

13. Vault
    Type: plist string
    Failsafe: Secure
    Description: Enables the OpenCore vaulting mechanism.

    Valid values:

    • Optional — require nothing, no vault is enforced, insecure.
    • Basic — require vault.plist file present in OC directory. This provides basic filesystem integrity verification and may protect from unintentional filesystem corruption.
    • Secure — require vault.sig signature file for vault.plist in OC directory. This includes Basic integrity checking but also attempts to build a trusted bootchain.

    The vault.plist file should contain SHA-256 hashes for all files used by OpenCore. The presence of this file is highly recommended to ensure that unintentional file modifications (including filesystem corruption) do not go unnoticed. To create this file automatically, use the create_vault.sh script. Notwithstanding the underlying file system, the path names and cases between config.plist and vault.plist must match.

    The vault.sig file should contain a raw 256 byte RSA-2048 signature from a SHA-256 hash of vault.plist. The signature is verified against the public key embedded into OpenCore.efi.

    To embed the public key, either one of the following should be performed:

    • Provide public key during the OpenCore.efi compilation in OpenCoreVault.c file.
    • Binary patch OpenCore.efi replacing zeroes with the public key between =BEGIN OC VAULT= and ==END OC VAULT== ASCII markers.

    The RSA public key 520 byte format description can be found in Chromium OS documentation. To convert the public key from X.509 certificate or from PEM file use RsaTool.

    The steps to binary patch OpenCore.efi are:

    • Create vault.plist.
    • Create a new RSA key (always do this to avoid loading old configuration).
    • Embed RSA key into OpenCore.efi.
    • Create vault.sig.

    A script to do this is privided in OpenCore releases:

    /Utilities/CreateVault/sign.command /Volumes/EFI/EFI/OC

    Note 1: While it may appear obvious, an external method is required to verify OpenCore.efi and BOOTx64.efi for secure boot path. For this, it is recommended to enable UEFI SecureBoot using a custom certificate and to sign OpenCore.efi and BOOTx64.efi with a custom key. More details on customising secure boot on modern firmware can be found in the Taming UEFI SecureBoot paper (in Russian).

    Note 2: Regardless of this option, vault.plist is always used when present, and both vault.plist and vault.sig are used and required when a public key is embedded into OpenCore.efi, and errors will abort the boot process in either case. Setting this option allows OpenCore to warn the user if the configuration is not as required to achieve an expected higher security level.

8.7 Serial Properties

1. Custom
   Type: plist dict
   Description: Update serial port properties in BaseSerialPortLib16550.

   This section lists the PCD values that are used by the BaseSerialPortLib16550. When option Override is set to false, this dictionary is optional.

2. Init
   Type: plist boolean
   Failsafe: false
   Description: Perform serial port initialisation.

   This option will perform serial port initialisation within OpenCore prior to enabling (any) debug logging.

   Refer to the Debugging section for details.

3. Override
   Type: plist boolean
   Failsafe: false
   Description: Override serial port properties. When this option is set to false, no keys from Custom will be overridden.

   This option will override serial port properties listed in the Serial Custom Properties section below.

8.7.1 Serial Custom Properties

1. BaudRate
   Type: plist integer
   Failsafe: 115200
   Description: Set the baud rate for serial port.

   This option will override the value of gEfiMdeModulePkgTokenSpaceGuid.PcdSerialBaudRate defined in MdeModulePkg.dec.

2. ClockRate
   Type: plist integer
   Failsafe: 1843200
   Description: Set the clock rate for serial port.

   This option will override the value of gEfiMdeModulePkgTokenSpaceGuid.PcdSerialClockRate defined in MdeModulePkg.dec.

3. DetectCable
   Type: plist boolean
   Failsafe: false
   Description: Enable serial port cable detection.

   This option will override the value of gEfiMdeModulePkgTokenSpaceGuid.PcdSerialDetectCable defined in MdeModulePkg.dec.

4. ExtendedTxFifoSize
   Type: plist integer
   Failsafe: 64
   Description: Set the extended transmit FIFO size for serial port.

   This option will override the value of gEfiMdeModulePkgTokenSpaceGuid.PcdSerialExtendedTxFifoSize defined in MdeModulePkg.dec.

5. FifoControl
   Type: plist integer
   Failsafe: 0x07
   Description: Configure serial port FIFO Control settings.

   This option will override the value of gEfiMdeModulePkgTokenSpaceGuid.PcdSerialFifoControl defined in MdeModulePkg.dec.

6. LineControl
   Type: plist integer
   Failsafe: 0x07
   Description: Configure serial port Line Control settings.

   This option will override the value of gEfiMdeModulePkgTokenSpaceGuid.PcdSerialLineControl defined in MdeModulePkg.dec.

7. PciDeviceInfo
   Type: plist data
   Failsafe: 0xFF
   Description: Set PCI serial device information.

   This option will override the value of gEfiMdeModulePkgTokenSpaceGuid.PcdSerialPciDeviceInfo defined in MdeModulePkg.dec.

   Note: The maximum allowed size of this option is 41 bytes. Refer to acidanthera/bugtracker#1954 for more details.

   Note 2: This option can be set by running the FindSerialPort tool.

8. RegisterAccessWidth
   Type: plist integer
   Failsafe: 8
   Description: Set serial port register access width.

   This option will override the value of gEfiMdeModulePkgTokenSpaceGuid.PcdSerialRegisterAccessWidth defined in MdeModulePkg.dec.

9. RegisterBase
   Type: plist integer
   Failsafe: 0x03F8
   Description: Set the base address of serial port registers.

   This option will override the value of gEfiMdeModulePkgTokenSpaceGuid.PcdSerialRegisterBase defined in MdeModulePkg.dec.

10. RegisterStride
    Type: plist integer
    Failsafe: 1
    Description: Set the serial port register stride in bytes.

    This option will override the value of gEfiMdeModulePkgTokenSpaceGuid.PcdSerialRegisterStride defined in MdeModulePkg.dec.

11. UseHardwareFlowControl
    Type: plist boolean
    Failsafe: false
    Description: Enable serial port hardware flow control.

    This option will override the value of gEfiMdeModulePkgTokenSpaceGuid.PcdSerialUseHardwareFlowControl defined in MdeModulePkg.dec.

12. UseMmio
    Type: plist boolean
    Failsafe: false
    Description: Indicate whether the serial port registers are in MMIO space.

    This option will override the value of gEfiMdeModulePkgTokenSpaceGuid.PcdSerialUseMmio defined in MdeModulePkg.dec.

9 NVRAM

9.1 Introduction

This section allows setting non-volatile UEFI variables commonly described as NVRAM variables. Refer to man nvram for details. The macOS operating system extensively uses NVRAM variables for OS — Bootloader — Firmware intercommunication. Hence, the supply of several NVRAM variables is required for the proper functioning of macOS.

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

• 4D1EDE05-38C7-4A6A-9CC6-4BCCA8B38C14 (APPLE_VENDOR_VARIABLE_GUID)
• 7C436110-AB2A-4BBB-A880-FE41995C9F82 (APPLE_BOOT_VARIABLE_GUID)
• 5EDDA193-A070-416A-85EB-2A1181F45B18 (Apple Hardware Configuration Storage for MacPro7,1)
• 8BE4DF61-93CA-11D2-AA0D-00E098032B8C (EFI_GLOBAL_VARIABLE_GUID)
• 4D1FDA02-38C7-4A6A-9CC6-4BCCA8B30102 (OC_VENDOR_VARIABLE_GUID)

Note: Some of the variables may be added by the PlatformNVRAM or Generic subsections of the PlatformInfo section. Please ensure that variables set in this section do not conflict with items in those subsections as the implementation behaviour is undefined otherwise.

The OC_FIRMWARE_RUNTIME protocol implementation, currently offered as a part of the OpenRuntime driver, is often required for macOS to function properly. While this brings many benefits, there are some limitations that should be considered for certain use cases.

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 must be aware of the 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 multidata format. GUIDs must be provided in canonic string format in upper or lower case (e.g. 8BE4DF61-93CA-11D2-AA0D-00E098032B8C).

   The EFI_VARIABLE_BOOTSERVICE_ACCESS and EFI_VARIABLE_RUNTIME_ACCESS attributes of created variables are set. Variables will only be set if not present or deleted. That is, to overwrite an existing variable value, add the variable name to the Delete section. This approach enables the provision of default values until the operating system takes the lead.

   Note: The implementation behaviour is undefined when the plist key does not conform to the GUID format.

2. Delete
   Type: plist dict
   Description: Removes NVRAM variables from a map (plist dict) of GUIDs to an array (plist array) of variable names in plist string format.

3. LegacyOverwrite
   Type: plist boolean
   Failsafe: false
   Description: Permits overwriting firmware variables from nvram.plist.

   Note: Only variables accessible from the operating system will be overwritten.

4. LegacySchema
   Type: plist dict
   Description: Allows setting certain NVRAM variables from a map (plist dict) of GUIDs to an array (plist array) of variable names in plist string format.

   * value can be used to accept all variables for certain GUID.

   WARNING: Choose variables carefully, as the nvram.plist file is not vaulted. For instance, do not include boot-args or csr-active-config, as these can be used to bypass SIP.

5. WriteFlash
   Type: plist boolean
   Failsafe: false
   Description: Enables writing to flash memory for all added variables.

   Note: This value should be enabled on most types of firmware but is left configurable to account for firmware that may have issues with NVRAM variable storage garbage collection or similar.

The nvram command can be used to read NVRAM variable values from macOS by concatenating the GUID and name variables separated by a : symbol. For example, nvram 7C436110-AB2A-4BBB-A880-FE41995C9F82:boot-args.

A continuously updated variable list can be found in a corresponding document: NVRAM Variables.

9.3 Mandatory Variables

Warning: These variables may be added by the PlatformNVRAM or Generic subsections of the PlatformInfo section. Using PlatformInfo is the recommended way of setting these variables.

The following variables are mandatory for macOS functioning:

• 4D1EDE05-38C7-4A6A-9CC6-4BCCA8B38C14:FirmwareFeatures 32-bit FirmwareFeatures. Present on all Macs to avoid extra parsing of SMBIOS tables.
• 4D1EDE05-38C7-4A6A-9CC6-4BCCA8B38C14:FirmwareFeaturesMask 32-bit FirmwareFeaturesMask. Present on all Macs to avoid extra parsing of SMBIOS tables.
• 4D1EDE05-38C7-4A6A-9CC6-4BCCA8B38C14:MLB BoardSerialNumber. Present on newer Macs (2013+ at least) to avoid extra parsing of SMBIOS tables, especially in boot.efi.
• 4D1EDE05-38C7-4A6A-9CC6-4BCCA8B38C14:ROM Primary network adapter MAC address or replacement value. Present on newer Macs (2013+ at least) to avoid accessing special memory region, especially in boot.efi.

9.4 Recommended Variables

The following variables are recommended for faster startup or other improvements:

• 4D1EDE05-38C7-4A6A-9CC6-4BCCA8B38C14:BridgeOSHardwareModel Bridge OS hardware model variable used to propagate to IODT bridge-model by EfiBoot. Read by hw.target sysctl, used by SoftwareUpdateCoreSupport.
• 7C436110-AB2A-4BBB-A880-FE41995C9F82:csr-active-config 32-bit System Integrity Protection bitmask. Declared in XNU source code in csr.h.
• 4D1EDE05-38C7-4A6A-9CC6-4BCCA8B38C14:ExtendedFirmwareFeatures Combined FirmwareFeatures and ExtendedFirmwareFeatures. Present on newer Macs to avoid extra parsing of SMBIOS tables.
• 4D1EDE05-38C7-4A6A-9CC6-4BCCA8B38C14:ExtendedFirmwareFeaturesMask Combined FirmwareFeaturesMask and ExtendedFirmwareFeaturesMask. Present on newer Macs to avoid extra parsing of SMBIOS tables.
• 4D1EDE05-38C7-4A6A-9CC6-4BCCA8B38C14:HW_BID Hardware BoardProduct (e.g. Mac-35C1E88140C3E6CF). Not present on real Macs, but used to avoid extra parsing of SMBIOS tables, especially in boot.efi.
• 4D1EDE05-38C7-4A6A-9CC6-4BCCA8B38C14:HW_MLB Hardware BoardSerialNumber. Override for MLB. Present on newer Macs (2013+ at least).
• 4D1EDE05-38C7-4A6A-9CC6-4BCCA8B38C14:HW_ROM Hardware ROM. Override for ROM. Present on newer Macs (2013+ at least).
• 4D1EDE05-38C7-4A6A-9CC6-4BCCA8B38C14:SSN Serial number. Present on newer Macs (2013+ at least).
• 7C436110-AB2A-4BBB-A880-FE41995C9F82:prev-lang:kbd ASCII string defining default keyboard layout. Format is lang-COUNTRY:keyboard, e.g. ru-RU:252 for Russian locale and ABC keyboard. Also accepts short forms: ru:252 or ru:0 (U.S. keyboard, compatible with 10.9). Full 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.
• 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.
• 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.
• 7C436110-AB2A-4BBB-A880-FE41995C9F82:ForceDisplayRotationInEFI 32-bit integer defining display rotation. Can be 0 for no rotation or any of 90, 180, 270 for matching rotation in degrees.
• 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.

9.5 Other Variables

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

• 7C436110-AB2A-4BBB-A880-FE41995C9F82:boot-args Kernel arguments, used to pass configuration to Apple kernel and drivers. There are many arguments, which may be found by looking for the use of PE_parse_boot_argn function in the kernel or driver code. Some of the known boot arguments include:

  • acpi_layer=0xFFFFFFFF
  • acpi_level=0xFFFF5F (implies ACPI_ALL_COMPONENTS)
  • arch=i386 (force kernel architecture to i386, see KernelArch)
  • batman=VALUE (AppleSmartBatteryManager debug mask)
  • batman-nosmc=1 (disable AppleSmartBatteryManager SMC interface)
  • cpus=VALUE (maximum number of CPUs used)
  • debug=VALUE (debug mask)
  • io=VALUE (IOKit debug mask)
  • ioaccel_debug=VALUE (IOAccelerator debug mask)
  • keepsyms=1 (show panic log debug symbols)
  • kextlog=VALUE (kernel extension loading debug mask)
  • nvram-log=1 (enables AppleEFINVRAM logs)
  • nv_disable=1 (disables NVIDIA GPU acceleration)
  • nvda_drv=1 (legacy way to enable NVIDIA web driver, removed in 10.12)
  • npci=0x2000 ( legacy, disables kIOPCIConfiguratorPFM64)
  • lapic_dont_panic=1 (disable lapic spurious interrupt panic on AP cores)
  • panic_on_display_hang=1 (trigger panic on display hang)
  • panic_on_gpu_hang=1 (trigger panic on GPU hang)

  • serial=VALUE (configure serial logging mode) — The following bits are used by XNU:

    • 0x01 (SERIALMODE_OUTPUT, bit 0) — Enable serial output.
    • 0x02 (SERIALMODE_INPUT, bit 1) — Enable serial input.
    • 0x04 (SERIALMODE_SYNCDRAIN, bit 2) — Enable serial drain synchronisation.
    • 0x08 (SERIALMODE_BASE_TTY, bit 3) — Load Base/Recovery/FVUnlock TTY.
    • 0x10 (SERIALMODE_NO_IOLOG, bit 4) — Prevent IOLogs writing to serial.
  • slide=VALUE (manually set KASLR slide)
  • smcdebug=VALUE (AppleSMC debug mask)
  • spin_wait_for_gpu=1 (reduces GPU timeout on high load)
  • -amd_no_dgpu_accel (alternative to WhateverGreen’s -radvesa for new GPUs)
  • -nehalem_error_disable (disables the AppleTyMCEDriver)
  • -no_compat_check (disable model checking on 10.7+)
  • -s (single mode)
  • -v (verbose mode)
  • -x (safe mode)

  There are multiple external places summarising macOS argument lists: example 1, example 2.

• 7C436110-AB2A-4BBB-A880-FE41995C9F82:bootercfg Booter arguments, similar to boot-args but for boot.efi. Accepts a set of arguments, which are hexadecimal 64-bit values with or without 0x. At different stages boot.efi will request different debugging (logging) modes (e.g. after ExitBootServices it will only print to serial). Several booter arguments control whether these requests will succeed. The list of known requests is covered below:

  • 0x00 – INIT.
  • 0x01 – VERBOSE (e.g. -v, force console logging).
  • 0x02 – EXIT.
  • 0x03 – RESET:OK.
  • 0x04 – RESET:FAIL (e.g. unknown board-id, hibernate mismatch, panic loop, etc.).
  • 0x05 – RESET:RECOVERY.
  • 0x06 – RECOVERY.
  • 0x07 – REAN:START.
  • 0x08 – REAN:END.
  • 0x09 – DT (can no longer log to DeviceTree).
  • 0x0A – EXITBS:START (forced serial only).
  • 0x0B – EXITBS:END (forced serial only).
  • 0x0C – UNKNOWN.

  In 10.15, debugging support was defective up to the 10.15.4 release due to refactoring issues as well as the introduction of a new debug protocol. Some of the arguments and their values below may not be valid for versions prior to 10.15.4. The list of known arguments is covered below:

  • boot-save-log=VALUE — debug log save mode for normal boot.

    • 0
    • 1
    • 2 — (default).
    • 3
    • 4 — (save to file).

  • wake-save-log=VALUE — debug log save mode for hibernation wake.

    • 0 — disabled.
    • 1
    • 2 — (default).
    • 3 — (unavailable).
    • 4 — (save to file, unavailable).

  • breakpoint=VALUE — enables debug breaks (missing in production boot.efi).

    • 0 — disables debug breaks on errors (default).
    • 1 — enables debug breaks on errors.

  • console=VALUE — enables console logging.

    • 0 — disables console logging.
    • 1 — enables console logging when debug protocol is missing (default).
    • 2 — enables console logging unconditionally (unavailable).

  • embed-log-dt=VALUE — enables DeviceTree logging.

    • 0 — disables DeviceTree logging (default).
    • 1 — enables DeviceTree logging.
  • kc-read-size=VALUE — Chunk size used for buffered I/O from network or disk for prelinkedkernel reading and related. Set to 1MB (0x100000) by default, can be tuned for faster booting.

  • log-level=VALUE — log level bitmask.

    • 0x01 — enables trace logging (default).

  • serial=VALUE — enables serial logging.

    • 0 — disables serial logging (default).
    • 1 — enables serial logging for EXITBS:END onwards.
    • 2 — enables serial logging for EXITBS:START onwards.
    • 3 — enables serial logging when debug protocol is missing.
    • 4 — enables serial logging unconditionally.

  • timestamps=VALUE — enables timestamp logging.

    • 0 — disables timestamp logging.
    • 1 — enables timestamp logging (default).

  • log=VALUE — deprecated starting from 10.15.

    • 1 — AppleLoggingConOutOrErrSet/AppleLoggingConOutOrErrPrint (classical ConOut/StdErr)
    • 2 — AppleLoggingStdErrSet/AppleLoggingStdErrPrint (StdErr or serial?)
    • 4 — AppleLoggingFileSet/AppleLoggingFilePrint (BOOTER.LOG/BOOTER.OLD file on EFI partition)

  • debug=VALUE — deprecated starting from 10.15.

    • 1 — enables print something to BOOTER.LOG (stripped code implies there may be a crash)
    • 2 — enables perf logging to /efi/debug-log in the device three
    • 4 — enables timestamp printing for styled printf calls
  • level=VALUE — deprecated starting from 10.15. Verbosity level of DEBUG output. Everything but 0x80000000 is stripped from the binary, and this is the default value.

  Note: Enable the AppleDebug option to display verbose output from boot.efi on modern macOS versions. This will save the log to the general OpenCore log file. For versions before 10.15.4, set bootercfg to log=1. This will print verbose output onscreen.

• 7C436110-AB2A-4BBB-A880-FE41995C9F82:bootercfg-once Booter arguments override removed after first launch. Otherwise equivalent to bootercfg.
• 7C436110-AB2A-4BBB-A880-FE41995C9F82:csr-data Specify sources of kexts which will be approved regardless of SIP CSR_ALLOW_UNAPPROVED_KEXTS value.
  Example contents:
  <dict><key>kext-allowed-teams</key><array><string>{DEVELOPER-TEAM-ID}</string></array></dict>%00
• 7C436110-AB2A-4BBB-A880-FE41995C9F82:efiboot-perf-record Enable performance log saving in boot.efi. Performance log is saved to physical memory and is pointed to by the efiboot-perf-record-data and efiboot-perf-record-size variables. Starting from 10.15.4, it can also be saved to the OpenCore log by setting the AppleDebug option.
• 7C436110-AB2A-4BBB-A880-FE41995C9F82:fmm-computer-name Current saved host name. ASCII string.
• 7C436110-AB2A-4BBB-A880-FE41995C9F82:nvda_drv NVIDIA Web Driver control variable. Takes ASCII digit 1 or 0 to enable or disable installed driver.
• 7C436110-AB2A-4BBB-A880-FE41995C9F82:run-efi-updater Override EFI firmware updating support in macOS (MultiUpdater, ThorUtil, and so on). Setting this to No or alternative boolean-castable value will prevent any firmware updates in macOS starting with 10.10 at least.
• 7C436110-AB2A-4BBB-A880-FE41995C9F82:StartupMute Mute startup chime sound in firmware audio support. 8-bit integer. The value of 0x00 means unmuted. Missing variable or any other value means muted.
• 7C436110-AB2A-4BBB-A880-FE41995C9F82:SystemAudioVolume System audio volume level for firmware audio support. 8-bit unsigned integer. The bit of 0x80 means muted. The remaining bits are used to encode the raw amplifier gain setting to be applied to the audio amplifier in use. Exactly what this value means depends on the codec (and potentially on the specific amplifier within the codec). This value is capped by macOS to the MaximumBootBeepVolume AppleHDA layout value, to avoid over-loud audio playback in the firmware.

• 7C436110-AB2A-4BBB-A880-FE41995C9F82:SystemAudioVolumeDB Current system audio volume level in decibels (dB). 8-bit signed integer. The value represents the audio offset (gain if positive, attenuation if negative) in dB relative to the amplifier reference value of 0 dB. Exactly which volume level is represented by 0 dB depends on the codec (and potentially on the specific amplifier within the codec) but it is normally at or near the maximum available amplifier volume. Typical values of this variable range from approximately -60 (the exact value depends on the audio hardware) up to exactly 0. On non-typical audio hardware, the value may go above zero.

  Note: Unlike SystemAudioVolume, this value is not capped.

• 5EDDA193-A070-416A-85EB-2A1181F45B18:PEXConf PCI expansion slot configuration for MacPro7,1. 8-byte sequence describing default PCI slot configuration. Each byte refers to a configuration for a dedicated PCI slot.

  • Slot 1 resides at IOService:/AppleACPIPlatformExpert/PC01@0/AppleACPIPCI/BR1A@0 and its path is hardcoded. This slot is not behind a muxer.
  • Slot 3 resides at IOService:/AppleACPIPlatformExpert/PC03@0/AppleACPIPCI/BR3A@0 and its path is hardcoded. This slot is not behind a muxer.
  • Slots 2, 4-8 are dynamic and are matched based on AAPL,slot-name property with Slot-N value, where N is the slot number. All these slots are behind the muxer.

  Refer to the support page for more details on how MacPro7,1 slots are configured.

• 5EDDA193-A070-416A-85EB-2A1181F45B18:SlotUtilPEXConf User PCI expansion slot configuration for MacPro7,1. 8-byte sequence describing user PCI slot configuration.

10 PlatformInfo

Platform information consists of several identification fields generated or filled manually to be compatible with macOS services. The base part of the configuration may be obtained from AppleModels, which itself generates a set of interfaces based on a database in YAML format. These fields are written to three destinations:

• SMBIOS
• Data Hub
• NVRAM

Most of the fields specify the overrides in SMBIOS, and their field names conform to EDK2 SmBios.h header file. However, several important fields reside in Data Hub and NVRAM. Some of the values can be found in more than one field and/or destination, so there are two ways to control their update process: manual, where all the values are specified (the default), and semi-automatic, where (Automatic) only certain values are specified, and later used for system configuration.

The dmidecode utility can be used to inspect SMBIOS contents and a version with macOS specific enhancements can be downloaded from Acidanthera/dmidecode.

10.1 Properties

1. Automatic
   Type: plist boolean
   Failsafe: false
   Description: Generate PlatformInfo based on the Generic section instead of using values from the DataHub, NVRAM, and SMBIOS sections.

   Enabling this option is useful when Generic section is flexible enough:

   • When enabled SMBIOS, DataHub, and PlatformNVRAM data is unused.
   • When disabled Generic section is unused.

   Warning: Setting this option to false is strongly discouraged when intending to update platform information. A false setting is typically only valid for minor corrections to SMBIOS values on legacy Apple hardware. In all other cases, setting Automatic to false may lead to hard-to-debug errors resulting from inconsistent or invalid settings.

2. CustomMemory
   Type: plist boolean
   Failsafe: false
   Description: Use custom memory configuration defined in the Memory section. This completely replaces any existing memory configuration in SMBIOS, and is only active when UpdateSMBIOS is set to true.

3. DataHub
   Type: plist dictionary
   Description: Update Data Hub fields in non-Automatic mode.

   Note: This section is ignored and may be removed when Automatic is true.

4. Generic
   Type: plist dictionary
   Description: Update all fields in Automatic mode.

   Note: This section is ignored but may not be removed when Automatic is false.

5. Memory
   Type: plist dictionary
   Description: Define custom memory configuration.

   Note: This section is ignored and may be removed when CustomMemory is false.

6. PlatformNVRAM
   Type: plist dictionary
   Description: Update platform NVRAM fields in non-Automatic mode.

   Note: This section is ignored and may be removed when Automatic is true.

7. SMBIOS
   Type: plist dictionary
   Description: Update SMBIOS fields in non-Automatic mode.

   Note: This section is ignored and may be removed when Automatic is true.

8. UpdateDataHub
   Type: plist boolean
   Failsafe: false
   Description: Update Data Hub fields. These fields are read from the Generic or DataHub sections depending on the setting of the Automatic property.

   Note: The implementation of the Data Hub protocol in EFI firmware on virtually all systems, including Apple hardware, means that existing Data Hub entries cannot be overridden. New entries are added to the end of the Data Hub instead, with macOS ignoring old entries. This can be worked around by replacing the Data Hub protocol using the ProtocolOverrides section. Refer to the DataHub protocol override description for details.

9. UpdateNVRAM
   Type: plist boolean
   Failsafe: false
   Description: Update NVRAM fields related to platform information.

   These fields are read from the Generic or PlatformNVRAM sections depending on the setting of the Automatic property. All the other fields are to be specified with the NVRAM section.

   If UpdateNVRAM is set to false, the aforementioned variables can be updated with the NVRAM section. If UpdateNVRAM is set to true, the behaviour is undefined when any of the fields are present in the NVRAM section.

10. UpdateSMBIOS
    Type: plist boolean
    Failsafe: false
    Description: Update SMBIOS fields. These fields are read from the Generic or SMBIOS sections depending on the setting of the Automatic property.

11. UpdateSMBIOSMode
    Type: plist string
    Failsafe: Create
    Description: Update SMBIOS fields approach:

    • TryOverwrite — Overwrite if new size is <= than the page-aligned original and there are no issues with legacy region unlock. Create otherwise. Has issues on some types of firmware.
    • Create — Replace the tables with newly allocated EfiReservedMemoryType at AllocateMaxAddress without any fallbacks.
    • Overwrite — Overwrite existing gEfiSmbiosTableGuid and gEfiSmbiosTable3Guid data if it fits new size. Abort with unspecified state otherwise.
    • Custom — Write SMBIOS tables (gEfiSmbios(3)TableGuid) to gOcCustomSmbios(3)TableGuid to workaround firmware overwriting SMBIOS contents at ExitBootServices. Otherwise equivalent to Create. Requires patching AppleSmbios.kext and AppleACPIPlatform.kext to read from another GUID: "EB9D2D31" - "EB9D2D35" (in ASCII), done automatically by CustomSMBIOSGuid quirk.

    Note: A side effect of using the Custom approach that it makes SMBIOS updates exclusive to macOS, avoiding a collision with existing Windows activation and custom OEM software but potentially obstructing the operation of Apple-specific tools.

12. UseRawUuidEncoding
    Type: plist boolean
    Failsafe: false
    Description: Use raw encoding for SMBIOS UUIDs.

    Each UUID AABBCCDD-EEFF-GGHH-IIJJ-KKLLMMNNOOPP is essentially a hexadecimal 16-byte number. It can be encoded in two ways:

    • Big Endian — by writing all the bytes as they are without making any order changes ({AA BB CC DD EE FF GG HH II JJ KK LL MM NN OO PP}). This method is also known as RFC 4122 encoding or Raw encoding.
    • Little Endian — by interpreting the bytes as numbers and using Little Endian byte representation ({DD CC BB AA FF EE HH GG II JJ KK LL MM NN OO PP}).

    The SMBIOS specification did not explicitly specify the encoding format for the UUID up to SMBIOS 2.6, where it stated that Little Endian encoding shall be used. This led to the confusion in both firmware implementations and system software as different vendors used different encodings prior to that.

    • Apple uses the Big Endian format everywhere but it ignores SMBIOS UUID within macOS.
    • dmidecode uses the Big Endian format for SMBIOS 2.5.x or lower and the Little Endian format for 2.6 and newer. Acidanthera dmidecode prints all three.
    • Windows uses the Little Endian format everywhere, but this only affects the visual representation of the values.

    OpenCore always sets a recent SMBIOS version (currently 3.2) when generating the modified DMI tables. If UseRawUuidEncoding is enabled, the Big Endian format is used to store the SystemUUID data. Otherwise, the Little Endian format is used.

    Note: This preference does not affect UUIDs used in DataHub and NVRAM as they are not standardised and are added by Apple. Unlike SMBIOS, they are always stored in the Big Endian format.

10.2 DataHub Properties

1. ARTFrequency
   Type: plist integer, 64-bit
   Failsafe: 0 (Automatic)
   Description: Sets ARTFrequency in gEfiProcessorSubClassGuid.

   This value contains CPU ART frequency, also known as crystal clock frequency. Its existence is exclusive to the Skylake generation and newer. The value is specified in Hz, and is normally 24 MHz for the client Intel segment, 25 MHz for the server Intel segment, and 19.2 MHz for Intel Atom CPUs. macOS till 10.15 inclusive assumes 24 MHz by default.

   Note: On Intel Skylake X ART frequency may be a little less (approx. 0.25%) than 24 or 25 MHz due to special EMI-reduction circuit as described in Acidanthera Bugtracker.

2. BoardProduct
   Type: plist string
   Failsafe: Empty (Not installed)
   Description: Sets board-id in gEfiMiscSubClassGuid. The value found on Macs is equal to SMBIOS BoardProduct in ASCII.
3. BoardRevision
   Type: plist data, 1 byte
   Failsafe: 0
   Description: Sets board-rev in gEfiMiscSubClassGuid. The value found on Macs seems to correspond to internal board revision (e.g. 01).
4. DevicePathsSupported
   Type: plist integer, 32-bit
   Failsafe: 0 (Not installed)
   Description: Sets DevicePathsSupported in gEfiMiscSubClassGuid. Must be set to 1 for AppleACPIPlatform.kext to append SATA device paths to Boot#### and efi-boot-device-data variables. Set to 1 on all modern Macs.

5. FSBFrequency
   Type: plist integer, 64-bit
   Failsafe: 0 (Automatic)
   Description: Sets FSBFrequency in gEfiProcessorSubClassGuid.

   Sets CPU FSB frequency. This value equals to CPU nominal frequency divided by CPU maximum bus ratio and is specified in Hz. Refer to MSR_NEHALEM_PLATFORM_INFO (CEh) MSR value to determine maximum bus ratio on modern Intel CPUs.

   Note: This value is not used on Skylake and newer but is still provided to follow suit.

6. InitialTSC
   Type: plist integer, 64-bit
   Failsafe: 0
   Description: Sets InitialTSC in gEfiProcessorSubClassGuid. Sets initial TSC value, normally 0.
7. PlatformName
   Type: plist string
   Failsafe: Empty (Not installed)
   Description: Sets name in gEfiMiscSubClassGuid. The value found on Macs is platform in ASCII.
8. SmcBranch
   Type: plist data, 8 bytes
   Failsafe: Empty (Not installed)
   Description: Sets RBr in gEfiMiscSubClassGuid. Custom property read by VirtualSMC or FakeSMC to generate SMC RBr key.
9. SmcPlatform
   Type: plist data, 8 bytes
   Failsafe: Empty (Not installed)
   Description: Sets RPlt in gEfiMiscSubClassGuid. Custom property read by VirtualSMC or FakeSMC to generate SMC RPlt key.
10. SmcRevision
    Type: plist data, 6 bytes
    Failsafe: Empty (Not installed)
    Description: Sets REV in gEfiMiscSubClassGuid. Custom property read by VirtualSMC or FakeSMC to generate SMC REV key.

11. StartupPowerEvents
    Type: plist integer, 64-bit
    Failsafe: 0
    Description: Sets StartupPowerEvents in gEfiMiscSubClassGuid. The value found on Macs is power management state bitmask, normally 0. Known bits read by X86PlatformPlugin.kext:

    • 0x00000001 — Shutdown cause was a PWROK event (Same as GEN_PMCON_2 bit 0)
    • 0x00000002 — Shutdown cause was a SYS_PWROK event (Same as GEN_PMCON_2 bit 1)
    • 0x00000004 — Shutdown cause was a THRMTRIP# event (Same as GEN_PMCON_2 bit 3)
    • 0x00000008 — Rebooted due to a SYS_RESET# event (Same as GEN_PMCON_2 bit 4)
    • 0x00000010 — Power Failure (Same as GEN_PMCON_3 bit 1 PWR_FLR)
    • 0x00000020 — Loss of RTC Well Power (Same as GEN_PMCON_3 bit 2 RTC_PWR_STS)
    • 0x00000040 — General Reset Status (Same as GEN_PMCON_3 bit 9 GEN_RST_STS)
    • 0xffffff80 — SUS Well Power Loss (Same as GEN_PMCON_3 bit 14)
    • 0x00010000 — Wake cause was a ME Wake event (Same as PRSTS bit 0, ME_WAKE_STS)
    • 0x00020000 — Cold Reboot was ME Induced event (Same as PRSTS bit 1 ME_HRST_COLD_STS)
    • 0x00040000 — Warm Reboot was ME Induced event (Same as PRSTS bit 2 ME_HRST_WARM_STS)
    • 0x00080000 — Shutdown was ME Induced event (Same as PRSTS bit 3 ME_HOST_PWRDN)
    • 0x00100000 — Global reset ME Watchdog Timer event (Same as PRSTS bit 6)
    • 0x00200000 — Global reset PowerManagement Watchdog Timer event (Same as PRSTS bit 15)
12. SystemProductName
    Type: plist string
    Failsafe: Empty (Not installed)
    Description: Sets Model in gEfiMiscSubClassGuid. The value found on Macs is equal to SMBIOS SystemProductName in Unicode.
13. SystemSerialNumber
    Type: plist string
    Failsafe: Empty (Not installed)
    Description: Sets SystemSerialNumber in gEfiMiscSubClassGuid. The value found on Macs is equal to SMBIOS SystemSerialNumber in Unicode.
14. SystemUUID
    Type: plist string, GUID
    Failsafe: Empty (Not installed)
    Description: Sets system-id in gEfiMiscSubClassGuid. The value found on Macs is equal to SMBIOS SystemUUID (with swapped byte order).

10.3 Generic Properties

1. AdviseFeatures
   Type: plist boolean
   Failsafe: false
   Description: Updates FirmwareFeatures with supported bits.

   Added bits to FirmwareFeatures:

   • FW_FEATURE_SUPPORTS_CSM_LEGACY_MODE (0x1) - Without this bit, it is not possible to reboot to Windows installed on a drive with an EFI partition that is not the first partition on the disk.
   • FW_FEATURE_SUPPORTS_UEFI_WINDOWS_BOOT (0x20000000) - Without this bit, it is not possible to reboot to Windows installed on a drive with an EFI partition that is the first partition on the disk.
   • FW_FEATURE_SUPPORTS_APFS (0x00080000) - Without this bit, it is not possible to install macOS on an APFS disk.
   • FW_FEATURE_SUPPORTS_LARGE_BASESYSTEM (0x800000000) - Without this bit, it is not possible to install macOS versions with large BaseSystem images, such as macOS 12.

   Note: On most newer firmwares these bits are already set, the option may be necessary when "upgrading" the firmware with new features.

2. MLB
   Type: plist string
   Failsafe: Empty (OEM specified or not installed)
   Description: Refer to SMBIOS BoardSerialNumber.

   Specify special string value OEM to extract current value from NVRAM (MLB variable) or SMBIOS and use it throughout the sections. This feature can only be used on Mac-compatible firmware.

3. MaxBIOSVersion
   Type: plist boolean
   Failsafe: false
   Description: Sets BIOSVersion to 9999.999.999.999.999, recommended for legacy Macs when using Automatic PlatformInfo, to avoid BIOS updates in unofficially supported macOS versions.
4. ProcessorType
   Type: plist integer
   Failsafe: 0 (Automatic)
   Description: Refer to SMBIOS ProcessorType.

5. ROM
   Type: plist multidata, 6 bytes
   Failsafe: Empty (OEM specified or not installed)
   Description: Refer to 4D1EDE05-38C7-4A6A-9CC6-4BCCA8B38C14:ROM.

   Specify special string value OEM to extract current value from NVRAM (ROM variable) and use it throughout the sections. This feature can only be used on Mac-compatible firmware.

6. SpoofVendor
   Type: plist boolean
   Failsafe: false
   Description: Sets SMBIOS vendor fields to Acidanthera.

   It can be dangerous to use “Apple” in SMBIOS vendor fields for reasons outlined in the SystemManufacturer description. However, certain firmware may not provide valid values otherwise, which could obstruct the operation of some software.

7. SystemMemoryStatus
   Type: plist string
   Failsafe: Auto
   Description: Indicates whether system memory is upgradable in PlatformFeature. This controls the visibility of the Memory tab in “About This Mac”.

   Valid values:

   • Auto — use the original PlatformFeature value.
   • Upgradable — explicitly unset PT_FEATURE_HAS_SOLDERED_SYSTEM_MEMORY (0x2) in PlatformFeature.
   • Soldered — explicitly set PT_FEATURE_HAS_SOLDERED_SYSTEM_MEMORY (0x2) in PlatformFeature.

   Note: On certain Mac models, such as the MacBookPro10,x and any MacBookAir, SPMemoryReporter.spreporter will ignore PT_FEATURE_HAS_SOLDERED_SYSTEM_MEMORY and assume that system memory is non-upgradable.

8. SystemProductName
   Type: plist string
   Failsafe: Empty (OEM specified or not installed)
   Description: Refer to SMBIOS SystemProductName.

9. SystemSerialNumber
   Type: plist string
   Failsafe: Empty (OEM specified or not installed)
   Description: Refer to SMBIOS SystemSerialNumber.

   Specify special string value OEM to extract current value from NVRAM (SSN variable) or SMBIOS and use it throughout the sections. This feature can only be used on Mac-compatible firmware.

10. SystemUUID
    Type: plist string, GUID
    Failsafe: Empty (OEM specified or not installed)
    Description: Refer to SMBIOS SystemUUID.

    Specify special string value OEM to extract current value from NVRAM (system-id variable) or SMBIOS and use it throughout the sections. Since not every firmware implementation has valid (and unique) values, this feature is not applicable to some setups, and may provide unexpected results. It is highly recommended to specify the UUID explicitly. Refer to UseRawUuidEncoding to determine how SMBIOS value is parsed.