PIC

OpenCore

Reference Manual (0.7.6.7)

[2022.01.20]

Copyright ©2018-2021 2018-2022 vit9696

  • nvram.plist
    OpenCore variable import 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 ?? 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. 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:

    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 
    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
    Listing 1:Compilation Commands

    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
    Listing 2:ECC Configuration

    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.

    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.

    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.

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

                         ^^