diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index cf4902afe..e9459978b 100755 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -99,6 +99,8 @@ module.exports = { 'DEBUG', 'UNINSTALL', 'ICNS', + 'TERMS', + 'PATCH-EXPLAIN', ] }, diff --git a/docs/MODELS.md b/docs/MODELS.md index ae2b23689..ccdd2c5e3 100644 --- a/docs/MODELS.md +++ b/docs/MODELS.md @@ -26,9 +26,9 @@ Note: In this patcher, Brightness Control is tied to GPU acceleration | MacBook2,1 | Late 2006 | ^^ | 32-Bit Firmware limitation | | MacBook3,1 | Late 2007 | ^^ | ^^ | | MacBook4,1 | Early 2008 | ^^ | ^^ | -| MacBook5,1 | Late 2008 | YES | - No GPU Acceleration in Big Sur
- No AppleHDA(Audio) Patching implemented
| +| MacBook5,1 | Late 2008 | YES | - No GPU Acceleration in Big Sur
- No AppleHDA(Audio) Patching implemented([#76](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/76))
| | MacBook5,2 | Early 2009 | ^^ | ^^ | -| MacBook6,1 | Late 2009 | ^^ | - No GPU Acceleration in Big Sur
- No AppleHDA(Audio) Patching implemented
| +| MacBook6,1 | Late 2009 | ^^ | - No GPU Acceleration in Big Sur
- No AppleHDA(Audio) Patching implemented([#76](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/76))
| | MacBook7,1 | Mid-2010 | ^^ | ^^ | ### MacBook Air @@ -36,8 +36,8 @@ Note: In this patcher, Brightness Control is tied to GPU acceleration | SMBIOS | Year | Supported | Comment | | :--- | :--- | :--- | :--- | | MacBookAir1,1 | Early 2008 | NO | Requires SSE4.1 CPU | -| MacBookAir2,1 | Late 2008 | YES | - No GPU Acceleration in Big Sur
- No AppleHDA(Audio) Patching implemented
- No Wifi Patches implemented | -| MacBookAir3,1 | Late 2010 | ^^ | - No GPU Acceleration in Big Sur
- No AppleHDA(Audio) Patching implemented | +| MacBookAir2,1 | Late 2008 | YES | - No GPU Acceleration in Big Sur
- No AppleHDA(Audio) Patching implemented([#76](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/76))
- No Wifi Patches implemented([#102](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/102)) | +| MacBookAir3,1 | Late 2010 | ^^ | - No GPU Acceleration in Big Sur
- No AppleHDA(Audio) Patching implemented([#76](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/76)) | | MacBookAir3,2 | ^^ | ^^ | ^^ | | MacBookAir4,1 | Mid-2011 | ^^ | ^^ | | MacBookAir4,2 | ^^ | ^^ | ^^ | @@ -53,16 +53,16 @@ Note: In this patcher, Brightness Control is tied to GPU acceleration | MacBookPro2,1 | Late 2006 | ^^ | 32-Bit Firmware limitation | | MacBookPro2,2 | Late 2006 | ^^ | ^^ | | MacBookPro3,1 | Mid-2007 | ^^ | - Requires SSE4.1 CPU | -| MacBookPro4,1 | Early 2008 | YES | - No GPU Acceleration in Big Sur
- No AppleHDA(Audio) Patching implemented
- No Wifi Patches implemented | -| MacBookPro5,1 | Late 2008 | ^^ | - No GPU Acceleration in Big Sur
- No AppleHDA(Audio) Patching implemented | +| MacBookPro4,1 | Early 2008 | YES | - No GPU Acceleration in Big Sur
- No AppleHDA(Audio) Patching implemented([#76](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/76))
- No Wifi Patches implemented([#102](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/102)) | +| MacBookPro5,1 | Late 2008 | ^^ | - No GPU Acceleration in Big Sur
- No AppleHDA(Audio) Patching implemented([#76](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/76)) | | MacBookPro5,2 | Early 2009 | ^^ | ^^ | | MacBookPro5,3 | Mid-2009 | ^^ | ^^ | | MacBookPro5,4 | ^^ | ^^ | ^^ | | MacBookPro5,5 | ^^ | ^^ | ^^ | | MacBookPro6,1 | Mid-2010 | ^^ | ^^ | | MacBookPro6,2 | ^^ | ^^ | ^^ | -| MacBookPro7,1 | ^^ | ^^ | - No GPU Acceleration in Big Sur
- No AppleHDA(Audio) Patching implemented
- Ethernet issues | -| MacBookPro8,1 | Early 2011 | ^^ | - No GPU Acceleration in Big Sur
- No AppleHDA(Audio) Patching implemented
- Ethernet Connection Issues | +| MacBookPro7,1 | ^^ | ^^ | - No GPU Acceleration in Big Sur
- No AppleHDA(Audio) Patching implemented([#76](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/76))
- Ethernet Connection Issues([#45](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/45)) | +| MacBookPro8,1 | Early 2011 | ^^ | ^^ | | MacBookPro8,2 | ^^ | ^^ | ^^ | | MacBookPro8,3 | ^^ | ^^ | ^^ | | MacBookPro9,1 | Mid-2012 | ^^ | Everything is supported | @@ -76,9 +76,9 @@ Note: In this patcher, Brightness Control is tied to GPU acceleration | :--- | :--- | :--- | :--- | | Macmini1,1 | Early 2006 | NO | 32-Bit CPU limitation | | Macmini2,1 | Mid-2007 | ^^ | 32-Bit Firmware limitation | -| Macmini3,1 | Early 2009 | YES | - No GPU Acceleration in Big Sur
- No AppleHDA(Audio) Patching implemented | +| Macmini3,1 | Early 2009 | YES | - No GPU Acceleration in Big Sur
- No AppleHDA(Audio) Patching implemented([#76](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/76)) | | Macmini4,1 | Mid-2010 | ^^ | ^^ | -| Macmini5,1 | Mid-2011 | ^^ | - No GPU Acceleration in Big Sur
- No AppleHDA(Audio) Patching implemented
- Ethernet Connection Issues | +| Macmini5,1 | Mid-2011 | ^^ | - No GPU Acceleration in Big Sur
- No AppleHDA(Audio) Patching implemented([#76](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/76))
- Ethernet Connection Issues([#45](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/45)) | | Macmini5,2 | ^^ | ^^ | ^^ | | Macmini5,3 | ^^ | ^^ | ^^ | | Macmini6,1 | Late 2012 | ^^ | Everything is supported | @@ -93,11 +93,11 @@ Note: In this patcher, Brightness Control is tied to GPU acceleration | iMac5,1 | Late 2006 | ^^ | 32-Bit Firmware limitation | | iMac5,2 | ^^ | ^^ | ^^ | | iMac6,1 | ^^ | ^^ | ^^ | -| iMac7,1 | Mid-2007 | YES | - Requires an SSE4.1 CPU Upgrade
- No GPU Acceleration in Big Sur
- No AppleHDA(Audio) Patching implemented
| -| iMac8,1 | Early 2008 | ^^ | - No GPU Acceleration in Big Sur
- No AppleHDA(Audio) Patching implemented
| -| iMac9,1 | Early 2009 | ^^ | ^^ | -| iMac10,1 | Late 2009 | ^^ | - No GPU Acceleration in Big Sur
- No AppleHDA(Audio) Patching implemented | -| iMac11,1 | ^^ | ^^ | - No GPU Acceleration in Big Sur
- No AppleHDA(Audio) Patching implemented
- Ethernet Connection Issues | +| iMac7,1 | Mid-2007 | YES | - Requires an SSE4.1 CPU Upgrade
- No GPU Acceleration in Big Sur
- No AppleHDA(Audio) Patching implemented([#76](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/76))
| +| iMac8,1 | Early 2008 | ^^ | - No GPU Acceleration in Big Sur
- No AppleHDA(Audio) Patching implemented([#76](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/76))
- No Wifi Patches implemented([#102](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/102)) | +| iMac9,1 | Early 2009 | ^^ | - No GPU Acceleration in Big Sur
- No AppleHDA(Audio) Patching implemented([#76](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/76))
| +| iMac10,1 | Late 2009 | ^^ | ^^ | +| iMac11,1 | ^^ | ^^ | - No GPU Acceleration in Big Sur
- No AppleHDA(Audio) Patching implemented([#76](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/76))
- Ethernet Connection Issues([#45](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/45)) | | iMac11,2 | Mid-2010 | ^^ | ^^ | | iMac11,3 | ^^ | ^^ | ^^ | | iMac12,1 | Mid-2011 | ^^ | ^^ | @@ -114,7 +114,7 @@ Note: In this patcher, Brightness Control is tied to GPU acceleration | :--- | :--- | :--- | :--- | | MacPro1,1 | Mid-2006 | NO | 32-Bit Firmware limitation | | MacPro2,1 | Mid-2007 | ^^ | ^^ | -| MacPro3,1 | Early 2008 | YES | - Requires an SSE4.1 CPU Upgrade
- No AppleHDA(Audio) Patching implemented | +| MacPro3,1 | Early 2008 | YES | - Requires an SSE4.1 CPU Upgrade
- No AppleHDA(Audio) Patching implemented([#76](https://github.com/dortania/OpenCore-Legacy-Patcher/issues/76)) | | MacPro4,1 | Early 2009 | ^^ | Everything is supported as long as GPU is Metal capable | | MacPro5,1 | Mid-2010, Mid-2012 | ^^ | ^^ | diff --git a/docs/PATCH-EXPLAIN.md b/docs/PATCH-EXPLAIN.md new file mode 100644 index 000000000..a108e41fb --- /dev/null +++ b/docs/PATCH-EXPLAIN.md @@ -0,0 +1,175 @@ +# Explaining the patches in OpenCore Legacy Patcher + +In our patcher, there are numerous patches used to ensure a stable system. Here we're going to go over what patches are used and why we recommend or even require them. + +## OpenCore Settings + +### ACPI -> Patch + +* EHCx and XHC1 Patches + * Reason: Required for proper USB operation + * Logic: Avoids USB maps of newer models attaching and breaking USB port functionality + * Models: All models require + +### Booter -> Quirks + +* ForceBooterSignature + * Reason: Required to ensure Hibernation support + * Logic: Tricks boot.efi into thinking OpenCore is Apple's firmware + * Models: All models require + +### DeviceProperties -> Add + +* `PciRoot(0x0)/Pci(0x15,0x0)/Pci(0x0,0x0)` +* `PciRoot(0x0)/Pci(0x1C,0x4)/Pci(0x0,0x0)` +* `PciRoot(0x0)/Pci(0x1C,0x3)/Pci(0x0,0x0)` +* `PciRoot(0x0)/Pci(0x1C,0x5)/Pci(0x0,0x0)` +* `PciRoot(0x0)/Pci(0x1C,0x1)/Pci(0x0,0x0)` + * Reason: Required to ensure Wifi works with full, native support + * Logic: Tricks AirPortBrcmNIC.kext into thinking our device is a BCM94360 (`14e4,43ba`) + * Models: [Machines with BCM943224 and BCM94331 chipsets](https://github.com/dortania/OpenCore-Legacy-Patcher/blob/79ab028b0a039e97a528e0b99c876d95d9c2d41d/Resources/ModelArray.py#L199-L225) +* `PciRoot(0x0)/Pci(0x3,0x0)/Pci(0x0,0x0)` +* `PciRoot(0x0)/Pci(0x1,0x0)/Pci(0x0,0x0)` + * Reason: Required to ensure Brightness Control works on upgraded iMacs + * Logic: Sets AppleBackLight properties + * Models: iMac11,x and iMac12,x with upgraded Nvidia Metal GPUs +* `PciRoot(0x0)/Pci(0x2,0x0)` + * Reason: Disables internal GPU to fix sleep issues on upgrades iMacs + * Logic: Tricks macOS into thinking iGPU is a generic PCI device + * Models: iMac12,x with upgraded Metal GPUs + +### Kernel -> Patch + +* SMC Patch + * Reason: Required to avoid SMC Firmware updates + * Logic: Patches out `smc-version` in AppleSMC.kext, requires SMC-Spoof.kext for full functionality + * Models: All models require +* IOHIDFamily Patch + * Reason: Required for HID peripheral support in macOS on older hardware + * Logic: Tricks IOHIDFamily into thinking it's always booting recovery + * Models: [2010 and older](https://github.com/dortania/OpenCore-Legacy-Patcher/blob/79ab028b0a039e97a528e0b99c876d95d9c2d41d/Resources/ModelArray.py#L310-L332) + +### Kernel -> Quirks + +* ThridPartyDrives + * Reason: Required to avoid Hibernation wake issues on 3rd party drives + * Logic: Patches AppleAHCIPort.kext into support + * Models: All models with standard SATA ports +* PanicNoKextDump + * Reason: Avoids kext dump on kernel panics, easier kernel debugging + * Logic: Patches Kernel to not dump dump unnecessary info + * Models: Only set when Verbose Boot is enabled by the user + +### Misc -> Security + +* SecureBootModel + * Reason: Required to ensure seamless OS updates with Big Sur + * Logic: Sets iMacPro1,1's Secure Enclave Identifier (j137) + * Models: All models require + +### NVRAM -> Add + +* `-v debug=0x100` + * Reason: Used to see debug info of macOS's kernel and kexts, and avoids reboots on panic + * Logic: Adds args to NVRAM + * Models: Only set when Verbose Boot is enabled by the user +* `-liludbgall` + * Reason: Enables Lilu and plugin debug logging + * Logic: Adds args to NVRAM + * Models: Only set when Kext DEBUG is enabled by the user +* `msgbuf=1048576` + * Reason: Sets message buffer size to 1MB, ensures boot logs are retained + * Logic: Adds args to NVRAM + * Models: Only set when Kext DEBUG is enabled by the user +* `agdpmod=pikera` + * Reason: Fixes GPU switching on MacBookPro9,x + * Logic: Adds args to NVRAM + * Models: MacBookPro9,x +* `shikigva=80 unfairgva=1` +* `shikigva=128 unfairgva=1 -wegtree` + * Reason: Fixes DRM support on models with upgraded AMD Metal GPUs + * Logic: Adds args to NVRAM + * Models: Models with upgraded AMD Metal GPUs +### UEFI -> ProtocolOverrides + +* GopPassThrough + * Reason: Used for proper output on machines with UGA firmware but GOP GPU + * Logic: Provide GOP protocol instances on top of UGA protocol instances + * Models: MacPro3,1 + +## Injected Kext + +### Acidanthera + +* Lilu + * Reason: Patching engine for other kexts + * Models: All models require +* WhateverGreen + * Reason: Patches GPU Frameworks and kext to ensure proper support + * Models: All models require +* CPUFriend + * Reason: Patches IOx86PlatformPlugin to restore previous CPU profiles + * Models: 2012 and newer models +* AirportBrcmFixup + * Reason: Patches IO80211 and co to fix networking support for unsupported cards + * Models: BCM943224 and BCM94331 +* RestrictEvents + * Reason: Disables memory errors on MacPro7,1 + * Models: Mac Pros and Xserves + +### Audio + +* VoodooHDA + * Reason: Attempts to add audio support for pre-2012 hardware + * Models: 2011 and older +### Ethernet + +* nForceEthernet +* MarvelYukonEthernet +* CatalinaBCM5701Ethernet + +### Maps + +* USBMap + * Reason: Inject old USB map profiles to fix USB + * Models: All models require + +### SSE + +* AAMouSSE + * Reason: Translates SSE4.2 instructions to compatible code for SSE4,1 CPUs, required for AMD Metal drives + * Models: MacPro3,1 +* telemetrap + * Reason: Ensures temelemtry.plugin doesn't run, required for SSE4,1 CPUs + * Models: Penryn CPUs + +### Wifi + +* IO80211HighSierra + * Reason: Re-inject Atheros wifi drivers from High Sierra + * Models: Atheros cards +* IO80211Mojave + * Reason: Re-inject Broadcom wifi drivers from Mojave + * Models: BCm94322 + +### Misc + +* AppleBackLightFixup + * Reason: Patch AppleBacklight for iMacs with Nvidia Metal GPU upgrades + * Models: iMac11,x, iMac12,x with upgraded Nvidia Metal GPUs +* AppleIntelPIIXATA + * Reason: Fix IDE support on MacPro3,1 + * Models: MacPro3,1 +* AppleIntelMCEDisabler + * Reason: Fix dual socket support in Catalina and newer + * Models: Mac Pros and Xserves +* NightShiftEnabler + * Reason: Enables NightShift support on unsupported models + * Models: 2011 and older, MacBookPro9,x included +* SMC-Spoof + * Reason: Spoofs SMC version to 9.9999 + * Models: All models require + + + + diff --git a/docs/TERMS.md b/docs/TERMS.md new file mode 100644 index 000000000..52182d243 --- /dev/null +++ b/docs/TERMS.md @@ -0,0 +1,28 @@ +# OpenCore Patcher Terminology + +With OpenCore Legacy Patcher, we use a lot of different terms to refer to hardware including `SSE4.1`, `32-Bit Firmware`, etc. This page is to help users understand what all these confusing words mean. + +# Terminology + +Term | Description +--- | --- +**macOS** | Apple's own UNIX based OS used for Mac machines and "What makes a Mac a Mac". +**Windows** | Microsoft's proprietary OS that is used and supported on a wide range of devices (stay with this OS if you don't want headaches) +**Linux** | Family of open source Unix-like operating systems based on the Linux kernel, an operating system kernel first released on September 17, 1991, by Linus Torvalds. Linux is typically packaged in a Linux distribution. Note that while macOS and Linux may be UNIX-based, they're vastly different. +**Bootloader** | Piece of software that loads an OS, usually made by the OS creators. OpenCore is technically not a bootloader per se (see boot manager explanation down below). Apple's Boot.efi would be the actual boot loader in a Mac. +**Boot Manager** | Piece of software that manages bootloaders – we have many of these: Clover, systemd-boot, OpenCore, rEFInd, rEFIt... These are generally seen as prepping the system for the actual boot loader. +--- +Term | Description +--- | --- +**OpenCore** | The new hotness on the scene, made with security in mind by the [Acidanthera team](https://github.com/acidanthera), has faster booting and lighter weight than previous boot managers. Supports many native Mac features such as SIP, FileVault, Secure Boot, etc +**XNU** | Also known as **X** is **N**ot **U**nix, XNU is referred to as macOS's "kernel" and the heart of what makes macOS tick +**Kexts** | Also known as **K**ernel **Ext**ensions, are macOS's drivers. They're used to perform different tasks like device drivers or for a different purpose (in this patcher) like patching the OS, injecting information or running tasks. +**KernelCollection** | Also known as the ImmutableKernel and PrelinkedKernel, this is a bundle of the kernel(XNU) and kernel extensions(Kexts) that we use to boot macOS. This is also what OpenCore patches in memory to allow us to have a seamless experience
- PrelinkedKernel: Default caching system since 10.7
- ImmutableKernel: Secure Boot based caching system since 10.13
- KernelCollection: Merge of both Prelinked and ImmutableKernel's since macOS 11, Big Sur +--- +Term | Description +--- | --- +**EFI** | It can denote two things:
- Mac's firmware, which is the same as UEFI, but pretty modified for Macs only, so not so "Universal"
- The partition on your hard drive that stores software read by the UEFI to load OSes (like the Windows bootloader) or UEFI Applications (like OpenCore), it's FAT32 formatted and has an ID type of EF00 (in hex). It can be named ESP or SYSTEM, and it's usually from 100MB to 400MB in size but the size doesn't reflect upon anything. +**32 and 64-Bit CPU** | The bit number of a CPU determines how much data a CPU can address.
- 32-Bit CPUs were only supported up-to Mac OS X 10.6, Snow Leopard. +**32-Bit Firmware** | The bit number of a Firmware determines how much data the firmware can address. In some older Macs, it's common to have a 64-Bit CPU can have a 32-Bit firmware
- 32-Bit Firmwares were only supported up-to Mac OS X 10.7, Lion. +**SSE Instructions** | Also known as **S**IMD **S**ingle-Precision Floating-Point **I**nstructions, these are defined as instruction sets supported by your CPU. In macOS, there are a certain number of instruction sets required for normal operation:
- SSE3: Required for all Intel CPUs since Mac OS X 10.4, Tiger
- SSSE3: Required for all Intel 64-Bit CPUs since Mac OS X 10.6, Snow Leopard
- SSE4.1: Required for all Intel CPUs since macOS 10.12, Sierra +--- diff --git a/images/efi-boot.png b/images/efi-boot.png index 9785e4211..61f5cb882 100644 Binary files a/images/efi-boot.png and b/images/efi-boot.png differ