Reference Manual (0.7.2.3)
Copyright ©2018-2021 vit9696
OpenCore variable import file.
OpenCore log file.
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.
To install OpenCore, replicate the ?? 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 ?? 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. For a lightweight cross-platform and open-source alternative, the ProperTree editor can be utilised.
It is strongly advised not to use any software that is aware of the internal configration structure as it constantly gets out of date and will cause incorrect configuration to be generated. If it is a must desprite the warning one should make sure to only use stable versions of OpenCore with explicit support for the particular version in the app. The choice of open-source implementations with transparent binary generation is encouraged (e.g. OCAT), since other tools may contain malware. Remember that a configuration made for a different hardware setup shall never be used on another hardware setup.
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).
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.
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:
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:
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 ?? 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.
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.
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
MMDD — MmapDump
OCPAVP — PavpProvision
OCRST — ResetSystem
OCUI — OpenCanopy
OC — OpenCore main, also OcMainLib
VMOPT — VerifyMemOpt
AAPL — OcDebugLogLib, Apple EfiBoot logging
OCABC — OcAfterBootCompatLib
OCAE — OcAppleEventLib
OCAK — OcAppleKernelLib
CSR_ALLOW_UNAUTHENTICATED_ROOT (0x800) is not practical as it prevents incremental (non-full) OTA updates.
Note3: For any other value which you may need to use, it is possible to configure CsrUtil.efi as a TextMode Tools entry to configure a different value, e.g. use toggle 0x6F in Arguments to toggle the SIP disabled value set by default by csrutil disable --no-internal in Big Sur.
Type: plist integer, 64 bit
Description: Apple Enclave Identifier.
Setting this value to any non-zero 64-bit integer will allow using personalised Apple Secure Boot identifiers. To use this setting, generate a random 64-bit number with a cryptographically secure random number generator. As an alternative, the first 8 bytes of SystemUUID can be used for ApECID, this is found in macOS 11 for Macs without the T2 chip.
With this value set and SecureBootModel valid (and not Disabled), it is possible to achieve Full Security of Apple Secure Boot.
To start using personalised Apple Secure Boot, the operating system must be reinstalled or personalised. Unless the operating system is personalised, macOS DMG recovery cannot be loaded. In cases where DMG recovery is missing, it can be downloaded by using the macrecovery utility and saved in com.apple.recovery.boot as explained in the ?? section. Note that ?? needs to be set to Signed to use any DMG with Apple Secure Boot.
To personalise an existing operating system, use the bless command after loading to macOS DMG recovery. Mount the system volume partition, unless it has already been mounted, and execute the following command:
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:
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_EXTLINUX_ROOT, allows scanning of EXT (Linux Root Linux Root file systems.
0x00002000 (bit 13) — OC_SCAN_ALLOW_FS_LINUX_DATA, allows scanning of Linux Data file systems.
0x00004000(bit 14) file system— 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.
ote: the transformation used in macOS is not linear, but it is very close and this nuance is thus ignored.
Type: plist string
Description: Path of file to be loaded as a UEFI driver from OC/Drivers directory.
Type: plist boolean
Description: If false this driver entry will be ignored.
Type: plist string
Description: Some OC plugins accept optional additional arguments which may be specified as a string here.
Type: plist boolean
Description: Enable keyboard input sanity checking.
Apparently some boards such as the GA Z77P-D3 may return uninitialised data in EFI_INPUT_KEY with all input protocols. This option discards keys that are neither ASCII, nor are defined in the UEFI specification (see tables 107 and 108 in version 2.8).
Type: plist integer
Description: Treat duplicate key presses as held keys if they arrive during this timeout, in 10 ms units. Only applies to systems using KeySupport.
AppleKeyMapAggregator protocol is supposed to contain a fixed length buffer of currently pressed keys. However,