PIC

OpenCore

Reference Manual (0.7.2.3)

[2021.09.26]

Copyright ©2018-2021 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. 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).

    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.

    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 
    source edksetup.sh 
    . ./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.

    When interpreting the log, note that the lines are prefixed with a tag describing the relevant location (module) of the log line allowing better attribution of the line to the functionality.

    The list of currently used tags is as follows.

    Drivers and tools:

    Libraries:

    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.

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

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

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

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

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

    bless --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
  • 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 systemOC_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: