diff --git a/Docs/Configuration.pdf b/Docs/Configuration.pdf index ed5c45ae..628a8e92 100644 Binary files a/Docs/Configuration.pdf and b/Docs/Configuration.pdf differ diff --git a/Docs/Configuration.tex b/Docs/Configuration.tex index 4aa59066..c13c49e0 100755 --- a/Docs/Configuration.tex +++ b/Docs/Configuration.tex @@ -144,6 +144,11 @@ Please note that regardless of the sources used, users are required to fully und OpenCore configuration option, and the principles behind them, before posting issues to the \href{https://github.com/acidanthera/bugtracker}{Acidanthera Bugtracker}. +\emph{Note}: Creating this document would not have been possible without the invaluable +contributions from other people: Andrey1970, Goldfish64, dakanji, PMHeart, and several others, +with the full list available in +\href{https://github.com/acidanthera/OpenCorePkg/commits/master/Docs}{OpenCorePkg history}. + \subsection{Generic Terms}\label{generic-terms} \begin{itemize} diff --git a/Docs/Differences/Differences.pdf b/Docs/Differences/Differences.pdf index 4d9714f3..13df0625 100644 Binary files a/Docs/Differences/Differences.pdf and b/Docs/Differences/Differences.pdf differ diff --git a/Docs/Differences/Differences.tex b/Docs/Differences/Differences.tex index 73fdb0fc..2526c062 100644 --- a/Docs/Differences/Differences.tex +++ b/Docs/Differences/Differences.tex @@ -1,7 +1,7 @@ \documentclass[]{article} %DIF LATEXDIFF DIFFERENCE FILE -%DIF DEL PreviousConfiguration.tex Tue Oct 6 21:24:03 2020 -%DIF ADD ../Configuration.tex Tue Oct 6 21:26:05 2020 +%DIF DEL PreviousConfiguration.tex Wed Oct 7 12:20:52 2020 +%DIF ADD ../Configuration.tex Tue Oct 13 11:12:47 2020 \usepackage{lmodern} \usepackage{amssymb,amsmath} @@ -192,7 +192,7 @@ and UEFI functionality. For these reasons, this document is available exclusivel and all other sources or translations of this document are unofficial and may contain errors. -Third-party articles, utilities, books, and alike, may be more useful for a wider audience as +Third-party articles, utilities, books, and \DIFdelbegin \DIFdel{alike}\DIFdelend \DIFaddbegin \DIFadd{similar}\DIFaddend , may be more useful for a wider audience as they could provide guide-like material. However, they are subject to their authors' preferences, tastes, misinterpretations of this document, and unavoidable obsolescence. In cases of using such sources, such as \href{https://dortania.github.io}{Dortania}'s @@ -204,7 +204,13 @@ Please note that regardless of the sources used, users are required to fully und OpenCore configuration option, and the principles behind them, before posting issues to the \href{https://github.com/acidanthera/bugtracker}{Acidanthera Bugtracker}. -\subsection{Generic Terms}\label{generic-terms} +\DIFaddbegin \emph{\DIFadd{Note}}\DIFadd{: Creating this document would not have been possible without the invaluable +contributions from other people: Andrey1970, Goldfish64, dakanji, PMHeart, and several others, +with the full list available in +}\href{https://github.com/acidanthera/OpenCorePkg/commits/master/Docs}{OpenCorePkg history}\DIFadd{. +} + +\DIFaddend \subsection{Generic Terms}\label{generic-terms} \begin{itemize} \item @@ -560,8 +566,9 @@ entries include: \texttt{BootProtect} for more details. \item \texttt{boot} \\ - Duet bootstrap loader, which initialises UEFI environment on legacy BIOS firmwares - and loads \texttt{OpenCore.efi} similarly to other bootstrap loaders. Modern Duet + Duet bootstrap loader, which initialises UEFI environment on legacy BIOS \DIFdelbegin \DIFdel{firmwares + }\DIFdelend \DIFaddbegin \DIFadd{firmware + }\DIFaddend and loads \texttt{OpenCore.efi} similarly to other bootstrap loaders. Modern Duet bootstrap loader will default to \texttt{OpenCore.efi} on the same partition when present. \item @@ -621,7 +628,7 @@ To install OpenCore reflect the \hyperref[configuration-structure]{Configuration Structure} described in the previous section on a EFI volume of a GPT partition. While corresponding sections of this document do provide some information -in regards to external resources like ACPI tables, UEFI drivers, +\DIFdelbegin \DIFdel{in regards to external resources like }\DIFdelend \DIFaddbegin \DIFadd{regarding external resources such as }\DIFaddend 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 @@ -731,13 +738,16 @@ all possible means. \subsection{Coding conventions}\label{configuration-conv} -Just like any other project we have conventions that we follow during the development. -All third-party contributors are highly recommended to read and follow the conventions -listed below before submitting their patches. In general it is also recommended to firstly -discuss the issue in \href{https://github.com/acidanthera/bugtracker}{Acidanthera Bugtracker} -before sending the patch to ensure no double work and to avoid the patch being rejected. +\DIFdelbegin \DIFdel{Just like }\DIFdelend \DIFaddbegin \DIFadd{As with }\DIFaddend any other project\DIFaddbegin \DIFadd{, }\DIFaddend we have conventions that we follow during \DIFdelbegin \DIFdel{the }\DIFdelend development. +All third-party contributors are \DIFdelbegin \DIFdel{highly recommended to read and follow }\DIFdelend \DIFaddbegin \DIFadd{advised to adhere to }\DIFaddend the conventions listed below +before submitting \DIFdelbegin \DIFdel{their patches. In general it is also recommended to firstly +discuss the issue in }\DIFdelend \DIFaddbegin \DIFadd{patches. To minimise abortive work and the potential rejection of +submissions, third-party contributors should initially raise issues to the +}\DIFaddend \href{https://github.com/acidanthera/bugtracker}{Acidanthera Bugtracker} +\DIFdelbegin \DIFdel{before sending the patch to ensure no double work and to avoid the +patch being rejected}\DIFdelend \DIFaddbegin \DIFadd{for feedback before submitting patches}\DIFaddend . -\textbf{Organisation}. The codebase is contained in \texttt{OpenCorePkg} repository, +\textbf{Organisation}. The codebase is contained in \DIFaddbegin \DIFadd{the }\DIFaddend \texttt{OpenCorePkg} repository, which is the primary EDK II package. \begin{itemize} \tightlist @@ -834,7 +844,7 @@ for extensive messages that should not appear in NVRAM log that is heavily limit When trying to find the problematic change it is useful to rely on \href{https://git-scm.com/docs/git-bisect}{\texttt{git-bisect}} functionality. There also are some unofficial resources that provide per-commit binary -builds of OpenCore, like \href{https://dortania.github.io/builds}{Dortania}. +builds of OpenCore, \DIFdelbegin \DIFdel{like }\DIFdelend \DIFaddbegin \DIFadd{such as }\DIFaddend \href{https://dortania.github.io/builds}{Dortania}. \section{ACPI}\label{acpi} @@ -1119,10 +1129,11 @@ In the majority of the cases ACPI patches are not useful and harmful: \item Try to avoid patching \texttt{\_OSI} to support a higher level of feature sets whenever possible. Commonly this enables a number of hacks on APTIO - firmwares, which result in the need to add more patches. Modern firmwares - generally do not need it at all, and those that do are fine with much + \DIFdelbegin \DIFdel{firmwares}\DIFdelend \DIFaddbegin \DIFadd{firmware}\DIFaddend , which result in the need to add more patches. Modern \DIFdelbegin \DIFdel{firmwares + generally do }\DIFdelend \DIFaddbegin \DIFadd{firmware + generally does }\DIFaddend not need it\DIFdelbegin \DIFdel{at all}\DIFdelend , and those that do are fine with much smaller patches. However, laptop vendors usually rely on this method to - determine the availability of functions like modern I2C input support, thermal + determine the availability of functions \DIFdelbegin \DIFdel{like }\DIFdelend \DIFaddbegin \DIFadd{such as }\DIFaddend modern I2C input support, thermal adjustment and custom feature additions. \item Avoid patching embedded controller event \texttt{\_Qxx} just for enabling @@ -1131,7 +1142,7 @@ In the majority of the cases ACPI patches are not useful and harmful: newer systems. Please switch to built-in brightness key discovery of \href{https://github.com/acidanthera/BrightnessKeys}{BrightnessKeys} instead. \item - Try to avoid hacky changes like renaming \texttt{\_PRW} or \texttt{\_DSM} + Try to avoid hacky changes \DIFdelbegin \DIFdel{like }\DIFdelend \DIFaddbegin \DIFadd{such as }\DIFaddend renaming \texttt{\_PRW} or \texttt{\_DSM} whenever possible. \end{itemize} @@ -1219,7 +1230,7 @@ patching or the padding of \texttt{NOP} to the remaining area might be taken int \textbf{Description}: Reset \texttt{FACS} table \texttt{HardwareSignature} value to \texttt{0}. - This works around firmwares that fail to maintain hardware signature across + This works around \DIFdelbegin \DIFdel{firmwares }\DIFdelend \DIFaddbegin \DIFadd{firmware }\DIFaddend that fail to maintain hardware signature across the reboots and cause issues with waking from hibernation. \item @@ -1229,7 +1240,7 @@ patching or the padding of \texttt{NOP} to the remaining area might be taken int \textbf{Description}: Reset \texttt{BGRT} table \texttt{Displayed} status field to \texttt{false}. - This works around firmwares that provide \texttt{BGRT} table but + This works around \DIFdelbegin \DIFdel{firmwares that provide }\DIFdelend \DIFaddbegin \DIFadd{firmware that provide a }\DIFaddend \texttt{BGRT} table but fail to handle screen updates afterwards. \end{enumerate} @@ -1241,7 +1252,7 @@ patching or the padding of \texttt{NOP} to the remaining area might be taken int This section allows to apply different kinds of UEFI modifications on Apple bootloader (\texttt{boot.efi}). The modifications currently provide -various patches and environment alterations for different firmwares. Some +various patches and environment alterations for different \DIFdelbegin \DIFdel{firmwares}\DIFdelend \DIFaddbegin \DIFadd{firmware}\DIFaddend . Some of these features were originally implemented as a part of \href{https://github.com/acidanthera/AptioFixPkg}{\text{AptioMemoryFix.efi}}, which is no longer maintained. See \hyperref[troubleshootingtricks]{Tips and Tricks} @@ -1364,10 +1375,10 @@ To view their current state use \texttt{pmset -g} command in Terminal. \textbf{Description}: Protect from boot.efi runtime memory defragmentation. This option fixes UEFI runtime services (date, time, NVRAM, power control, etc.) - support on many firmwares using SMM backing for select services like variable + support on \DIFdelbegin \DIFdel{many firmwares using }\DIFdelend \DIFaddbegin \DIFadd{firmware that uses }\DIFaddend SMM backing for select services \DIFdelbegin \DIFdel{like }\DIFdelend \DIFaddbegin \DIFadd{such as }\DIFaddend variable storage. SMM may try to access physical addresses, but they get moved by boot.efi. - \emph{Note}: Most but Apple and VMware firmwares need this quirk. + \emph{Note}: Most \DIFdelbegin \DIFdel{but }\DIFdelend \DIFaddbegin \DIFadd{types of firmware, apart from }\DIFaddend Apple and VMware\DIFdelbegin \DIFdel{firmwares }\DIFdelend \DIFaddbegin \DIFadd{, }\DIFaddend need this quirk. \item \texttt{DevirtualiseMmio}\\ @@ -1383,10 +1394,13 @@ To view their current state use \texttt{pmset -g} command in Terminal. is the only way to boot macOS, which otherwise fails with allocation error at bootloader stage. - This option is generally useful on all firmwares except some very old ones, - like Sandy Bridge. On select firmwares it may require a list of exceptional - addresses that still need to get their virtual addresses for proper NVRAM and - hibernation functioning. Use \texttt{MmioWhitelist} section to do this. + This option is generally useful on all \DIFdelbegin \DIFdel{firmwares }\DIFdelend \DIFaddbegin \DIFadd{types of firmware, }\DIFaddend except some very old ones + \DIFdelbegin \DIFdel{, + like }\DIFdelend \DIFaddbegin \DIFadd{such as }\DIFaddend Sandy Bridge. On \DIFdelbegin \DIFdel{select firmwares it may require }\DIFdelend \DIFaddbegin \DIFadd{some types of firmware, }\DIFaddend a list of \DIFdelbegin \DIFdel{exceptional + addresses that still need to get their }\DIFdelend \DIFaddbegin \DIFadd{addresses that need }\DIFaddend virtual + addresses for proper NVRAM and hibernation \DIFdelbegin \DIFdel{functioning. + Use }\DIFdelend \DIFaddbegin \DIFadd{functionality may be required. + Use the }\DIFaddend \texttt{MmioWhitelist} section \DIFdelbegin \DIFdel{to do }\DIFdelend \DIFaddbegin \DIFadd{for }\DIFaddend this. \item \texttt{DisableSingleUser}\\ @@ -1427,7 +1441,7 @@ To view their current state use \texttt{pmset -g} command in Terminal. \emph{Note}: This may be used to workaround buggy memory maps on older hardware, and is now considered rare legacy. Examples of such hardware are Ivy Bridge laptops - with Insyde firmware, like Acer V3-571G. Do not use this unless a complete understanding of + with Insyde firmware, \DIFdelbegin \DIFdel{like }\DIFdelend \DIFaddbegin \DIFadd{such as }\DIFaddend Acer V3-571G. Do not use this unless a complete understanding of the consequences can be ensured. \item @@ -1479,7 +1493,7 @@ To view their current state use \texttt{pmset -g} command in Terminal. \textbf{Failsafe}: \texttt{false}\\ \textbf{Description}: Protect memory regions from incorrect access. - Some firmwares incorrectly map select memory regions: + Some \DIFdelbegin \DIFdel{firmwares }\DIFdelend \DIFaddbegin \DIFadd{types of firmware }\DIFaddend incorrectly map select memory regions: \begin{itemize} \tightlist @@ -1493,7 +1507,7 @@ To view their current state use \texttt{pmset -g} command in Terminal. CSM or MMIO for MMIO. \emph{Note}: The necessity of this quirk is determined by artifacts, sleep - wake issues, and boot failures. In general only very old firmwares need + wake issues, and boot failures. \DIFdelbegin \DIFdel{In general only very old firmwares }\DIFdelend \DIFaddbegin \DIFadd{Only very old firmware typically }\DIFaddend need this quirk. \item @@ -1514,10 +1528,10 @@ To view their current state use \texttt{pmset -g} command in Terminal. \textbf{Failsafe}: \texttt{false}\\ \textbf{Description}: Protect UEFI services from being overridden by the firmware. - Some modern firmwares including both hardware and virtual machines, like VMware, + Some modern \DIFdelbegin \DIFdel{firmwares including both hardware and virtual machines , like }\DIFdelend \DIFaddbegin \DIFadd{firmware, including on virtual machines such as }\DIFaddend VMware, may update pointers to UEFI services during driver loading and related actions. Consequentially this directly breaks other quirks that affect memory management, - like \texttt{DevirtualiseMmio}, \texttt{ProtectMemoryRegions}, or \texttt{RebuildAppleMemoryMap}, + \DIFdelbegin \DIFdel{like }\DIFdelend \DIFaddbegin \DIFadd{such as }\DIFaddend \texttt{DevirtualiseMmio}, \texttt{ProtectMemoryRegions}, or \texttt{RebuildAppleMemoryMap}, and may also break other quirks depending on the effects of these. \emph{Note}: On VMware the need for this quirk may be diagnosed by ``Your Mac OS guest @@ -1549,15 +1563,14 @@ To view their current state use \texttt{pmset -g} command in Terminal. This option overrides the maximum slide of 255 by a user specified value between 1 and 254 inclusive when \texttt{ProvideCustomSlide} is enabled. - It is believed that modern firmwares allocate pool memory from top to bottom, effectively resulting in - free memory at the time of slide scanning being later used as temporary - memory during kernel loading. In case those memory are unavailable, this - option can stop evaluating higher slides. + It is believed that modern \DIFdelbegin \DIFdel{firmwares allocate }\DIFdelend \DIFaddbegin \DIFadd{firmware allocates }\DIFaddend pool memory from top to bottom, effectively resulting in + free memory \DIFdelbegin \DIFdel{at the time of slide scanning being later used }\DIFdelend \DIFaddbegin \DIFadd{when slide scanning is used later }\DIFaddend as temporary memory during kernel loading. + \DIFdelbegin \DIFdel{In case those memory are unavailable}\DIFdelend \DIFaddbegin \DIFadd{When such memory is not available}\DIFaddend , this option can stop \DIFdelbegin \DIFdel{evaluating }\DIFdelend \DIFaddbegin \DIFadd{the evaluation of }\DIFaddend higher slides. \emph{Note}: The necessity of this quirk is determined by random boot failure when \texttt{ProvideCustomSlide} is enabled and the randomized slide fall into the unavailable range. When \texttt{AppleDebug} is enabled, usually the - debug log may contain messages like \texttt{AAPL: [EB|`LD:LKC] \} Err(0x9)}. + debug log may contain messages \DIFdelbegin \DIFdel{like }\DIFdelend \DIFaddbegin \DIFadd{such as }\DIFaddend \texttt{AAPL: [EB|`LD:LKC] \} Err(0x9)}. To find the optimal value, manually append \texttt{slide=X} to \texttt{boot-args} and log the largest one that will not result in boot failures. @@ -1572,8 +1585,8 @@ To view their current state use \texttt{pmset -g} command in Terminal. \begin{itemize} \tightlist \item Memory map size must not exceed 4096 bytes as Apple kernel maps - it as a single 4K page. Since some firmwares have very large memory maps - (approximately over 100 entries) Apple kernel will crash at boot. + it as a single 4K page. Since some \DIFdelbegin \DIFdel{firmwares }\DIFdelend \DIFaddbegin \DIFadd{types of firmware can }\DIFaddend have very large memory maps\DIFdelbegin \DIFdel{(approximately }\DIFdelend \DIFaddbegin \DIFadd{, + potentially }\DIFaddend over 100 entries\DIFdelbegin \DIFdel{) }\DIFdelend \DIFaddbegin \DIFadd{, the }\DIFaddend Apple kernel will crash \DIFdelbegin \DIFdel{at }\DIFdelend \DIFaddbegin \DIFadd{on }\DIFaddend boot. \item Memory attributes table is ignored. \texttt{EfiRuntimeServicesCode} memory statically gets \texttt{RX} permissions, and all other memory types get \texttt{RW} permissions. Since some firmware drivers may write to global @@ -1582,19 +1595,21 @@ To view their current state use \texttt{pmset -g} command in Terminal. type. \end{itemize} - To workaround these limitations this quirk applies memory attributes table - permissions to memory map passed to Apple kernel and optionally attempts + To workaround these limitations\DIFaddbegin \DIFadd{, }\DIFaddend this quirk applies memory \DIFdelbegin \DIFdel{attributes }\DIFdelend \DIFaddbegin \DIFadd{attribute }\DIFaddend table + permissions to \DIFaddbegin \DIFadd{the }\DIFaddend memory map passed to \DIFaddbegin \DIFadd{the }\DIFaddend Apple kernel and optionally attempts to unify contiguous slots of similar types if the resulting memory map exceeds 4 KB. - \emph{Note 1}: Since many firmwares come with incorrect memory protection - table this quirk often comes in pair with \texttt{SyncRuntimePermissions}. + \emph{Note 1}: Since \DIFdelbegin \DIFdel{many firmwares }\DIFdelend \DIFaddbegin \DIFadd{several types of firmware }\DIFaddend come with incorrect memory protection + \DIFdelbegin \DIFdel{table }\DIFdelend \DIFaddbegin \DIFadd{tables, }\DIFaddend this quirk often comes \DIFdelbegin \DIFdel{in pair }\DIFdelend \DIFaddbegin \DIFadd{paired }\DIFaddend with \texttt{SyncRuntimePermissions}. \emph{Note 2}: The necessity of this quirk is determined by early boot failures. - This quirk replaces \texttt{EnableWriteUnprotector} on firmwares supporting - memory attributes table (MAT). This quirk is generally unnecessary when using - \texttt{OpenDuetPkg}, but may be required to boot macOS 10.6 and earlier for - unclear reasons. + This quirk replaces \texttt{EnableWriteUnprotector} on \DIFdelbegin \DIFdel{firmwares supporting + memory attributes table }\DIFdelend \DIFaddbegin \DIFadd{firmware supporting + Memory Attribute Tables }\DIFaddend (MAT). This quirk is \DIFdelbegin \DIFdel{generally }\DIFdelend \DIFaddbegin \DIFadd{usually }\DIFaddend unnecessary when using + \texttt{OpenDuetPkg}, but may be required to boot macOS 10.6\DIFdelbegin \DIFdel{and earlier for + unclear reasons }\DIFdelend \DIFaddbegin \DIFadd{, and earlier, for + reasons that are not clear}\DIFaddend . \item \texttt{SetupVirtualMap}\\ @@ -1602,14 +1617,15 @@ To view their current state use \texttt{pmset -g} command in Terminal. \textbf{Failsafe}: \texttt{false}\\ \textbf{Description}: Setup virtual memory at \texttt{SetVirtualAddresses}. - Select firmwares access memory by virtual addresses after \texttt{SetVirtualAddresses} - call, which results in early boot crashes. This quirk workarounds the problem by + \DIFdelbegin \DIFdel{Select firmwares }\DIFdelend \DIFaddbegin \DIFadd{Some types of firmware }\DIFaddend access memory by virtual addresses after \DIFaddbegin \DIFadd{a }\DIFaddend \texttt{SetVirtualAddresses} + call, \DIFdelbegin \DIFdel{which results }\DIFdelend \DIFaddbegin \DIFadd{resulting }\DIFaddend in early boot crashes. This quirk workarounds the problem by performing early boot identity mapping of assigned virtual addresses to physical memory. - \emph{Note}: The necessity of this quirk is determined by early boot failures. Currently - new firmwares with memory protection support (like OVMF) do not support this quirk due to - \href{https://github.com/acidanthera/bugtracker/issues/719}{acidanthera/bugtracker\#719}. + \emph{Note}: The necessity of this quirk is determined by early boot failures. Currently\DIFdelbegin \DIFdel{new firmwares }\DIFdelend \DIFaddbegin \DIFadd{, + new firmware }\DIFaddend with memory protection support (\DIFdelbegin \DIFdel{like }\DIFdelend \DIFaddbegin \DIFadd{such as }\DIFaddend OVMF) do not support this quirk\DIFdelbegin \DIFdel{due to + }\DIFdelend \DIFaddbegin \DIFadd{. See + }\DIFaddend \href{https://github.com/acidanthera/bugtracker/issues/719}{acidanthera/bugtracker\#719}. \item \texttt{SignalAppleOS}\\ @@ -1617,7 +1633,7 @@ To view their current state use \texttt{pmset -g} command in Terminal. \textbf{Failsafe}: \texttt{false}\\ \textbf{Description}: Report macOS being loaded through OS Info for any OS. - This quirk is useful on Mac firmwares, which behave differently in different OS. + This quirk is useful on Mac \DIFdelbegin \DIFdel{firmwares, which behave }\DIFdelend \DIFaddbegin \DIFadd{firmware, which behaves }\DIFaddend differently in different OS. For example, it is supposed to enable Intel GPU in Windows and Linux in some dual-GPU MacBook models. @@ -1627,7 +1643,7 @@ To view their current state use \texttt{pmset -g} command in Terminal. \textbf{Failsafe}: \texttt{false}\\ \textbf{Description}: Update memory permissions for runtime environment. - Some firmwares either fail to properly handle runtime permissions: + Some \DIFdelbegin \DIFdel{firmwares either }\DIFdelend \DIFaddbegin \DIFadd{types of firmware }\DIFaddend fail to properly handle runtime permissions: \begin{itemize} \tightlist \item They incorrectly mark \texttt{OpenRuntime} as not executable in the memory map. @@ -1640,8 +1656,10 @@ To view their current state use \texttt{pmset -g} command in Terminal. This quirk tries to update memory map and memory attributes table to correct this. - \emph{Note}: The necessity of this quirk is determined by early boot failures either in - macOS or in Linux/Windows. In general only firmwares released in 2018 or later are affected. + \emph{Note}: The \DIFdelbegin \DIFdel{necessity of }\DIFdelend \DIFaddbegin \DIFadd{need for }\DIFaddend this quirk is \DIFdelbegin \DIFdel{determined }\DIFdelend \DIFaddbegin \DIFadd{indicated }\DIFaddend by early boot failures\DIFdelbegin \DIFdel{either in + macOS or in Linux/Windows. + In general only firmwares released in 2018 or later are }\DIFdelend \DIFaddbegin \DIFadd{. + Only firmware released after 2017 is typically }\DIFaddend affected. \end{enumerate} @@ -1693,7 +1711,7 @@ The second stage applies to all devices much later after the PCI configuration and may repeat the first stage if the device was not present in ACPI. For all kernel drivers, which may inspect the \texttt{IODeviceTree} plane without -probing (e.g. \texttt{Lilu} and its plugins like \texttt{WhateverGreen}) it is particularly +probing (e.g. \texttt{Lilu} and its plugins \DIFdelbegin \DIFdel{like }\DIFdelend \DIFaddbegin \DIFadd{such as }\DIFaddend \texttt{WhateverGreen}) it is particularly important to ensure device presence in the ACPI tables. Failing to do so may result \textbf{in all kinds of erratic behaviour} caused by ignoring the injected device properties as they were not constructed at the first stage. See \texttt{SSDT-IMEI.dsl} and @@ -1809,7 +1827,7 @@ blocking. See \hyperref[kernelpropsforce]{Force Properties} section below. This section resolves the problem of injecting drivers that depend on other drivers, which are not cached otherwise. The issue normally affects older - operating systems, where various dependency kexts, like \texttt{IOAudioFamily} + operating systems, where various dependency kexts, \DIFdelbegin \DIFdel{like }\DIFdelend \DIFaddbegin \DIFadd{such as }\DIFaddend \texttt{IOAudioFamily} or \texttt{IONetworkingFamily} may not be present in the kernel cache by default. Kernel driver load order follows the item order in the array, thus the dependencies should be written prior to their consumers. \texttt{Force} happens before @@ -2280,14 +2298,14 @@ blocking. MSR modification in AppleIntelCPUPowerManagement.kext, commonly causing early kernel panic, when it is locked from writing. - Certain firmwares lock \texttt{PKG\_CST\_CONFIG\_CONTROL} MSR register. The bundled - \texttt{VerifyMsrE2} tool can be used to check its state. Some firmware have this - register locked only on some cores. + \DIFdelbegin \DIFdel{Certain firmwares lock }\DIFdelend \DIFaddbegin \DIFadd{Some types of firmware lock the }\DIFaddend \texttt{PKG\_CST\_CONFIG\_CONTROL} MSR register \DIFdelbegin \DIFdel{. The }\DIFdelend \DIFaddbegin \DIFadd{and the }\DIFaddend bundled + \texttt{VerifyMsrE2} tool can be used to check its state. \DIFdelbegin \DIFdel{Some firmware }\DIFdelend \DIFaddbegin \DIFadd{Note that some types of firmware only + }\DIFaddend have this register locked \DIFdelbegin \DIFdel{only }\DIFdelend on some cores. - As modern firmwares provide \texttt{CFG Lock} setting, which allows configuring - \texttt{PKG\_CST\_CONFIG\_CONTROL} MSR register lock, this option should be avoided - whenever possible. For several APTIO firmwares not displaying \texttt{CFG Lock} setting - in the GUI it is possible to access the option directly: + As modern \DIFdelbegin \DIFdel{firmwares provide }\DIFdelend \DIFaddbegin \DIFadd{firmware provide a }\DIFaddend \texttt{CFG Lock} setting \DIFdelbegin \DIFdel{, which allows configuring }\DIFdelend \DIFaddbegin \DIFadd{that allows configuring the + }\DIFaddend \texttt{PKG\_CST\_CONFIG\_CONTROL} MSR register lock, this option should be avoided + whenever possible. \DIFdelbegin \DIFdel{For several APTIO firmwares not displaying }\DIFdelend \DIFaddbegin \DIFadd{On APTIO firmware that do not provide a }\DIFaddend \texttt{CFG Lock} + setting in the GUI\DIFaddbegin \DIFadd{, }\DIFaddend it is possible to access the option directly: \begin{enumerate} \tightlist @@ -2418,8 +2436,9 @@ blocking. \textbf{Description}: Apply icon type patches to AppleAHCIPort.kext to force internal disk icons for all AHCI disks. - \emph{Note}: This option should be avoided whenever possible. Modern firmwares - usually have compatible AHCI controllers. + \emph{Note}: This option should be avoided whenever possible. Modern \DIFdelbegin \DIFdel{firmwares + }\DIFdelend \DIFaddbegin \DIFadd{firmware + }\DIFaddend usually have compatible AHCI controllers. \item \texttt{IncreasePciBarSize}\\ @@ -2515,8 +2534,9 @@ refer to \hyperref[legacyapple]{Legacy Apple OS}. \textbf{Description}: Use \texttt{kernelcache} with different checksums when available. On macOS 10.6 and earlier \texttt{kernelcache} filename has a checksum, which essentially - is \texttt{adler32} from SMBIOS product name and EfiBoot device path. On certain firmwares - EfiBoot device path differs between UEFI and macOS due to ACPI or hardware specifics, + is \texttt{adler32} from SMBIOS product name and EfiBoot device path. On \DIFdelbegin \DIFdel{certain firmwares + }\DIFdelend \DIFaddbegin \DIFadd{some types of firmware, + the }\DIFaddend EfiBoot device path differs between UEFI and macOS due to ACPI or hardware specifics, rendering \texttt{kernelcache} checksum as always different. This setting allows matching the latest \texttt{kernelcache} with a suitable architecture @@ -2588,7 +2608,7 @@ refer to \hyperref[legacyapple]{Legacy Apple OS}. of them all is complicated and not practical, because several point releases had genuine bugs and failed to properly perform the server detection in the first place. For this reason OpenCore on macOS~10.6 will fallback to \texttt{x86\_64} - architecture whenever it is supported by the board at all, just like on macOS~10.7. + architecture whenever it is supported by the board at all, \DIFdelbegin \DIFdel{just like }\DIFdelend \DIFaddbegin \DIFadd{as }\DIFaddend on macOS~10.7. As a reference here is the 64-bit Mac model compatibility corresponding to actual EfiBoot behaviour on macOS 10.6.8 and 10.7.5. @@ -2988,9 +3008,9 @@ entry choice will update till next manual reconfiguration. handled by operating system bootloader, namely \texttt{boot.efi}. These keys allow to change operating system behaviour by providing different boot modes. - On some firmwares it may be problematic to use modifier keys due to driver incompatibilities. - To workaround this problem this option allows registering select hotkeys in a more - permissive manner from within boot picker. Such extensions include the support + On some \DIFdelbegin \DIFdel{firmwares }\DIFdelend \DIFaddbegin \DIFadd{types of firmware, }\DIFaddend it may be problematic to use modifier keys due to driver + incompatibilities. To workaround this problem this option allows registering select hotkeys + in a more permissive manner from within boot picker. Such extensions include the support of tapping on keys in addition to holding and pressing \texttt{Shift} along with other keys instead of just \texttt{Shift} alone, which is not detectable on many PS/2 keyboards. This list of known \texttt{modifier hotkeys} includes: @@ -3080,16 +3100,16 @@ entry choice will update till next manual reconfiguration. \end{itemize} \emph{Note 1}: Activated \texttt{KeySupport}, \texttt{OpenUsbKbDxe}, or similar driver is required - for key handling to work. On many firmwares it is not possible to get all the keys function. + for key handling to work. On \DIFdelbegin \DIFdel{many firmwares }\DIFdelend \DIFaddbegin \DIFadd{sevaral types of firmware, }\DIFaddend it is not possible to get all the \DIFdelbegin \DIFdel{keys function}\DIFdelend \DIFaddbegin \DIFadd{key functions}\DIFaddend . \emph{Note 2}: In addition to \texttt{OPT} OpenCore supports \texttt{Escape} key to display picker when - \texttt{ShowPicker} is disabled. This key exists for \texttt{Apple} picker mode and for - firmwares with PS/2 keyboards that fail to report held \texttt{OPT} key and require continual - presses of \texttt{Escape} key to enter the boot menu. + \texttt{ShowPicker} is disabled. This key exists for \DIFaddbegin \DIFadd{the }\DIFaddend \texttt{Apple} picker mode and for + \DIFdelbegin \DIFdel{firmwares }\DIFdelend \DIFaddbegin \DIFadd{firmware }\DIFaddend with PS/2 keyboards that fail to report held \texttt{OPT} \DIFdelbegin \DIFdel{key and require }\DIFdelend \DIFaddbegin \DIFadd{keys and requiring }\DIFaddend continual + presses of \DIFaddbegin \DIFadd{the }\DIFaddend \texttt{Escape} key to \DIFdelbegin \DIFdel{enter }\DIFdelend \DIFaddbegin \DIFadd{access }\DIFaddend the boot menu. - \emph{Note 3}: On Macs with problematic GOP it may be difficult to access Apple BootPicker. - \texttt{BootKicker} utility can be blessed to workaround this problem even without loading - OpenCore. On some Macs \texttt{BootKicker} will not run from OpenCore. + \emph{Note 3}: On Macs with problematic GOP\DIFaddbegin \DIFadd{, }\DIFaddend it may be difficult to access \DIFaddbegin \DIFadd{the }\DIFaddend Apple BootPicker. + \DIFaddbegin \DIFadd{The }\DIFaddend \texttt{BootKicker} utility can be blessed to workaround this problem even without loading + OpenCore. On some Macs \DIFaddbegin \DIFadd{however, the }\DIFaddend \texttt{BootKicker} \DIFdelbegin \DIFdel{will not }\DIFdelend \DIFaddbegin \DIFadd{utility cannot be }\DIFaddend run from OpenCore. \end{enumerate} @@ -3138,9 +3158,10 @@ cat Kernel.panic | grep macOSProcessedStackshotData | \texttt{DisableWatchDog}\\ \textbf{Type}: \texttt{plist\ boolean}\\ \textbf{Failsafe}: \texttt{false}\\ - \textbf{Description}: Select firmwares may not succeed in quickly booting - the operating system, especially in debug mode, which results in watch dog - timer aborting the process. This option turns off watch dog timer. + \textbf{Description}: \DIFdelbegin \DIFdel{Select firmwares }\DIFdelend \DIFaddbegin \DIFadd{Some types of firmware }\DIFaddend may not succeed in \DIFdelbegin \DIFdel{quickly }\DIFdelend booting + the operating system \DIFaddbegin \DIFadd{quickly}\DIFaddend , especially in debug mode, which results in \DIFdelbegin \DIFdel{watch dog + }\DIFdelend \DIFaddbegin \DIFadd{the watchdog + }\DIFaddend timer aborting the process. This option turns off \DIFdelbegin \DIFdel{watch dog }\DIFdelend \DIFaddbegin \DIFadd{the watchdog }\DIFaddend timer. \item \texttt{DisplayDelay}\\ @@ -3233,7 +3254,7 @@ ioreg -lw0 -p IODeviceTree | grep boot-log | sort | sed 's/.*<\(.*\)>.*/\1/' | x \end{lstlisting} UEFI variable log does not include some messages and has no performance data. For safety - reasons log size is limited to 32 kilobytes. Some firmwares may truncate it much earlier + reasons log size is limited to 32 kilobytes. Some \DIFdelbegin \DIFdel{firmwares }\DIFdelend \DIFaddbegin \DIFadd{types of firmware }\DIFaddend may truncate it much earlier or drop completely if they have no memory. Using non-volatile flag will write the log to NVRAM flash after every printed line. To obtain UEFI variable log use the following command in macOS: @@ -3242,7 +3263,7 @@ nvram 4D1FDA02-38C7-4A6A-9CC6-4BCCA8B30102:boot-log | awk '{gsub(/%0d%0a%00/,"");gsub(/%0d%0a/,"\n")}1' \end{lstlisting} - \textbf{Warning}: Some firmwares are reported to have broken NVRAM garbage collection. + \textbf{Warning}: Some \DIFdelbegin \DIFdel{firmwares are reported to have broken }\DIFdelend \DIFaddbegin \DIFadd{types of firmware appear to have flawed }\DIFaddend NVRAM garbage collection. This means that they may not be able to always free space after variable deletion. Do not use non-volatile NVRAM logging without extra need on such devices. @@ -3253,11 +3274,11 @@ nvram 4D1FDA02-38C7-4A6A-9CC6-4BCCA8B30102:boot-log | File logging will create a file named \texttt{opencore-YYYY-MM-DD-HHMMSS.txt} at EFI volume root with log contents (the upper case letter sequence is replaced with date and time from the firmware). Please be warned that some file system drivers present - in firmwares are not reliable, and may corrupt data when writing files through UEFI. - Log is attempted to be written in the safest manner, and thus is very slow. Ensure that + in \DIFdelbegin \DIFdel{firmwares }\DIFdelend \DIFaddbegin \DIFadd{firmware }\DIFaddend are not reliable \DIFdelbegin \DIFdel{, }\DIFdelend and may corrupt data when writing files through UEFI. + Log \DIFdelbegin \DIFdel{is attempted to be written }\DIFdelend \DIFaddbegin \DIFadd{writing is attempted }\DIFaddend in the safest manner \DIFdelbegin \DIFdel{, and thus}\DIFdelend \DIFaddbegin \DIFadd{and thus, }\DIFaddend is very slow. Ensure that \texttt{DisableWatchDog} is set to \texttt{true} when a slow drive is used. Try to avoid frequent use of this option when dealing with flash drives as large I/O - amounts may speedup memory wear and render this flash drive unusable in shorter time. + amounts may speedup memory wear and render \DIFdelbegin \DIFdel{this }\DIFdelend \DIFaddbegin \DIFadd{the }\DIFaddend flash drive unusable \DIFdelbegin \DIFdel{in shorter time}\DIFdelend \DIFaddbegin \DIFadd{quicker}\DIFaddend . 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 @@ -3437,11 +3458,12 @@ diskutil mount -mountpoint /var/tmp/OSPersonalizationTemp $disk file. By creating a custom option in \texttt{Bootstrap} mode this file path becomes no longer used for bootstrapping OpenCore. - \emph{Note 1}: Some firmwares may have broken NVRAM, no boot option support, or various other - incompatibilities of any kind. While unlikely, the use of this option may even cause boot failure. + \emph{Note 1}: Some \DIFdelbegin \DIFdel{firmwares may have broken }\DIFdelend \DIFaddbegin \DIFadd{types of firmware may have faulty }\DIFaddend NVRAM, no boot option support, or \DIFdelbegin \DIFdel{various other + incompatibilitiesof any kind}\DIFdelend \DIFaddbegin \DIFadd{other + incompatibilities}\DIFaddend . While unlikely, the use of this option may even cause boot \DIFdelbegin \DIFdel{failure}\DIFdelend \DIFaddbegin \DIFadd{failures}\DIFaddend . This option should be used without any warranty exclusively on the boards known to be compatible. - \emph{Note 2}: Be warned that while NVRAM reset executed from OpenCore should not erase the boot + \emph{Note 2}: Be \DIFdelbegin \DIFdel{warned }\DIFdelend \DIFaddbegin \DIFadd{aware }\DIFaddend that while NVRAM reset executed from OpenCore should not erase the boot option created in \texttt{Bootstrap}, executing NVRAM reset prior to loading OpenCore will remove it. \item \label{securedmgloading} @@ -3474,7 +3496,7 @@ diskutil mount -mountpoint /var/tmp/OSPersonalizationTemp $disk \textbf{Failsafe}: \texttt{false}\\ \textbf{Description}: Enable password protection to allow sensitive operations. - Password protection ensures that sensitive operations like booting a non-default + Password protection ensures that sensitive operations \DIFdelbegin \DIFdel{like }\DIFdelend \DIFaddbegin \DIFadd{such as }\DIFaddend booting a non-default operating system (e.g. macOS recovery or a tool), resetting NVRAM storage, trying to boot into a non-default mode (e.g. verbose mode or safe mode) are not allowed without explicit user authentication by a custom password. Currently @@ -3609,8 +3631,9 @@ rm vault.pub method is required to verify \texttt{OpenCore.efi} and \texttt{BOOTx64.efi} for secure boot path. For this, it is recommended to enable UEFI SecureBoot using a custom certificate and to sign \texttt{OpenCore.efi} and \texttt{BOOTx64.efi} - with a custom key. More details on customising secure boot on modern firmwares - can be found in \href{https://habr.com/post/273497/}{Taming UEFI SecureBoot} + with a custom key. More details on customising secure boot on modern \DIFdelbegin \DIFdel{firmwares + }\DIFdelend \DIFaddbegin \DIFadd{firmware + }\DIFaddend can be found in \href{https://habr.com/post/273497/}{Taming UEFI SecureBoot} paper (in Russian). \emph{Note 2}: \texttt{vault.plist} and \texttt{vault.sig} are used regardless of this @@ -3743,8 +3766,9 @@ rm vault.pub \item The list of cached drivers may be different, resulting in the need to change the list of \texttt{Added} or \texttt{Forced} kernel drivers. For example, \texttt{IO80211Family} cannot be injected in this case. - \item System volume alterations on operating systems with sealing, like - macOS~11, may result in the operating system being unbootable. Do not + \item System volume alterations on operating systems with sealing, \DIFdelbegin \DIFdel{like + }\DIFdelend \DIFaddbegin \DIFadd{such as + }\DIFaddend macOS~11, may result in the operating system being unbootable. Do not try to disable system volume encryption unless Apple Secure Boot is disabled. \item If the platform requires certain settings, but they were not enabled, because the obvious issues did not trigger before, boot failure might occur. @@ -3752,7 +3776,7 @@ rm vault.pub \item Operating systems released before Apple Secure Boot landed (e.g. macOS~10.12 or earlier) will still boot until UEFI Secure Boot is enabled. This is so, because from Apple Secure Boot point they are treated as incompatible - and are assumed to be handled by the firmware just like Microsoft Windows is. + and are assumed to be handled by the firmware \DIFdelbegin \DIFdel{just like }\DIFdelend \DIFaddbegin \DIFadd{as }\DIFaddend Microsoft Windows is. \item On older CPUs (e.g. before Sandy Bridge) enabling Apple Secure Boot might cause slightly slower loading by up to 1 second. \item Since \texttt{Default} value will increase with time to support the latest @@ -3965,9 +3989,9 @@ use. \textbf{Failsafe}: \texttt{false}\\ \textbf{Description}: Enables writing to flash memory for all added variables. - \emph{Note}: This value is recommended to be enabled on most firmwares, but is - left configurable for firmwares that may have issues with NVRAM variable storage - garbage collection or alike. + \emph{Note}: \DIFdelbegin \DIFdel{This value }\DIFdelend \DIFaddbegin \DIFadd{It }\DIFaddend is recommended to \DIFdelbegin \DIFdel{be }\DIFdelend \DIFaddbegin \DIFadd{have this value }\DIFaddend enabled on most \DIFdelbegin \DIFdel{firmwares, but }\DIFdelend \DIFaddbegin \DIFadd{types of firmware but it }\DIFaddend is + left configurable for \DIFdelbegin \DIFdel{firmwares }\DIFdelend \DIFaddbegin \DIFadd{firmware }\DIFaddend that may have issues with NVRAM variable storage + garbage collection or \DIFdelbegin \DIFdel{alike}\DIFdelend \DIFaddbegin \DIFadd{similar}\DIFaddend . \end{enumerate} @@ -4331,7 +4355,7 @@ be used. Version with macOS specific enhancements can be downloaded from \textbf{Warning}: It is strongly discouraged set this option to \texttt{false} when intending to update platform information. The only reason to do that is - when doing minor correction of the SMBIOS present and alike. In all other + when doing minor correction of the SMBIOS present and \DIFdelbegin \DIFdel{alike}\DIFdelend \DIFaddbegin \DIFadd{similar}\DIFaddend . In all other cases not using \texttt{Automatic} may lead to hard to debug errors. \item @@ -4373,7 +4397,7 @@ be used. Version with macOS specific enhancements can be downloaded from \item \texttt{TryOverwrite} --- \texttt{Overwrite} if new size is \textless{}= than the page-aligned original and there are no issues with legacy region - unlock. \texttt{Create} otherwise. Has issues with some firmwares. + unlock. \texttt{Create} otherwise. Has issues \DIFdelbegin \DIFdel{with some firmwares}\DIFdelend \DIFaddbegin \DIFadd{on some types of firmware}\DIFaddend . \item \texttt{Create} --- Replace the tables with newly allocated EfiReservedMemoryType at AllocateMaxAddress without any fallbacks. @@ -4384,7 +4408,7 @@ be used. Version with macOS specific enhancements can be downloaded from \item \texttt{Custom} --- Write SMBIOS tables (\texttt{gEfiSmbios(3)TableGuid}) to \texttt{gOcCustomSmbios(3)TableGuid} - to workaround firmwares overwriting SMBIOS contents at + to workaround \DIFdelbegin \DIFdel{firmwares }\DIFdelend \DIFaddbegin \DIFadd{firmware }\DIFaddend overwriting SMBIOS contents at ExitBootServices. Otherwise equivalent to \texttt{Create}. Requires patching AppleSmbios.kext and AppleACPIPlatform.kext to read from another GUID: \texttt{"EB9D2D31"} - \texttt{"EB9D2D35"} (in ASCII), @@ -4430,8 +4454,9 @@ be used. Version with macOS specific enhancements can be downloaded from \textbf{Description}: Sets SMBIOS vendor fields to \texttt{Acidanthera}. It is dangerous to use Apple in SMBIOS vendor fields for reasons given - in \texttt{SystemManufacturer} description. However, certain firmwares - may not provide valid values otherwise, which could break some software. + in \texttt{SystemManufacturer} description. However, certain \DIFdelbegin \DIFdel{firmwares + }\DIFdelend \DIFaddbegin \DIFadd{firmware + }\DIFaddend may not provide valid values otherwise, which could break some software. \item \texttt{AdviseWindows}\\ @@ -4634,7 +4659,7 @@ be used. Version with macOS specific enhancements can be downloaded from \texttt{gEfiProcessorSubClassGuid}. This value contains CPU ART frequency, also known as crystal clock frequency. - Its existence is exclusive to Skylake generation and newer. The value is specified + Its existence is exclusive to \DIFaddbegin \DIFadd{the }\DIFaddend Skylake generation and newer. The value is specified in Hz, and is normally 24 MHz for client Intel segment, 25 MHz for server Intel segment, and 19.2 MHz for Intel Atom CPUs. macOS till 10.15 inclusive assumes 24 MHz by default. @@ -4746,10 +4771,10 @@ be used. Version with macOS specific enhancements can be downloaded from \textbf{Description}: Firmware version. This value gets updated and takes part in update delivery configuration and macOS version compatibility. This value could look like - \texttt{MM71.88Z.0234.B00.1809171422} in older firmwares, and is + \texttt{MM71.88Z.0234.B00.1809171422} in older \DIFdelbegin \DIFdel{firmwares, }\DIFdelend \DIFaddbegin \DIFadd{firmware }\DIFaddend and is described in \href{https://github.com/acidanthera/OpenCorePkg/blob/master/Include/Apple/Guid/BiosId.h}{BiosId.h}. - In newer firmwares it should look like \texttt{236.0.0.0.0} or + In newer \DIFdelbegin \DIFdel{firmwares }\DIFdelend \DIFaddbegin \DIFadd{firmware, }\DIFaddend it should look like \texttt{236.0.0.0.0} or \texttt{220.230.16.0.0\ (iBridge:\ 16.16.2542.0.0,0)}. iBridge version is read from \texttt{BridgeOSVersion} variable, and is only present on macs with T2. @@ -4786,7 +4811,7 @@ Apple ROM Version the operating system, such as firmware updates, eficheck, as well as kernel extensions developed in Acidanthera, such as Lilu and its plugins. In addition it will also make some operating systems - like Linux unbootable. + \DIFdelbegin \DIFdel{like }\DIFdelend \DIFaddbegin \DIFadd{such as }\DIFaddend Linux unbootable. \item \texttt{SystemProductName}\\ \textbf{Type}: \texttt{plist\ string}\\ @@ -5016,7 +5041,7 @@ even cause permanent firmware damage. Some of the known drivers are listed below \begin{tabular}{p{1.3in}p{5.55in}} \href{https://github.com/acidanthera/OpenCorePkg}{\texttt{AudioDxe}}\textbf{*} -& HDA audio support driver in UEFI firmwares for most Intel and some other analog audio controllers. +& HDA audio support driver in UEFI \DIFdelbegin \DIFdel{firmwares }\DIFdelend \DIFaddbegin \DIFadd{firmware }\DIFaddend for most Intel and some other analog audio controllers. Staging driver, refer to \href{https://github.com/acidanthera/bugtracker/issues/740}{acidanthera/bugtracker\#740} for known issues in AudioDxe. \\ \href{https://github.com/acidanthera/OpenCorePkg}{\texttt{CrScreenshotDxe}}\textbf{*} @@ -5026,25 +5051,26 @@ even cause permanent firmware damage. Some of the known drivers are listed below driver by \href{https://github.com/NikolajSchlej}{Nikolaj Schlej}. \\ \href{https://github.com/acidanthera/OcBinaryData}{\texttt{ExFatDxe}} & Proprietary ExFAT file system driver for Bootcamp support commonly found in Apple - firmwares. For Sandy Bridge and earlier CPUs \texttt{ExFatDxeLegacy} driver should be + \DIFdelbegin \DIFdel{firmwares}\DIFdelend \DIFaddbegin \DIFadd{firmware}\DIFaddend . For Sandy Bridge and earlier CPUs \texttt{ExFatDxeLegacy} driver should be used due to the lack of \texttt{RDRAND} instruction support. \\ \href{https://github.com/acidanthera/OcBinaryData}{\texttt{HfsPlus}} & Proprietary HFS file system driver with bless support commonly found in Apple - firmwares. For Sandy Bridge and earlier CPUs \texttt{HfsPlusLegacy} driver should be + \DIFdelbegin \DIFdel{firmwares}\DIFdelend \DIFaddbegin \DIFadd{firmware}\DIFaddend . For Sandy Bridge and earlier CPUs \texttt{HfsPlusLegacy} driver should be used due to the lack of \texttt{RDRAND} instruction support. \\ \href{https://github.com/acidanthera/audk}{\texttt{HiiDatabase}}\textbf{*} & HII services support driver from \texttt{MdeModulePkg}. This driver is included in - most firmwares starting with Ivy Bridge generation. Some applications with the GUI - like UEFI Shell may need this driver to work properly. \\ + most \DIFdelbegin \DIFdel{firmwares starting with }\DIFdelend \DIFaddbegin \DIFadd{types of firmware starting with the }\DIFaddend Ivy Bridge generation. Some applications with \DIFdelbegin \DIFdel{the GUIlike UEFI Shell}\DIFdelend \DIFaddbegin \DIFadd{GUI, + such as UEFI Shell, }\DIFaddend may need this driver to work properly. \\ \href{https://github.com/acidanthera/audk}{\texttt{EnhancedFatDxe}} & FAT filesystem driver from \texttt{FatPkg}. This driver is embedded in all - UEFI firmwares, and cannot be used from OpenCore. It is known that multiple firmwares - have a bug in their FAT support implementation, which leads to corrupted filesystems - on write attempt. Embedding this driver within the firmware may be required in case - writing to EFI partition is needed during the boot process. \\ + UEFI \DIFdelbegin \DIFdel{firmwares, }\DIFdelend \DIFaddbegin \DIFadd{firmware }\DIFaddend and cannot be used from OpenCore. \DIFdelbegin \DIFdel{It is known that multiple firmwares + have a bug in their }\DIFdelend \DIFaddbegin \DIFadd{Sevaral firmware + have a flawed }\DIFaddend FAT support implementation \DIFdelbegin \DIFdel{, which leads }\DIFdelend \DIFaddbegin \DIFadd{that may lead }\DIFaddend to corrupted filesystems + on write \DIFdelbegin \DIFdel{attempt}\DIFdelend \DIFaddbegin \DIFadd{attempts}\DIFaddend . Embedding this driver within the firmware may be required in case + writing to \DIFaddbegin \DIFadd{the }\DIFaddend EFI partition is needed during the boot process. \\ \href{https://github.com/acidanthera/audk}{\texttt{NvmExpressDxe}}\textbf{*} & NVMe support driver from \texttt{MdeModulePkg}. This driver is included in most - firmwares starting with Broadwell generation. For Haswell and earlier embedding it + \DIFdelbegin \DIFdel{firmwares starting with }\DIFdelend \DIFaddbegin \DIFadd{firmware starting with the }\DIFaddend Broadwell generation. For Haswell and earlier\DIFaddbegin \DIFadd{, }\DIFaddend embedding it within the firmware may be more favourable in case a NVMe SSD drive is installed. \\ \href{https://github.com/acidanthera/OpenCorePkg}{\texttt{OpenCanopy}}\textbf{*} & \hyperref[ueficanopy]{OpenCore plugin} implementing graphical interface. \\ @@ -5056,32 +5082,36 @@ even cause permanent firmware damage. Some of the known drivers are listed below builtin \texttt{KeySupport}, which may work better or worse depending on the firmware. \\ \href{https://github.com/acidanthera/OcBinaryData}{\texttt{PartitionDxe}} & Proprietary partition management driver with Apple Partitioning Scheme support - commonly found in Apple firmwares. This driver can be used to support loading + commonly found in Apple \DIFdelbegin \DIFdel{firmwares}\DIFdelend \DIFaddbegin \DIFadd{firmware}\DIFaddend . This driver can be used to support loading older DMG recoveries such as macOS 10.9 using Apple Partitioning Scheme. For Sandy Bridge and earlier CPUs \texttt{PartitionDxeLegacy} driver should be used due to the lack of \texttt{RDRAND} instruction support. \\ \href{https://github.com/acidanthera/audk}{\texttt{Ps2KeyboardDxe}}\textbf{*} -& PS/2 keyboard driver from \texttt{MdeModulePkg}. \texttt{OpenDuetPkg} and some firmwares - may not include this driver, but it is necessary for PS/2 keyboard to work. +& PS/2 keyboard driver from \texttt{MdeModulePkg}. \texttt{OpenDuetPkg} and some \DIFdelbegin \DIFdel{firmwares + }\DIFdelend \DIFaddbegin \DIFadd{types of firmware + }\DIFaddend may not include this driver, but it is necessary for PS/2 keyboard to work. Note, unlike \texttt{OpenUsbKbDxe} this driver has no \texttt{AppleKeyMapAggregator} support and thus requires \texttt{KeySupport} to be enabled. \\ \href{https://github.com/acidanthera/audk}{\texttt{Ps2MouseDxe}}\textbf{*} -& PS/2 mouse driver from \texttt{MdeModulePkg}. Some very old laptop firmwares - may not include this driver, but it is necessary for touchpad to work - in UEFI graphical interfaces, such as \texttt{OpenCanopy}. \\ +& PS/2 mouse driver from \texttt{MdeModulePkg}. Some very old laptop \DIFdelbegin \DIFdel{firmwares + }\DIFdelend \DIFaddbegin \DIFadd{firmware + }\DIFaddend may not include this driver \DIFdelbegin \DIFdel{, }\DIFdelend but it is necessary for \DIFaddbegin \DIFadd{the }\DIFaddend touchpad to work + in UEFI graphical interfaces \DIFdelbegin \DIFdel{, }\DIFdelend such as \texttt{OpenCanopy}. \\ \href{https://github.com/acidanthera/audk}{\texttt{UsbMouseDxe}}\textbf{*} -& USB mouse driver from \texttt{MdeModulePkg}. Some virtual machine firmwares - like OVMF may not include this driver, but it is necessary for mouse to work - in UEFI graphical interfaces, such as \texttt{OpenCanopy}. \\ +& USB mouse driver from \texttt{MdeModulePkg}. Some virtual machine \DIFdelbegin \DIFdel{firmwares + like }\DIFdelend \DIFaddbegin \DIFadd{firmware + such as }\DIFaddend OVMF may not include this driver \DIFdelbegin \DIFdel{, }\DIFdelend but it is necessary for \DIFaddbegin \DIFadd{the }\DIFaddend mouse to work + in UEFI graphical interfaces \DIFdelbegin \DIFdel{, }\DIFdelend such as \texttt{OpenCanopy}. \\ \href{https://github.com/acidanthera/OpenCorePkg}{\texttt{VBoxHfs}} & HFS file system driver with bless support. This driver is an alternative to - a closed source \texttt{HfsPlus} driver commonly found in Apple firmwares. While + a closed source \texttt{HfsPlus} driver commonly found in Apple \DIFdelbegin \DIFdel{firmwares}\DIFdelend \DIFaddbegin \DIFadd{firmware}\DIFaddend . While it is feature complete, it is approximately 3~times slower and is yet to undergo a security audit. \\ \href{https://github.com/acidanthera/audk}{\texttt{XhciDxe}}\textbf{*} & XHCI USB controller support driver from \texttt{MdeModulePkg}. This driver is - included in most firmwares starting with Sandy Bridge generation. For earlier firmwares - or legacy systems it may be used to support external USB 3.0 PCI cards. + included in most \DIFdelbegin \DIFdel{firmwares starting with }\DIFdelend \DIFaddbegin \DIFadd{types of firmware starting with the }\DIFaddend Sandy Bridge generation. For earlier \DIFdelbegin \DIFdel{firmwares + }\DIFdelend \DIFaddbegin \DIFadd{firmware + }\DIFaddend or legacy systems\DIFaddbegin \DIFadd{, }\DIFaddend it may be used to support external USB 3.0 PCI cards. \end{tabular} Driver marked with \textbf{*} are bundled with OpenCore. @@ -5147,7 +5177,7 @@ Some of the known tools are listed below (builtin tools are marked with \textbf{ when launching from OpenCore. \\ \href{https://github.com/acidanthera/OpenCorePkg}{\texttt{OpenShell}}\textbf{*} & OpenCore-configured \href{http://github.com/tianocore/edk2}{\texttt{UEFI Shell}} for compatibility - with a broad range of firmwares. \\ + with a broad range of \DIFdelbegin \DIFdel{firmwares}\DIFdelend \DIFaddbegin \DIFadd{firmware}\DIFaddend . \\ \href{https://github.com/acidanthera/OpenCorePkg}{\texttt{PavpProvision}} & Perform EPID provisioning (requires certificate data configuration). \\ \href{https://github.com/acidanthera/OpenCorePkg}{\texttt{ResetSystem}}\textbf{*} @@ -5236,7 +5266,7 @@ functioning. Feature highlights: \item NVRAM namespaces, allowing to isolate operating systems from accessing select variables (e.g. \texttt{RequestBootVarRouting} or \texttt{ProtectSecureBoot}). \item Read-only and write-only NVRAM variables, enhancing the security of OpenCore, - Lilu, and Lilu plugins, like VirtualSMC, which implements \texttt{AuthRestart} support. + Lilu, and Lilu plugins, \DIFdelbegin \DIFdel{like }\DIFdelend \DIFaddbegin \DIFadd{such as }\DIFaddend VirtualSMC, which implements \texttt{AuthRestart} support. \item NVRAM isolation, allowing to protect all variables from being written from an untrusted operating system (e.g. \texttt{DisableVariableWrite}). \item UEFI Runtime Services memory protection management to workaround read-only @@ -5306,9 +5336,9 @@ functioning. Feature highlights: or audio drivers. While effective, this option may not be necessary for drivers performing automatic connection, and may slightly slowdown the boot. - \emph{Note}: Some firmwares, made by Apple in particular, only connect the boot + \emph{Note}: Some \DIFdelbegin \DIFdel{firmwares, }\DIFdelend \DIFaddbegin \DIFadd{types of firmware, particularly those }\DIFaddend made by Apple\DIFdelbegin \DIFdel{in particular}\DIFdelend , only connect the boot drive to speed up the boot process. Enable this option to be able to see all the - boot options when having multiple drives. + boot options when \DIFdelbegin \DIFdel{having }\DIFdelend \DIFaddbegin \DIFadd{running }\DIFaddend multiple drives. \item \texttt{Drivers}\\ @@ -5385,8 +5415,9 @@ functioning. Feature highlights: Instead of partition handle connection normally used for APFS driver loading every handle is connected recursively. This may take more time than usual - but can be the only way to access APFS partitions on some firmwares like - those found on older HP laptops. + but can be the only way to access APFS partitions on some \DIFdelbegin \DIFdel{firmwares like + those found }\DIFdelend \DIFaddbegin \DIFadd{types of firmware such as + those }\DIFaddend on older HP laptops. \item \texttt{HideVerbose}\\ @@ -5568,7 +5599,7 @@ functioning. Feature highlights: \textbf{Failsafe}: \texttt{false}\\ \textbf{Description}: Enable keyboard input sanity checking. - Apparently some boards like GA Z77P-D3 may return uninitialised data + Apparently some boards \DIFdelbegin \DIFdel{like }\DIFdelend \DIFaddbegin \DIFadd{such as the }\DIFaddend GA Z77P-D3 may return uninitialised data in \texttt{EFI\_INPUT\_KEY} with all input protocols. This option discards keys that are neither ASCII, nor are defined in the UEFI specification (see tables 107 and 108 in version 2.8). @@ -5711,9 +5742,10 @@ functioning. Feature highlights: a different set of options. It is recommended to use \texttt{Builtin} renderer, as it supports HiDPI mode and uses full screen resolution. - UEFI firmwares generally support \texttt{ConsoleControl} with two - rendering modes: \texttt{Graphics} and \texttt{Text}. Some firmwares - do not support \texttt{ConsoleControl} and rendering modes. OpenCore + UEFI \DIFdelbegin \DIFdel{firmwares generally support }\DIFdelend \DIFaddbegin \DIFadd{firmware generally supports }\DIFaddend \texttt{ConsoleControl} with two + rendering modes: \texttt{Graphics} and \texttt{Text}. Some \DIFdelbegin \DIFdel{firmwares + }\DIFdelend \DIFaddbegin \DIFadd{types of firmware + }\DIFaddend do not support \texttt{ConsoleControl} and rendering modes. OpenCore and macOS expect text to only be shown in \texttt{Graphics} mode and graphics to be drawn in any mode. Since this is not required by UEFI specification, exact behaviour varies. @@ -5742,7 +5774,7 @@ functioning. Feature highlights: For most platforms it is necessary to enable \texttt{ProvideConsoleGop}, set \texttt{Resolution} to \texttt{Max}. \texttt{BuiltinText} variant is an alternative \texttt{BuiltinGraphics} for some very old and buggy laptop - firmwares, which can only draw in \texttt{Text} mode. + \DIFdelbegin \DIFdel{firmwares}\DIFdelend \DIFaddbegin \DIFadd{firmware}\DIFaddend , which can only draw in \texttt{Text} mode. The use of \texttt{System} protocols is more complicated. In general the preferred setting is \texttt{SystemGraphics} or \texttt{SystemText}. @@ -5768,7 +5800,7 @@ functioning. Feature highlights: \texttt{Builtin} text renderer supports only one console mode, so this option is ignored. - \emph{Note}: This field is best to be left empty on most firmwares. + \emph{Note}: This field is best \DIFdelbegin \DIFdel{to be }\DIFdelend left empty on most \DIFdelbegin \DIFdel{firmwares}\DIFdelend \DIFaddbegin \DIFadd{types of firmware}\DIFaddend . \item \texttt{Resolution}\\ @@ -5799,8 +5831,8 @@ functioning. Feature highlights: \texttt{ClearScreenOnModeSwitch}\\ \textbf{Type}: \texttt{plist\ boolean}\\ \textbf{Failsafe}: \texttt{false}\\ - \textbf{Description}: Some firmwares clear only part of screen when switching - from graphics to text mode, leaving a fragment of previously drawn image visible. + \textbf{Description}: Some \DIFdelbegin \DIFdel{firmwares clear only part of }\DIFdelend \DIFaddbegin \DIFadd{types of firmware only clear part of the }\DIFaddend screen when switching + from graphics to text mode, leaving a fragment of previously drawn \DIFdelbegin \DIFdel{image }\DIFdelend \DIFaddbegin \DIFadd{images }\DIFaddend visible. This option fills the entire graphics screen with black colour before switching to text mode. @@ -5812,27 +5844,29 @@ functioning. Feature highlights: \textbf{Failsafe}: \texttt{false}\\ \textbf{Description}: Use builtin graphics output protocol renderer for console. - On some firmwares this may provide better performance or even fix rendering issues, - like on \texttt{MacPro5,1}. However, it is recommended not to use this option unless - there is an obvious benefit as it may even result in slower scrolling. + On some \DIFdelbegin \DIFdel{firmwares }\DIFdelend \DIFaddbegin \DIFadd{types of firmware, such as on the }\texttt{\DIFadd{MacPro5,1}}\DIFadd{, }\DIFaddend this may provide better + performance or \DIFdelbegin \DIFdel{even }\DIFdelend fix rendering issues\DIFdelbegin \DIFdel{, + like on }\texttt{\DIFdel{MacPro5,1}}%DIFAUXCMD +\DIFdelend . However, \DIFdelbegin \DIFdel{it is recommended not to use this option }\DIFdelend \DIFaddbegin \DIFadd{this option is not recommended }\DIFaddend unless + there is an obvious benefit as it may \DIFdelbegin \DIFdel{even result in }\DIFdelend \DIFaddbegin \DIFadd{result in issues such as }\DIFaddend slower scrolling. \item \texttt{IgnoreTextInGraphics}\\ \textbf{Type}: \texttt{plist\ boolean}\\ \textbf{Failsafe}: \texttt{false}\\ - \textbf{Description}: Select firmwares output text onscreen in both graphics and - text mode. This is normally unexpected, because random text may appear over + \textbf{Description}: \DIFdelbegin \DIFdel{Select firmwares }\DIFdelend \DIFaddbegin \DIFadd{Some types of firmware }\DIFaddend output text onscreen in both graphics and + text mode. This is \DIFdelbegin \DIFdel{normally unexpected , because }\DIFdelend \DIFaddbegin \DIFadd{typically unexpected as }\DIFaddend random text may appear over graphical images and cause UI corruption. Setting this option to \texttt{true} will - discard all text output when console control is in mode different from \texttt{Text}. + discard all text output when console control is in \DIFdelbegin \DIFdel{mode different }\DIFdelend \DIFaddbegin \DIFadd{a different mode }\DIFaddend from \texttt{Text}. - \emph{Note}: This option only applies to \texttt{System} renderer. + \emph{Note}: This option only applies to \DIFaddbegin \DIFadd{the }\DIFaddend \texttt{System} renderer. \item \texttt{ReplaceTabWithSpace}\\ \textbf{Type}: \texttt{plist\ boolean}\\ \textbf{Failsafe}: \texttt{false}\\ - \textbf{Description}: Some firmwares do not print tab characters or even everything - that follows them, causing difficulties or inability to use the UEFI Shell builtin + \textbf{Description}: Some \DIFdelbegin \DIFdel{firmwares }\DIFdelend \DIFaddbegin \DIFadd{types of firmware }\DIFaddend do not print tab characters or \DIFdelbegin \DIFdel{even }\DIFdelend everything + that follows them, causing difficulties \DIFdelbegin \DIFdel{or inability to use }\DIFdelend \DIFaddbegin \DIFadd{in using }\DIFaddend the UEFI Shell\DIFaddbegin \DIFadd{'s }\DIFaddend builtin text editor to edit property lists and other documents. This option makes the console output spaces instead of tabs. @@ -5858,9 +5892,10 @@ functioning. Feature highlights: \textbf{Failsafe}: \texttt{false}\\ \textbf{Description}: Reconnect console controllers after changing screen resolution. - On some firmwares when screen resolution is changed via GOP, it is required to reconnect - the controllers, which produce the console protocols (simple text out). Otherwise they - will not produce text based on the new resolution. + On some \DIFdelbegin \DIFdel{firmwares when screen resolution is changed via GOP, it is required to reconnect + the controllers , which }\DIFdelend \DIFaddbegin \DIFadd{types of firmware, the controllers that }\DIFaddend produce the console protocols + (simple text out) \DIFaddbegin \DIFadd{must be reconnected when the screen resolution is changed via GOP}\DIFaddend . + Otherwise they will not produce text based on the new resolution. \emph{Note}: On several boards this logic may result in black screen when launching OpenCore from Shell and thus it is optional. In versions prior to 0.5.2 this option @@ -5870,8 +5905,8 @@ functioning. Feature highlights: \texttt{SanitiseClearScreen}\\ \textbf{Type}: \texttt{plist\ boolean}\\ \textbf{Failsafe}: \texttt{false}\\ - \textbf{Description}: Some firmwares reset screen resolution to a failsafe - value (like \texttt{1024x768}) on the attempts to clear screen contents + \textbf{Description}: Some \DIFdelbegin \DIFdel{firmwares reset screen resolution }\DIFdelend \DIFaddbegin \DIFadd{types of firmware reset screen resolutions }\DIFaddend to a failsafe + value (\DIFdelbegin \DIFdel{like }\DIFdelend \DIFaddbegin \DIFadd{such as }\DIFaddend \texttt{1024x768}) on the attempts to clear screen contents when large display (e.g. 2K or 4K) is used. This option attempts to apply a workaround. @@ -5885,8 +5920,8 @@ functioning. Feature highlights: \textbf{Failsafe}: \texttt{false}\\ \textbf{Description}: Provide UGA protocol instances on top of GOP protocol. - Some firmwares do not implement legacy UGA protocol, but it may be required - for screen output by older EFI applications like EfiBoot from 10.4. + Some \DIFdelbegin \DIFdel{firmwares }\DIFdelend \DIFaddbegin \DIFadd{types of firmware }\DIFaddend do not implement \DIFaddbegin \DIFadd{the }\DIFaddend legacy UGA protocol \DIFdelbegin \DIFdel{, but it }\DIFdelend \DIFaddbegin \DIFadd{but this }\DIFaddend may be required + for screen output by older EFI applications \DIFdelbegin \DIFdel{like }\DIFdelend \DIFaddbegin \DIFadd{such as }\DIFaddend EfiBoot from 10.4. \end{enumerate} @@ -5947,7 +5982,7 @@ functioning. Feature highlights: \textbf{Failsafe}: \texttt{false}\\ \textbf{Description}: Reinstalls Apple Framebuffer Info protocol with a builtin version. This may be used to override framebuffer information on VMs or legacy Macs - to improve compatibility with legacy EfiBoot like the one in macOS 10.4. + to improve compatibility with legacy EfiBoot \DIFdelbegin \DIFdel{like }\DIFdelend \DIFaddbegin \DIFadd{such as }\DIFaddend the one in macOS 10.4. \item \texttt{AppleImageConversion}\\ @@ -6090,11 +6125,12 @@ functioning. Feature highlights: or anyhow corrupted. \end{itemize} - However, some firmwares do their own boot option scanning upon startup by checking - file presence on the available disks. Quite often this scanning includes non-standard - locations, such as Windows Bootloader paths. Normally it is not an issue, but some - firmwares, ASUS firmwares on APTIO V in particular, have bugs. For them scanning is - implemented improperly, and firmware preferences may get accidentally corrupted + However, some \DIFdelbegin \DIFdel{firmwares }\DIFdelend \DIFaddbegin \DIFadd{types of firmware }\DIFaddend do their own boot option scanning \DIFdelbegin \DIFdel{upon }\DIFdelend \DIFaddbegin \DIFadd{on }\DIFaddend startup by checking + \DIFaddbegin \DIFadd{for }\DIFaddend file presence on the available disks. \DIFdelbegin \DIFdel{Quite often this scanning }\DIFdelend \DIFaddbegin \DIFadd{This scanning often }\DIFaddend includes non-standard + locations \DIFdelbegin \DIFdel{, }\DIFdelend such as Windows Bootloader paths. \DIFdelbegin \DIFdel{Normally it is }\DIFdelend \DIFaddbegin \DIFadd{This is typically }\DIFaddend not an issue \DIFdelbegin \DIFdel{, but some + firmwares, ASUS firmwares on APTIO V in particular}\DIFdelend \DIFaddbegin \DIFadd{but some + firmware, such as ASUS firmware on the APTIO V}\DIFaddend , have bugs. \DIFdelbegin \DIFdel{For them }\DIFdelend \DIFaddbegin \DIFadd{On such, }\DIFaddend scanning is + implemented improperly \DIFdelbegin \DIFdel{, }\DIFdelend and firmware preferences may get accidentally corrupted due to \texttt{BootOrder} entry duplication (each option will be added twice) making it impossible to boot without resetting NVRAM. @@ -6114,31 +6150,34 @@ functioning. Feature highlights: \textbf{Description}: Adds delay in microseconds after \texttt{EXIT\_BOOT\_SERVICES} event. - This is a very ugly quirk to circumvent "Still waiting for root device" message - on select APTIO IV firmwares, namely ASUS Z87-Pro, when using FileVault 2 in particular. - It seems that for some reason they execute code in parallel to \texttt{EXIT\_BOOT\_SERVICES}, - which results in SATA controller being inaccessible from macOS. A better approach should be - found in some future. Expect 3-5 seconds to be enough in case the quirk is needed. + This is a very \DIFdelbegin \DIFdel{ugly quirk to circumvent "Still waiting for root device" message + on select APTIO IV firmwares, namely }\DIFdelend \DIFaddbegin \DIFadd{rough workaround to circumvent the }\texttt{\DIFadd{Still\ waiting\ for\ root\ device}} \DIFadd{message + on some APTIO IV firmware (}\DIFaddend ASUS Z87-Pro\DIFdelbegin \DIFdel{, }\DIFdelend \DIFaddbegin \DIFadd{) particularly }\DIFaddend when using FileVault \DIFdelbegin \DIFdel{2 in particular. + It seems }\DIFdelend \DIFaddbegin \DIFadd{2. + It appears }\DIFaddend that for some reason\DIFaddbegin \DIFadd{, }\DIFaddend they execute code in parallel to \texttt{EXIT\_BOOT\_SERVICES}, + which results in \DIFaddbegin \DIFadd{the }\DIFaddend SATA controller being inaccessible from macOS. A better approach should be + found in some future. Expect \DIFdelbegin \DIFdel{3-5 }\DIFdelend \DIFaddbegin \DIFadd{3 to 5 }\DIFaddend seconds to be \DIFdelbegin \DIFdel{enough in case the }\DIFdelend \DIFaddbegin \DIFadd{adequate when this }\DIFaddend quirk is needed. \item \texttt{IgnoreInvalidFlexRatio}\\ \textbf{Type}: \texttt{plist\ boolean}\\ \textbf{Failsafe}: \texttt{false}\\ - \textbf{Description}: Select firmwares, namely APTIO IV, may contain invalid values in - \texttt{MSR\_FLEX\_RATIO} (\texttt{0x194}) MSR register. These values may cause - macOS boot failure on Intel platforms. + \textbf{Description}: \DIFdelbegin \DIFdel{Select firmwares, namely APTIO IV, }\DIFdelend \DIFaddbegin \DIFadd{Some types of firmware (such as APTIO IV) }\DIFaddend may contain invalid values in \DIFaddbegin \DIFadd{the + }\DIFaddend \texttt{MSR\_FLEX\_RATIO} (\texttt{0x194}) MSR register. These values may cause + macOS boot \DIFdelbegin \DIFdel{failure }\DIFdelend \DIFaddbegin \DIFadd{failures }\DIFaddend on Intel platforms. - \emph{Note}: While the option is not supposed to induce harm on unaffected firmwares, - its usage is not recommended when it is not required. + \emph{Note}: While the option is not \DIFdelbegin \DIFdel{supposed to induce harm on unaffected firmwares, + its usage is not }\DIFdelend \DIFaddbegin \DIFadd{expected to harm unaffected firmware, + its use is only }\DIFaddend recommended when it is \DIFdelbegin \DIFdel{not }\DIFdelend \DIFaddbegin \DIFadd{specifically }\DIFaddend required. \item \texttt{ReleaseUsbOwnership}\\ \textbf{Type}: \texttt{plist\ boolean}\\ \textbf{Failsafe}: \texttt{false}\\ \textbf{Description}: Attempt to detach USB controller ownership from - the firmware driver. While most firmwares manage to properly do that, - or at least have an option for, select firmwares do not. As a result, - operating system may freeze upon boot. Not recommended unless required. + the firmware driver. While most \DIFdelbegin \DIFdel{firmwares manage to properly do that }\DIFdelend \DIFaddbegin \DIFadd{types of firmware manage to do that properly}\DIFaddend , + or at least have an option for \DIFdelbegin \DIFdel{, select firmwares }\DIFdelend \DIFaddbegin \DIFadd{this, some }\DIFaddend do not. As a result, + \DIFaddbegin \DIFadd{the }\DIFaddend operating system may freeze upon boot. Not recommended unless required. \item \texttt{RequestBootVarRouting}\\ @@ -6149,9 +6188,9 @@ functioning. Feature highlights: This quirk requires \texttt{OC\_FIRMWARE\_RUNTIME} protocol implemented in \texttt{OpenRuntime.efi}. The quirk lets default boot entry - preservation at times when firmwares delete incompatible boot entries. - Simply said, this quirk is required to reliably - use \href{https://support.apple.com/HT202796}{Startup Disk} preference + preservation at times when \DIFdelbegin \DIFdel{firmwares delete }\DIFdelend \DIFaddbegin \DIFadd{the firmware deletes }\DIFaddend incompatible boot entries. + \DIFdelbegin \DIFdel{Simply said}\DIFdelend \DIFaddbegin \DIFadd{In summary}\DIFaddend , this quirk is required to reliably + use \DIFaddbegin \DIFadd{the }\DIFaddend \href{https://support.apple.com/HT202796}{Startup Disk} preference pane in firmware that is not compatible with macOS boot entries by design. \item @@ -6168,23 +6207,25 @@ functioning. Feature highlights: This is an experimental quirk, which should only be used for the aforementioned problem. In all other cases the quirk may render the operating system unstable and is not recommended. - The recommended solution in the other cases is to install a kernel driver like - \href{https://github.com/RehabMan/VoodooTSCSync}{VoodooTSCSync}, + The recommended solution in the other cases is to install a kernel driver \DIFdelbegin \DIFdel{like + }\DIFdelend \DIFaddbegin \DIFadd{such as + }\DIFaddend \href{https://github.com/RehabMan/VoodooTSCSync}{VoodooTSCSync}, \href{https://github.com/interferenc/TSCAdjustReset}{TSCAdjustReset}, or \href{https://github.com/lvs1974/CpuTscSync}{CpuTscSync} (a more specialised variant of VoodooTSCSync for newer laptops). \emph{Note}: The reason this quirk cannot replace the kernel driver is - because it cannot operate in ACPI S3 mode (sleep wake) and because the UEFI firmwares - provide very limited multicore support preventing the precise update of the MSR + because it cannot operate in ACPI S3 mode (sleep wake) and because the UEFI \DIFdelbegin \DIFdel{firmwares + provide }\DIFdelend \DIFaddbegin \DIFadd{firmware + provides }\DIFaddend very limited multicore support preventing the precise update of the MSR registers. \item \texttt{UnblockFsConnect}\\ \textbf{Type}: \texttt{plist\ boolean}\\ \textbf{Failsafe}: \texttt{false}\\ - \textbf{Description}: Some firmwares block partition handles by opening them - in By Driver mode, which results in File System protocols being unable to install. + \textbf{Description}: Some \DIFdelbegin \DIFdel{firmwares }\DIFdelend \DIFaddbegin \DIFadd{types of firmware }\DIFaddend block partition handles by opening them + in \DIFdelbegin \DIFdel{By Driver mode, which results in File System protocols }\DIFdelend \DIFaddbegin \texttt{\DIFadd{By\ Driver}} \DIFadd{mode, resulting in }\DIFaddend being unable to install \DIFaddbegin \DIFadd{File System protocols}\DIFaddend . \emph{Note}: The quirk is mostly relevant for select HP laptops with no drives listed. @@ -6204,7 +6245,7 @@ functioning. Feature highlights: The addresses written here must be part of the memory map, have \texttt{EfiConventionalMemory} type, and page-aligned (4 KBs). - \emph{Note}: Some firmwares may not allocate memory areas used by S3 (sleep) and S4 (hibernation) + \emph{Note}: Some \DIFdelbegin \DIFdel{firmwares }\DIFdelend \DIFaddbegin \DIFadd{types of firmware }\DIFaddend may not allocate memory areas used by S3 (sleep) and S4 (hibernation) code unless CSM is enabled causing wake failures. After comparing the memory maps with CSM disabled and enabled, these areas can be found in the lower memory and can be fixed up by doing the reservation. See \texttt{Sample.plist} for more details. @@ -6302,8 +6343,9 @@ Since it is not always accurate, the latest versions are listed below. unsupported on macOS~10.7 and older as they require newer kernel APIs, which are not part of the macOS~10.7 SDK. \item Prior to macOS~10.8 KASLR sliding is not supported, which - will result in memory allocation failures on firmwares - that utilise lower memory for their own purposes. Refer to + will result in memory allocation failures on \DIFdelbegin \DIFdel{firmwares + }\DIFdelend \DIFaddbegin \DIFadd{firmware + }\DIFaddend that utilise lower memory for their own purposes. Refer to \href{https://github.com/acidanthera/bugtracker/issues/1125}{acidanthera/bugtracker\#1125} for tracking. \end{itemize} @@ -6387,7 +6429,7 @@ hdiutil convert ReadWrite.dmg -format UDZO -o ReadOnly.dmg \item Last released installer images for macOS~10.4 are macOS~10.4.10 builds \texttt{8R4061a} (for \texttt{MacBookPro3,1}) and \texttt{8R4088} (for \texttt{iMac7,1})). These images are limited - to their target model identifiers just like the newer macOS versions. + to their target model identifiers \DIFdelbegin \DIFdel{just like the }\DIFdelend \DIFaddbegin \DIFadd{as on }\DIFaddend newer macOS versions. Modified \texttt{8R4088} images (with \texttt{ACDT} suffix) without model restrictions can be found \href{https://mega.nz/folder/D3ASzLzA\#7sjYXE2X09f6aGjol\_C7dg}{here}, @@ -6426,7 +6468,7 @@ requires several steps and careful configuration of select settings as explained devices. It is a good idea to prohibit all removable drivers or unknown filesystems. \item Sign all the installed drivers and tools with the private key. Do not sign - tools that provide administrative access to the computer, like UEFI Shell. + tools that provide administrative access to the computer, \DIFdelbegin \DIFdel{like }\DIFdelend \DIFaddbegin \DIFadd{such as }\DIFaddend UEFI Shell. \item Vault the configuration as explained \hyperref[securevaulting]{Vaulting} section. \item Sign all OpenCore binaries (\texttt{BOOTX64.efi}, \texttt{BOOTIa32.efi}, @@ -6438,7 +6480,7 @@ requires several steps and careful configuration of select settings as explained \href{https://wiki.debian.org/SecureBoot}{Debian Wiki}. \item Enable UEFI Secure Boot in firmware preferences and install the certificate with a private key. Details on how to generate a certificate - can be found in various articles, like \href{https://habr.com/en/post/273497}{this one}, + can be found in various articles, \DIFdelbegin \DIFdel{like }\DIFdelend \DIFaddbegin \DIFadd{such as }\DIFaddend \href{https://habr.com/en/post/273497}{this one}, and are out of the scope of this document. If Windows is needed one will also need to add the \href{http://go.microsoft.com/fwlink/?LinkID=321192}{Microsoft Windows Production CA 2011}. @@ -6454,7 +6496,7 @@ requires several steps and careful configuration of select settings as explained While no official Windows support is provided, 64-bit UEFI Windows installations (Windows 8 and above) prepared with Boot Camp are supposed to work. Third-party UEFI installations - as well as systems partially supporting UEFI boot, like Windows 7, might work with + as well as systems partially supporting UEFI boot, \DIFdelbegin \DIFdel{like }\DIFdelend \DIFaddbegin \DIFadd{such as }\DIFaddend Windows 7, might work with some extra precautions. Things to consider: \begin{itemize} @@ -6467,8 +6509,9 @@ requires several steps and careful configuration of select settings as explained \href{https://github.com/acidanthera/bugtracker/issues/327}{workaround} for this, it is highly recommend not to rely on it and install properly. \item Windows may need to be reactivated. To avoid it consider - setting SystemUUID to the original firmware UUID. Be warned, - on old firmwares it may be invalid, i.e. not random. If there still are issues, + setting SystemUUID to the original firmware UUID. Be \DIFdelbegin \DIFdel{warned, + on old firmwares }\DIFdelend \DIFaddbegin \DIFadd{aware that }\DIFaddend it may be invalid + \DIFaddbegin \DIFadd{on old firmware}\DIFaddend , i.e.\DIFaddbegin \DIFadd{, }\DIFaddend not random. If there still are issues, consider using HWID or KMS38 license or making the use \texttt{Custom} \texttt{UpdateSMBIOSMode}. Other nuances of Windows activation are out of the scope of this document and can be found online. @@ -6503,7 +6546,7 @@ requires several steps and careful configuration of select settings as explained \item \texttt{RealTimeIsUniversal} must be set to \texttt{1} to avoid time desync between Windows and macOS as explained on \href{https://superuser.com/q/494432}{SuperUser} (this is usually not needed). - \item To access Apple filesystems like HFS and APFS separate software may need to + \item To access Apple filesystems \DIFdelbegin \DIFdel{like HFSand APFS }\DIFdelend \DIFaddbegin \DIFadd{such as HFS+ and APFS, }\DIFaddend separate software may need to be installed. Some of the known utilities are: \href{https://forums.macrumors.com/threads/apple-hfs-windows-driver-download.1368010/}{Apple HFS+ driver} (\href{https://forums.macrumors.com/threads/apple-hfs-windows-driver-download.1368010/post-24180079}{hack for Windows 10}), @@ -6617,7 +6660,7 @@ than 1 meter to avoid output corruption. To additionally enable XNU kernel seria \texttt{DEBUG\_INFO} (\texttt{0x00000040}) levels are visible onscreen: \texttt{Misc} $\rightarrow$ \texttt{Debug} $\rightarrow$ \texttt{DisplayLevel} $=$ \texttt{0x80000042}. - \item Critical error messages, like \texttt{DEBUG\_ERROR}, stop booting: + \item Critical error messages, \DIFdelbegin \DIFdel{like }\DIFdelend \DIFaddbegin \DIFadd{such as }\DIFaddend \texttt{DEBUG\_ERROR}, stop booting: \texttt{Misc} $\rightarrow$ \texttt{Security} $\rightarrow$ \texttt{HaltLevel} $=$ \texttt{0x80000000}. \item Watch Dog is disabled to prevent automatic reboot: @@ -6637,7 +6680,7 @@ than 1 meter to avoid output corruption. To additionally enable XNU kernel seria \begin{itemize} \tightlist - \item Refer to \texttt{boot-args} values like \texttt{debug=0x100}, \texttt{keepsyms=1}, + \item Refer to \texttt{boot-args} values \DIFdelbegin \DIFdel{like }\DIFdelend \DIFaddbegin \DIFadd{such as }\DIFaddend \texttt{debug=0x100}, \texttt{keepsyms=1}, \texttt{-v}, and similar. \item Do not forget about \texttt{AppleDebug} and \texttt{ApplePanic} properties. \item Take care of \texttt{Booter}, \texttt{Kernel}, and \texttt{UEFI} quirks. @@ -6663,7 +6706,7 @@ than 1 meter to avoid output corruption. To additionally enable XNU kernel seria \href{https://support.apple.com/HT202796}{Startup Disk} preference, or the Windows \href{https://support.apple.com/guide/bootcamp-control-panel/start-up-your-mac-in-windows-or-macos-bcmp29b8ac66/mac}{Boot Camp} Control Panel. Since choosing OpenCore's \texttt{BOOTx64.EFI} as a primary boot option limits this - functionality in addition to several firmwares deleting incompatible boot options, + functionality in addition to several \DIFdelbegin \DIFdel{firmwares }\DIFdelend \DIFaddbegin \DIFadd{types of firmware }\DIFaddend deleting incompatible boot options, potentially including those created by macOS, users are strongly encouraged to use the \texttt{RequestBootVarRouting} quirk, which will preserve the selection made in the operating system within the OpenCore variable space. Note, that \texttt{RequestBootVarRouting} @@ -6730,13 +6773,13 @@ than 1 meter to avoid output corruption. To additionally enable XNU kernel seria \item \texttt{SetupVirtualMap} \end{itemize} - However, as of today such set is strongly discouraged as some of these quirks + However, as of today\DIFaddbegin \DIFadd{, }\DIFaddend such set is strongly discouraged as some of these quirks are not necessary to be enabled or need additional quirks. For example, \texttt{DevirtualiseMmio} and \texttt{ProtectUefiServices} are often required, while \texttt{DiscardHibernateMap} and \texttt{ForceExitBootServices} are rarely necessary. - Unfortunately for some quirks like \texttt{RebuildAppleMemoryMap}, + Unfortunately for some quirks \DIFdelbegin \DIFdel{like }\DIFdelend \DIFaddbegin \DIFadd{such as }\DIFaddend \texttt{RebuildAppleMemoryMap}, \texttt{EnableWriteUnprotector}, \texttt{ProtectMemoryRegions}, \texttt{SetupVirtualMap}, and \texttt{SyncRuntimePermissions} there is no definite approach even on similar systems, so trying all their diff --git a/Docs/Errata/Errata.pdf b/Docs/Errata/Errata.pdf index 7ff54d9e..a85ad1d3 100644 Binary files a/Docs/Errata/Errata.pdf and b/Docs/Errata/Errata.pdf differ