logo

Getting Started With OpenCore 0.5.0

A brief guide to using the OpenCore boot-loader for hackintoshes

OpenCore is an alternative bootloader to CloverEFI or Chameleon. It is not only for Hackintosh and can also be used on real macs for purposes that require an emulated EFI. It also aims to have the ability to boot Windows and Linux without the need for using different acpi tables. It has a clean codebase and aims to stay closer to how a real mac bootloader functions. Kext injection has been greatly improved. While already functioning well,

OpenCore should be considered in Public Beta stage at this time and is intended to be used by experienced hackintosh users, developers, or users who are happy to recover a system which fails to boot or becomes broken in some way.

This guide may not always be able to keep up with every change to OpenCore, (currently OpenCore is in active development,and therefore a moving target) please keep that in mind when compiling the latest version of OpenCore. To be safe, use release versions of OpenCore rather than the latest commits. (0.0.4 Current Release)

This guide is intended to complement the excellent opencore “configuration.pdf” rather than be used instead of it. If you did not already do so, please read it now:

Full Documentation From Acidanthera GitHub

Current known issues

Refer to opencore bugtracker for current known bugs here

Things to note with OpenCore

Getting Started

Requirements:

OpenCorePkg (Advanced users can build the latest from source code, less advanced users should stick to the builds on the release page).

AppleSupportPkg

WhateverGreen

Lilu

Emulated-NVRAM For emulated Nvram on systems with nvram issues.

Xcode (or other plist editor) to edit .plist files.

AudioPkg AudioPkg is a set of drivers/applications for supporting audio (currently only Intel HD audio) under UEFI.

USB drive formatted as MacOS Journaled with GUID partition map. This is to test opencore without overwriting your working Clover. Knowledge of how a hackintosh works and what files yours requires. A previously setup and functioning hackintosh is assumed: which you are happy to potentially break. Time and patience. Without these, you are wasting your effort. *Sign out of all apple services until you are sure you have MLB and ROM sections of smbios set to match your previous Clover set up. Not doing so could cause said services to cease to function, or worst case block your machine.

Creating the USB

Creating the USB is simple, format a USB stick (any size will suffice) as MacOS Journaled with GUID partition map.

Formatting the USB

Next, mount the EFI partition on the USB with either diskutil terminal command or Clover Configurator.

mountEFI

By default, the EFI partition will be empty.

EFI folder structure

To setup OpenCore’s folder structure, copy the files from OpenCorePkg so your EFI looks like the one below:


   |--EFI
   |   |--BOOT
   |   |   |--BOOTx64.efi
   |   |--OC
   |   |   |--ACPI
   |   |   |--Drivers
   |   |   |   |--ApfsDriverLoader.efi
   |   |   |   |--AppleGenericInput.efi
   |   |   |   |--AppleUiSupport.efi
   |   |   |   |--FWRuntimeServices.efi
   |   |   |   |--UsbKbDxe.efi
   |   |   |   |--VBoxHfs.efi
   |   |   |   |--VirtualSmc.efi (Filevault Only))
   |   |   |--Kexts
   |   |   |   |--AppleALC.kext
   |   |   |   |--CPUFriend.kext
   |   |   |   |--Lilu.kext
   |   |   |   |--SMCBatteryManager.kext (Laptop)
   |   |   |   |--SMCLightSensor.kext (Laptop)
   |   |   |   |--SMCProcessor.kext
   |   |   |   |--SMCSuperIO.kext
   |   |   |   |--VirtualSMC.kext
   |   |   |   |--WhateverGreen.kext
   |   |   |--OpenCore.efi
   |   |   |--Tools
   |   |   |   |--CleanNvram.efi
   |   |   |   |--Shell.efi
   |   |   |   |--VerifyMsrE2.efi

Place necessary .efi drivers from AppleSupportPkg and AptioFixPkg into the drivers folder, then kexts/ACPI into their respective folders.

Setting up the config.plist

While sharing the name, the config.plist in OpenCore, is very different from Clover config.plist, they cannot be mixed and matched. It is also not recommended to duplicate every patch and option from your clover config.

First, duplicate the sample.plist, rename it to config.plist and open in your .plist editor of choice.

The config contains a number of sections:

We can delete #WARNING -1 and #WARNING -2 You did heed the warning didn’t you?

1. ACPI

Add: Here you add your SSDTs or custom DSDT. (SSDT-EC.aml for example)

Block: Certain systems benefit from dropping some acpi tables, most modern desktops however require nothing in this section.

Patch: In OpenCore we should be keeping ACPI device renames to a minimum as they are often harmful and unnecessary. If your system absolutely needs something, you should add it in this section. Refer to configuration.pdf.

## Quirks:

Certain ACPI fixes. Avoid unless necessary.

​

2. Booter

NOTES:

Booter-Quirks (Boolean)

AvoidRuntimeDefrag: This option fixes UEFI runtime services (date, time, NVRAM, power control, etc.), Most but Apple and VMware firmwares need this quirk. maybe required for Z390 or other Boards with NVRAM Issues. Default=YES

DisableVariableWrite : This is a security option allowing one to restrict NVRAM access in macOS. This quirk requires OC_FIRMWARE_RUNTIME protocol implemented in FwRuntimeServices.efi. can also be used as an ugly workaround to buggy UEFI runtime services implementations that fail to write variables to NVRAM (Z390) and break the rest of the operating system. Default=NO

DiscardHibernateMap : This may be used to workaround buggy memory maps on older hardware, and is now considered rare legacy. Default=NO

EnableSafeModeSlide : The necessity of this quirk is determined by safe mode availability. If booting to safe mode fails, this option can be tried to be enabled. This option is relevant to the users that have issues booting to safe mode (e.g. by holding shift or using -x boot argument). By default safe mode forces 0 slide as if the system was launched with slide=0 boot argument. This quirk tries to patch boot.efi to lift that limitation and let some other value (from 1 to 255) be used. This quirk requires ProvideCustomSlide to be enabled. Default=YES

EnableWriteUnprotector : This option bypasses Rˆ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 FwRuntimeServices.efi. Default=YES

ForceExitBootServices : Try to ensure that ExitBootServices call succeeds even with outdated MemoryMap key argument, this quirk is determined by early boot crashes of the firmware. Default=NO

ProtectCsmRegion : The necessity of this quirk is determined by artifacts and sleep wake issues. As AvoidRuntimeDefrag resolves a similar problem, no known firmwares should need this quirk. Default=No

ProvideCustomSlide : Provide custom KASLR slide on low memory, this option forces macOS to use a pseudo random value among the available ones. This also ensures that slide= argument is never passed to the operating system for security reasons. Default=YES

SetupVirtualMap : The necessity of this quirk is determined by early boot failures, workarounds the problem by performing early boot identity mapping of assigned virtual addresses to physical memory. Default=YES

ShrinkMemoryMap : Select firmwares have very large memory maps, which do not fit Apple kernel, permitting up to 64 slots for runtime memory. This quirk attempts to unify contiguous slots of similar types to prevent boot failures. Default=NO

Fixing Certain NVRAM Issues

AvoidRuntimeDefrag : Set to YES for Enabled NVRAM Reading.

EnableWriteUnprotector : Set to YES for Enabled NVRAM Writing.

4. DeviceProperties

Add: Injects Device properties.

PciRoot(0x0)/Pci(0x2,0x0) -> AAPL,ig-platform-id

PciRoot(0x0)/Pci(0x1b,0x0) -> Layout-id

Block: Removes device properties from map. Normally not required.

5. Kernel

Add: Here we can specify kexts to inject from our EFI into the kernel kextcache. Order of kexts is important, they are loaded in this order. Plugins for other kexts should always come after the main kext. Lilu should be first, then Lilu plugins like WhateverGreen and VirtualSMC.

Emulate: Needed for spoofing CPU, for unsupported CPUs.

Block: Blocks kexts from loading. Sometimes needed for disabling Apple’s trackpad driver for some laptops.

Patch: Kext or kernel patches can be added here.

Quirks: (Boolean)

6. Misc

Boot

** You won’t be able to boot with Open Core Bootloader If you do not set YES at UsePicker. ** If you want to make macOS the default boot disk, set ‘System Preferences > Startup Disk > (Your preferred OS disk)’ as the default boot disk.

Clean Boot Without Text

UEFI/Protocols:

UEFI/Quirks:

Misc/Boot:

Debug

Further information will be added to this section soon.

Security

Scan Policy in (Bits)

ScanPolicy value, add the values with a hexidecimal calculator, macOS caluclator app has this built in with ⌘+3). Add your values up, and add this hexidecimal value to ScanPolicy, this will need converting to a decimal value which Xcode will automatically convert for you once you paste it.

0x00000001 - Known File Systems Only
0x00000002 - Known Device Types.
0x00000200 - HFS File System Scan
0x00000400 - Allow EFI Partition Scan
0x00010000 - Allow Sata Scan
0x00020000 - SAS Scan
0x00040000 - SCSI Scan
0x00080000 - NVMe Scan
0x00100000 - CD/DVD Scan
0x00200000 - USB Drive Scan
0x00400000 - FireWire Scan
0x00800000 - SD/Card Media Scan

Tools

Used for running boot time tools like clearing NVRAM, EFIShell or memtest86. Enable if required.

Entries

More Information coming soon.

7. NVRAM

Add

7C436110-AB2A-4BBB-A880-FE41995C9F82 (APPLE_BOOT_VARIABLE_GUID)

4D1EDE05-38C7-4A6A-9CC6-4BCCA8B38C14 (APPLE_VENDOR_VARIABLE_GUID)

Block: Forcibly rewrites NVRAM variables, not needed for us as sudo nvram is prefered but useful for those edge cases.

LegacyEnable: Allows for NVRAM to be stored on nvram.plist for systems without working NVRAM. (Example Z390).

LegacySchema: Used for assigning nvram variable on such systems. (This is written to the NVRAM.plist).

Emulated NVRAM

So this section is for those who don’t have native NVRAM, Hardware to have incompatible native NVRAM with macOS are the Z390-300 series chipsets:

Making the nvram.plist

Outlay’s to making a NVRAM.plist file, Requires the following:

Change these settings within the config.plist:

Booter Section

And within your EFI:

Now grab the ‘LogoutHook.command’ and place it somewhere safe like within your user directory:

/Users/(your username)/LogoutHook/LogoutHook.command

Open up terminal and run the following:

sudo defaults write com.apple.loginwindow LogoutHook /Users/(your username)/LogoutHook/LogoutHook.command

Now you have emulated NVRAM, Just to note that for macOS to support the -x flag and work correctly which is unavailable on 10.12 and below. nvram.mojave fixes this by injecting it instead of the system based one.

8. Platforminfo

Automatic: NO (setting YES will provide default values from the Generic section, which in some cases may be acceptable, also maybe required when booting a fresh install from createinstallmedia USB).

Output Example from above command:

iMac19,1 | C02YC2Y1JV3Q | C02909403CDLNV9A8
iMac19,1 | C02YX1Y9JV3Q | C02926401GULNV91H
iMac19,1 | C02YN07JJV3Q | C02918207J9LNV91M
iMac19,1 | C02YJKZTJV3Q | C029142004NLNV9A8
iMac19,1 | C02Y6QY5JV3Q | C02905100CDLNV9FB
iMac19,1 | C02Z4EY6JV3Q | C02930310GULNV98C
iMac19,1 | C02Y1VY1JV3Q | C02853130GULNV91M
iMac19,1 | C02ZL06PJV3Q | C029438024NLNV9JA
iMac19,1 | C02YX072JV3Q | C02926500CDLNV9CB
iMac19,1 | C02ZW3YFJV3Q | C02952301GULNV9UE

Generic:

DataHub: Fill all these fields to match your clover smbios.

PlatformNVRAM: Fill all these fields to match your clover smbios.

SMBIOS: Fill all these fields to match your clover smbios.

UpdateDataHub: YES (Update Data Hub fields)

UpdateNVRAM: YES (Update NVRAM fields)

UpdateSMBIOS: YES (Update SMBIOS fields)

UpdateSMBIOSMode: Create (Replace the tables with newly allocated EfiReservedMemoryType)

9. UEFI

Quirks:

AMD Zen Based CPU’s and Threadripper

Further Information regarding AMD CPU Booting with opencore and how to set various patches can be found here: AMD OSX Github

Time to boot with OpenCore!

AboutThisMac

Making Opencore your default Bootloader

When you are satisfied opencore boots your system correctly, simply mount your Clover efi partition, (back it up somewhere safe) and overwrite it with your OpenCore one. Certain system BIOS may require you to manually remove Clover as an EFI boot option (rarely some system might need a factory reset to permanently remove it).

Legacy Install

OpenCore supports DuetPkg which emulates a UEFI environment for legacy systems.

To start, you need the following:

Within your OpenCore build folder, navigate to Utilities/BootInstall. Here you’ll find a file called BootInstall.command. What this does is install DuetPkg to your desired drive.

Now you’ll want to run BootInstall.command, do note that you may need sudo for this to work correctly on newer versions of macOS

sudo Utilities/BootInstall/BootInstall.command

This will give you a list of available disks, choose yours and you will be prompted to write a new MBR. Choose yes[y] and you’ll be finished. This will provide you with an EFI partition with a boot file, this is where we’ll add our OpenCore EFI.

How to Enable a bootchime?

Credits

Developers of OpenCore: