Skip to content

Latest commit

 

History

History
458 lines (345 loc) · 23.9 KB

ktext.md

File metadata and controls

458 lines (345 loc) · 23.9 KB
Raw

Gathering files

This section is for gathering miscellaneous files for booting macOS, we do expect you to know your hardware well before starting and hopefully made a Hackintosh before as we won't be deep diving in here.

What's the best way to figure out if my hardware is supported?

See the Hardware Limitations page for some better insight into what macOS requires to boot, hardware support between Clover and OpenCore are quite similar.

What are some ways to figure out what hardware I have?

See the page before: Finding your hardware

[[toc]]

Firmware Drivers

Firmware drivers are drivers used by OpenCore in the UEFI environment. They're mainly required to boot a machine, either by extending OpenCore's patching ability or showing you different types of drives in the OpenCore picker(ie. HFS drives).

  • Location Note: These files must be placed under EFI/OC/Drivers/

Universal

::: tip Required Drivers

For the majority of systems, you'll only need 2 .efi drivers to get up and running:

  • HfsPlus.efi(Required)
    • Needed for seeing HFS volumes(ie. macOS Installers and Recovery partitions/images). Do not mix other HFS drivers
    • For Sandy Bridge and older(as well as low end Ivy Bridge(i3 and Celerons), see the legacy section below
  • OpenRuntime.efi(Required)
    • Replacement for AptioMemoryFix.efi, used as an extension for OpenCore to help with patching boot.efi for NVRAM fixes and better memory management.
    • Reminder this was bundled in OpenCorePkg we downloaded earlier

:::

Legacy users

In addition to the above, if your hardware doesn't support UEFI(2011 and older era) then you'll need the following. Pay close attention to each entry as you may not need all 4:

  • OpenUsbKbDxe.efi
  • HfsPlusLegacy.efi
    • Legacy variant of HfsPlus, used for systems that lack RDRAND instruction support. This is generally seen on Sandy Bridge and older(as well as low end Ivy Bridge(i3 and Celerons))
    • Don't mix this with HfsPlus.efi, choose one or the other depending on your hardware
  • OpenPartitionDxe
    • Required to boot recovery on OS X 10.7 through 10.9
      • This file is bundled with OpenCorePkg under EFI/OC/Drivers
      • Note: OpenDuet users(ie. without UEFI) will have this driver built-in, not requiring it
    • Not required for OS X 10.10, Yosemite and newer

These files will go in your Drivers folder in your EFI

::: details 32-Bit specifics

For those with 32-Bit CPUs, you'll want to grab these drivers as well

  • HfsPlus32
    • Alternative to HfsPlusLegacy but for 32-bit CPUs, don't mix this with other HFS .efi drivers

:::

Kexts

A kext is a kernel extension, you can think of this as a driver for macOS, these files will go into the Kexts folder in your EFI.

  • Windows and Linux note: Kexts will look like normal folders in your OS, double check that the folder you are installing has a .kext extension visible(and do not add one manually if it's missing).
    • If any kext also includes a .dSYM file, you can simply delete it. They're only for debugging purposes.
  • Location Note: These files must be placed under EFI/OC/Kexts/.

All kext listed below can be found pre-compiled in the Kext Repo. Kexts here are compiled each time there's a new commit.

Must haves

::: tip Required Kexts

Without the below 2, no system is bootable:

  • VirtualSMC(Required)
    • Emulates the SMC chip found on real macs, without this macOS will not boot
    • Alternative is FakeSMC which can have better or worse support, most commonly used on legacy hardware.
    • Requires OS X 10.6 or newer
  • Lilu(Required)
    • A kext to patch many processes, required for AppleALC, WhateverGreen, VirtualSMC and many other kexts. Without Lilu, they will not work.
    • Note that Lilu and plugins requires OS X 10.8 or newer to function

::: details Legacy "Must haves" kexts

For those planning to boot OS X 10.7 and older on 32 bit hardware, you'll want to use the below instead of VirtualSMC:

Reminder if you don't plan to boot these older OSes, you can ignore this kext.

  • OS X 10.4 and 10.5 note: Even on 64-bit CPUs, OS X's kernel space is still 32-bit. So we recommend using FakeSMC-32 in tandem with VirtualSMC, specifically by setting FakeSMC-32's Arch entry to i386 and VirtualSMC's to x86_64. This is discussed further on in the guide.

:::

VirtualSMC Plugins

The below plugins are not required to boot, and merely add extra functionality to the system like hardware monitoring(Note while VirtualSMC supports 10.6, plugins may require 10.8+):

  • SMCProcessor.kext
    • Used for monitoring CPU temperature, doesn't work on AMD CPU based systems
  • SMCSuperIO.kext
    • Used for monitoring fan speed, doesn't work on AMD CPU based systems
  • SMCLightSensor.kext
    • Used for the ambient light sensor on laptops, desktops can ignore
    • Do not use if you don't have an ambient light sensor, can cause issues otherwise
  • SMCBatteryManager.kext
    • Used for measuring battery readouts on laptops, desktops can ignore
  • SMCDellSensors.kext
    • Allows for finer monitoring and control of the fans on Dell machines supporting System Management Mode(SMM)
    • Do not use if you do not have a supported Dell machine, mainly Dell laptops can benefit from this kext

Graphics

  • WhateverGreen(Required)
    • Used for graphics patching, DRM fixes, board ID checks, framebuffer fixes, etc; all GPUs benefit from this kext.
    • Note the SSDT-PNLF.dsl file included is only required for laptops and AIOs, see Getting started with ACPI for more info
    • Requires OS X 10.8 or newer

Audio

  • AppleALC
    • Used for AppleHDA patching, allowing support for the majority of on-board sound controllers
    • AMD 15h/16h may have issues with this and Ryzen/Threadripper systems rarely have mic support
    • Requires OS X 10.8 or newer

::: details Legacy Audio Kext

For those who plan to boot 10.7 and older may want to opt for these kexts instead:

  • VoodooHDA

    • Requires OS X 10.6 or newer

  • VoodooHDA-FAT

    • Similar to the above, however supports 32 and 64-Bit kernels so perfect for OS X 10.4-5 booting and 32-Bit CPUs

:::

Ethernet

Here we're going to assume you know what ethernet card your system has, reminder that product spec pages will most likely list the type of network card.

  • IntelMausi
    • Required for the majority of Intel NICs, chipsets that are based off of I211 will need the SmallTreeIntel82576 kext
    • Intel's 82578, 82579, I217, I218 and I219 NICs are officially supported
    • Requires OS X 10.9 or newer, 10.6-10.8 users can use the IntelSnowMausi instead for older OSes
  • SmallTreeIntel82576 kext
    • Required for I211 NICs, based off of the SmallTree kext but patched to support I211
    • Required for most AMD boards running Intel NICs
    • Requires OS X 10.9-12(v1.0.6), macOS 10.13-14(v1.2.5), macOS 10.15+(v1.3.0)
  • AtherosE2200Ethernet
    • Required for Atheros and Killer NICs
    • Requires OS X 10.8 or newer
    • Note: Atheros Killer E2500 models are actually Realtek based, for these systems please use RealtekRTL8111 instead
  • RealtekRTL8111
    • For Realtek's Gigabit Ethernet
    • Requires OS X 10.8 and up for versions v2.2.0 and below, macOS 10.12 and up for versions v2.2.2 through v2.3.0 (inclusive), macOS 10.14 and up for versions v2.4.0 and up
    • NOTE: Sometimes the latest version of the kext might not work properly with your Ethernet. If you see this issue, try older versions.
  • LucyRTL8125Ethernet
    • For Realtek's 2.5Gb Ethernet
    • Requires macOS 10.15 or newer
  • For Intel's I225-V NICs, patches are mentioned in the desktop Comet Lake DeviceProperties section. No kext is required.
    • Requires macOS 10.15 or newer
  • For Intel's I350 NICs, patches are mentioned in the HEDT Sandy and Ivy Bridge-E DeviceProperties section. No kext is required.
    • Requires OS X 10.10 or newer

::: details Legacy Ethernet Kexts

Relevant for either legacy macOS installs or older PC hardware.

  • AppleIntele1000e
    • Mainly relevant for 10/100MBe based Intel Ethernet controllers
    • Requires 10.6 or newer
  • RealtekRTL8100
    • Mainly relevant for 10/100MBe based Realtek Ethernet controllers
    • Requires macOS 10.12 or newer with v2.0.0+
  • BCM5722D
    • Mainly relevant for BCM5722 based Broadcom Ethernet controllers
    • Requires OS X 10.6 or newer

:::

And also keep in mind certain NICs are actually natively supported in macOS:

::: details Native Ethernet Controllers

Aquantia Series

# AppleEthernetAquantiaAqtion.kext
pci1d6a,1    = Aquantia AQC107
pci1d6a,d107 = Aquantia AQC107
pci1d6a,7b1  = Aquantia AQC107
pci1d6a,80b1 = Aquantia AQC107
pci1d6a,87b1 = Aquantia AQC107
pci1d6a,88b1 = Aquantia AQC107
pci1d6a,89b1 = Aquantia AQC107
pci1d6a,91b1 = Aquantia AQC107
pci1d6a,92b1 = Aquantia AQC107
pci1d6a,c0   = Aquantia AQC113
pci1d6a,4c0  = Aquantia AQC113

Note: Due to some outdated firmware shipped on many Aquantia NICs, you may need to update the firmware in Linux/Windows to ensure it's macOS-compatible.

Intel Series

# AppleIntel8254XEthernet.kext
pci8086,1096 = Intel 80003ES2LAN
pci8086,100f = Intel 82545EM
pci8086,105e = Intel 82571EB/82571GB

# AppleIntelI210Ethernet.kext
pci8086,1533 = Intel I210
pci8086,15f2 = Intel I225LM (Added in macOS 10.15)

# Intel82574L.kext
pci8086,104b = Intel 82566DC
pci8086,10f6 = Intel 82574L

Broadcom Series

# AppleBCM5701Ethernet.kext
pci14e4,1684 = Broadcom BCM5764M
pci14e4,16b0 = Broadcom BCM57761
pci14e4,16b4 = Broadcom BCM57765
pci14e4,1682 = Broadcom BCM57762
pci14e4,1686 = Broadcom BCM57766

:::

USB

  • USBInjectAll

    • Used for injecting Intel USB controllers on systems without defined USB ports in ACPI
    • Shouldn't be needed on Desktop Skylake and newer
      • AsRock is dumb and does need this
      • Coffee Lake and older laptops are however recommended to use this kext
    • Does not work on AMD CPUs at all
    • Requires OS X 10.11 or newer

  • XHCI-unsupported

    • Needed for non-native USB controllers
    • AMD CPU based systems don't need this
    • Common chipsets needing this:
      • H370
      • B360
      • H310
      • Z390(Not needed on Mojave and newer)
      • X79
      • X99
      • AsRock boards(On Intel motherboards specifically, B460/Z490+ boards do not need it however)

WiFi and Bluetooth

Intel

  • AirportItlwm
    • Adds support for a large variety of Intel wireless cards and works natively in recovery thanks to IO80211Family integration
    • Requires macOS 10.13 or newer and requires Apple's Secure Boot to function correctly
  • IntelBluetoothFirmware
    • Adds Bluetooth support to macOS when paired with an Intel wireless card
    • Requires macOS 10.13 or newer

::: details More info on enabling AirportItlwm

To enable AirportItlwm support with OpenCore, you'll need to either:

  • Enable Misc -> Security -> SecureBootModel by either setting it as Default or some other valid value
    • This is discussed both later on in this guide and in the post-install guide: Apple Secure Boot
  • If you cannot enable SecureBootModel, you can still force inject IO80211Family(Highly discouraged)
    • Set the following under Kernel -> Force in your config.plist(discussed later in this guide):

:::

Broadcom

  • AirportBrcmFixup
    • Used for patching non-Apple/non-Fenvi Broadcom cards, will not work on Intel, Killer, Realtek, etc
    • Requires OS X 10.10 or newer
    • For Big Sur see Big Sur Known Issues for extra steps regarding AirPortBrcm4360 drivers.
  • BrcmPatchRAM
    • Used for uploading firmware on Broadcom Bluetooth chipset, required for all non-Apple/non-Fenvi Airport cards.
    • To be paired with BrcmFirmwareData.kext
      • BrcmPatchRAM3 for 10.15+ (must be paired with BrcmBluetoothInjector)
      • BrcmPatchRAM2 for 10.11-10.14
      • BrcmPatchRAM for 10.8-10.10

::: details BrcmPatchRAM Load order

The order in Kernel -> Add should be:

  1. BrcmBluetoothInjector
  2. BrcmFirmwareData
  3. BrcmPatchRAM3

However ProperTree will handle this for you, so you need not concern yourself

:::

AMD CPU Specific kexts

  • XLNCUSBFIX
    • USB fix for AMD FX systems, not recommended for Ryzen
    • Requires macOS 10.13 or newer
  • VoodooHDA
    • Audio for FX systems and front panel Mic+Audio support for Ryzen system, do not mix with AppleALC. Audio quality is noticeably worse than AppleALC on Zen CPUs
    • Requires OS X 10.6 or newer

Extras

  • AppleMCEReporterDisabler
    • Useful starting with Catalina to disable the AppleMCEReporter kext which will cause kernel panics on AMD CPUs and dual-socket systems
    • Affected SMBIOS:
      • MacPro6,1
      • MacPro7,1
      • iMacPro1,1
    • Requires macOS 10.15 or newer
  • CpuTscSync
    • Needed for syncing TSC on some of Intel's HEDT and server motherboards, without this macOS may be extremely slow or even unbootable.
    • Does not work on AMD CPUs
    • Requires OS X 10.8 or newer
  • NVMeFix
    • Used for fixing power management and initialization on non-Apple NVMe
    • Requires macOS 10.14 or newer
  • SATA-Unsupported
    • Adds support for a large variety of SATA controllers, mainly relevant for laptops which have issues seeing the SATA drive in macOS. We recommend testing without this first.
    • macOS Big Sur Note: CtlnaAHCIPort will need to be used instead due to numerous controllers being dropped from the binary itself
      • Catalina and older need not concern

::: details Legacy SATA Kexts

  • AHCIPortInjector
    • Legacy SATA/AHCI injector, mainly relevant for older machines of the Penryn era
  • ATAPortInjector
    • Legacy ATA injector, mainly relevant for IDE and ATA devices(ie. when no AHCI option is present in the BIOS)

:::

Laptop Specifics

To figure out what kind of keyboard and trackpad you have, check Device Manager in Windows or dmesg | grep -i input in Linux

Input drivers

  • VoodooPS2
    • For systems with PS2 keyboards, mice, and trackpads
    • Requires macOS 10.11 or newer for MT2 (Magic Trackpad 2) functions
  • RehabMan's VoodooPS2
    • For older systems with PS2 keyboards, mice, and trackpads, or when you don't want to use VoodooInput
    • Supports macOS 10.6+ support
  • VoodooRMI
    • For systems with Synaptics SMBus-based devices, mainly for trackpads and trackpoints.
    • Requires macOS 10.11 or newer for MT2 functions
  • VoodooSMBus
    • For systems with ELAN SMBus-based devices, mainly for trackpads and trackpoints.
    • Supports macOS 10.14 or newer currently
  • VoodooI2C
    • Used for fixing I2C devices, found with some fancier touchpads and touchscreen machines
    • Requires macOS 10.11 or newer for MT2 functions ::: details VoodooI2C Plugins | Connection type | Plugin | Notes | | :--- | :--- | :--- | | Microsoft HID | VoodooI2CHID | Can be used to support some USB touchscreens as well | | ELAN Proprietary | VoodooI2CElan | ELAN1200+ require VoodooI2CHID instead | | Synaptics Proprietary | VoodooI2CSynaptics | Synaptics F12 protocol require VoodooI2CHID instead | | ^^ | VoodooRMI | Supports Synaptics protocols F12/F3A - These generally support Microsoft's HID standard so you should attempt using VoodooI2CHID first | | FTE1001 touchpad | VoodooI2CFTE | | | Atmel Multitouch Protocol | VoodooI2CAtmelMXT | | :::

Misc

  • ECEnabler
    • Fixes reading battery status on many devices (Allows reading EC fields over 8 bits long)
  • BrightnessKeys
    • Fixes brightness keys automatically

Please refer to Kexts.md for a full list of supported kexts

SSDTs

So you see all those SSDTs in the AcpiSamples folder and wonder whether you need any of them. For us, we will be going over what SSDTs you need in your specific ACPI section of the config.plist, as the SSDTs you need are platform specific. With some even system specific where they need to be configured and you can easily get lost if I give you a list of SSDTs to choose from now.

Getting started with ACPI has an extended section on SSDTs including compiling them on different platforms.

A quick TL;DR of needed SSDTs(This is source code, you will have to compile them into a .aml file):

Desktop

Platforms CPU EC AWAC NVRAM USB
Penryn N/A SSDT-EC N/A N/A N/A
Lynnfield and Clarkdale ^^ ^^ ^^ ^^ ^^
SandyBridge CPU-PM (Run in Post-Install) ^^ ^^ ^^ ^^
Ivy Bridge ^^ ^^ ^^ ^^ ^^
Haswell SSDT-PLUG ^^ ^^ ^^ ^^
Broadwell ^^ ^^ ^^ ^^ ^^
Skylake ^^ SSDT-EC-USBX ^^ ^^ ^^
Kaby Lake ^^ ^^ ^^ ^^ ^^
Coffee Lake ^^ ^^ SSDT-AWAC SSDT-PMC ^^
Comet Lake ^^ ^^ ^^ N/A SSDT-RHUB
AMD (15/16h) N/A ^^ N/A ^^ N/A
AMD (17/19h) SSDT-CPUR for B550 and A520 ^^ ^^ ^^ ^^

High End Desktop

Platforms CPU EC RTC PCI
Nehalem and Westmere N/A SSDT-EC N/A N/A
Sandy Bridge-E ^^ ^^ ^^ SSDT-UNC
Ivy Bridge-E ^^ ^^ ^^ ^^
Haswell-E SSDT-PLUG SSDT-EC-USBX SSDT-RTC0-RANGE ^^
Broadwell-E ^^ ^^ ^^ ^^
Skylake-X ^^ ^^ ^^ N/A

Laptop

Platforms CPU EC Backlight I2C Trackpad AWAC USB IRQ
Clarksfield and Arrandale N/A SSDT-EC SSDT-PNLF N/A N/A N/A IRQ SSDT
SandyBridge CPU-PM (Run in Post-Install) ^^ ^^ ^^ ^^ ^^ ^^
Ivy Bridge ^^ ^^ ^^ ^^ ^^ ^^ ^^
Haswell SSDT-PLUG ^^ ^^ SSDT-GPI0 ^^ ^^ ^^
Broadwell ^^ ^^ ^^ ^^ ^^ ^^ ^^
Skylake ^^ SSDT-EC-USBX ^^ ^^ ^^ ^^ N/A
Kaby Lake ^^ ^^ ^^ ^^ ^^ ^^ ^^
Coffee Lake (8th Gen) and Whiskey Lake ^^ ^^ SSDT-PNLF-CFL ^^ SSDT-AWAC ^^ ^^
Coffee Lake (9th Gen) ^^ ^^ ^^ ^^ ^^ ^^ ^^
Comet Lake ^^ ^^ ^^ ^^ ^^ ^^ ^^
Ice Lake ^^ ^^ ^^ ^^ ^^ SSDT-RHUB ^^

Continuing:

Platforms NVRAM IMEI
Clarksfield and Arrandale N/A N/A
Sandy Bridge ^^ SSDT-IMEI
Ivy Bridge ^^ ^^
Haswell ^^ N/A
Broadwell ^^ ^^
Skylake ^^ ^^
Kaby Lake ^^ ^^
Coffee Lake (8th Gen) and Whiskey Lake ^^ ^^
Coffee Lake (9th Gen) SSDT-PMC ^^
Comet Lake N/A ^^
Ice Lake ^^ ^^

Now with all this done, head to Getting Started With ACPI