diff --git a/Docs/Configuration.pdf b/Docs/Configuration.pdf index c4c2c8456467a301e194c373d313e2f03d901556..92c93618b2c00958b7f5f6b19c8ec1c28ff4ac32 100644 Binary files a/Docs/Configuration.pdf and b/Docs/Configuration.pdf differ diff --git a/Docs/Configuration.tex b/Docs/Configuration.tex index d63cfaae1156830f185d2ceb531e6c70bd944f9e..e47f153f1673fdad148fffa5d12b4d10b0149af2 100755 --- a/Docs/Configuration.tex +++ b/Docs/Configuration.tex @@ -89,7 +89,7 @@ \vspace{0.2in} - Reference Manual (0.5.6) + Reference Manual (0.5.7) \vspace{0.2in} diff --git a/Docs/Differences/Differences.pdf b/Docs/Differences/Differences.pdf index 1219b291e57b98a452fdc011f878448d5030ee5a..407f636f65ae60eeca1f20a65994ccd9e56f07a7 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 e6b062ee27a3da20d2ea8f37204765f0044574a4..67de6266b95a4b85e24986a613b5c65f2fddc80c 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 Sat Feb 29 16:48:42 2020 -%DIF ADD ../Configuration.tex Sun Mar 1 22:13:56 2020 +%DIF DEL PreviousConfiguration.tex Sun Mar 1 22:18:28 2020 +%DIF ADD ../Configuration.tex Mon Mar 2 22:37:12 2020 \usepackage{lmodern} \usepackage{amssymb,amsmath} @@ -149,7 +149,7 @@ \vspace{0.2in} - Reference Manual (0.5\DIFdelbegin \DIFdel{.5}\DIFdelend \DIFaddbegin \DIFadd{.6}\DIFaddend ) + Reference Manual (0.5\DIFdelbegin \DIFdel{.6}\DIFdelend \DIFaddbegin \DIFadd{.7}\DIFaddend ) \vspace{0.2in} @@ -185,7 +185,7 @@ articles, tools, books, etc., providing such material are prone to their authors preferences, tastes, this document misinterpretation, and essential obsolescence. In case you still use these sources, for example, \href{https://khronokernel-2.gitbook.io/opencore-vanilla-desktop-guide}{Opencore Vanilla Desktop Guide} -\DIFaddbegin \DIFadd{(}\href{https://khronokernel-1.gitbook.io/getting-started-with-opencore}{parent link}\DIFadd{)}\DIFaddend , +(\href{https://khronokernel-1.gitbook.io/getting-started-with-opencore}{parent link}), please ensure following this document for every made decision and judging its consequences. Regardless of the sources used you are required to fully understand every dedicated OpenCore configuration option and concept prior to reporting any issues in @@ -426,72 +426,7 @@ be relied upon, and all fields must be properly specified in the configuration. \subsection{Directory Structure}\label{directory-structure} \begin{center} -\DIFdelbegin %DIFDELCMD < \begin{tikzpicture}[% -%DIFDELCMD < grow via three points={one child at (0.5,-0.7) and -%DIFDELCMD < two children at (0.5,-0.7) and (0.5,-1.4)}, -%DIFDELCMD < edge from parent path={(\tikzparentnode.south) |- (\tikzchildnode.west)}] -%DIFDELCMD < \node {ESP} -%DIFDELCMD < child { node {EFI} -%DIFDELCMD < child { node {BOOT} -%DIFDELCMD < child { node [selected] {BOOTx64.efi}} -%DIFDELCMD < } -%DIFDELCMD < child [missing] {} -%DIFDELCMD < child { node {OC} -%DIFDELCMD < child { node {ACPI} -%DIFDELCMD < child { node [optional] {DSDT.aml}} -%DIFDELCMD < child { node [optional] {SSDT-1.aml}} -%DIFDELCMD < child { node [optional] {MYTABLE.aml}} -%DIFDELCMD < } -%DIFDELCMD < child [missing] {} -%DIFDELCMD < child [missing] {} -%DIFDELCMD < child [missing] {} -%DIFDELCMD < child { node {Drivers} -%DIFDELCMD < child { node [optional] {MyDriver.efi}} -%DIFDELCMD < child { node [optional] {OtherDriver.efi}} -%DIFDELCMD < } -%DIFDELCMD < child [missing] {} -%DIFDELCMD < child [missing] {} -%DIFDELCMD < child { node {Kexts} -%DIFDELCMD < child { node [optional] {MyKext.kext}} -%DIFDELCMD < child { node [optional] {OtherKext.kext}} -%DIFDELCMD < } -%DIFDELCMD < child [missing] {} -%DIFDELCMD < child [missing] {} -%DIFDELCMD < child { node {Tools} -%DIFDELCMD < child { node [optional] {Tool.efi}} -%DIFDELCMD < } -%DIFDELCMD < child [missing] {} -%DIFDELCMD < child { node [selected] {OpenCore.efi}} -%DIFDELCMD < child { node [optional] {vault.plist}} -%DIFDELCMD < child { node {config.plist}} -%DIFDELCMD < child { node [optional] {vault.sig}} -%DIFDELCMD < } -%DIFDELCMD < } -%DIFDELCMD < child [missing] {} -%DIFDELCMD < child [missing] {} -%DIFDELCMD < child [missing] {} -%DIFDELCMD < child [missing] {} -%DIFDELCMD < child [missing] {} -%DIFDELCMD < child [missing] {} -%DIFDELCMD < child [missing] {} -%DIFDELCMD < child [missing] {} -%DIFDELCMD < child [missing] {} -%DIFDELCMD < child [missing] {} -%DIFDELCMD < child [missing] {} -%DIFDELCMD < child [missing] {} -%DIFDELCMD < child [missing] {} -%DIFDELCMD < child [missing] {} -%DIFDELCMD < child [missing] {} -%DIFDELCMD < child [missing] {} -%DIFDELCMD < child [missing] {} -%DIFDELCMD < child [missing] {} -%DIFDELCMD < child [missing] {} -%DIFDELCMD < child { node [optional] {nvram.plist}} -%DIFDELCMD < child { node [optional] {opencore-YYYY-MM-DD-HHMMSS.txt}} -%DIFDELCMD < ; -%DIFDELCMD < \end{tikzpicture} -%DIFDELCMD < %%% -\DIFdelend \DIFaddbegin \begin{tikzpicture}[% +\begin{tikzpicture}[% grow via three points={one child at (0.5,-0.7) and two children at (0.5,-0.7) and (0.5,-1.4)}, edge from parent path={(\tikzparentnode.south) |- (\tikzchildnode.west)}] @@ -561,7 +496,7 @@ be relied upon, and all fields must be properly specified in the configuration. child { node [optional] {opencore-YYYY-MM-DD-HHMMSS.txt}} ; \end{tikzpicture} -\DIFaddend \break +\break \label{fig:DS} Figure 1. Directory Structure \end{center} @@ -593,13 +528,13 @@ entries include: Directory used for storing supplemental kernel information for \hyperref[kernel]{\texttt{Kernel}} section. \item - \DIFaddbegin \texttt{\DIFadd{Resources}} + \texttt{Resources} \break - \DIFadd{Directory used for storing media resources, such as audio files - for screen reader support. See }\hyperref[uefiaudioprops]{\texttt{UEFI Audio Properties}} - \DIFadd{section for more details. -}\item - \DIFaddend \texttt{Tools} + Directory used for storing media resources, such as audio files + for screen reader support. See \hyperref[uefiaudioprops]{\texttt{UEFI Audio Properties}} + section for more details. +\item + \texttt{Tools} \break Directory used for storing supplemental tools. \item @@ -654,8 +589,7 @@ For BIOS booting a third-party UEFI environment provider will have to be used. \texttt{DuetPkg} is one of the known UEFI environment providers for legacy systems. To run OpenCore on such a legacy system you can install \texttt{DuetPkg} with a dedicated tool: -\DIFdelbegin %DIFDELCMD < \href{https://github.com/acidanthera/OcSupportPkg/tree/master/Utilities/BootInstall}{BootInstall}%%% -\DIFdelend \DIFaddbegin \href{https://github.com/acidanthera/OpenCorePkg/tree/master/Utilities/BootInstall}{BootInstall}\DIFaddend . +\href{https://github.com/acidanthera/OpenCorePkg/tree/master/Utilities/BootInstall}{BootInstall}. For upgrade purposes refer to \texttt{Differences.pdf} document, providing the information about the changes affecting the configuration compared @@ -678,13 +612,8 @@ patches is welcome. Please do follow \href{https://github.com/tianocore/tianocore.github.io/wiki/Code-Style-C}{EDK II C Codestyle}. Required external package dependencies include -\DIFdelbegin %DIFDELCMD < \href{https://github.com/acidanthera/OcSupportPkg}{EfiPkg}%%% -\DIFdel{, -}%DIFDELCMD < \href{https://github.com/acidanthera/OcSupportPkg}{MacInfoPkg}%%% -\DIFdel{, and -}%DIFDELCMD < \href{https://github.com/acidanthera/OcSupportPkg}{OcSupportPkg}%%% -\DIFdelend \DIFaddbegin \href{https://github.com/acidanthera/EfiPkg}{EfiPkg} \DIFadd{and -}\href{https://github.com/acidanthera/MacInfoPkg}{MacInfoPkg}\DIFaddend . +\href{https://github.com/acidanthera/EfiPkg}{EfiPkg} and +\href{https://github.com/acidanthera/MacInfoPkg}{MacInfoPkg}. To compile with \texttt{XCODE5}, besides \href{https://developer.apple.com/xcode}{Xcode}, one should also install \href{https://www.nasm.us}{NASM} and @@ -692,39 +621,34 @@ one should also install \href{https://www.nasm.us}{NASM} and The latest Xcode version is recommended for use despite the toolchain name. Example command sequence may look as follows: -\DIFmodbegin -\begin{lstlisting}[caption=Compilation Commands, label=compile, style=ocbash,alsolanguage=DIFcode] +\begin{lstlisting}[caption=Compilation Commands, label=compile, style=ocbash] git clone https://github.com/acidanthera/audk UDK cd UDK git clone https://github.com/acidanthera/EfiPkg git clone https://github.com/acidanthera/MacInfoPkg -%DIF < git clone https://github.com/acidanthera/OcSupportPkg git clone https://github.com/acidanthera/OpenCorePkg source edksetup.sh make -C BaseTools build -a X64 -b RELEASE -t XCODE5 -p OpenCorePkg/OpenCorePkg.dsc \end{lstlisting} -\DIFmodend For IDE usage Xcode projects are available in the root of the repositories. Another approach could be \href{https://www.sublimetext.com}{Sublime Text} with \href{https://niosus.github.io/EasyClangComplete}{EasyClangComplete} plugin. Add \texttt{.clang\_complete} file with similar content to your UDK root: -\DIFmodbegin -\begin{lstlisting}[caption=ECC Configuration, label=eccfile, style=ocbash,alsolanguage=DIFcode] +\begin{lstlisting}[caption=ECC Configuration, label=eccfile, style=ocbash] -I/UefiPackages/MdePkg -I/UefiPackages/MdePkg/Include -I/UefiPackages/MdePkg/Include/X64 -%DIF > -I/UefiPackages/MdeModulePkg -%DIF > -I/UefiPackages/MdeModulePkg/Include -%DIF > -I/UefiPackages/MdeModulePkg/Include/X64 +-I/UefiPackages/MdeModulePkg +-I/UefiPackages/MdeModulePkg/Include +-I/UefiPackages/MdeModulePkg/Include/X64 -I/UefiPackages/EfiPkg -I/UefiPackages/EfiPkg/Include -I/UefiPackages/EfiPkg/Include/X64 -I/UefiPackages/AppleSupportPkg/Include -I/UefiPackages/OpenCorePkg/Include -%DIF < -I/UefiPackages/OcSupportPkg/Include -I/UefiPackages/MacInfoPkg/Include -I/UefiPackages/UefiCpuPkg/Include -IInclude @@ -742,7 +666,6 @@ Add \texttt{.clang\_complete} file with similar content to your UDK root: -Wno-unused-const-variable -DOC_TARGET_NOOPT=1 \end{lstlisting} -\DIFmodend \textbf{Warning}: Tool developers modifying \texttt{config.plist} or any other OpenCore files must ensure that their tool checks for \texttt{opencore-version} NVRAM variable @@ -762,8 +685,7 @@ before sending the patch to ensure no double work and to avoid your patch being \textbf{Organisation}. The codebase is structured in multiple repositories which contain separate EDK II packages. \texttt{AppleSupportPkg} and \texttt{OpenCorePkg} -are primary packages, and \texttt{EfiPkg}, \DIFdelbegin \texttt{\DIFdel{OcSupportPkg}}%DIFAUXCMD -\DIFdel{, }\DIFdelend \texttt{MacInfoPkg.dsc}) +are primary packages, and \texttt{EfiPkg}, \texttt{MacInfoPkg.dsc}) are dependent packages. \begin{itemize} \tightlist @@ -1237,16 +1159,12 @@ list of checks to do first. Prior to starting please ensure that you have: firmware settings if present. Cconsider \href{https://github.com/LongSoft/UEFITool/blob/master/UEFIPatch/patches.txt}{patching it} if you have enough skills and no option is available. See -\DIFdelbegin %DIFDELCMD < \href{https://github.com/acidanthera/AppleSupportPkg#verifymsre2}{VerifyMsrE2} -%DIFDELCMD < %%% -\DIFdel{nots }\DIFdelend \DIFaddbegin \hyperref[kernelpropsquirks]{VerifyMsrE2} - \DIFadd{notes }\DIFaddend for more details. +\hyperref[kernelpropsquirks]{VerifyMsrE2} + notes for more details. \item \texttt{CSM} (Compatibility Support Module) disabled in firmware settings if present. You may need to flash GOP ROM on NVIDIA 6xx/AMD 2xx or older. Use - \DIFdelbegin %DIFDELCMD < \href{https://www.win-raid.com/t892f16-AMD-and-Nvidia-GOP-update-No-requests-DIY.html#msg15730}{GopUpdate} -%DIFDELCMD < %%% -\DIFdelend \DIFaddbegin \href{https://www.win-raid.com/t892f16-AMD-and-Nvidia-GOP-update-No-requests-DIY.html}{GopUpdate} - \DIFadd{(see the second post) }\DIFaddend or \href{http://www.insanelymac.com/forum/topic/299614-asus-eah6450-video-bios-uefi-gop-upgrade-and-gop-uefi-binary-in-efi-for-many-ati-cards/page-1#entry2042163}{AMD UEFI GOP MAKER} + \href{https://www.win-raid.com/t892f16-AMD-and-Nvidia-GOP-update-No-requests-DIY.html}{GopUpdate} + (see the second post) or \href{http://www.insanelymac.com/forum/topic/299614-asus-eah6450-video-bios-uefi-gop-upgrade-and-gop-uefi-binary-in-efi-for-many-ati-cards/page-1#entry2042163}{AMD UEFI GOP MAKER} in case you are not sure how. \item \texttt{EHCI/XHCI Hand-off} enabled in firmware settings \texttt{only} if boot stalls unless USB devices are disconnected. @@ -1459,22 +1377,19 @@ To view their current state use \texttt{pmset -g} command in Terminal. this quirk. Do not use this unless you fully understand the consequences. \item - \DIFaddbegin \texttt{\DIFadd{ProtectSecureBoot}}\\ - \textbf{\DIFadd{Type}}\DIFadd{: }\texttt{\DIFadd{plist\ boolean}}\\ - \textbf{\DIFadd{Failsafe}}\DIFadd{: }\texttt{\DIFadd{false}}\\ - \textbf{\DIFadd{Description}}\DIFadd{: Protect UEFI Secure Boot variables from being written. -} + \texttt{ProtectSecureBoot}\\ + \textbf{Type}: \texttt{plist\ boolean}\\ + \textbf{Failsafe}: \texttt{false}\\ + \textbf{Description}: Protect UEFI Secure Boot variables from being written. - \DIFadd{Reports security violation during attempts to write to }\texttt{\DIFadd{db}}\DIFadd{, }\texttt{\DIFadd{dbx}}\DIFadd{, - }\texttt{\DIFadd{PK}}\DIFadd{, and }\texttt{\DIFadd{KEK}} \DIFadd{variables from the operating system. -} + Reports security violation during attempts to write to \texttt{db}, \texttt{dbx}, + \texttt{PK}, and \texttt{KEK} variables from the operating system. - \emph{\DIFadd{Note}}\DIFadd{: This quirk mainly attempts to avoid issues with NVRAM implementations - with problematic defragmentation, such as select Insyde or }\texttt{\DIFadd{MacPro5,1}}\DIFadd{. -} + \emph{Note}: This quirk mainly attempts to avoid issues with NVRAM implementations + with problematic defragmentation, such as select Insyde or \texttt{MacPro5,1}. \item - \DIFaddend \texttt{ProvideCustomSlide}\\ + \texttt{ProvideCustomSlide}\\ \textbf{Type}: \texttt{plist\ boolean}\\ \textbf{Failsafe}: \texttt{false}\\ \textbf{Description}: Provide custom KASLR slide on low memory. @@ -1502,10 +1417,9 @@ To view their current state use \texttt{pmset -g} command in Terminal. 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. \DIFaddbegin \DIFadd{Currently + \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}\DIFadd{. -}\DIFaddend + \href{https://github.com/acidanthera/bugtracker/issues/719}{acidanthera/bugtracker\#719}. \item \texttt{ShrinkMemoryMap}\\ @@ -2203,249 +2117,111 @@ behaviour that does not go to any other sections \begin{enumerate} \item - \texttt{\DIFdelbegin \DIFdel{BuiltinTextRenderer}\DIFdelend \DIFaddbegin \DIFadd{HibernateMode}\DIFaddend }\\ - \textbf{Type}: \texttt{plist\ \DIFdelbegin \DIFdel{boolean}\DIFdelend \DIFaddbegin \DIFadd{string}\DIFaddend }\\ - \textbf{Failsafe}: \texttt{\DIFdelbegin \DIFdel{false}\DIFdelend \DIFaddbegin \DIFadd{None}\DIFaddend }\\ - \textbf{Description}: \DIFdelbegin \DIFdel{Enables experimental builtin text renderer. }\DIFdelend \DIFaddbegin \DIFadd{Hibernation detection mode. The following modes are supported: -}\DIFaddend - - \DIFdelbegin \DIFdel{This option makes all text going through standard console output - render through builtin text renderer bypassing firmware services. - While still experimental and feature incomplete, this option - effecitly avoids the need for various quirks like - }\texttt{\DIFdel{ReplaceTabWithSpace}} %DIFAUXCMD -\DIFdel{or }\texttt{\DIFdel{SanitiseClearScreen}}%DIFAUXCMD -\DIFdel{. - It - should also increase the dimensions of the output area. -}%DIFDELCMD < - -%DIFDELCMD < %%% -\DIFdel{Since builtin text renderer works in graphics mode, extra care - may need to be paid to }\DIFdelend \DIFaddbegin \begin{itemize} + \texttt{HibernateMode}\\ + \textbf{Type}: \texttt{plist\ string}\\ + \textbf{Failsafe}: \texttt{None}\\ + \textbf{Description}: Hibernation detection mode. The following modes are supported: + + \begin{itemize} \tightlist - \item \texttt{\DIFadd{None}} \DIFadd{--- Avoid hibernation for your own good. - }\item \DIFaddend \texttt{\DIFdelbegin \DIFdel{ConsoleBehaviourOs}\DIFdelend \DIFaddbegin \DIFadd{Auto}\DIFaddend } \DIFdelbegin \DIFdel{, - }\texttt{\DIFdel{ConsoleBehaviourUi}}%DIFAUXCMD -\DIFdel{, }\texttt{\DIFdel{ConsoleControl}}%DIFAUXCMD -\DIFdel{, and }\texttt{\DIFdel{IgnoreTextInGraphics}} %DIFAUXCMD -\DIFdel{options. - While individual for the - target system, it is recommended to use }\DIFdelend \DIFaddbegin \DIFadd{--- Use RTC and NVRAM detection. - }\item \DIFaddend \texttt{\DIFdelbegin \DIFdel{ForceGraphics}\DIFdelend \DIFaddbegin \DIFadd{RTC}\DIFaddend } \DIFdelbegin \DIFdel{and - builtin }\texttt{\DIFdel{ConsoleControl}} %DIFAUXCMD -\DIFdel{to avoid compatibility issues. - }%DIFDELCMD < - -%DIFDELCMD < %%% -\emph{\DIFdel{Note}}%DIFAUXCMD -\DIFdel{: Some Macs, namely }\DIFdelend \DIFaddbegin \DIFadd{--- Use RTC detection. - }\item \DIFaddend \texttt{\DIFdelbegin \DIFdel{MacPro5,1}\DIFdelend \DIFaddbegin \DIFadd{NVRAM}\DIFaddend } \DIFdelbegin \DIFdel{, may have broken - console output with newer GPUs, and thus enabling this option can - be required for them. - }\DIFdelend \DIFaddbegin \DIFadd{--- Use NVRAM detection. - }\end{itemize} -\DIFaddend - -\item - \texttt{\DIFdelbegin \DIFdel{ConsoleMode}\DIFdelend \DIFaddbegin \DIFadd{HideAuxiliary}\DIFaddend }\\ - \textbf{Type}: \texttt{plist\ \DIFdelbegin \DIFdel{string}\DIFdelend \DIFaddbegin \DIFadd{boolean}\DIFaddend }\\ - \textbf{Failsafe}: \DIFdelbegin \DIFdel{Empty string}\DIFdelend \DIFaddbegin \texttt{\DIFadd{false}}\DIFaddend \\ - \textbf{Description}: \DIFdelbegin \DIFdel{Sets console output mode as specified - with the }\DIFdelend \DIFaddbegin \DIFadd{Hides auxiliary entries from picker menu by default. -} + \item \texttt{None} --- Avoid hibernation for your own good. + \item \texttt{Auto} --- Use RTC and NVRAM detection. + \item \texttt{RTC} --- Use RTC detection. + \item \texttt{NVRAM} --- Use NVRAM detection. + \end{itemize} - \DIFadd{An entry is considered auxiliary when at least one of the following applies: -} +\item + \texttt{HideAuxiliary}\\ + \textbf{Type}: \texttt{plist\ boolean}\\ + \textbf{Failsafe}: \texttt{false}\\ + \textbf{Description}: Hides auxiliary entries from picker menu by default. + + An entry is considered auxiliary when at least one of the following applies: \begin{itemize} \tightlist - \item \DIFadd{Entry is macOS recovery. - }\item \DIFadd{Entry is explicitly marked as }\DIFaddend \texttt{\DIFdelbegin \DIFdel{WxH}\DIFdelend \DIFaddbegin \DIFadd{Auxiliary}\DIFaddend }\DIFaddbegin \DIFadd{. - }\item \DIFadd{Entry is system }\DIFaddend (e.g. \texttt{\DIFdelbegin \DIFdel{80x24}\DIFdelend \DIFaddbegin \DIFadd{Clean NVRAM}\DIFaddend })\DIFdelbegin \DIFdel{formatted string. - Set to empty string not to change console mode }\DIFdelend . - \DIFdelbegin \DIFdel{Set to }\texttt{\DIFdel{Max}} - %DIFAUXCMD -\DIFdel{to try to use largest available console mode}\DIFdelend \DIFaddbegin \end{itemize} - - \DIFadd{To see all entries picker menu needs to be reloaded in extended mode by pressing - }\texttt{\DIFadd{Spacebar}} \DIFadd{key. Hiding auxiliary entries may increase boot performance - for multidisk systems}\DIFaddend . - -\DIFdelbegin \emph{\DIFdel{Note}}%DIFAUXCMD -\DIFdel{: This field is - best to be left empty on most firmwares}\DIFdelend \DIFaddbegin \item - \texttt{\DIFadd{HideSelf}}\\ - \textbf{\DIFadd{Type}}\DIFadd{: }\texttt{\DIFadd{plist\ boolean}}\\ - \textbf{\DIFadd{Failsafe}}\DIFadd{: }\texttt{\DIFadd{false}}\\ - \textbf{\DIFadd{Description}}\DIFadd{: Hides own boot entry from boot picker. This - may potentially hide other entries, for instance, when another UEFI OS is - installed on the same volume and driver boot is used}\DIFaddend . + \item Entry is macOS recovery. + \item Entry is explicitly marked as \texttt{Auxiliary}. + \item Entry is system (e.g. \texttt{Clean NVRAM}). + \end{itemize} + + To see all entries picker menu needs to be reloaded in extended mode by pressing + \texttt{Spacebar} key. Hiding auxiliary entries may increase boot performance + for multidisk systems. \item - \texttt{\DIFdelbegin \DIFdel{ConsoleBehaviourOs}\DIFdelend \DIFaddbegin \DIFadd{PickerAttributes}\DIFaddend }\\ - \textbf{Type}: \texttt{plist\ \DIFdelbegin \DIFdel{string}\DIFdelend \DIFaddbegin \DIFadd{integer}\DIFaddend }\\ - \textbf{Failsafe}: \DIFdelbegin \DIFdel{Empty string}\DIFdelend \DIFaddbegin \texttt{\DIFadd{0}}\DIFaddend \\ - \textbf{Description}: \DIFdelbegin \DIFdel{Set console control behaviour upon operating system load}\DIFdelend \DIFaddbegin \DIFadd{Sets specific attributes for picker}\DIFaddend . + \texttt{HideSelf}\\ + \textbf{Type}: \texttt{plist\ boolean}\\ + \textbf{Failsafe}: \texttt{false}\\ + \textbf{Description}: Hides own boot entry from boot picker. This + may potentially hide other entries, for instance, when another UEFI OS is + installed on the same volume and driver boot is used. - \DIFdelbegin \DIFdel{Console control is a legacy protocol used for switching between text and graphics - screen output. Some firmwares do not provide it, yet select operating systems - require its presence, which is what }\texttt{\DIFdel{ConsoleControl}} %DIFAUXCMD -\DIFdel{UEFI protocol is for. }%DIFDELCMD < +\item + \texttt{PickerAttributes}\\ + \textbf{Type}: \texttt{plist\ integer}\\ + \textbf{Failsafe}: \texttt{0}\\ + \textbf{Description}: Sets specific attributes for picker. -%DIFDELCMD < %%% -\DIFdel{When console control is available, OpenCore can be made console control aware, - and - set different modes for the operating system booter (}\DIFdelend \DIFaddbegin \DIFadd{Builtin picker supports colour arguments as a sum of foreground and background + Builtin picker supports colour arguments as a sum of foreground and background colors according to UEFI specification. The value of black background and - black foreground (}\DIFaddend \texttt{\DIFdelbegin \DIFdel{ConsoleBehaviourOs}\DIFdelend \DIFaddbegin \DIFadd{0}\DIFaddend }) \DIFdelbegin \DIFdel{, - which normally runs in graphics mode, and its own user interface - (}\texttt{\DIFdel{ConsoleBehaviourUi}}%DIFAUXCMD -\DIFdel{), which normally runs in text mode. Possible - behaviours, set as values of these options, include}\DIFdelend \DIFaddbegin \DIFadd{is reserved. List of colour names}\DIFaddend : + black foreground (\texttt{0}) is reserved. List of colour names: \begin{itemize} \tightlist - \item \DIFdelbegin \DIFdel{Empty string }\DIFdelend \DIFaddbegin \texttt{\DIFadd{0x00}} \DIFaddend --- \DIFdelbegin \DIFdel{Do not modify console control mode. - }\DIFdelend \DIFaddbegin \texttt{\DIFadd{EFI\_BLACK}} - \DIFaddend \item \texttt{\DIFdelbegin \DIFdel{Text}\DIFdelend \DIFaddbegin \DIFadd{0x01}\DIFaddend } --- \DIFdelbegin \DIFdel{Switch to text mode. - }\DIFdelend \DIFaddbegin \texttt{\DIFadd{EFI\_BLUE}} - \DIFaddend \item \texttt{\DIFdelbegin \DIFdel{Graphics}\DIFdelend \DIFaddbegin \DIFadd{0x02}\DIFaddend } --- \DIFdelbegin \DIFdel{Switch to graphics mode. - }\DIFdelend \DIFaddbegin \texttt{\DIFadd{EFI\_GREEN}} - \DIFaddend \item \texttt{\DIFdelbegin \DIFdel{ForceText}\DIFdelend \DIFaddbegin \DIFadd{0x03}\DIFaddend } --- \DIFdelbegin \DIFdel{Switch to text mode and preserve it - (requires }\DIFdelend \texttt{\DIFdelbegin \DIFdel{ConsoleControl}\DIFdelend \DIFaddbegin \DIFadd{EFI\_CYAN}\DIFaddend } - \DIFdelbegin \DIFdel{). - }\DIFdelend \item \texttt{\DIFdelbegin \DIFdel{ForceGraphics}\DIFdelend \DIFaddbegin \DIFadd{0x04}\DIFaddend } --- \DIFdelbegin \DIFdel{Switch to graphics mode and preserve it - (require }\DIFdelend \texttt{\DIFdelbegin \DIFdel{ConsoleControl}\DIFdelend \DIFaddbegin \DIFadd{EFI\_RED}\DIFaddend } - \DIFdelbegin \DIFdel{). - }%DIFDELCMD < \end{itemize} -%DIFDELCMD < - -%DIFDELCMD < %%% -\DIFdel{Hints: - }%DIFDELCMD < \begin{itemize} -%DIFDELCMD < \tightlist -%DIFDELCMD < %%% -\DIFdelend \item \DIFdelbegin \DIFdel{Unless empty works, firstly try to set - }\DIFdelend \texttt{\DIFdelbegin \DIFdel{ConsoleBehaviourOs}\DIFdelend \DIFaddbegin \DIFadd{0x05}\DIFaddend } \DIFdelbegin \DIFdel{to }\DIFdelend \DIFaddbegin \DIFadd{--- }\DIFaddend \texttt{\DIFdelbegin \DIFdel{Graphics}\DIFdelend \DIFaddbegin \DIFadd{EFI\_MAGENTA}\DIFaddend } - \DIFdelbegin \DIFdel{and - }\texttt{\DIFdel{ConsoleBehaviourUi}} %DIFAUXCMD -\DIFdel{to }\texttt{\DIFdel{Text}}%DIFAUXCMD -\DIFdel{. - }\DIFdelend \item \DIFdelbegin \DIFdel{On APTIO IV (Haswell and earlier) it is usually enough to have - }\DIFdelend \texttt{\DIFdelbegin \DIFdel{ConsoleBehaviourOs}\DIFdelend \DIFaddbegin \DIFadd{0x06}\DIFaddend } \DIFdelbegin \DIFdel{set to }\DIFdelend \DIFaddbegin \DIFadd{--- }\DIFaddend \texttt{\DIFdelbegin \DIFdel{Graphics}\DIFdelend \DIFaddbegin \DIFadd{EFI\_BROWN}\DIFaddend } - \DIFdelbegin \DIFdel{and - }\texttt{\DIFdel{ConsoleBehaviourUi}} %DIFAUXCMD -\DIFdel{set to }\texttt{\DIFdel{ForceText}} %DIFAUXCMD -\DIFdel{to avoid visual glitches. - }\DIFdelend \item \DIFdelbegin \DIFdel{On APTIO V (Broadwell and newer) }\DIFdelend \texttt{\DIFdelbegin \DIFdel{ConsoleBehaviourOs}\DIFdelend \DIFaddbegin \DIFadd{0x07}\DIFaddend } \DIFdelbegin \DIFdel{set to }\DIFdelend \DIFaddbegin \DIFadd{--- }\DIFaddend \texttt{\DIFdelbegin \DIFdel{ForceGraphics}\DIFdelend \DIFaddbegin \DIFadd{EFI\_LIGHTGRAY}\DIFaddend } - \DIFdelbegin \DIFdel{and }\texttt{\DIFdel{ConsoleBehaviourUi}} %DIFAUXCMD -\DIFdel{set to - }\texttt{\DIFdel{ForceText}} %DIFAUXCMD -\DIFdel{usually works best. - }\DIFdelend \item \DIFdelbegin \DIFdel{On Apple firmwares }\DIFdelend \texttt{\DIFdelbegin \DIFdel{ConsoleBehaviourOs}\DIFdelend \DIFaddbegin \DIFadd{0x08}\DIFaddend } \DIFdelbegin \DIFdel{set to }\DIFdelend \DIFaddbegin \DIFadd{--- }\DIFaddend \texttt{\DIFdelbegin \DIFdel{Graphics}\DIFdelend \DIFaddbegin \DIFadd{EFI\_DARKGRAY}\DIFaddend } - \DIFdelbegin \DIFdel{and }\texttt{\DIFdel{ConsoleBehaviourUi}} %DIFAUXCMD -\DIFdel{set to - }\texttt{\DIFdel{Text}} %DIFAUXCMD -\DIFdel{is supposed to work best. - }%DIFDELCMD < \end{itemize} -%DIFDELCMD < - -%DIFDELCMD < %%% -\emph{\DIFdel{Note}}%DIFAUXCMD -\DIFdel{: }\texttt{\DIFdel{IgnoreTextInGraphics}} %DIFAUXCMD -\DIFdel{and }\texttt{\DIFdel{SanitiseClearScreen}} %DIFAUXCMD -\DIFdel{may need to be enabled for select - firmware implementations. Particularly APTIO firmwares. -}%DIFDELCMD < - -%DIFDELCMD < %%% -\DIFdelend \item \texttt{\DIFdelbegin \DIFdel{ConsoleBehaviourUi}\DIFdelend \DIFaddbegin \DIFadd{0x09}\DIFaddend } \DIFdelbegin %DIFDELCMD < \\ -%DIFDELCMD < %%% -\textbf{\DIFdel{Type}}%DIFAUXCMD -\DIFdel{: }\texttt{\DIFdel{plist\ string}}%DIFAUXCMD -%DIFDELCMD < \\ -%DIFDELCMD < %%% -\textbf{\DIFdel{Failsafe}}%DIFAUXCMD -\DIFdel{: Empty string}%DIFDELCMD < \\ -%DIFDELCMD < %%% -\textbf{\DIFdel{Description}}%DIFAUXCMD -\DIFdel{: Set console control behaviour upon OpenCore user - interface load. Refer to }\DIFdelend \DIFaddbegin \DIFadd{--- }\DIFaddend \texttt{\DIFdelbegin \DIFdel{ConsoleBehaviourOs}\DIFdelend \DIFaddbegin \DIFadd{EFI\_LIGHTBLUE}\DIFaddend } - \DIFdelbegin \DIFdel{description for details. -}%DIFDELCMD < - -%DIFDELCMD < %%% -\DIFdelend \item \texttt{\DIFdelbegin \DIFdel{HibernateMode}\DIFdelend \DIFaddbegin \DIFadd{0x0A}\DIFaddend } \DIFdelbegin %DIFDELCMD < \\ -%DIFDELCMD < %%% -\textbf{\DIFdel{Type}}%DIFAUXCMD -\DIFdel{: }\DIFdelend \DIFaddbegin \DIFadd{--- }\DIFaddend \texttt{\DIFdelbegin \DIFdel{plist\ string}\DIFdelend \DIFaddbegin \DIFadd{EFI\_LIGHTGREEN}\DIFaddend } - \DIFdelbegin %DIFDELCMD < \\ -%DIFDELCMD < %%% -\textbf{\DIFdel{Failsafe}}%DIFAUXCMD -\DIFdel{: }\texttt{\DIFdel{None}}%DIFAUXCMD -%DIFDELCMD < \\ -%DIFDELCMD < %%% -\textbf{\DIFdel{Description}}%DIFAUXCMD -\DIFdel{: Hibernation detection mode. The following modes are supported: -}%DIFDELCMD < - -%DIFDELCMD < \begin{itemize} -%DIFDELCMD < \tightlist -%DIFDELCMD < %%% -\DIFdelend \item \texttt{\DIFdelbegin \DIFdel{None}\DIFdelend \DIFaddbegin \DIFadd{0x0B}\DIFaddend } --- \DIFdelbegin \DIFdel{Avoid hibernation for your own good. - }\DIFdelend \DIFaddbegin \texttt{\DIFadd{EFI\_LIGHTCYAN}} - \DIFaddend \item \texttt{\DIFdelbegin \DIFdel{Auto}\DIFdelend \DIFaddbegin \DIFadd{0x0C}\DIFaddend } --- \DIFdelbegin \DIFdel{Use RTC and NVRAM detection. - }\DIFdelend \DIFaddbegin \texttt{\DIFadd{EFI\_LIGHTRED}} - \DIFaddend \item \texttt{\DIFdelbegin \DIFdel{RTC}\DIFdelend \DIFaddbegin \DIFadd{0x0D}\DIFaddend } --- \DIFdelbegin \DIFdel{Use RTC detection. - }\DIFdelend \DIFaddbegin \texttt{\DIFadd{EFI\_LIGHTMAGENTA}} - \DIFaddend \item \texttt{\DIFdelbegin \DIFdel{NVRAM}\DIFdelend \DIFaddbegin \DIFadd{0x0E}\DIFaddend } --- \DIFdelbegin \DIFdel{Use NVRAM detection. - }\DIFdelend \DIFaddbegin \texttt{\DIFadd{EFI\_YELLOW}} - \item \texttt{\DIFadd{0x0F}} \DIFadd{--- }\texttt{\DIFadd{EFI\_WHITE}} - \item \texttt{\DIFadd{0x00}} \DIFadd{--- }\texttt{\DIFadd{EFI\_BACKGROUND\_BLACK}} - \item \texttt{\DIFadd{0x10}} \DIFadd{--- }\texttt{\DIFadd{EFI\_BACKGROUND\_BLUE}} - \item \texttt{\DIFadd{0x20}} \DIFadd{--- }\texttt{\DIFadd{EFI\_BACKGROUND\_GREEN}} - \item \texttt{\DIFadd{0x30}} \DIFadd{--- }\texttt{\DIFadd{EFI\_BACKGROUND\_CYAN}} - \item \texttt{\DIFadd{0x40}} \DIFadd{--- }\texttt{\DIFadd{EFI\_BACKGROUND\_RED}} - \item \texttt{\DIFadd{0x50}} \DIFadd{--- }\texttt{\DIFadd{EFI\_BACKGROUND\_MAGENTA}} - \item \texttt{\DIFadd{0x60}} \DIFadd{--- }\texttt{\DIFadd{EFI\_BACKGROUND\_BROWN}} - \item \texttt{\DIFadd{0x70}} \DIFadd{--- }\texttt{\DIFadd{EFI\_BACKGROUND\_LIGHTGRAY}} - \DIFaddend \end{itemize} - - \DIFaddbegin \emph{\DIFadd{Note}}\DIFadd{: This option may not work well with }\texttt{\DIFadd{System}} \DIFadd{text renderer. + \item \texttt{0x00} --- \texttt{EFI\_BLACK} + \item \texttt{0x01} --- \texttt{EFI\_BLUE} + \item \texttt{0x02} --- \texttt{EFI\_GREEN} + \item \texttt{0x03} --- \texttt{EFI\_CYAN} + \item \texttt{0x04} --- \texttt{EFI\_RED} + \item \texttt{0x05} --- \texttt{EFI\_MAGENTA} + \item \texttt{0x06} --- \texttt{EFI\_BROWN} + \item \texttt{0x07} --- \texttt{EFI\_LIGHTGRAY} + \item \texttt{0x08} --- \texttt{EFI\_DARKGRAY} + \item \texttt{0x09} --- \texttt{EFI\_LIGHTBLUE} + \item \texttt{0x0A} --- \texttt{EFI\_LIGHTGREEN} + \item \texttt{0x0B} --- \texttt{EFI\_LIGHTCYAN} + \item \texttt{0x0C} --- \texttt{EFI\_LIGHTRED} + \item \texttt{0x0D} --- \texttt{EFI\_LIGHTMAGENTA} + \item \texttt{0x0E} --- \texttt{EFI\_YELLOW} + \item \texttt{0x0F} --- \texttt{EFI\_WHITE} + \item \texttt{0x00} --- \texttt{EFI\_BACKGROUND\_BLACK} + \item \texttt{0x10} --- \texttt{EFI\_BACKGROUND\_BLUE} + \item \texttt{0x20} --- \texttt{EFI\_BACKGROUND\_GREEN} + \item \texttt{0x30} --- \texttt{EFI\_BACKGROUND\_CYAN} + \item \texttt{0x40} --- \texttt{EFI\_BACKGROUND\_RED} + \item \texttt{0x50} --- \texttt{EFI\_BACKGROUND\_MAGENTA} + \item \texttt{0x60} --- \texttt{EFI\_BACKGROUND\_BROWN} + \item \texttt{0x70} --- \texttt{EFI\_BACKGROUND\_LIGHTGRAY} + \end{itemize} + + \emph{Note}: This option may not work well with \texttt{System} text renderer. Setting a background different from black could help testing proper GOP functioning. -} -\DIFaddend \item - \texttt{\DIFdelbegin \DIFdel{HideSelf}\DIFdelend \DIFaddbegin \DIFadd{PickerAudioAssist}\DIFaddend }\\ +\item + \texttt{PickerAudioAssist}\\ \textbf{Type}: \texttt{plist\ boolean}\\ \textbf{Failsafe}: \texttt{false}\\ - \textbf{Description}: \DIFdelbegin \DIFdel{Hides own boot entry from boot picker. -This - may potentially hide other entries, for instance, when another UEFI OS is installed on the same volume and driver boot is used. - }\DIFdelend \DIFaddbegin \DIFadd{Enable screen reader by default in boot picker. -}\DIFaddend - - \DIFaddbegin \DIFadd{For macOS bootloader screen reader preference is set in }\texttt{\DIFadd{preferences.efires}} - \DIFadd{archive in }\texttt{\DIFadd{isVOEnabled.int32}} \DIFadd{file and is controlled by the operating system. + \textbf{Description}: Enable screen reader by default in boot picker. + + For macOS bootloader screen reader preference is set in \texttt{preferences.efires} + archive in \texttt{isVOEnabled.int32} file and is controlled by the operating system. For OpenCore screen reader support this option is an independent equivalent. Toggling screen reader support in both OpenCore boot picker and macOS bootloader - FileVault 2 login window can also be done with }\texttt{\DIFadd{Command}} \DIFadd{+ }\texttt{\DIFadd{F5}} \DIFadd{key + FileVault 2 login window can also be done with \texttt{Command} + \texttt{F5} key combination. -} - \emph{\DIFadd{Note}}\DIFadd{: screen reader requires working audio support, see - }\hyperref[uefiaudioprops]{\texttt{UEFI Audio Properties}} - \DIFadd{section for more details. -} + \emph{Note}: screen reader requires working audio support, see + \hyperref[uefiaudioprops]{\texttt{UEFI Audio Properties}} + section for more details. -\DIFaddend \item +\item \texttt{PollAppleHotKeys}\\ \textbf{Type}: \texttt{plist\ boolean}\\ \textbf{Failsafe}: \texttt{false}\\ \textbf{Description}: Enable \texttt{modifier hotkey} handling in boot picker. - In addition to \texttt{action hotkeys}, which are partially described in \texttt{\DIFdelbegin \DIFdel{UsePicker}\DIFdelend \DIFaddbegin \DIFadd{PickerMode}\DIFaddend } + In addition to \texttt{action hotkeys}, which are partially described in \texttt{PickerMode} section and are normally handled by Apple BDS, there exist modifier keys, which are handled by operating system bootloader, namely \texttt{boot.efi}. These keys allow to change operating system behaviour by providing different boot modes. @@ -2467,68 +2243,7 @@ This \end{itemize} \item - \DIFdelbegin \texttt{\DIFdel{Resolution}}%DIFAUXCMD -%DIFDELCMD < \\ -%DIFDELCMD < %%% -\textbf{\DIFdel{Type}}%DIFAUXCMD -\DIFdel{: }\texttt{\DIFdel{plist\ string}}%DIFAUXCMD -%DIFDELCMD < \\ -%DIFDELCMD < %%% -\textbf{\DIFdel{Failsafe}}%DIFAUXCMD -\DIFdel{: Empty string}%DIFDELCMD < \\ -%DIFDELCMD < %%% -\textbf{\DIFdel{Description}}%DIFAUXCMD -\DIFdel{: Sets console output screen resolution. -}%DIFDELCMD < - -%DIFDELCMD < \begin{itemize} -\begin{itemize}%DIFAUXCMD -%DIFDELCMD < \tightlist -%DIFDELCMD < \item %%% -\item%DIFAUXCMD -\DIFdel{Set to }\texttt{\DIFdel{WxH@Bpp}} %DIFAUXCMD -\DIFdel{(e.g. }\texttt{\DIFdel{1920x1080@32}}%DIFAUXCMD -\DIFdel{) or }\texttt{\DIFdel{WxH}} - %DIFAUXCMD -\DIFdel{(e.g. }\texttt{\DIFdel{1920x1080}}%DIFAUXCMD -\DIFdel{) formatted string to request custom resolution - from GOP if available. - }%DIFDELCMD < \item %%% -\item%DIFAUXCMD -\DIFdel{Set to empty string not to change screen resolution. - }%DIFDELCMD < \item %%% -\item%DIFAUXCMD -\DIFdel{Set to }\texttt{\DIFdel{Max}} %DIFAUXCMD -\DIFdel{to try to use largest available screen resolution. - } -\end{itemize}%DIFAUXCMD -%DIFDELCMD < \end{itemize} -%DIFDELCMD < - -%DIFDELCMD < %%% -\DIFdel{On HiDPI screens }\texttt{\DIFdel{APPLE\_VENDOR\_VARIABLE\_GUID}} %DIFAUXCMD -\texttt{\DIFdel{UIScale}} - %DIFAUXCMD -\DIFdel{NVRAM variable may need to be set to }\texttt{\DIFdel{02}} %DIFAUXCMD -\DIFdel{to enable HiDPI scaling - in FileVault 2 UEFI password interface and boot screen logo. Refer to - }%DIFDELCMD < \hyperref[nvramvarsrec]{Recommended Variables} %%% -\DIFdel{section for more details. -}%DIFDELCMD < - -%DIFDELCMD < %%% -\emph{\DIFdel{Note}}%DIFAUXCMD -\DIFdel{: This will fail when console handle has no GOP protocol. When - the firmware does not provide it, it can be added with }\texttt{\DIFdel{ProvideConsoleGop}} - %DIFAUXCMD -\DIFdel{UEFI quirk set to }\texttt{\DIFdel{true}}%DIFAUXCMD -\DIFdel{. -}%DIFDELCMD < - -%DIFDELCMD < \item -\item%DIFAUXCMD -%DIFDELCMD < %%% -\DIFdelend \texttt{ShowPicker}\\ + \texttt{ShowPicker}\\ \textbf{Type}: \texttt{plist\ boolean}\\ \textbf{Failsafe}: \texttt{false}\\ \textbf{Description}: Show simple boot picker to allow boot entry selection. @@ -2553,38 +2268,32 @@ This automatic booting of the default boot entry. Use 0 to disable timer. \item - \texttt{\DIFdelbegin \DIFdel{UsePicker}\DIFdelend \DIFaddbegin \DIFadd{PickerMode}\DIFaddend }\\ - \textbf{Type}: \texttt{plist\ \DIFdelbegin \DIFdel{boolean}\DIFdelend \DIFaddbegin \DIFadd{string}\DIFaddend }\\ - \textbf{Failsafe}: \texttt{\DIFdelbegin \DIFdel{false}\DIFdelend \DIFaddbegin \DIFadd{Builtin}\DIFaddend }\\ - \textbf{Description}: \DIFdelbegin \DIFdel{Use OpenCore built-in boot picker }\DIFdelend \DIFaddbegin \DIFadd{Choose boot picker used }\DIFaddend for boot management. + \texttt{PickerMode}\\ + \textbf{Type}: \texttt{plist\ string}\\ + \textbf{Failsafe}: \texttt{Builtin}\\ + \textbf{Description}: Choose boot picker used for boot management. - \DIFaddbegin \DIFadd{Picker describes underlying boot management with an optional user interface + Picker describes underlying boot management with an optional user interface responsible for handling boot options. The following values are supported: -} \begin{itemize} \tightlist - \item \DIFaddend \texttt{\DIFdelbegin \DIFdel{UsePicker}\DIFdelend \DIFaddbegin \DIFadd{Builtin}\DIFaddend } \DIFdelbegin \DIFdel{set to }\DIFdelend \DIFaddbegin \DIFadd{--- boot management is handled by OpenCore, a simple + \item \texttt{Builtin} --- boot management is handled by OpenCore, a simple text only user interface is used. - }\item \DIFaddend \texttt{\DIFdelbegin \DIFdel{false}%DIFDELCMD < \MBLOCKRIGHTBRACE %%% -\DIFdel{entirely disables }\DIFdelend \DIFaddbegin \DIFadd{External}} \DIFadd{--- an external boot management protocol is used - if available. Otherwise }\texttt{\DIFadd{Builtin}} \DIFadd{mode is used. - }\item \texttt{\DIFadd{Apple}} \DIFadd{--- Apple boot management is used if available. - Otherwise }\texttt{\DIFadd{Builtin}} \DIFadd{mode is used. - }\end{itemize} - - - \DIFadd{Upon success }\texttt{\DIFadd{External}} \DIFadd{mode will entirely disable }\DIFaddend all boot management - in OpenCore except policy enforcement. In \DIFdelbegin \DIFdel{this case }\DIFdelend \DIFaddbegin \texttt{\DIFadd{Apple}} \DIFadd{mode it may additionally - bypass policy enforcement. To implement }\texttt{\DIFadd{External}} \DIFadd{mode }\DIFaddend a custom user interface may - utilise \DIFdelbegin %DIFDELCMD < \href{https://github.com/acidanthera/OcSupportPkg}{OcSupportPkg} -%DIFDELCMD < %%% -\DIFdelend \DIFaddbegin \href{https://github.com/acidanthera/OpenCorePkg}{OpenCorePkg} - \DIFaddend \texttt{OcBootManagementLib}\DIFdelbegin \DIFdel{to implement a user friendly boot picker oneself}\DIFdelend . Reference example of external graphics interface is provided in - \DIFdelbegin %DIFDELCMD < \href{https://github.com/acidanthera/OcSupportPkg/tree/master/Tests/ExternalUi}{ExternalUi} -%DIFDELCMD < %%% -\DIFdelend \DIFaddbegin \href{https://github.com/acidanthera/OpenCorePkg/tree/master/Tests/ExternalUi}{ExternalUi} - \DIFaddend test driver. + \item \texttt{External} --- an external boot management protocol is used + if available. Otherwise \texttt{Builtin} mode is used. + \item \texttt{Apple} --- Apple boot management is used if available. + Otherwise \texttt{Builtin} mode is used. + \end{itemize} + + + Upon success \texttt{External} mode will entirely disable all boot management + in OpenCore except policy enforcement. In \texttt{Apple} mode it may additionally + bypass policy enforcement. To implement \texttt{External} mode a custom user interface may + utilise \href{https://github.com/acidanthera/OpenCorePkg}{OpenCorePkg} + \texttt{OcBootManagementLib}. Reference example of external graphics interface is provided in + \href{https://github.com/acidanthera/OpenCorePkg/tree/master/Tests/ExternalUi}{ExternalUi} + test driver. OpenCore built-in boot picker contains a set of actions chosen during the boot process. The list of supported actions is similar to Apple BDS and in general can be accessed by @@ -2612,19 +2321,18 @@ This recovery. Hold \texttt{CMD+R} key combination to choose this option. \end{itemize} - \emph{Note \DIFaddbegin \DIFadd{1}\DIFaddend }: Activated \texttt{KeySupport}, \texttt{AppleUsbKbDxe}, or similar driver is required + \emph{Note 1}: Activated \texttt{KeySupport}, \texttt{AppleUsbKbDxe}, or similar driver is required for key handling to work. On many firmwares it is not possible to get all the keys function. - \DIFaddbegin \emph{\DIFadd{Note 2}}\DIFadd{: }\DIFaddend In addition to \texttt{OPT} OpenCore supports \texttt{Escape} key \DIFaddbegin \DIFadd{to display picker when - }\DIFaddend \texttt{ShowPicker} \DIFaddbegin \DIFadd{is disabled}\DIFaddend . This key exists for \DIFaddbegin \texttt{\DIFadd{Apple}} \DIFadd{picker mode and for - }\DIFaddend firmwares with PS/2 keyboards that fail to report held \texttt{OPT} key and require continual + \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. - \DIFaddbegin \emph{\DIFadd{Note 3}}\DIFadd{: On Macs with problematic GOP it may be difficult to access Apple BootPicker. - To workaround this problem even without loading OpenCore }\texttt{\DIFadd{BootKicker}} \DIFadd{utility can be blessed. -} + \emph{Note 3}: On Macs with problematic GOP it may be difficult to access Apple BootPicker. + To workaround this problem even without loading OpenCore \texttt{BootKicker} utility can be blessed. -\DIFaddend \end{enumerate} +\end{enumerate} \subsection{Debug Properties}\label{miscdebugprops} @@ -2804,44 +2512,35 @@ nvram 4D1FDA02-38C7-4A6A-9CC6-4BCCA8B30102:oem-board # SMBIOS Type2 ProductNam Possible values match \texttt{DisplayLevel} values. \item - \texttt{\DIFdelbegin \DIFdel{RequireSignature}\DIFdelend \DIFaddbegin \DIFadd{Vault}\DIFaddend }\\ - \textbf{Type}: \texttt{plist\ \DIFdelbegin \DIFdel{boolean}\DIFdelend \DIFaddbegin \DIFadd{string}\DIFaddend }\\ - \textbf{Failsafe}: \texttt{\DIFdelbegin \DIFdel{true}\DIFdelend \DIFaddbegin \DIFadd{Secure}\DIFaddend }\\ - \textbf{Description}: \DIFdelbegin \DIFdel{Require }\DIFdelend \DIFaddbegin \DIFadd{Enables vaulting mechanism in OpenCore. -} + \texttt{Vault}\\ + \textbf{Type}: \texttt{plist\ string}\\ + \textbf{Failsafe}: \texttt{Secure}\\ + \textbf{Description}: Enables vaulting mechanism in OpenCore. - \DIFadd{Valid values: -} + Valid values: \begin{itemize} \tightlist - \item \texttt{\DIFadd{Optional}} \DIFadd{--- require nothing, no vault is enforced, insecure. - }\item \texttt{\DIFadd{Basic}} \DIFadd{--- require }\texttt{\DIFadd{vault.plist}} \DIFadd{file present - in }\texttt{\DIFadd{OC}} \DIFadd{directory. This provides basic filesystem integrity + \item \texttt{Optional} --- require nothing, no vault is enforced, insecure. + \item \texttt{Basic} --- require \texttt{vault.plist} file present + in \texttt{OC} directory. This provides basic filesystem integrity verification and may protect from unintentional filesystem corruption. - }\item \texttt{\DIFadd{Secure}} \DIFadd{--- require }\DIFaddend \texttt{vault.sig} signature file for - \texttt{vault.plist} in \texttt{OC} directory. \DIFdelbegin %DIFDELCMD < - -%DIFDELCMD < %%% -\DIFdel{This }\DIFdelend \DIFaddbegin \DIFadd{This includes }\texttt{\DIFadd{Basic}} - \DIFadd{integrity checking but also attempts to build a trusted bootchain. - }\end{itemize} + \item \texttt{Secure} --- require \texttt{vault.sig} signature file for + \texttt{vault.plist} in \texttt{OC} directory. This includes \texttt{Basic} + integrity checking but also attempts to build a trusted bootchain. + \end{itemize} - \texttt{\DIFadd{vault.plist}} \DIFaddend file should contain \DIFaddbegin \DIFadd{SHA-256 hashes for all files used by OpenCore. + \texttt{vault.plist} file should contain SHA-256 hashes for all files used by OpenCore. Presence of this file is highly recommended to ensure that unintentional file modifications (including filesystem corruption) do not happen unnoticed. To create this file automatically use - }\href{https://github.com/acidanthera/OpenCorePkg/tree/master/Utilities/CreateVault}{\texttt{create\_vault.sh}} \DIFadd{script. + \href{https://github.com/acidanthera/OpenCorePkg/tree/master/Utilities/CreateVault}{\texttt{create\_vault.sh}} script. Regardless of the underlying filesystem, path name and case must match - between }\texttt{\DIFadd{config.plist}} \DIFadd{and }\texttt{\DIFadd{vault.plist}}\DIFadd{. -} + between \texttt{config.plist} and \texttt{vault.plist}. - \texttt{\DIFadd{vault.sig}} \DIFadd{file should contain }\DIFaddend a raw 256 byte RSA-2048 signature from SHA-256 + \texttt{vault.sig} file should contain a raw 256 byte RSA-2048 signature from SHA-256 hash of \texttt{vault.plist}. The signature is verified against the public - key embedded into \texttt{OpenCore.efi}. \DIFdelbegin %DIFDELCMD < - -%DIFDELCMD < %%% -\DIFdelend To embed the public key you should + key embedded into \texttt{OpenCore.efi}. To embed the public key you should do either of the following: \begin{itemize} @@ -2854,68 +2553,10 @@ nvram 4D1FDA02-38C7-4A6A-9CC6-4BCCA8B30102:oem-board # SMBIOS Type2 ProductNam RSA public key 520 byte format description can be found in Chromium OS documentation. To convert public key from X.509 certificate or from PEM file use - \DIFdelbegin %DIFDELCMD < \href{https://github.com/acidanthera/OcSupportPkg/tree/master/Utilities/CreateVault}{RsaTool}%%% -\DIFdelend \DIFaddbegin \href{https://github.com/acidanthera/OpenCorePkg/tree/master/Utilities/CreateVault}{RsaTool}\DIFaddend . - - - \DIFdelbegin \emph{\DIFdel{Note}}%DIFAUXCMD -\DIFdel{: }\texttt{\DIFdel{vault.sig}} %DIFAUXCMD -\DIFdel{is used regardless of this option when public key - is embedded into }\texttt{\DIFdel{OpenCore.efi}}%DIFAUXCMD -\DIFdel{. Setting it to }\texttt{\DIFdel{true}} %DIFAUXCMD -\DIFdel{will only ensure - configuration sanity, and abort the boot process when public key is not set but - was supposed to be used for verification. -}%DIFDELCMD < - -%DIFDELCMD < \item -\item%DIFAUXCMD -%DIFDELCMD < %%% -\texttt{\DIFdel{RequireVault}}%DIFAUXCMD -%DIFDELCMD < \\ -%DIFDELCMD < %%% -\textbf{\DIFdel{Type}}%DIFAUXCMD -\DIFdel{: }\texttt{\DIFdel{plist\ boolean}}%DIFAUXCMD -%DIFDELCMD < \\ -%DIFDELCMD < %%% -\textbf{\DIFdel{Failsafe}}%DIFAUXCMD -\DIFdel{: }\texttt{\DIFdel{true}}%DIFAUXCMD -%DIFDELCMD < \\ -%DIFDELCMD < %%% -\textbf{\DIFdel{Description}}%DIFAUXCMD -\DIFdel{: Require }\texttt{\DIFdel{vault.plist}} %DIFAUXCMD -\DIFdel{file present - in }\texttt{\DIFdel{OC}} %DIFAUXCMD -\DIFdel{directory. -}%DIFDELCMD < - -%DIFDELCMD < %%% -\DIFdel{This file should contain SHA-256 hashes for all files used by OpenCore. - Presence of this file is highly recommended to ensure that unintentional - file modifications (including filesystem corruption) do not happen unnoticed. - To create this file automatically use - }%DIFDELCMD < \href{https://github.com/acidanthera/OcSupportPkg/tree/master/Utilities/CreateVault}{\texttt{create\_vault.sh}} %%% -\DIFdel{script. -}%DIFDELCMD < - -%DIFDELCMD < %%% -\DIFdel{Regardless of the underlying filesystem, path name and case must match - between }\texttt{\DIFdel{config.plist}} %DIFAUXCMD -\DIFdel{and }\texttt{\DIFdel{vault.plist}}%DIFAUXCMD -\DIFdel{. -}%DIFDELCMD < - -%DIFDELCMD < %%% -\emph{\DIFdel{Note}}%DIFAUXCMD -\DIFdel{: }\texttt{\DIFdel{vault.plist}} %DIFAUXCMD -\DIFdel{is tried to be read regardless of the value - of this option, but setting it to }\texttt{\DIFdel{true}} %DIFAUXCMD -\DIFdel{will ensure configuration - sanity, and abort the boot process. -}%DIFDELCMD < - -%DIFDELCMD < %%% -\DIFdelend The complete set of commands to: + \href{https://github.com/acidanthera/OpenCorePkg/tree/master/Utilities/CreateVault}{RsaTool}. + + + The complete set of commands to: \begin{itemize} \tightlist @@ -2935,7 +2576,7 @@ dd of=OpenCore.efi if=vault.pub bs=1 seek=$off count=528 conv=notrunc rm vault.pub \end{lstlisting} - \emph{Note \DIFaddbegin \DIFadd{1}\DIFaddend }: While it may appear obvious, but you have to use an external + \emph{Note 1}: While it may appear obvious, but you have to use an external method to verify \texttt{OpenCore.efi} and \texttt{BOOTx64.efi} for secure boot path. For this you are recommended to at least enable UEFI SecureBoot with a custom certificate, and sign \texttt{OpenCore.efi} and \texttt{BOOTx64.efi} @@ -2943,13 +2584,12 @@ rm vault.pub can be found in \href{https://habr.com/post/273497/}{Taming UEFI SecureBoot} paper (in Russian). - \DIFaddbegin \emph{\DIFadd{Note 2}}\DIFadd{: }\texttt{\DIFadd{vault.plist}} \DIFadd{and }\texttt{\DIFadd{vault.sig}} \DIFadd{are used regardless of this - option when }\texttt{\DIFadd{vault.plist}} \DIFadd{is present or public key is embedded into - }\texttt{\DIFadd{OpenCore.efi}}\DIFadd{. Setting this option will only ensure configuration sanity, + \emph{Note 2}: \texttt{vault.plist} and \texttt{vault.sig} are used regardless of this + option when \texttt{vault.plist} is present or public key is embedded into + \texttt{OpenCore.efi}. Setting this option will only ensure configuration sanity, and abort the boot process otherwise. -} -\DIFaddend \item +\item \texttt{ScanPolicy}\\ \textbf{Type}: \texttt{plist\ integer}, 32 bit\\ \textbf{Failsafe}: \texttt{0xF0103}\\ @@ -3035,15 +2675,14 @@ rm vault.pub of the specified entry. \item - \DIFaddbegin \texttt{\DIFadd{Auxiliary}}\\ - \textbf{\DIFadd{Type}}\DIFadd{: }\texttt{\DIFadd{plist\ boolean}}\\ - \textbf{\DIFadd{Failsafe}}\DIFadd{: }\texttt{\DIFadd{false}}\\ - \textbf{\DIFadd{Description}}\DIFadd{: This entry will not be listed by default when - }\texttt{\DIFadd{HideAuxiliary}} \DIFadd{is set to }\texttt{\DIFadd{true}}\DIFadd{. -} + \texttt{Auxiliary}\\ + \textbf{Type}: \texttt{plist\ boolean}\\ + \textbf{Failsafe}: \texttt{false}\\ + \textbf{Description}: This entry will not be listed by default when + \texttt{HideAuxiliary} is set to \texttt{true}. \item - \DIFaddend \texttt{Comment}\\ + \texttt{Comment}\\ \textbf{Type}: \texttt{plist\ string}\\ \textbf{Failsafe}: Empty string\\ \textbf{Description}: Arbitrary ASCII string used to provide human readable @@ -3306,8 +2945,7 @@ improvements: e.g. \texttt{ru-RU:252} for Russian locale and ABC keyboard. Also accepts short forms: \texttt{ru:252} or \texttt{ru:0} (U.S. keyboard, compatible with 10.9). Full decoded keyboard list from \texttt{AppleKeyboardLayouts-L.dat} can be found - \DIFdelbegin %DIFDELCMD < \href{https://github.com/acidanthera/OcSupportPkg/tree/master/Utilities/AppleKeyboardLayouts}{here}%%% -\DIFdelend \DIFaddbegin \href{https://github.com/acidanthera/OpenCorePkg/tree/master/Utilities/AppleKeyboardLayouts}{here}\DIFaddend . Using non-latin keyboard on 10.14 + \href{https://github.com/acidanthera/OpenCorePkg/tree/master/Utilities/AppleKeyboardLayouts}{here}. Using non-latin keyboard on 10.14 will not enable ABC keyboard, unlike previous and subsequent macOS versions, and is thus not recommended in case you need 10.14. \item \texttt{7C436110-AB2A-4BBB-A880-FE41995C9F82:security-mode} @@ -3323,13 +2961,13 @@ improvements: \break One-byte data defining boot.efi user interface scaling. Should be \textbf{01} for normal screens and \textbf{02} for HiDPI screens. - \DIFaddbegin \item - \texttt{\DIFadd{4D1EDE05-38C7-4A6A-9CC6-4BCCA8B38C14:DefaultBackgroundColor}} + \item + \texttt{4D1EDE05-38C7-4A6A-9CC6-4BCCA8B38C14:DefaultBackgroundColor} \break - \DIFadd{Four-byte }\texttt{\DIFadd{RGBA}} \DIFadd{data defining boot.efi user interface background colour. - Standard colours include }\textbf{\DIFadd{BF BF BF 00}} \DIFadd{(Light Gray) and }\textbf{\DIFadd{00 00 00 00}} - \DIFadd{(Syrah Black). Other colours may be set at user's preference. -}\DIFaddend \end{itemize} + Four-byte \texttt{RGBA} data defining boot.efi user interface background colour. + Standard colours include \textbf{BF BF BF 00} (Light Gray) and \textbf{00 00 00 00} + (Syrah Black). Other colours may be set at user's preference. +\end{itemize} \subsection{Other Variables}\label{nvramvarsother} @@ -3380,122 +3018,111 @@ troubleshooting: \texttt{7C436110-AB2A-4BBB-A880-FE41995C9F82:bootercfg} \break Booter arguments, similar to \texttt{boot-args} but for boot.efi. Accepts a set of - arguments, which are hexadecimal 64-bit values with or without \DIFdelbegin \DIFdel{0x prefix primarily - for loggingcontrol: - }\DIFdelend \DIFaddbegin \texttt{\DIFadd{0x}}\DIFadd{. + arguments, which are hexadecimal 64-bit values with or without \texttt{0x}. At different stages boot.efi will request different debugging (logging) - modes (e.g. after }\texttt{\DIFadd{ExitBootServices}} \DIFadd{it will only print to serial). + modes (e.g. after \texttt{ExitBootServices} it will only print to serial). Several booter arguments control whether these requests will succeed. The list of known requests is covered below: -} - \DIFaddend \begin{itemize} - \DIFaddbegin \tightlist - \DIFaddend \item \DIFaddbegin \texttt{\DIFadd{0x00}} \DIFadd{-- }\texttt{\DIFadd{INIT}}\DIFadd{. - }\item \texttt{\DIFadd{0x01}} \DIFadd{-- }\texttt{\DIFadd{VERBOSE}} \DIFadd{(e.g. }\texttt{\DIFadd{-v}}\DIFadd{, force console logging). - }\item \texttt{\DIFadd{0x02}} \DIFadd{-- }\texttt{\DIFadd{EXIT}}\DIFadd{. - }\item \texttt{\DIFadd{0x03}} \DIFadd{-- }\texttt{\DIFadd{RESET:OK}}\DIFadd{. - }\item \texttt{\DIFadd{0x04}} \DIFadd{-- }\texttt{\DIFadd{RESET:FAIL}} \DIFadd{(e.g. unknown }\texttt{\DIFadd{board-id}}\DIFadd{, hibernate mismatch, panic loop, etc.). - }\item \texttt{\DIFadd{0x05}} \DIFadd{-- }\texttt{\DIFadd{RESET:RECOVERY}}\DIFadd{. - }\item \texttt{\DIFadd{0x06}} \DIFadd{-- }\texttt{\DIFadd{RECOVERY}}\DIFadd{. - }\item \texttt{\DIFadd{0x07}} \DIFadd{-- }\texttt{\DIFadd{REAN:START}}\DIFadd{. - }\item \texttt{\DIFadd{0x08}} \DIFadd{-- }\texttt{\DIFadd{REAN:END}}\DIFadd{. - }\item \texttt{\DIFadd{0x09}} \DIFadd{-- }\texttt{\DIFadd{DT}} \DIFadd{(can no longer log to DeviceTree). - }\item \texttt{\DIFadd{0x0A}} \DIFadd{-- }\texttt{\DIFadd{EXITBS:START}} \DIFadd{(forced serial only). - }\item \texttt{\DIFadd{0x0B}} \DIFadd{-- }\texttt{\DIFadd{EXITBS:END}} \DIFadd{(forced serial only). - }\item \texttt{\DIFadd{0x0C}} \DIFadd{-- }\texttt{\DIFadd{UNKNOWN}}\DIFadd{. - }\end{itemize} - - \DIFadd{In 10.15 debugging support was mostly broken before 10.15.4 due to some + \begin{itemize} + \tightlist + \item \texttt{0x00} -- \texttt{INIT}. + \item \texttt{0x01} -- \texttt{VERBOSE} (e.g. \texttt{-v}, force console logging). + \item \texttt{0x02} -- \texttt{EXIT}. + \item \texttt{0x03} -- \texttt{RESET:OK}. + \item \texttt{0x04} -- \texttt{RESET:FAIL} (e.g. unknown \texttt{board-id}, hibernate mismatch, panic loop, etc.). + \item \texttt{0x05} -- \texttt{RESET:RECOVERY}. + \item \texttt{0x06} -- \texttt{RECOVERY}. + \item \texttt{0x07} -- \texttt{REAN:START}. + \item \texttt{0x08} -- \texttt{REAN:END}. + \item \texttt{0x09} -- \texttt{DT} (can no longer log to DeviceTree). + \item \texttt{0x0A} -- \texttt{EXITBS:START} (forced serial only). + \item \texttt{0x0B} -- \texttt{EXITBS:END} (forced serial only). + \item \texttt{0x0C} -- \texttt{UNKNOWN}. + \end{itemize} + + In 10.15 debugging support was mostly broken before 10.15.4 due to some kind of refactoring and introduction of a - }\href{https://github.com/acidanthera/EfiPkg/blob/master/Include/Protocol/AppleDebugLog.h}{new debug protocol}\DIFadd{. + \href{https://github.com/acidanthera/EfiPkg/blob/master/Include/Protocol/AppleDebugLog.h}{new debug protocol}. Some of the arguments and their values below may not be valid for versions prior to 10.15.4. The list of known arguments is covered below: -} \begin{itemize} - \item \texttt{\DIFadd{boot-save-log=VALUE}} \DIFadd{--- debug log save mode for normal boot. - }\begin{itemize} - \item \texttt{\DIFadd{0}} - \item \texttt{\DIFadd{1}} - \item \texttt{\DIFadd{2}} \DIFadd{--- (default). - }\item \texttt{\DIFadd{3}} - \item \texttt{\DIFadd{4}} \DIFadd{--- (save to file). - }\end{itemize} - \item \texttt{\DIFadd{wake-save-log=VALUE}} \DIFadd{--- debug log save mode for hibernation wake. - }\begin{itemize} - \item \texttt{\DIFadd{0}} \DIFadd{--- disabled. - }\item \texttt{\DIFadd{1}} - \item \texttt{\DIFadd{2}} \DIFadd{--- (default). - }\item \texttt{\DIFadd{3}} \DIFadd{--- (unavailable). - }\item \texttt{\DIFadd{4}} \DIFadd{--- (save to file, unavailable). - }\end{itemize} - \item \texttt{\DIFadd{breakpoint=VALUE}} \DIFadd{--- enables debug breaks (missing in production }\texttt{\DIFadd{boot.efi}}\DIFadd{). - }\begin{itemize} - \item \texttt{\DIFadd{0}} \DIFadd{--- disables debug breaks on errors (default). - }\item \texttt{\DIFadd{1}} \DIFadd{--- enables debug breaks on errors. - }\end{itemize} - \item \texttt{\DIFadd{console=VALUE}} \DIFadd{--- enables console logging. - }\begin{itemize} - \item \texttt{\DIFadd{0}} \DIFadd{--- disables console logging. - }\item \texttt{\DIFadd{1}} \DIFadd{--- enables console logging when debug protocol is missing (default). - }\item \texttt{\DIFadd{2}} \DIFadd{--- enables console logging unconditionally (unavailable). - }\end{itemize} - \item \texttt{\DIFadd{embed-log-dt=VALUE}} \DIFadd{--- enables DeviceTree logging. - }\begin{itemize} - \item \texttt{\DIFadd{0}} \DIFadd{--- disables DeviceTree logging (default). - }\item \texttt{\DIFadd{1}} \DIFadd{--- enables DeviceTree logging. - }\end{itemize} - \item \texttt{\DIFadd{kc-read-size=VALUE}} \DIFadd{--- Chunk size used for buffered I/O from network or + \item \texttt{boot-save-log=VALUE} --- debug log save mode for normal boot. + \begin{itemize} + \item \texttt{0} + \item \texttt{1} + \item \texttt{2} --- (default). + \item \texttt{3} + \item \texttt{4} --- (save to file). + \end{itemize} + \item \texttt{wake-save-log=VALUE} --- debug log save mode for hibernation wake. + \begin{itemize} + \item \texttt{0} --- disabled. + \item \texttt{1} + \item \texttt{2} --- (default). + \item \texttt{3} --- (unavailable). + \item \texttt{4} --- (save to file, unavailable). + \end{itemize} + \item \texttt{breakpoint=VALUE} --- enables debug breaks (missing in production \texttt{boot.efi}). + \begin{itemize} + \item \texttt{0} --- disables debug breaks on errors (default). + \item \texttt{1} --- enables debug breaks on errors. + \end{itemize} + \item \texttt{console=VALUE} --- enables console logging. + \begin{itemize} + \item \texttt{0} --- disables console logging. + \item \texttt{1} --- enables console logging when debug protocol is missing (default). + \item \texttt{2} --- enables console logging unconditionally (unavailable). + \end{itemize} + \item \texttt{embed-log-dt=VALUE} --- enables DeviceTree logging. + \begin{itemize} + \item \texttt{0} --- disables DeviceTree logging (default). + \item \texttt{1} --- enables DeviceTree logging. + \end{itemize} + \item \texttt{kc-read-size=VALUE} --- Chunk size used for buffered I/O from network or disk for prelinkedkernel reading and related. Set to 1MB (0x100000) by default, can be tuned for faster booting. - }\item \texttt{\DIFadd{log-level=VALUE}} \DIFadd{--- log level bitmask. - }\begin{itemize} - \item \texttt{\DIFadd{0x01}} \DIFadd{--- enables trace logging (default). - }\end{itemize} - \item \texttt{\DIFadd{serial=VALUE}} \DIFadd{--- enables serial logging. - }\begin{itemize} - \item \texttt{\DIFadd{0}} \DIFadd{--- disables serial logging (default). - }\item \texttt{\DIFadd{1}} \DIFadd{--- enables serial logging for }\texttt{\DIFadd{EXITBS:END}} \DIFadd{onwards. - }\item \texttt{\DIFadd{1}} \DIFadd{--- enables serial logging for }\texttt{\DIFadd{EXITBS:START}} \DIFadd{onwards. - }\item \texttt{\DIFadd{3}} \DIFadd{--- enables serial logging when debug protocol is missing. - }\item \texttt{\DIFadd{4}} \DIFadd{--- enables serial logging unconditionally. - }\end{itemize} - \item \texttt{\DIFadd{timestamps=VALUE}} \DIFadd{--- enables timestamp logging. - }\begin{itemize} - \item \texttt{\DIFadd{0}} \DIFadd{--- disables timestamp logging. - }\item \texttt{\DIFadd{1}} \DIFadd{--- enables timestamp logging (default). - }\end{itemize} - \item \DIFaddend \texttt{log=VALUE} \DIFaddbegin \DIFadd{--- deprecated starting from 10.15. - }\DIFaddend \begin{itemize} + \item \texttt{log-level=VALUE} --- log level bitmask. + \begin{itemize} + \item \texttt{0x01} --- enables trace logging (default). + \end{itemize} + \item \texttt{serial=VALUE} --- enables serial logging. + \begin{itemize} + \item \texttt{0} --- disables serial logging (default). + \item \texttt{1} --- enables serial logging for \texttt{EXITBS:END} onwards. + \item \texttt{1} --- enables serial logging for \texttt{EXITBS:START} onwards. + \item \texttt{3} --- enables serial logging when debug protocol is missing. + \item \texttt{4} --- enables serial logging unconditionally. + \end{itemize} + \item \texttt{timestamps=VALUE} --- enables timestamp logging. + \begin{itemize} + \item \texttt{0} --- disables timestamp logging. + \item \texttt{1} --- enables timestamp logging (default). + \end{itemize} + \item \texttt{log=VALUE} --- deprecated starting from 10.15. + \begin{itemize} \item \texttt{1} --- AppleLoggingConOutOrErrSet/AppleLoggingConOutOrErrPrint (classical ConOut/StdErr) \item \texttt{2} --- AppleLoggingStdErrSet/AppleLoggingStdErrPrint (StdErr or serial?) \item \texttt{4} --- AppleLoggingFileSet/AppleLoggingFilePrint (BOOTER.LOG/BOOTER.OLD file on EFI partition) \end{itemize} - \item \texttt{debug=VALUE} \DIFaddbegin \DIFadd{--- deprecated starting from 10.15. - }\DIFaddend \begin{itemize} + \item \texttt{debug=VALUE} --- deprecated starting from 10.15. + \begin{itemize} \item \texttt{1} --- enables print something to BOOTER.LOG (stripped code implies there may be a crash) \item \texttt{2} --- enables perf logging to /efi/debug-log in the device three \item \texttt{4} --- enables timestamp printing for styled printf calls \end{itemize} - \item \texttt{level=VALUE} --- \DIFaddbegin \DIFadd{deprecated starting from 10.15. }\DIFaddend Verbosity level of + \item \texttt{level=VALUE} --- deprecated starting from 10.15. Verbosity level of DEBUG output. Everything but \texttt{0x80000000} is stripped from the binary, and this is the default value. - \DIFdelbegin %DIFDELCMD < \item %%% -\item%DIFAUXCMD -\texttt{\DIFdel{kc-read-size=VALUE}} %DIFAUXCMD -\DIFdel{--- Chunk size used for buffered I/O from network or - disk for prelinkedkernel reading and related. Set to 1MB (0x100000) by default, can be - tuned for faster booting. -}\DIFdelend \end{itemize} -\DIFaddbegin - - \emph{\DIFadd{Note}}\DIFadd{: To quickly see verbose output from }\texttt{\DIFadd{boot.efi}} \DIFadd{on versions before 10.15 - set }\texttt{\DIFadd{bootercfg}} \DIFadd{to }\texttt{\DIFadd{log=1}}\DIFadd{. -}\DIFaddend \item \texttt{7C436110-AB2A-4BBB-A880-FE41995C9F82:bootercfg-once} + \end{itemize} + + \emph{Note}: To quickly see verbose output from \texttt{boot.efi} on versions before 10.15 + set \texttt{bootercfg} to \texttt{log=1}. +\item \texttt{7C436110-AB2A-4BBB-A880-FE41995C9F82:bootercfg-once} \break Booter arguments override removed after first launch. Otherwise equivalent to \texttt{bootercfg}. \item @@ -3507,22 +3134,22 @@ troubleshooting: \break NVIDIA Web Driver control variable. Takes ASCII digit \texttt{1} or \texttt{0} to enable or disable installed driver. -\DIFaddbegin \item - \texttt{\DIFadd{7C436110-AB2A-4BBB-A880-FE41995C9F82:StartupMute}} +\item + \texttt{7C436110-AB2A-4BBB-A880-FE41995C9F82:StartupMute} \break - \DIFadd{Mute startup chime sound in firmware audio support. 8-bit integer. - The value of }\texttt{\DIFadd{0x00}} \DIFadd{means unmuted. Missing variable or any + Mute startup chime sound in firmware audio support. 8-bit integer. + The value of \texttt{0x00} means unmuted. Missing variable or any other value means muted. This variable only affects Gibraltar machines (T2). -}\item - \texttt{\DIFadd{7C436110-AB2A-4BBB-A880-FE41995C9F82:SystemAudioVolume}} +\item + \texttt{7C436110-AB2A-4BBB-A880-FE41995C9F82:SystemAudioVolume} \break - \DIFadd{System audio volume level for firmware audio support. 8-bit integer. - The bit of }\texttt{\DIFadd{0x80}} \DIFadd{means muted. Lower bits are used to encode + System audio volume level for firmware audio support. 8-bit integer. + The bit of \texttt{0x80} means muted. Lower bits are used to encode volume range specific to installed audio codec. The value is capped - by }\texttt{\DIFadd{MaximumBootBeepVolume}} \DIFadd{AppleHDA layout value to avoid + by \texttt{MaximumBootBeepVolume} AppleHDA layout value to avoid too loud audio playback in the firmware. -}\DIFaddend \end{itemize} +\end{itemize} \section{PlatformInfo}\label{platforminfo} @@ -4025,8 +3652,7 @@ Apple ROM Version \textbf{SMBIOS}: System Information (Type 1) --- Serial Number\\ \textbf{Description}: Product serial number in defined format. Known formats are described in - \DIFdelbegin %DIFDELCMD < \href{https://github.com/acidanthera/macserial/blob/master/FORMAT.md}{macserial}%%% -\DIFdelend \DIFaddbegin \href{https://github.com/acidanthera/MacInfoPkg/blob/master/macserial/FORMAT.md}{macserial}\DIFaddend . + \href{https://github.com/acidanthera/MacInfoPkg/blob/master/macserial/FORMAT.md}{macserial}. \item \texttt{SystemUUID}\\ \textbf{Type}: \texttt{plist\ string}, GUID\\ @@ -4211,61 +3837,56 @@ and supplementary utilities can be used. \begin{enumerate} \item - \DIFaddbegin \texttt{\DIFadd{Audio}}\\ - \textbf{\DIFadd{Type}}\DIFadd{: }\texttt{\DIFadd{plist\ dict}}\\ - \textbf{\DIFadd{Failsafe}}\DIFadd{: None}\\ - \textbf{\DIFadd{Description}}\DIFadd{: Configure audio backend support described - in }\hyperref[uefiaudioprops]{Audio Properties} \DIFadd{section below. -} + \texttt{Audio}\\ + \textbf{Type}: \texttt{plist\ dict}\\ + \textbf{Failsafe}: None\\ + \textbf{Description}: Configure audio backend support described + in \hyperref[uefiaudioprops]{Audio Properties} section below. - \DIFadd{Audio support provides a way for upstream protocols to interact with the + Audio support provides a way for upstream protocols to interact with the selected hardware and audio resources. All audio resources should reside - in }\texttt{\DIFadd{\textbackslash EFI\textbackslash OC\textbackslash Resources\textbackslash Audio}} - \DIFadd{directory. Currently the only supported audio file format is WAVE PCM. While it is + in \texttt{\textbackslash EFI\textbackslash OC\textbackslash Resources\textbackslash Audio} + directory. Currently the only supported audio file format is WAVE PCM. While it is driver-dependent which audio stream format is supported, most common audio cards support 16-bit signed stereo audio at 44100 or 48000 Hz. -} - \DIFadd{Audio file path is determined by audio type, audio localisation, and audio path. Each filename - looks as follows: }\texttt{[\DIFadd{audio type}]\DIFadd{\_}[\DIFadd{audio localisation}]\DIFadd{\_}[\DIFadd{audio path}]\DIFadd{.wav}}\DIFadd{. For unlocalised + Audio file path is determined by audio type, audio localisation, and audio path. Each filename + looks as follows: \texttt{[audio type]\_[audio localisation]\_[audio path].wav}. For unlocalised files filename does not include the language code and looks as follows: - }\texttt{[\DIFadd{audio type}]\DIFadd{\_}[\DIFadd{audio path}]\DIFadd{.wav}}\DIFadd{. -} + \texttt{[audio type]\_[audio path].wav}. \begin{itemize} \tightlist - \item \DIFadd{Audio type can be }\texttt{\DIFadd{OCEFIAudio}} \DIFadd{for OpenCore audio files or - }\texttt{\DIFadd{AXEFIAudio}} \DIFadd{for macOS bootloader audio files. - }\item \DIFadd{Audio localisation is a two letter language code (e.g. }\texttt{\DIFadd{en}}\DIFadd{) + \item Audio type can be \texttt{OCEFIAudio} for OpenCore audio files or + \texttt{AXEFIAudio} for macOS bootloader audio files. + \item Audio localisation is a two letter language code (e.g. \texttt{en}) with an exception for Chinese, Spanish, and Portuguese. Refer to - }\href{https://github.com/acidanthera/EfiPkg/blob/master/Include/Protocol/AppleVoiceOver.h}{\texttt{APPLE\_VOICE\_OVER\_LANGUAGE\_CODE} definition} - \DIFadd{for the list of all supported localisations. - }\item \DIFadd{Audio path is the base filename corresponding to a file identifier. For macOS bootloader audio paths refer to - }\href{https://github.com/acidanthera/EfiPkg/blob/master/Include/Protocol/AppleVoiceOver.h}{\texttt{APPLE\_VOICE\_OVER\_AUDIO\_FILE} definition}\DIFadd{. + \href{https://github.com/acidanthera/EfiPkg/blob/master/Include/Protocol/AppleVoiceOver.h}{\texttt{APPLE\_VOICE\_OVER\_LANGUAGE\_CODE} definition} + for the list of all supported localisations. + \item Audio path is the base filename corresponding to a file identifier. For macOS bootloader audio paths refer to + \href{https://github.com/acidanthera/EfiPkg/blob/master/Include/Protocol/AppleVoiceOver.h}{\texttt{APPLE\_VOICE\_OVER\_AUDIO\_FILE} definition}. For OpenCore audio paths refer to - }\href{https://github.com/acidanthera/OpenCorePkg/blob/master/Include/Protocol/OcAudio.h}{\texttt{OC\_VOICE\_OVER\_AUDIO\_FILE} definition}\DIFadd{. - The only exception is OpenCore boot chime file, which is }\texttt{\DIFadd{OCEFIAudio\_VoiceOver\_Boot.wav}}\DIFadd{. - }\end{itemize} - - \DIFadd{Audio localisation is determined separately for macOS bootloader and OpenCore. - For macOS bootloader it is set in }\texttt{\DIFadd{preferences.efires}} \DIFadd{archive in - }\texttt{\DIFadd{systemLanguage.utf8}} \DIFadd{file and is controlled by the operating system. - For OpenCore the value of }\texttt{\DIFadd{prev-lang:kbd}} \DIFadd{variable is used. + \href{https://github.com/acidanthera/OpenCorePkg/blob/master/Include/Protocol/OcAudio.h}{\texttt{OC\_VOICE\_OVER\_AUDIO\_FILE} definition}. + The only exception is OpenCore boot chime file, which is \texttt{OCEFIAudio\_VoiceOver\_Boot.wav}. + \end{itemize} + + Audio localisation is determined separately for macOS bootloader and OpenCore. + For macOS bootloader it is set in \texttt{preferences.efires} archive in + \texttt{systemLanguage.utf8} file and is controlled by the operating system. + For OpenCore the value of \texttt{prev-lang:kbd} variable is used. When native audio localisation of a particular file is missing, English language - (}\texttt{\DIFadd{en}}\DIFadd{) localisation is used. Sample audio files can be found in - }\href{https://github.com/acidanthera/OcBinaryData}{OcBinaryData repository}\DIFadd{. -} + (\texttt{en}) localisation is used. Sample audio files can be found in + \href{https://github.com/acidanthera/OcBinaryData}{OcBinaryData repository}. \item - \DIFaddend \texttt{ConnectDrivers}\\ + \texttt{ConnectDrivers}\\ \textbf{Type}: \texttt{plist\ boolean}\\ \textbf{Failsafe}: \texttt{false}\\ \textbf{Description}: Perform UEFI controller connection after driver loading. - This option is useful for loading \DIFdelbegin \DIFdel{filesystem drivers , which - usually follow }\DIFdelend \DIFaddbegin \DIFadd{drivers following }\DIFaddend UEFI driver model - \DIFdelbegin \DIFdel{, and }\DIFdelend \DIFaddbegin \DIFadd{as they }\DIFaddend may not start by themselves. \DIFaddbegin \DIFadd{Examples of such drivers are filesystem - or audio drivers. }\DIFaddend While effective, this option may not be necessary for drivers + This option is useful for loading drivers following UEFI driver model + as they may not start by themselves. Examples of such drivers are filesystem + 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 @@ -4289,32 +3910,30 @@ and supplementary utilities can be used. \item \href{https://github.com/acidanthera/AppleSupportPkg}{\texttt{ApfsDriverLoader}} --- APFS file system bootstrap driver adding the support of embedded APFS drivers in bootable APFS containers in UEFI firmwares. - \item \DIFdelbegin %DIFDELCMD < \href{https://github.com/acidanthera/OcSupportPkg}{\texttt{FwRuntimeServices}} -%DIFDELCMD < %%% -\DIFdelend \DIFaddbegin \href{https://github.com/acidanthera/AppleSupportPkg}{\texttt{AudioDxe}} - \DIFaddend --- \DIFaddbegin \DIFadd{HDA audio support driver in UEFI firmwares for most Intel and some other analog audio controllers. - Refer to }\href{https://github.com/acidanthera/bugtracker/issues/740}{acidanthera/bugtracker\#740} - \DIFadd{for known issues in AudioDxe. - }\item \href{https://github.com/acidanthera/OcBinaryData}{\texttt{ExFatDxe}} - \DIFadd{--- Proprietary ExFAT file system driver for Bootcamp support commonly found in Apple - firmwares. For Sandy Bridge and earlier CPUs }\texttt{\DIFadd{ExFatDxeLegacy}} \DIFadd{driver should be - used due to the lack of }\texttt{\DIFadd{RDRAND}} \DIFadd{instruction support. - }\item \href{https://github.com/acidanthera/OpenCorePkg}{\texttt{FwRuntimeServices}} - \DIFadd{--- }\DIFaddend \texttt{OC\_FIRMWARE\_RUNTIME} protocol implementation that increases the security - of \DIFdelbegin \DIFdel{OpenCore }\DIFdelend \DIFaddbegin \DIFadd{\mbox{OpenCore} }\DIFaddend and Lilu by supporting read-only and write-only NVRAM variables. Some - \DIFdelbegin \DIFdel{quirks, like }\DIFdelend \DIFaddbegin \DIFadd{commonly used quirks, e.g. }\DIFaddend \texttt{RequestBootVarRouting}, require this driver for proper function. + \item \href{https://github.com/acidanthera/AppleSupportPkg}{\texttt{AudioDxe}} + --- HDA audio support driver in UEFI firmwares for most Intel and some other analog audio controllers. + Refer to \href{https://github.com/acidanthera/bugtracker/issues/740}{acidanthera/bugtracker\#740} + for known issues in AudioDxe. + \item \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 + used due to the lack of \texttt{RDRAND} instruction support. + \item \href{https://github.com/acidanthera/OpenCorePkg}{\texttt{FwRuntimeServices}} + --- \texttt{OC\_FIRMWARE\_RUNTIME} protocol implementation that increases the security + of \mbox{OpenCore} and Lilu by supporting read-only and write-only NVRAM variables. Some + commonly used quirks, e.g. \texttt{RequestBootVarRouting}, require this driver for proper function. Due to the nature of being a runtime driver, i.e. functioning in parallel with the target operating system, it cannot be implemented within OpenCore itself, but is bundled with OpenCore releases. - \item \DIFaddbegin \href{https://github.com/acidanthera/OcBinaryData}{\texttt{HfsPlus}} - \DIFadd{--- Proprietary HFS file system driver with bless support commonly found in Apple - firmwares. For Sandy Bridge and earlier CPUs }\texttt{\DIFadd{HfsPlusLegacy}} \DIFadd{driver should be - used due to the lack of }\texttt{\DIFadd{RDRAND}} \DIFadd{instruction support. - }\item \href{https://github.com/acidanthera/audk}{\texttt{HiiDatabase}} - \DIFadd{--- HII services support driver from }\texttt{\DIFadd{MdeModulePkg}}\DIFadd{. This driver is included in + \item \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 + used due to the lack of \texttt{RDRAND} instruction support. + \item \href{https://github.com/acidanthera/audk}{\texttt{HiiDatabase}} + --- 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. - }\item \DIFaddend \href{https://github.com/acidanthera/audk}{\texttt{EnhancedFatDxe}} + \item \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 @@ -4324,15 +3943,13 @@ and supplementary utilities can be used. --- NVMe support driver from \texttt{MdeModulePkg}. This driver is included in most firmwares starting with Broadwell generation. For Haswell and earlier embedding it within the firmware may be more favourable in case a NVMe SSD drive is installed. - \item \DIFdelbegin %DIFDELCMD < \href{https://github.com/acidanthera/OcSupportPkg}{\texttt{AppleUsbKbDxe}} -%DIFDELCMD < %%% -\DIFdelend \DIFaddbegin \href{https://github.com/acidanthera/OpenCorePkg}{\texttt{AppleUsbKbDxe}} - \DIFaddend --- USB keyboard driver adding the support of \texttt{AppleKeyMapAggregator} protocols + \item \href{https://github.com/acidanthera/OpenCorePkg}{\texttt{AppleUsbKbDxe}} + --- USB keyboard driver adding the support of \texttt{AppleKeyMapAggregator} protocols on top of a custom USB keyboard driver implementation. This is an alternative to builtin \texttt{KeySupport}, which may work better or worse depending on the firmware. \item \href{https://github.com/acidanthera/AppleSupportPkg}{\texttt{VBoxHfs}} --- HFS file system driver with bless support. This driver is an alternative to - a closed source \texttt{\DIFdelbegin \DIFdel{HFSPlus}\DIFdelend \DIFaddbegin \DIFadd{HfsPlus}\DIFaddend } driver commonly found in Apple firmwares. While + a closed source \texttt{HfsPlus} driver commonly found in Apple firmwares. While it is feature complete, it is approximately 3~times slower and is yet to undergo a security audit. \item \href{https://github.com/acidanthera/audk}{\texttt{XhciDxe}} @@ -4360,15 +3977,14 @@ build -a X64 -b RELEASE -t XCODE5 -p MdeModulePkg/MdeModulePkg.dsc \hyperref[uefiinputprops]{Input Properties} section below. \item - \DIFaddbegin \texttt{\DIFadd{Output}}\\ - \textbf{\DIFadd{Type}}\DIFadd{: }\texttt{\DIFadd{plist\ dict}}\\ - \textbf{\DIFadd{Failsafe}}\DIFadd{: None}\\ - \textbf{\DIFadd{Description}}\DIFadd{: Apply individual settings designed for output (text and graphics) in - }\hyperref[uefioutputprops]{Output Properties} \DIFadd{section below. -} + \texttt{Output}\\ + \textbf{Type}: \texttt{plist\ dict}\\ + \textbf{Failsafe}: None\\ + \textbf{Description}: Apply individual settings designed for output (text and graphics) in + \hyperref[uefioutputprops]{Output Properties} section below. \item - \DIFaddend \texttt{Protocols}\\ + \texttt{Protocols}\\ \textbf{Type}: \texttt{plist\ dict}\\ \textbf{Failsafe}: None\\ \textbf{Description}: Force builtin versions of select protocols described @@ -4386,128 +4002,110 @@ build -a X64 -b RELEASE -t XCODE5 -p MdeModulePkg/MdeModulePkg.dsc \end{enumerate} -\DIFaddbegin \subsection{\DIFadd{Audio Properties}}\label{uefiaudioprops} +\subsection{Audio Properties}\label{uefiaudioprops} \begin{enumerate} \item - \texttt{\DIFadd{AudioCodec}}\\ - \textbf{\DIFadd{Type}}\DIFadd{: }\texttt{\DIFadd{plist\ integer}}\\ - \textbf{\DIFadd{Failsafe}}\DIFadd{: empty string}\\ - \textbf{\DIFadd{Description}}\DIFadd{: Codec address on the specified audio controller for audio support. -} + \texttt{AudioCodec}\\ + \textbf{Type}: \texttt{plist\ integer}\\ + \textbf{Failsafe}: empty string\\ + \textbf{Description}: Codec address on the specified audio controller for audio support. - \DIFadd{Normally this contains first audio codec address on the builtin analog audio controller (}\texttt{\DIFadd{HDEF}}\DIFadd{). - Audio codec addresses, e.g. }\texttt{\DIFadd{2}}\DIFadd{, can be found in the debug log (marked in bold): -} + Normally this contains first audio codec address on the builtin analog audio controller (\texttt{HDEF}). + Audio codec addresses, e.g. \texttt{2}, can be found in the debug log (marked in bold): - \texttt{\DIFadd{OCAU: 1/3 PciRoot(0x0)/Pci(0x1,0x0)/Pci(0x0,0x1)/VenMsg(,}\textbf{\DIFadd{00000000}}\DIFadd{) (4 outputs)}}\\ - \texttt{\DIFadd{OCAU: 2/3 PciRoot(0x0)/Pci(0x3,0x0)/VenMsg(,}\textbf{\DIFadd{00000000}}\DIFadd{) (1 outputs)}}\\ - \texttt{\DIFadd{OCAU: 3/3 PciRoot(0x0)/Pci(0x1B,0x0)/VenMsg(,}\textbf{\DIFadd{02000000}}\DIFadd{) (7 outputs)}} + \texttt{OCAU: 1/3 PciRoot(0x0)/Pci(0x1,0x0)/Pci(0x0,0x1)/VenMsg(,\textbf{00000000}) (4 outputs)}\\ + \texttt{OCAU: 2/3 PciRoot(0x0)/Pci(0x3,0x0)/VenMsg(,\textbf{00000000}) (1 outputs)}\\ + \texttt{OCAU: 3/3 PciRoot(0x0)/Pci(0x1B,0x0)/VenMsg(,\textbf{02000000}) (7 outputs)} - \DIFadd{As an alternative this value can be obtained from }\texttt{\DIFadd{IOHDACodecDevice}} \DIFadd{class in I/O Registry - containing it in }\texttt{\DIFadd{IOHDACodecAddress}} \DIFadd{field. -} + As an alternative this value can be obtained from \texttt{IOHDACodecDevice} class in I/O Registry + containing it in \texttt{IOHDACodecAddress} field. \item - \texttt{\DIFadd{AudioDevice}}\\ - \textbf{\DIFadd{Type}}\DIFadd{: }\texttt{\DIFadd{plist\ string}}\\ - \textbf{\DIFadd{Failsafe}}\DIFadd{: }\texttt{\DIFadd{0}}\\ - \textbf{\DIFadd{Description}}\DIFadd{: Device path of the specified audio controller for audio support. -} + \texttt{AudioDevice}\\ + \textbf{Type}: \texttt{plist\ string}\\ + \textbf{Failsafe}: \texttt{0}\\ + \textbf{Description}: Device path of the specified audio controller for audio support. - \DIFadd{Normally this contains builtin analog audio controller (}\texttt{\DIFadd{HDEF}}\DIFadd{) device path, - e.g. }\texttt{\DIFadd{PciRoot(0x0)/Pci(0x1b,0x0)}}\DIFadd{. The list of recognised audio controllers can be + Normally this contains builtin analog audio controller (\texttt{HDEF}) device path, + e.g. \texttt{PciRoot(0x0)/Pci(0x1b,0x0)}. The list of recognised audio controllers can be found in the debug log (marked in bold): -} - \texttt{\DIFadd{OCAU: 1/3 }\textbf{\DIFadd{PciRoot(0x0)/Pci(0x1,0x0)/Pci(0x0,0x1)}}\DIFadd{/VenMsg(,00000000) (4 outputs)}}\\ - \texttt{\DIFadd{OCAU: 2/3 }\textbf{\DIFadd{PciRoot(0x0)/Pci(0x3,0x0)}}\DIFadd{/VenMsg(,00000000) (1 outputs)}}\\ - \texttt{\DIFadd{OCAU: 3/3 }\textbf{\DIFadd{PciRoot(0x0)/Pci(0x1B,0x0)}}\DIFadd{/VenMsg(,02000000) (7 outputs)}} + \texttt{OCAU: 1/3 \textbf{PciRoot(0x0)/Pci(0x1,0x0)/Pci(0x0,0x1)}/VenMsg(,00000000) (4 outputs)}\\ + \texttt{OCAU: 2/3 \textbf{PciRoot(0x0)/Pci(0x3,0x0)}/VenMsg(,00000000) (1 outputs)}\\ + \texttt{OCAU: 3/3 \textbf{PciRoot(0x0)/Pci(0x1B,0x0)}/VenMsg(,02000000) (7 outputs)} - \DIFadd{As an alternative }\texttt{\DIFadd{gfxutil -f HDEF}} \DIFadd{command can be used in macOS. Specifying empty device + As an alternative \texttt{gfxutil -f HDEF} command can be used in macOS. Specifying empty device path will result in the first available audio controller to be used. -} \item - \texttt{\DIFadd{AudioOut}}\\ - \textbf{\DIFadd{Type}}\DIFadd{: }\texttt{\DIFadd{plist\ integer}}\\ - \textbf{\DIFadd{Failsafe}}\DIFadd{: }\texttt{\DIFadd{0}}\\ - \textbf{\DIFadd{Description}}\DIFadd{: Index of the output port of the specified codec starting from 0. -} + \texttt{AudioOut}\\ + \textbf{Type}: \texttt{plist\ integer}\\ + \textbf{Failsafe}: \texttt{0}\\ + \textbf{Description}: Index of the output port of the specified codec starting from 0. - \DIFadd{Normally this contains the index of the green out of the builtin analog audio controller (}\texttt{\DIFadd{HDEF}}\DIFadd{). - The number of output nodes (}\texttt{\DIFadd{N}}\DIFadd{) in the debug log (marked in bold): -} + Normally this contains the index of the green out of the builtin analog audio controller (\texttt{HDEF}). + The number of output nodes (\texttt{N}) in the debug log (marked in bold): - \texttt{\DIFadd{OCAU: 1/3 PciRoot(0x0)/Pci(0x1,0x0)/Pci(0x0,0x1)/VenMsg(,00000000) (}\textbf{\DIFadd{4 outputs}}\DIFadd{)}}\\ - \texttt{\DIFadd{OCAU: 2/3 PciRoot(0x0)/Pci(0x3,0x0)/VenMsg(,00000000) (}\textbf{\DIFadd{1 outputs}}\DIFadd{)}}\\ - \texttt{\DIFadd{OCAU: 3/3 PciRoot(0x0)/Pci(0x1B,0x0)/VenMsg(,02000000) (}\textbf{\DIFadd{7 outputs}}\DIFadd{)}} + \texttt{OCAU: 1/3 PciRoot(0x0)/Pci(0x1,0x0)/Pci(0x0,0x1)/VenMsg(,00000000) (\textbf{4 outputs})}\\ + \texttt{OCAU: 2/3 PciRoot(0x0)/Pci(0x3,0x0)/VenMsg(,00000000) (\textbf{1 outputs})}\\ + \texttt{OCAU: 3/3 PciRoot(0x0)/Pci(0x1B,0x0)/VenMsg(,02000000) (\textbf{7 outputs})} - \DIFadd{The quickest way to find the right port is to bruteforce the values from }\texttt{\DIFadd{0}} \DIFadd{to }\texttt{\DIFadd{N - 1}}\DIFadd{. -} + The quickest way to find the right port is to bruteforce the values from \texttt{0} to \texttt{N - 1}. \item - \texttt{\DIFadd{AudioSupport}}\\ - \textbf{\DIFadd{Type}}\DIFadd{: }\texttt{\DIFadd{plist\ boolean}}\\ - \textbf{\DIFadd{Failsafe}}\DIFadd{: }\texttt{\DIFadd{false}}\\ - \textbf{\DIFadd{Description}}\DIFadd{: Activate audio support by connecting to a backend driver. -} + \texttt{AudioSupport}\\ + \textbf{Type}: \texttt{plist\ boolean}\\ + \textbf{Failsafe}: \texttt{false}\\ + \textbf{Description}: Activate audio support by connecting to a backend driver. - \DIFadd{Enabling this setting routes audio playback from builtin protocols to a dedicated - audio port (}\texttt{\DIFadd{AudioOut}}\DIFadd{) of the specified codec (}\texttt{\DIFadd{AudioCodec}}\DIFadd{) located - on the audio controller (}\texttt{\DIFadd{AudioDevice}}\DIFadd{). -} + Enabling this setting routes audio playback from builtin protocols to a dedicated + audio port (\texttt{AudioOut}) of the specified codec (\texttt{AudioCodec}) located + on the audio controller (\texttt{AudioDevice}). \item - \texttt{\DIFadd{MinimumVolume}}\\ - \textbf{\DIFadd{Type}}\DIFadd{: }\texttt{\DIFadd{plist\ integer}}\\ - \textbf{\DIFadd{Failsafe}}\DIFadd{: }\texttt{\DIFadd{0}}\\ - \textbf{\DIFadd{Description}}\DIFadd{: Minimal heard volume level from }\texttt{\DIFadd{0}} \DIFadd{to }\texttt{\DIFadd{100}}\DIFadd{. -} + \texttt{MinimumVolume}\\ + \textbf{Type}: \texttt{plist\ integer}\\ + \textbf{Failsafe}: \texttt{0}\\ + \textbf{Description}: Minimal heard volume level from \texttt{0} to \texttt{100}. - \DIFadd{Screen reader will use this volume level, when the calculated volume level is - less than }\texttt{\DIFadd{MinimumVolume}}\DIFadd{. Boot chime sound will not play if the calculated - volume level is less than }\texttt{\DIFadd{MinimumVolume}}\DIFadd{. -} + Screen reader will use this volume level, when the calculated volume level is + less than \texttt{MinimumVolume}. Boot chime sound will not play if the calculated + volume level is less than \texttt{MinimumVolume}. \item - \texttt{\DIFadd{PlayChime}}\\ - \textbf{\DIFadd{Type}}\DIFadd{: }\texttt{\DIFadd{plist\ boolean}}\\ - \textbf{\DIFadd{Failsafe}}\DIFadd{: }\texttt{\DIFadd{false}}\\ - \textbf{\DIFadd{Description}}\DIFadd{: Play chime sound at startup. -} + \texttt{PlayChime}\\ + \textbf{Type}: \texttt{plist\ boolean}\\ + \textbf{Failsafe}: \texttt{false}\\ + \textbf{Description}: Play chime sound at startup. - \DIFadd{Enabling this setting plays boot chime through builtin audio support. Volume level - is determined by }\texttt{\DIFadd{MinimumVolume}} \DIFadd{and }\texttt{\DIFadd{VolumeAmplifier}} \DIFadd{settings and - }\texttt{\DIFadd{SystemAudioVolume}} \DIFadd{NVRAM variable. -} + Enabling this setting plays boot chime through builtin audio support. Volume level + is determined by \texttt{MinimumVolume} and \texttt{VolumeAmplifier} settings and + \texttt{SystemAudioVolume} NVRAM variable. - \emph{\DIFadd{Note}}\DIFadd{: this setting is separate from }\texttt{\DIFadd{StartupMute}} \DIFadd{NVRAM variable + \emph{Note}: this setting is separate from \texttt{StartupMute} NVRAM variable to avoid conflicts when the firmware is able to play boot chime. -} \item - \texttt{\DIFadd{VolumeAmplifier}}\\ - \textbf{\DIFadd{Type}}\DIFadd{: }\texttt{\DIFadd{plist\ integer}}\\ - \textbf{\DIFadd{Failsafe}}\DIFadd{: }\texttt{\DIFadd{0}}\\ - \textbf{\DIFadd{Description}}\DIFadd{: Multiplication coefficient for system volume to raw volume linear translation - from }\texttt{\DIFadd{0}} \DIFadd{to }\texttt{\DIFadd{1000}}\DIFadd{. -} + \texttt{VolumeAmplifier}\\ + \textbf{Type}: \texttt{plist\ integer}\\ + \textbf{Failsafe}: \texttt{0}\\ + \textbf{Description}: Multiplication coefficient for system volume to raw volume linear translation + from \texttt{0} to \texttt{1000}. - \DIFadd{Volume level range read from }\texttt{\DIFadd{SystemAudioVolume}} \DIFadd{varies depending on the codec. - To transform read value in }\texttt{[\DIFadd{0, 127}]} \DIFadd{range into raw volume range }\texttt{[\DIFadd{0, 100}]} - \DIFadd{the read value is scaled to }\texttt{\DIFadd{VolumeAmplifier}} \DIFadd{percents: - }\begin{align*} - \DIFadd{RawVolume }&\DIFadd{= MIN(\frac{SystemAudioVolume * VolumeAmplifier}{100}, 100) - }\end{align*} - \emph{\DIFadd{Note}}\DIFadd{: the transformation used in macOS is not linear, but it is very close + Volume level range read from \texttt{SystemAudioVolume} varies depending on the codec. + To transform read value in \texttt{[0, 127]} range into raw volume range \texttt{[0, 100]} + the read value is scaled to \texttt{VolumeAmplifier} percents: + \begin{align*} + RawVolume &= MIN(\frac{SystemAudioVolume * VolumeAmplifier}{100}, 100) + \end{align*} + \emph{Note}: the transformation used in macOS is not linear, but it is very close and this nuance is thus ignored. -} \end{enumerate} -\DIFaddend \subsection{Input Properties}\label{uefiinputprops} +\subsection{Input Properties}\label{uefiinputprops} \begin{enumerate} @@ -4622,249 +4220,216 @@ build -a X64 -b RELEASE -t XCODE5 -p MdeModulePkg/MdeModulePkg.dsc \end{enumerate} -\DIFaddbegin \subsection{\DIFadd{Output Properties}}\label{uefioutputprops} +\subsection{Output Properties}\label{uefioutputprops} \begin{enumerate} \item - \texttt{\DIFadd{TextRenderer}}\\ - \textbf{\DIFadd{Type}}\DIFadd{: }\texttt{\DIFadd{plist\ string}}\\ - \textbf{\DIFadd{Failsafe}}\DIFadd{: }\texttt{\DIFadd{BuiltinGraphics}}\\ - \textbf{\DIFadd{Description}}\DIFadd{: Chooses renderer for text going through standard + \texttt{TextRenderer}\\ + \textbf{Type}: \texttt{plist\ string}\\ + \textbf{Failsafe}: \texttt{BuiltinGraphics}\\ + \textbf{Description}: Chooses renderer for text going through standard console output. -} - \DIFadd{Currently two renderers are supported: }\texttt{\DIFadd{Builtin}} \DIFadd{and - }\texttt{\DIFadd{System}}\DIFadd{. }\texttt{\DIFadd{System}} \DIFadd{renderer uses firmware services - for text rendering. }\texttt{\DIFadd{Builtin}} \DIFadd{bypassing firmware services + Currently two renderers are supported: \texttt{Builtin} and + \texttt{System}. \texttt{System} renderer uses firmware services + for text rendering. \texttt{Builtin} bypassing firmware services and performs text rendering on its own. Different renderers support - a different set of options. It is recommended to use }\texttt{\DIFadd{Builtin}} - \DIFadd{renderer, as it supports HiDPI mode and uses full screen resolution. -} + a different set of options. It is recommended to use \texttt{Builtin} + renderer, as it supports HiDPI mode and uses full screen resolution. - \DIFadd{UEFI firmwares generally support }\texttt{\DIFadd{ConsoleControl}} \DIFadd{with two - rendering modes: }\texttt{\DIFadd{Graphics}} \DIFadd{and }\texttt{\DIFadd{Text}}\DIFadd{. Some firmwares - do not support }\texttt{\DIFadd{ConsoleControl}} \DIFadd{and rendering modes. OpenCore - and macOS expect text to only be shown in }\texttt{\DIFadd{Graphics}} \DIFadd{mode and + 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 + 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. -} - \DIFadd{Valid values are combinations of text renderer and rendering mode: -} + Valid values are combinations of text renderer and rendering mode: \begin{itemize} \tightlist - \item \texttt{\DIFadd{BuiltinGraphics}} \DIFadd{--- Switch to }\texttt{\DIFadd{Graphics}} - \DIFadd{mode and use }\texttt{\DIFadd{Builtin}} \DIFadd{renderer with - custom }\texttt{\DIFadd{ConsoleControl}}\DIFadd{. - }\item \texttt{\DIFadd{SystemGraphics}} \DIFadd{--- Switch to }\texttt{\DIFadd{Graphics}} - \DIFadd{mode and use }\texttt{\DIFadd{System}} \DIFadd{renderer with - custom }\texttt{\DIFadd{ConsoleControl}}\DIFadd{. - }\item \texttt{\DIFadd{SystemText}} \DIFadd{--- Switch to }\texttt{\DIFadd{Text}} - \DIFadd{mode and use }\texttt{\DIFadd{System}} \DIFadd{renderer with - custom }\texttt{\DIFadd{ConsoleControl}}\DIFadd{. - }\item \texttt{\DIFadd{SystemGeneric}} \DIFadd{--- Use }\texttt{\DIFadd{System}} \DIFadd{renderer with - system }\texttt{\DIFadd{ConsoleControl}} \DIFadd{assuming it behaves correctly. - }\end{itemize} - - \DIFadd{The use of }\texttt{\DIFadd{BuiltinGraphics}} \DIFadd{is generally straightforward. - For most platforms it is necessary to enable }\texttt{\DIFadd{ProvideConsoleGop}}\DIFadd{, - set }\texttt{\DIFadd{Resolution}} \DIFadd{to }\texttt{\DIFadd{Max}}\DIFadd{. -} + \item \texttt{BuiltinGraphics} --- Switch to \texttt{Graphics} + mode and use \texttt{Builtin} renderer with + custom \texttt{ConsoleControl}. + \item \texttt{SystemGraphics} --- Switch to \texttt{Graphics} + mode and use \texttt{System} renderer with + custom \texttt{ConsoleControl}. + \item \texttt{SystemText} --- Switch to \texttt{Text} + mode and use \texttt{System} renderer with + custom \texttt{ConsoleControl}. + \item \texttt{SystemGeneric} --- Use \texttt{System} renderer with + system \texttt{ConsoleControl} assuming it behaves correctly. + \end{itemize} + + The use of \texttt{BuiltinGraphics} is generally straightforward. + For most platforms it is necessary to enable \texttt{ProvideConsoleGop}, + set \texttt{Resolution} to \texttt{Max}. - \DIFadd{The use of }\texttt{\DIFadd{System}} \DIFadd{protocols is more complicated. In general - the preferred setting is }\texttt{\DIFadd{SystemGraphics}} \DIFadd{or }\texttt{\DIFadd{SystemText}}\DIFadd{. - Enabling }\texttt{\DIFadd{ProvideConsoleGop}}\DIFadd{, setting }\texttt{\DIFadd{Resolution}} \DIFadd{to - }\texttt{\DIFadd{Max}}\DIFadd{, enabling }\texttt{\DIFadd{ReplaceTabWithSpace}} \DIFadd{is useful on almost - all platforms. }\texttt{\DIFadd{SanitiseClearScreen}}\DIFadd{, }\texttt{\DIFadd{IgnoreTextInGraphics}}\DIFadd{, - and }\texttt{\DIFadd{ClearScreenOnModeSwitch}} \DIFadd{are more specific, and their use + The use of \texttt{System} protocols is more complicated. In general + the preferred setting is \texttt{SystemGraphics} or \texttt{SystemText}. + Enabling \texttt{ProvideConsoleGop}, setting \texttt{Resolution} to + \texttt{Max}, enabling \texttt{ReplaceTabWithSpace} is useful on almost + all platforms. \texttt{SanitiseClearScreen}, \texttt{IgnoreTextInGraphics}, + and \texttt{ClearScreenOnModeSwitch} are more specific, and their use depends on the firmware. -} - \emph{\DIFadd{Note}}\DIFadd{: Some Macs, namely }\texttt{\DIFadd{MacPro5,1}}\DIFadd{, may have broken - console output with newer GPUs, and thus only }\texttt{\DIFadd{BuiltinGraphics}} - \DIFadd{may work for them. -} + \emph{Note}: Some Macs, namely \texttt{MacPro5,1}, may have broken + console output with newer GPUs, and thus only \texttt{BuiltinGraphics} + may work for them. \item - \texttt{\DIFadd{ConsoleMode}}\\ - \textbf{\DIFadd{Type}}\DIFadd{: }\texttt{\DIFadd{plist\ string}}\\ - \textbf{\DIFadd{Failsafe}}\DIFadd{: Empty string}\\ - \textbf{\DIFadd{Description}}\DIFadd{: Sets console output mode as specified - with the }\texttt{\DIFadd{WxH}} \DIFadd{(e.g. }\texttt{\DIFadd{80x24}}\DIFadd{) formatted string. -} + \texttt{ConsoleMode}\\ + \textbf{Type}: \texttt{plist\ string}\\ + \textbf{Failsafe}: Empty string\\ + \textbf{Description}: Sets console output mode as specified + with the \texttt{WxH} (e.g. \texttt{80x24}) formatted string. - \DIFadd{Set to empty string not to change console mode. Set to }\texttt{\DIFadd{Max}} - \DIFadd{to try to use largest available console mode. Currently - }\texttt{\DIFadd{Builtin}} \DIFadd{text renderer supports only one console mode, so + Set to empty string not to change console mode. Set to \texttt{Max} + to try to use largest available console mode. Currently + \texttt{Builtin} text renderer supports only one console mode, so this option is ignored. -} - \emph{\DIFadd{Note}}\DIFadd{: This field is best to be left empty on most firmwares. -} + \emph{Note}: This field is best to be left empty on most firmwares. \item - \texttt{\DIFadd{Resolution}}\\ - \textbf{\DIFadd{Type}}\DIFadd{: }\texttt{\DIFadd{plist\ string}}\\ - \textbf{\DIFadd{Failsafe}}\DIFadd{: Empty string}\\ - \textbf{\DIFadd{Description}}\DIFadd{: Sets console output screen resolution. -} + \texttt{Resolution}\\ + \textbf{Type}: \texttt{plist\ string}\\ + \textbf{Failsafe}: Empty string\\ + \textbf{Description}: Sets console output screen resolution. \begin{itemize} \tightlist - \item \DIFadd{Set to }\texttt{\DIFadd{WxH@Bpp}} \DIFadd{(e.g. }\texttt{\DIFadd{1920x1080@32}}\DIFadd{) or }\texttt{\DIFadd{WxH}} - \DIFadd{(e.g. }\texttt{\DIFadd{1920x1080}}\DIFadd{) formatted string to request custom resolution + \item Set to \texttt{WxH@Bpp} (e.g. \texttt{1920x1080@32}) or \texttt{WxH} + (e.g. \texttt{1920x1080}) formatted string to request custom resolution from GOP if available. - }\item \DIFadd{Set to empty string not to change screen resolution. - }\item \DIFadd{Set to }\texttt{\DIFadd{Max}} \DIFadd{to try to use largest available screen resolution. - }\end{itemize} - - \DIFadd{On HiDPI screens }\texttt{\DIFadd{APPLE\_VENDOR\_VARIABLE\_GUID}} \texttt{\DIFadd{UIScale}} - \DIFadd{NVRAM variable may need to be set to }\texttt{\DIFadd{02}} \DIFadd{to enable HiDPI scaling - in }\texttt{\DIFadd{Builtin}} \DIFadd{text renderer, FileVault 2 UEFI password interface, - and boot screen logo. Refer to }\hyperref[nvramvarsrec]{Recommended Variables} - \DIFadd{section for more details. -} + \item Set to empty string not to change screen resolution. + \item Set to \texttt{Max} to try to use largest available screen resolution. + \end{itemize} - \emph{\DIFadd{Note}}\DIFadd{: This will fail when console handle has no GOP protocol. When - the firmware does not provide it, it can be added with }\texttt{\DIFadd{ProvideConsoleGop}} - \DIFadd{set to }\texttt{\DIFadd{true}}\DIFadd{. -} + On HiDPI screens \texttt{APPLE\_VENDOR\_VARIABLE\_GUID} \texttt{UIScale} + NVRAM variable may need to be set to \texttt{02} to enable HiDPI scaling + in \texttt{Builtin} text renderer, FileVault 2 UEFI password interface, + and boot screen logo. Refer to \hyperref[nvramvarsrec]{Recommended Variables} + section for more details. + + \emph{Note}: This will fail when console handle has no GOP protocol. When + the firmware does not provide it, it can be added with \texttt{ProvideConsoleGop} + set to \texttt{true}. \item - \texttt{\DIFadd{ClearScreenOnModeSwitch}}\\ - \textbf{\DIFadd{Type}}\DIFadd{: }\texttt{\DIFadd{plist\ boolean}}\\ - \textbf{\DIFadd{Failsafe}}\DIFadd{: }\texttt{\DIFadd{false}}\\ - \textbf{\DIFadd{Description}}\DIFadd{: Some firmwares clear only part of screen when switching + \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. This option fills the entire graphics screen with black color before switching to text mode. -} - \emph{\DIFadd{Note}}\DIFadd{: This option only applies to }\texttt{\DIFadd{System}} \DIFadd{renderer. -} + \emph{Note}: This option only applies to \texttt{System} renderer. \item - \texttt{\DIFadd{DirectGopRendering}}\\ - \textbf{\DIFadd{Type}}\DIFadd{: }\texttt{\DIFadd{plist\ boolean}}\\ - \textbf{\DIFadd{Failsafe}}\DIFadd{: }\texttt{\DIFadd{false}}\\ - \textbf{\DIFadd{Description}}\DIFadd{: Use builtin graphics output protocol renderer for console. -} + \texttt{DirectGopRendering}\\ + \textbf{Type}: \texttt{plist\ boolean}\\ + \textbf{Failsafe}: \texttt{false}\\ + \textbf{Description}: Use builtin graphics output protocol renderer for console. - \DIFadd{On some firmwares this may provide better performance or even fix rendering issues, - like on }\texttt{\DIFadd{MacPro5,1}}\DIFadd{. However, it is recommended not to use this option unless + 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. -} \item - \texttt{\DIFadd{IgnoreTextInGraphics}}\\ - \textbf{\DIFadd{Type}}\DIFadd{: }\texttt{\DIFadd{plist\ boolean}}\\ - \textbf{\DIFadd{Failsafe}}\DIFadd{: }\texttt{\DIFadd{false}}\\ - \textbf{\DIFadd{Description}}\DIFadd{: Select firmwares output text onscreen in both graphics and + \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 - graphical images and cause UI corruption. Setting this option to }\texttt{\DIFadd{true}} \DIFadd{will - discard all text output when console control is in mode different from }\texttt{\DIFadd{Text}}\DIFadd{. -} + 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}. - \emph{\DIFadd{Note}}\DIFadd{: This option only applies to }\texttt{\DIFadd{System}} \DIFadd{renderer. -} + \emph{Note}: This option only applies to \texttt{System} renderer. \item - \texttt{\DIFadd{ReplaceTabWithSpace}}\\ - \textbf{\DIFadd{Type}}\DIFadd{: }\texttt{\DIFadd{plist\ boolean}}\\ - \textbf{\DIFadd{Failsafe}}\DIFadd{: }\texttt{\DIFadd{false}}\\ - \textbf{\DIFadd{Description}}\DIFadd{: Some firmwares do not print tab characters or even everything + \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 text editor to edit property lists and other documents. This option makes the console output spaces instead of tabs. -} - \emph{\DIFadd{Note}}\DIFadd{: This option only applies to }\texttt{\DIFadd{System}} \DIFadd{renderer. -} + \emph{Note}: This option only applies to \texttt{System} renderer. \item - \texttt{\DIFadd{ProvideConsoleGop}}\\ - \textbf{\DIFadd{Type}}\DIFadd{: }\texttt{\DIFadd{plist\ boolean}}\\ - \textbf{\DIFadd{Failsafe}}\DIFadd{: }\texttt{\DIFadd{false}}\\ - \textbf{\DIFadd{Description}}\DIFadd{: Ensure GOP (Graphics Output Protocol) on console handle. -} + \texttt{ProvideConsoleGop}\\ + \textbf{Type}: \texttt{plist\ boolean}\\ + \textbf{Failsafe}: \texttt{false}\\ + \textbf{Description}: Ensure GOP (Graphics Output Protocol) on console handle. - \DIFadd{macOS bootloader requires GOP to be present on console handle, yet the exact + macOS bootloader requires GOP to be present on console handle, yet the exact location of GOP is not covered by the UEFI specification. This option will ensure GOP is installed on console handle if it is present. -} - \emph{\DIFadd{Note}}\DIFadd{: This option will also replace broken GOP protocol on console handle, - which may be the case on }\texttt{\DIFadd{MacPro5,1}} \DIFadd{with newer GPUs. -} + \emph{Note}: This option will also replace broken GOP protocol on console handle, + which may be the case on \texttt{MacPro5,1} with newer GPUs. \item - \texttt{\DIFadd{ReconnectOnResChange}}\\ - \textbf{\DIFadd{Type}}\DIFadd{: }\texttt{\DIFadd{plist\ boolean}}\\ - \textbf{\DIFadd{Failsafe}}\DIFadd{: }\texttt{\DIFadd{false}}\\ - \textbf{\DIFadd{Description}}\DIFadd{: Reconnect console controllers after changing screen resolution. -} + \texttt{ReconnectOnResChange}\\ + \textbf{Type}: \texttt{plist\ boolean}\\ + \textbf{Failsafe}: \texttt{false}\\ + \textbf{Description}: Reconnect console controllers after changing screen resolution. - \DIFadd{On some firmwares when screen resolution is changed via GOP, it is required to reconnect + 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. -} - \emph{\DIFadd{Note}}\DIFadd{: On several boards this logic may result in black screen when launching + \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 was mandatory and not configurable. Please do not use this unless required. -} \item - \texttt{\DIFadd{SanitiseClearScreen}}\\ - \textbf{\DIFadd{Type}}\DIFadd{: }\texttt{\DIFadd{plist\ boolean}}\\ - \textbf{\DIFadd{Failsafe}}\DIFadd{: }\texttt{\DIFadd{false}}\\ - \textbf{\DIFadd{Description}}\DIFadd{: Some firmwares reset screen resolution to a failsafe - value (like }\texttt{\DIFadd{1024x768}}\DIFadd{) on the attempts to clear screen contents + \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 when large display (e.g. 2K or 4K) is used. This option attempts to apply a workaround. -} - \emph{\DIFadd{Note}}\DIFadd{: This option only applies to }\texttt{\DIFadd{System}} \DIFadd{renderer. - On all known affected systems }\texttt{\DIFadd{ConsoleMode}} \DIFadd{had to be set to + \emph{Note}: This option only applies to \texttt{System} renderer. + On all known affected systems \texttt{ConsoleMode} had to be set to empty string for this to work. -} \end{enumerate} -\DIFaddend \subsection{Protocols Properties}\label{uefiprotoprops} +\subsection{Protocols Properties}\label{uefiprotoprops} \begin{enumerate} \item - \DIFaddbegin \texttt{\DIFadd{AppleAudio}}\\ - \textbf{\DIFadd{Type}}\DIFadd{: }\texttt{\DIFadd{plist\ boolean}}\\ - \textbf{\DIFadd{Failsafe}}\DIFadd{: }\texttt{\DIFadd{false}}\\ - \textbf{\DIFadd{Description}}\DIFadd{: Reinstalls Apple audio protocols with builtin + \texttt{AppleAudio}\\ + \textbf{Type}: \texttt{plist\ boolean}\\ + \textbf{Failsafe}: \texttt{false}\\ + \textbf{Description}: Reinstalls Apple audio protocols with builtin versions. -} - \DIFadd{Apple audio protocols allow macOS bootloader and OpenCore to play + Apple audio protocols allow macOS bootloader and OpenCore to play sounds and signals for screen reading or audible error reporting. Supported protocols are beep generation and VoiceOver. VoiceOver protocol is specific to Gibraltar machines (T2) and is not supported before macOS High Sierra (10.13). Instead older macOS versions use AppleHDA protocol, which is currently not implemented. -} - \DIFadd{Only one set of audio protocols can be available at a time, so in order + Only one set of audio protocols can be available at a time, so in order to get audio playback in OpenCore user interface on Mac system implementing some of these protocols this setting should be enabled. -} - \emph{\DIFadd{Note}}\DIFadd{: Backend audio driver needs to be configured in }\texttt{\DIFadd{UEFI Audio}} - \DIFadd{section for these protocols to be able to stream audio. -} + \emph{Note}: Backend audio driver needs to be configured in \texttt{UEFI Audio} + section for these protocols to be able to stream audio. \item - \DIFaddend \texttt{AppleBootPolicy}\\ + \texttt{AppleBootPolicy}\\ \textbf{Type}: \texttt{plist\ boolean}\\ \textbf{Failsafe}: \texttt{false}\\ \textbf{Description}: Reinstalls Apple Boot Policy protocol with a builtin @@ -4914,37 +4479,7 @@ build -a X64 -b RELEASE -t XCODE5 -p MdeModulePkg/MdeModulePkg.dsc version. \item - \DIFdelbegin \texttt{\DIFdel{ConsoleControl}}%DIFAUXCMD -%DIFDELCMD < \\ -%DIFDELCMD < %%% -\textbf{\DIFdel{Type}}%DIFAUXCMD -\DIFdel{: }\texttt{\DIFdel{plist\ boolean}}%DIFAUXCMD -%DIFDELCMD < \\ -%DIFDELCMD < %%% -\textbf{\DIFdel{Failsafe}}%DIFAUXCMD -\DIFdel{: }\texttt{\DIFdel{false}}%DIFAUXCMD -%DIFDELCMD < \\ -%DIFDELCMD < %%% -\textbf{\DIFdel{Description}}%DIFAUXCMD -\DIFdel{: Replaces Console Control protocol with a builtin version. -}%DIFDELCMD < - -%DIFDELCMD < %%% -\DIFdel{macOS bootloader requires console control protocol for text output, which some firmwares - miss. This option is required to be set when the protocol is already available in the - firmware, and other console control options are used, such as }\texttt{\DIFdel{IgnoreTextInGraphics}}%DIFAUXCMD -\DIFdel{, - }\texttt{\DIFdel{SanitiseClearScreen}}%DIFAUXCMD -\DIFdel{, and sometimes }\texttt{\DIFdel{ConsoleBehaviourOs}} %DIFAUXCMD -\DIFdel{with - }\texttt{\DIFdel{ConsoleBehaviourUi}}%DIFAUXCMD -\DIFdel{). -}%DIFDELCMD < - -%DIFDELCMD < \item -\item%DIFAUXCMD -%DIFDELCMD < %%% -\DIFdelend \texttt{DataHub}\\ + \texttt{DataHub}\\ \textbf{Type}: \texttt{plist\ boolean}\\ \textbf{Failsafe}: \texttt{false}\\ \textbf{Description}: Reinstalls Data Hub protocol with a builtin version. @@ -4966,11 +4501,10 @@ build -a X64 -b RELEASE -t XCODE5 -p MdeModulePkg/MdeModulePkg.dsc to support custom cursor images for File Vault 2. Should be set to \texttt{true} to ensure File Vault 2 compatibility on everything but VMs and legacy Macs. - \DIFaddbegin \emph{\DIFadd{Note}}\DIFadd{: Several virtual machines including VMware may have corrupted + \emph{Note}: Several virtual machines including VMware may have corrupted cursor image in HiDPI mode and thus may also require this setting to be enabled. -} -\DIFaddend \item +\item \texttt{HashServices}\\ \textbf{Type}: \texttt{plist\ boolean}\\ \textbf{Failsafe}: \texttt{false}\\ @@ -5004,64 +4538,7 @@ build -a X64 -b RELEASE -t XCODE5 -p MdeModulePkg/MdeModulePkg.dsc \begin{enumerate} \item - \DIFdelbegin \texttt{\DIFdel{AvoidHighAlloc}}%DIFAUXCMD -%DIFDELCMD < \\ -%DIFDELCMD < %%% -\textbf{\DIFdel{Type}}%DIFAUXCMD -\DIFdel{: }\texttt{\DIFdel{plist\ boolean}}%DIFAUXCMD -%DIFDELCMD < \\ -%DIFDELCMD < %%% -\textbf{\DIFdel{Failsafe}}%DIFAUXCMD -\DIFdel{: }\texttt{\DIFdel{false}}%DIFAUXCMD -%DIFDELCMD < \\ -%DIFDELCMD < %%% -\textbf{\DIFdel{Description}}%DIFAUXCMD -\DIFdel{: Advises allocators to avoid allocations above first 4 GBs of RAM. -}%DIFDELCMD < - -%DIFDELCMD < %%% -\DIFdel{This is a workaround for select board firmwares, namely GA-Z77P-D3 (rev. 1.1), failing - to properly access higher memory in UEFI Boot Services. On these boards this quirk is - required for booting entries that need to allocate large memory chunks, such as macOS DMG - recovery entries. On unaffected boards it may cause boot failures, and thus strongly not - recommended. For known issues refer to - }%DIFDELCMD < \href{https://github.com/acidanthera/bugtracker/issues/449}{\texttt{acidanthera/bugtracker\#449}}%%% -\DIFdel{. -}%DIFDELCMD < - -%DIFDELCMD < \item -\item%DIFAUXCMD -%DIFDELCMD < %%% -\texttt{\DIFdel{ClearScreenOnModeSwitch}}%DIFAUXCMD -%DIFDELCMD < \\ -%DIFDELCMD < %%% -\textbf{\DIFdel{Type}}%DIFAUXCMD -\DIFdel{: }\texttt{\DIFdel{plist\ boolean}}%DIFAUXCMD -%DIFDELCMD < \\ -%DIFDELCMD < %%% -\textbf{\DIFdel{Failsafe}}%DIFAUXCMD -\DIFdel{: }\texttt{\DIFdel{false}}%DIFAUXCMD -%DIFDELCMD < \\ -%DIFDELCMD < %%% -\textbf{\DIFdel{Description}}%DIFAUXCMD -\DIFdel{: Some firmwares clear only part of screen when switching - from graphics to text mode, leaving a fragment of previously drawn image visible. - This option fills the entire graphics screen with black color before switching to - text mode. -}%DIFDELCMD < - -%DIFDELCMD < %%% -\emph{\DIFdel{Note}}%DIFAUXCMD -\DIFdel{: }\texttt{\DIFdel{ConsoleControl}} %DIFAUXCMD -\DIFdel{should be set to - }\texttt{\DIFdel{true}} %DIFAUXCMD -\DIFdel{for this to work. -}%DIFDELCMD < - -%DIFDELCMD < \item -\item%DIFAUXCMD -%DIFDELCMD < %%% -\DIFdelend \texttt{ExitBootServicesDelay}\\ + \texttt{ExitBootServicesDelay}\\ \textbf{Type}: \texttt{plist\ integer}\\ \textbf{Failsafe}: \texttt{0}\\ \textbf{Description}: Adds delay in microseconds after \texttt{EXIT\_BOOT\_SERVICES} @@ -5085,131 +4562,7 @@ build -a X64 -b RELEASE -t XCODE5 -p MdeModulePkg/MdeModulePkg.dsc its usage is not recommended when it is not required. \item - \DIFdelbegin \texttt{\DIFdel{IgnoreTextInGraphics}}%DIFAUXCMD -%DIFDELCMD < \\ -%DIFDELCMD < %%% -\textbf{\DIFdel{Type}}%DIFAUXCMD -\DIFdel{: }\texttt{\DIFdel{plist\ boolean}}%DIFAUXCMD -%DIFDELCMD < \\ -%DIFDELCMD < %%% -\textbf{\DIFdel{Failsafe}}%DIFAUXCMD -\DIFdel{: }\texttt{\DIFdel{false}}%DIFAUXCMD -%DIFDELCMD < \\ -%DIFDELCMD < %%% -\textbf{\DIFdel{Description}}%DIFAUXCMD -\DIFdel{: Select firmwares output text onscreen in both graphics and - text mode. This is normally unexpected, because random text may appear over - graphical images and cause UI corruption. Setting this option to }\texttt{\DIFdel{true}} %DIFAUXCMD -\DIFdel{will - discard all text output when console control is in mode different from }\texttt{\DIFdel{Text}}%DIFAUXCMD -\DIFdel{. -}%DIFDELCMD < - -%DIFDELCMD < %%% -\emph{\DIFdel{Note}}%DIFAUXCMD -\DIFdel{: While the option is not supposed to induce harm on unaffected firmwares, - its usage is not recommended when it is not required. This option may hide - onscreen error messages. }\texttt{\DIFdel{ConsoleControl}} %DIFAUXCMD -\DIFdel{may need to be set to - }\texttt{\DIFdel{true}} %DIFAUXCMD -\DIFdel{for this to work. -}%DIFDELCMD < - -%DIFDELCMD < \item -\item%DIFAUXCMD -%DIFDELCMD < %%% -\texttt{\DIFdel{ReplaceTabWithSpace}}%DIFAUXCMD -%DIFDELCMD < \\ -%DIFDELCMD < %%% -\textbf{\DIFdel{Type}}%DIFAUXCMD -\DIFdel{: }\texttt{\DIFdel{plist\ boolean}}%DIFAUXCMD -%DIFDELCMD < \\ -%DIFDELCMD < %%% -\textbf{\DIFdel{Failsafe}}%DIFAUXCMD -\DIFdel{: }\texttt{\DIFdel{false}}%DIFAUXCMD -%DIFDELCMD < \\ -%DIFDELCMD < %%% -\textbf{\DIFdel{Description}}%DIFAUXCMD -\DIFdel{: Some firmwares do not print tab characters or even everything - that follows them, causing difficulties or inability to use the UEFI Shell builtin - text editor to edit property lists and other documents. This option makes the console - output spaces instead of tabs. -}%DIFDELCMD < - -%DIFDELCMD < %%% -\emph{\DIFdel{Note}}%DIFAUXCMD -\DIFdel{: }\texttt{\DIFdel{ConsoleControl}} %DIFAUXCMD -\DIFdel{may need to be set to - }\texttt{\DIFdel{true}} %DIFAUXCMD -\DIFdel{for this to work. -}%DIFDELCMD < - -%DIFDELCMD < \item -\item%DIFAUXCMD -%DIFDELCMD < %%% -\texttt{\DIFdel{ProvideConsoleGop}}%DIFAUXCMD -%DIFDELCMD < \\ -%DIFDELCMD < %%% -\textbf{\DIFdel{Type}}%DIFAUXCMD -\DIFdel{: }\texttt{\DIFdel{plist\ boolean}}%DIFAUXCMD -%DIFDELCMD < \\ -%DIFDELCMD < %%% -\textbf{\DIFdel{Failsafe}}%DIFAUXCMD -\DIFdel{: }\texttt{\DIFdel{false}}%DIFAUXCMD -%DIFDELCMD < \\ -%DIFDELCMD < %%% -\textbf{\DIFdel{Description}}%DIFAUXCMD -\DIFdel{: Ensure GOP (Graphics Output Protocol) on console handle. -}%DIFDELCMD < - -%DIFDELCMD < %%% -\DIFdel{macOS bootloader requires GOP to be present on console handle, yet the exact - location of GOP is not covered by the UEFI specification. This option will - ensure GOP is installed on console handle if it is present. -}%DIFDELCMD < - -%DIFDELCMD < %%% -\emph{\DIFdel{Note}}%DIFAUXCMD -\DIFdel{: This option will also replace broken GOP protocol on console handle, - which may be the case on }\texttt{\DIFdel{MacPro5,1}} %DIFAUXCMD -\DIFdel{with newer GPUs. -}%DIFDELCMD < - -%DIFDELCMD < \item -\item%DIFAUXCMD -%DIFDELCMD < %%% -\texttt{\DIFdel{ReconnectOnResChange}}%DIFAUXCMD -%DIFDELCMD < \\ -%DIFDELCMD < %%% -\textbf{\DIFdel{Type}}%DIFAUXCMD -\DIFdel{: }\texttt{\DIFdel{plist\ boolean}}%DIFAUXCMD -%DIFDELCMD < \\ -%DIFDELCMD < %%% -\textbf{\DIFdel{Failsafe}}%DIFAUXCMD -\DIFdel{: }\texttt{\DIFdel{false}}%DIFAUXCMD -%DIFDELCMD < \\ -%DIFDELCMD < %%% -\textbf{\DIFdel{Description}}%DIFAUXCMD -\DIFdel{: Reconnect console controllers after changing screen resolution. -}%DIFDELCMD < - -%DIFDELCMD < %%% -\DIFdel{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. -}%DIFDELCMD < - -%DIFDELCMD < %%% -\emph{\DIFdel{Note}}%DIFAUXCMD -\DIFdel{: 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 - was mandatory and not configurable. Please do not use this unless required. -}%DIFDELCMD < - -%DIFDELCMD < \item -\item%DIFAUXCMD -%DIFDELCMD < %%% -\DIFdelend \texttt{ReleaseUsbOwnership}\\ + \texttt{ReleaseUsbOwnership}\\ \textbf{Type}: \texttt{plist\ boolean}\\ \textbf{Failsafe}: \texttt{false}\\ \textbf{Description}: Attempt to detach USB controller ownership from @@ -5274,39 +4627,7 @@ build -a X64 -b RELEASE -t XCODE5 -p MdeModulePkg/MdeModulePkg.dsc pane in a firmware that is not compatible with macOS boot entries by design. \item - \DIFdelbegin \texttt{\DIFdel{SanitiseClearScreen}}%DIFAUXCMD -%DIFDELCMD < \\ -%DIFDELCMD < %%% -\textbf{\DIFdel{Type}}%DIFAUXCMD -\DIFdel{: }\texttt{\DIFdel{plist\ boolean}}%DIFAUXCMD -%DIFDELCMD < \\ -%DIFDELCMD < %%% -\textbf{\DIFdel{Failsafe}}%DIFAUXCMD -\DIFdel{: }\texttt{\DIFdel{false}}%DIFAUXCMD -%DIFDELCMD < \\ -%DIFDELCMD < %%% -\textbf{\DIFdel{Description}}%DIFAUXCMD -\DIFdel{: Some firmwares reset screen resolution to a failsafe - value (like }\texttt{\DIFdel{1024x768}}%DIFAUXCMD -\DIFdel{) on the attempts to clear screen contents - when large display (e.g. 2K or 4K) is used. This option attempts to apply - a workaround. -}%DIFDELCMD < - -%DIFDELCMD < %%% -\emph{\DIFdel{Note}}%DIFAUXCMD -\DIFdel{: }\texttt{\DIFdel{ConsoleControl}} %DIFAUXCMD -\DIFdel{may need to be set to - }\texttt{\DIFdel{true}} %DIFAUXCMD -\DIFdel{for this to work. On all known affected systems - }\texttt{\DIFdel{ConsoleMode}} %DIFAUXCMD -\DIFdel{had to be set to empty string for this to work. -}%DIFDELCMD < - -%DIFDELCMD < \item -\item%DIFAUXCMD -%DIFDELCMD < %%% -\DIFdelend \texttt{UnblockFsConnect}\\ + \texttt{UnblockFsConnect}\\ \textbf{Type}: \texttt{plist\ boolean}\\ \textbf{Failsafe}: \texttt{false}\\ \textbf{Description}: Some firmwares block partition handles by opening them @@ -5379,8 +4700,7 @@ build -a X64 -b RELEASE -t XCODE5 -p MdeModulePkg/MdeModulePkg.dsc \item To access Apple filesystems like HFS and APFS separate software may need to be installed. Some of the known tools are: \href{https://forums.macrumors.com/threads/apple-hfs-windows-driver-download.1368010/}{Apple HFS+ driver} - (\DIFdelbegin %DIFDELCMD < \href{https://forums.macrumors.com/threads/apple-hfs-windows-driver-download.1368010/page-4#post-24180079}{hack for Windows 10}%%% -\DIFdelend \DIFaddbegin \href{https://forums.macrumors.com/threads/apple-hfs-windows-driver-download.1368010/post-24180079}{hack for Windows 10}\DIFaddend ), + (\href{https://forums.macrumors.com/threads/apple-hfs-windows-driver-download.1368010/post-24180079}{hack for Windows 10}), \href{http://www.catacombae.org/hfsexplorer}{HFSExplorer}, MacDrive, Paragon APFS, Paragon HFS+, TransMac, etc. Remember to never ever attempt to modify Apple file systems from Windows as this often leads to irrecoverable data loss. @@ -5450,10 +4770,8 @@ Similar to other projects working with hardware OpenCore supports auditing and d The use of \texttt{NOOPT} or \texttt{DEBUG} build modes instead of \texttt{RELEASE} can produce a lot more debug output. With \texttt{NOOPT} source level debugging with GDB or IDA Pro is also available. For GDB check -\DIFdelbegin %DIFDELCMD < \href{https://github.com/acidanthera/OcSupportPkg/tree/master/Debug}{OcSupport Debug} -%DIFDELCMD < %%% -\DIFdelend \DIFaddbegin \href{https://github.com/acidanthera/OpenCorePkg/tree/master/Debug}{OcSupport Debug} -\DIFaddend page. For IDA Pro you will need IDA Pro 7.3 or newer, refer to +\href{https://github.com/acidanthera/OpenCorePkg/tree/master/Debug}{OcSupport Debug} +page. For IDA Pro you will need IDA Pro 7.3 or newer, refer to \href{https://www.hex-rays.com/products/ida/support/tutorials/index.shtml}{Debugging the XNU Kernel with IDA Pro} for more details. @@ -5551,9 +4869,7 @@ you will need \texttt{debug=0x8} boot argument. \textbf{Why do online recovery images (\texttt{*.dmg}) fail to load?} This may be caused by missing HFS+ driver, as all presently known recovery volumes - have HFS+ filesystem\DIFdelbegin \DIFdel{. Another cause may be buggy firmware allocator, which can be - worked around with }\texttt{\DIFdel{AvoidHighAlloc}} %DIFAUXCMD -\DIFdel{UEFI quirk}\DIFdelend . + have HFS+ filesystem. \item \textbf{Can I use this on Apple hardware or virtual machines?} diff --git a/Docs/Differences/PreviousConfiguration.tex b/Docs/Differences/PreviousConfiguration.tex index d6c8934b842aae1ad488924ead5d531e77f84cc5..d63cfaae1156830f185d2ceb531e6c70bd944f9e 100755 --- a/Docs/Differences/PreviousConfiguration.tex +++ b/Docs/Differences/PreviousConfiguration.tex @@ -89,7 +89,7 @@ \vspace{0.2in} - Reference Manual (0.5.5) + Reference Manual (0.5.6) \vspace{0.2in} @@ -123,8 +123,9 @@ This document is structured as a specification, and is not meant to provide a st step algorithm for configuring end-user board support package (BSP). Any third-party articles, tools, books, etc., providing such material are prone to their authors' preferences, tastes, this document misinterpretation, and essential obsolescence. -In case you still use these sources, for example, -\href{https://khronokernel-2.gitbook.io/opencore-vanilla-desktop-guide}{Opencore Vanilla Desktop Guide}, +In case you still use these sources, for example, +\href{https://khronokernel-2.gitbook.io/opencore-vanilla-desktop-guide}{Opencore Vanilla Desktop Guide} +(\href{https://khronokernel-1.gitbook.io/getting-started-with-opencore}{parent link}), please ensure following this document for every made decision and judging its consequences. Regardless of the sources used you are required to fully understand every dedicated OpenCore configuration option and concept prior to reporting any issues in @@ -396,6 +397,10 @@ be relied upon, and all fields must be properly specified in the configuration. } child [missing] {} child [missing] {} + child { node [optional] {Resources} + child { node [optional] {Audio}} + } + child [missing] {} child { node {Tools} child { node [optional] {Tool.efi}} } @@ -425,6 +430,8 @@ be relied upon, and all fields must be properly specified in the configuration. child [missing] {} child [missing] {} child [missing] {} + child [missing] {} + child [missing] {} child { node [optional] {nvram.plist}} child { node [optional] {opencore-YYYY-MM-DD-HHMMSS.txt}} ; @@ -460,6 +467,12 @@ entries include: \break Directory used for storing supplemental kernel information for \hyperref[kernel]{\texttt{Kernel}} section. +\item + \texttt{Resources} + \break + Directory used for storing media resources, such as audio files + for screen reader support. See \hyperref[uefiaudioprops]{\texttt{UEFI Audio Properties}} + section for more details. \item \texttt{Tools} \break @@ -516,7 +529,7 @@ For BIOS booting a third-party UEFI environment provider will have to be used. \texttt{DuetPkg} is one of the known UEFI environment providers for legacy systems. To run OpenCore on such a legacy system you can install \texttt{DuetPkg} with a dedicated tool: -\href{https://github.com/acidanthera/OcSupportPkg/tree/master/Utilities/BootInstall}{BootInstall}. +\href{https://github.com/acidanthera/OpenCorePkg/tree/master/Utilities/BootInstall}{BootInstall}. For upgrade purposes refer to \texttt{Differences.pdf} document, providing the information about the changes affecting the configuration compared @@ -539,9 +552,8 @@ patches is welcome. Please do follow \href{https://github.com/tianocore/tianocore.github.io/wiki/Code-Style-C}{EDK II C Codestyle}. Required external package dependencies include -\href{https://github.com/acidanthera/OcSupportPkg}{EfiPkg}, -\href{https://github.com/acidanthera/OcSupportPkg}{MacInfoPkg}, and -\href{https://github.com/acidanthera/OcSupportPkg}{OcSupportPkg}. +\href{https://github.com/acidanthera/EfiPkg}{EfiPkg} and +\href{https://github.com/acidanthera/MacInfoPkg}{MacInfoPkg}. To compile with \texttt{XCODE5}, besides \href{https://developer.apple.com/xcode}{Xcode}, one should also install \href{https://www.nasm.us}{NASM} and @@ -554,7 +566,6 @@ git clone https://github.com/acidanthera/audk UDK cd UDK git clone https://github.com/acidanthera/EfiPkg git clone https://github.com/acidanthera/MacInfoPkg -git clone https://github.com/acidanthera/OcSupportPkg git clone https://github.com/acidanthera/OpenCorePkg source edksetup.sh make -C BaseTools @@ -570,12 +581,14 @@ Add \texttt{.clang\_complete} file with similar content to your UDK root: -I/UefiPackages/MdePkg -I/UefiPackages/MdePkg/Include -I/UefiPackages/MdePkg/Include/X64 +-I/UefiPackages/MdeModulePkg +-I/UefiPackages/MdeModulePkg/Include +-I/UefiPackages/MdeModulePkg/Include/X64 -I/UefiPackages/EfiPkg -I/UefiPackages/EfiPkg/Include -I/UefiPackages/EfiPkg/Include/X64 -I/UefiPackages/AppleSupportPkg/Include -I/UefiPackages/OpenCorePkg/Include --I/UefiPackages/OcSupportPkg/Include -I/UefiPackages/MacInfoPkg/Include -I/UefiPackages/UefiCpuPkg/Include -IInclude @@ -612,7 +625,7 @@ before sending the patch to ensure no double work and to avoid your patch being \textbf{Organisation}. The codebase is structured in multiple repositories which contain separate EDK II packages. \texttt{AppleSupportPkg} and \texttt{OpenCorePkg} -are primary packages, and \texttt{EfiPkg}, \texttt{OcSupportPkg}, \texttt{MacInfoPkg.dsc}) +are primary packages, and \texttt{EfiPkg}, \texttt{MacInfoPkg.dsc}) are dependent packages. \begin{itemize} \tightlist @@ -694,7 +707,7 @@ use \texttt{OC:}, for libraries and drivers use their own unique prefixes. \item Use \texttt{DEBUG\_CODE\_BEGIN ()} and \texttt{DEBUG\_CODE\_END ()} constructions to guard debug checks that may potentially reduce the performance of release builds and are otherwise unnecessary. \item Use \texttt{DEBUG} macro to print debug messages during normal functioning, and \texttt{RUNTIME\_DEBUG} for -debugging after \texttt{EXIT\_BOOT\_SERVICES}. +debugging after \texttt{EXIT\_BOOT\_SERVICES}. \item Use \texttt{DEBUG\_VERBOSE} debug level to leave debug messages for future debugging of the code, which are currently not necessary. By default \texttt{DEBUG\_VERBOSE} messages are ignored even in \texttt{DEBUG} builds. \item Use \texttt{DEBUG\_INFO} debug level for all non critical messages (including errors) and \texttt{DEBUG\_BULK\_INFO} @@ -1086,12 +1099,12 @@ list of checks to do first. Prior to starting please ensure that you have: firmware settings if present. Cconsider \href{https://github.com/LongSoft/UEFITool/blob/master/UEFIPatch/patches.txt}{patching it} if you have enough skills and no option is available. See -\href{https://github.com/acidanthera/AppleSupportPkg#verifymsre2}{VerifyMsrE2} - nots for more details. +\hyperref[kernelpropsquirks]{VerifyMsrE2} + notes for more details. \item \texttt{CSM} (Compatibility Support Module) disabled in firmware settings if present. You may need to flash GOP ROM on NVIDIA 6xx/AMD 2xx or older. Use - \href{https://www.win-raid.com/t892f16-AMD-and-Nvidia-GOP-update-No-requests-DIY.html#msg15730}{GopUpdate} - or \href{http://www.insanelymac.com/forum/topic/299614-asus-eah6450-video-bios-uefi-gop-upgrade-and-gop-uefi-binary-in-efi-for-many-ati-cards/page-1#entry2042163}{AMD UEFI GOP MAKER} + \href{https://www.win-raid.com/t892f16-AMD-and-Nvidia-GOP-update-No-requests-DIY.html}{GopUpdate} + (see the second post) or \href{http://www.insanelymac.com/forum/topic/299614-asus-eah6450-video-bios-uefi-gop-upgrade-and-gop-uefi-binary-in-efi-for-many-ati-cards/page-1#entry2042163}{AMD UEFI GOP MAKER} in case you are not sure how. \item \texttt{EHCI/XHCI Hand-off} enabled in firmware settings \texttt{only} if boot stalls unless USB devices are disconnected. @@ -1303,6 +1316,18 @@ To view their current state use \texttt{pmset -g} command in Terminal. As \texttt{AvoidRuntimeDefrag} resolves a similar problem, no known firmwares should need this quirk. Do not use this unless you fully understand the consequences. +\item + \texttt{ProtectSecureBoot}\\ + \textbf{Type}: \texttt{plist\ boolean}\\ + \textbf{Failsafe}: \texttt{false}\\ + \textbf{Description}: Protect UEFI Secure Boot variables from being written. + + Reports security violation during attempts to write to \texttt{db}, \texttt{dbx}, + \texttt{PK}, and \texttt{KEK} variables from the operating system. + + \emph{Note}: This quirk mainly attempts to avoid issues with NVRAM implementations + with problematic defragmentation, such as select Insyde or \texttt{MacPro5,1}. + \item \texttt{ProvideCustomSlide}\\ \textbf{Type}: \texttt{plist\ boolean}\\ @@ -1332,7 +1357,9 @@ To view their current state use \texttt{pmset -g} command in Terminal. 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. + \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}. \item \texttt{ShrinkMemoryMap}\\ @@ -2030,115 +2057,103 @@ behaviour that does not go to any other sections \begin{enumerate} \item - \texttt{BuiltinTextRenderer}\\ - \textbf{Type}: \texttt{plist\ boolean}\\ - \textbf{Failsafe}: \texttt{false}\\ - \textbf{Description}: Enables experimental builtin text renderer. - - This option makes all text going through standard console output - render through builtin text renderer bypassing firmware services. - While still experimental and feature incomplete, this option - effecitly avoids the need for various quirks like - \texttt{ReplaceTabWithSpace} or \texttt{SanitiseClearScreen}. It - should also increase the dimensions of the output area. - - Since builtin text renderer works in graphics mode, extra care - may need to be paid to \texttt{ConsoleBehaviourOs}, - \texttt{ConsoleBehaviourUi}, \texttt{ConsoleControl}, and - \texttt{IgnoreTextInGraphics} options. While individual for the - target system, it is recommended to use \texttt{ForceGraphics} and - builtin \texttt{ConsoleControl} to avoid compatibility issues. - - \emph{Note}: Some Macs, namely \texttt{MacPro5,1}, may have broken - console output with newer GPUs, and thus enabling this option can - be required for them. - -\item - \texttt{ConsoleMode}\\ - \textbf{Type}: \texttt{plist\ string}\\ - \textbf{Failsafe}: Empty string\\ - \textbf{Description}: Sets console output mode as specified - with the \texttt{WxH} (e.g. \texttt{80x24}) formatted string. - Set to empty string not to change console mode. Set to \texttt{Max} - to try to use largest available console mode. - - \emph{Note}: This field is best to be left empty on most firmwares. - -\item - \texttt{ConsoleBehaviourOs}\\ + \texttt{HibernateMode}\\ \textbf{Type}: \texttt{plist\ string}\\ - \textbf{Failsafe}: Empty string\\ - \textbf{Description}: Set console control behaviour upon operating system load. - - Console control is a legacy protocol used for switching between text and graphics - screen output. Some firmwares do not provide it, yet select operating systems - require its presence, which is what \texttt{ConsoleControl} UEFI protocol is for. - - When console control is available, OpenCore can be made console control aware, - and set different modes for the operating system booter (\texttt{ConsoleBehaviourOs}), - which normally runs in graphics mode, and its own user interface - (\texttt{ConsoleBehaviourUi}), which normally runs in text mode. Possible - behaviours, set as values of these options, include: + \textbf{Failsafe}: \texttt{None}\\ + \textbf{Description}: Hibernation detection mode. The following modes are supported: \begin{itemize} \tightlist - \item Empty string --- Do not modify console control mode. - \item \texttt{Text} --- Switch to text mode. - \item \texttt{Graphics} --- Switch to graphics mode. - \item \texttt{ForceText} --- Switch to text mode and preserve it - (requires \texttt{ConsoleControl}). - \item \texttt{ForceGraphics} --- Switch to graphics mode and preserve it - (require \texttt{ConsoleControl}). + \item \texttt{None} --- Avoid hibernation for your own good. + \item \texttt{Auto} --- Use RTC and NVRAM detection. + \item \texttt{RTC} --- Use RTC detection. + \item \texttt{NVRAM} --- Use NVRAM detection. \end{itemize} - Hints: +\item + \texttt{HideAuxiliary}\\ + \textbf{Type}: \texttt{plist\ boolean}\\ + \textbf{Failsafe}: \texttt{false}\\ + \textbf{Description}: Hides auxiliary entries from picker menu by default. + + An entry is considered auxiliary when at least one of the following applies: + \begin{itemize} \tightlist - \item Unless empty works, firstly try to set - \texttt{ConsoleBehaviourOs} to \texttt{Graphics} and - \texttt{ConsoleBehaviourUi} to \texttt{Text}. - \item On APTIO IV (Haswell and earlier) it is usually enough to have - \texttt{ConsoleBehaviourOs} set to \texttt{Graphics} and - \texttt{ConsoleBehaviourUi} set to \texttt{ForceText} to avoid visual glitches. - \item On APTIO V (Broadwell and newer) \texttt{ConsoleBehaviourOs} - set to \texttt{ForceGraphics} and \texttt{ConsoleBehaviourUi} set to - \texttt{ForceText} usually works best. - \item On Apple firmwares \texttt{ConsoleBehaviourOs} - set to \texttt{Graphics} and \texttt{ConsoleBehaviourUi} set to - \texttt{Text} is supposed to work best. + \item Entry is macOS recovery. + \item Entry is explicitly marked as \texttt{Auxiliary}. + \item Entry is system (e.g. \texttt{Clean NVRAM}). \end{itemize} - \emph{Note}: \texttt{IgnoreTextInGraphics} and \texttt{SanitiseClearScreen} may need to be enabled for select - firmware implementations. Particularly APTIO firmwares. + To see all entries picker menu needs to be reloaded in extended mode by pressing + \texttt{Spacebar} key. Hiding auxiliary entries may increase boot performance + for multidisk systems. \item - \texttt{ConsoleBehaviourUi}\\ - \textbf{Type}: \texttt{plist\ string}\\ - \textbf{Failsafe}: Empty string\\ - \textbf{Description}: Set console control behaviour upon OpenCore user - interface load. Refer to \texttt{ConsoleBehaviourOs} description for details. + \texttt{HideSelf}\\ + \textbf{Type}: \texttt{plist\ boolean}\\ + \textbf{Failsafe}: \texttt{false}\\ + \textbf{Description}: Hides own boot entry from boot picker. This + may potentially hide other entries, for instance, when another UEFI OS is + installed on the same volume and driver boot is used. \item - \texttt{HibernateMode}\\ - \textbf{Type}: \texttt{plist\ string}\\ - \textbf{Failsafe}: \texttt{None}\\ - \textbf{Description}: Hibernation detection mode. The following modes are supported: + \texttt{PickerAttributes}\\ + \textbf{Type}: \texttt{plist\ integer}\\ + \textbf{Failsafe}: \texttt{0}\\ + \textbf{Description}: Sets specific attributes for picker. + + Builtin picker supports colour arguments as a sum of foreground and background + colors according to UEFI specification. The value of black background and + black foreground (\texttt{0}) is reserved. List of colour names: \begin{itemize} \tightlist - \item \texttt{None} --- Avoid hibernation for your own good. - \item \texttt{Auto} --- Use RTC and NVRAM detection. - \item \texttt{RTC} --- Use RTC detection. - \item \texttt{NVRAM} --- Use NVRAM detection. + \item \texttt{0x00} --- \texttt{EFI\_BLACK} + \item \texttt{0x01} --- \texttt{EFI\_BLUE} + \item \texttt{0x02} --- \texttt{EFI\_GREEN} + \item \texttt{0x03} --- \texttt{EFI\_CYAN} + \item \texttt{0x04} --- \texttt{EFI\_RED} + \item \texttt{0x05} --- \texttt{EFI\_MAGENTA} + \item \texttt{0x06} --- \texttt{EFI\_BROWN} + \item \texttt{0x07} --- \texttt{EFI\_LIGHTGRAY} + \item \texttt{0x08} --- \texttt{EFI\_DARKGRAY} + \item \texttt{0x09} --- \texttt{EFI\_LIGHTBLUE} + \item \texttt{0x0A} --- \texttt{EFI\_LIGHTGREEN} + \item \texttt{0x0B} --- \texttt{EFI\_LIGHTCYAN} + \item \texttt{0x0C} --- \texttt{EFI\_LIGHTRED} + \item \texttt{0x0D} --- \texttt{EFI\_LIGHTMAGENTA} + \item \texttt{0x0E} --- \texttt{EFI\_YELLOW} + \item \texttt{0x0F} --- \texttt{EFI\_WHITE} + \item \texttt{0x00} --- \texttt{EFI\_BACKGROUND\_BLACK} + \item \texttt{0x10} --- \texttt{EFI\_BACKGROUND\_BLUE} + \item \texttt{0x20} --- \texttt{EFI\_BACKGROUND\_GREEN} + \item \texttt{0x30} --- \texttt{EFI\_BACKGROUND\_CYAN} + \item \texttt{0x40} --- \texttt{EFI\_BACKGROUND\_RED} + \item \texttt{0x50} --- \texttt{EFI\_BACKGROUND\_MAGENTA} + \item \texttt{0x60} --- \texttt{EFI\_BACKGROUND\_BROWN} + \item \texttt{0x70} --- \texttt{EFI\_BACKGROUND\_LIGHTGRAY} \end{itemize} + \emph{Note}: This option may not work well with \texttt{System} text renderer. + Setting a background different from black could help testing proper GOP functioning. + \item - \texttt{HideSelf}\\ + \texttt{PickerAudioAssist}\\ \textbf{Type}: \texttt{plist\ boolean}\\ \textbf{Failsafe}: \texttt{false}\\ - \textbf{Description}: Hides own boot entry from boot picker. This - may potentially hide other entries, for instance, when another UEFI OS is - installed on the same volume and driver boot is used. + \textbf{Description}: Enable screen reader by default in boot picker. + + For macOS bootloader screen reader preference is set in \texttt{preferences.efires} + archive in \texttt{isVOEnabled.int32} file and is controlled by the operating system. + For OpenCore screen reader support this option is an independent equivalent. + Toggling screen reader support in both OpenCore boot picker and macOS bootloader + FileVault 2 login window can also be done with \texttt{Command} + \texttt{F5} key + combination. + + \emph{Note}: screen reader requires working audio support, see + \hyperref[uefiaudioprops]{\texttt{UEFI Audio Properties}} + section for more details. \item \texttt{PollAppleHotKeys}\\ @@ -2146,7 +2161,7 @@ behaviour that does not go to any other sections \textbf{Failsafe}: \texttt{false}\\ \textbf{Description}: Enable \texttt{modifier hotkey} handling in boot picker. - In addition to \texttt{action hotkeys}, which are partially described in \texttt{UsePicker} + In addition to \texttt{action hotkeys}, which are partially described in \texttt{PickerMode} section and are normally handled by Apple BDS, there exist modifier keys, which are handled by operating system bootloader, namely \texttt{boot.efi}. These keys allow to change operating system behaviour by providing different boot modes. @@ -2165,32 +2180,8 @@ behaviour that does not go to any other sections \item \texttt{CMD+S+MINUS} --- disable KASLR slide, requires disabled SIP. \item \texttt{CMD+V} --- verbose mode. \item \texttt{Shift} --- safe mode. - \end{itemize} - -\item - \texttt{Resolution}\\ - \textbf{Type}: \texttt{plist\ string}\\ - \textbf{Failsafe}: Empty string\\ - \textbf{Description}: Sets console output screen resolution. - - \begin{itemize} - \tightlist - \item Set to \texttt{WxH@Bpp} (e.g. \texttt{1920x1080@32}) or \texttt{WxH} - (e.g. \texttt{1920x1080}) formatted string to request custom resolution - from GOP if available. - \item Set to empty string not to change screen resolution. - \item Set to \texttt{Max} to try to use largest available screen resolution. \end{itemize} - On HiDPI screens \texttt{APPLE\_VENDOR\_VARIABLE\_GUID} \texttt{UIScale} - NVRAM variable may need to be set to \texttt{02} to enable HiDPI scaling - in FileVault 2 UEFI password interface and boot screen logo. Refer to - \hyperref[nvramvarsrec]{Recommended Variables} section for more details. - - \emph{Note}: This will fail when console handle has no GOP protocol. When - the firmware does not provide it, it can be added with \texttt{ProvideConsoleGop} - UEFI quirk set to \texttt{true}. - \item \texttt{ShowPicker}\\ \textbf{Type}: \texttt{plist\ boolean}\\ @@ -2217,17 +2208,31 @@ behaviour that does not go to any other sections automatic booting of the default boot entry. Use 0 to disable timer. \item - \texttt{UsePicker}\\ - \textbf{Type}: \texttt{plist\ boolean}\\ - \textbf{Failsafe}: \texttt{false}\\ - \textbf{Description}: Use OpenCore built-in boot picker for boot management. - - \texttt{UsePicker} set to \texttt{false} entirely disables all boot management - in OpenCore except policy enforcement. In this case a custom user interface may - utilise \href{https://github.com/acidanthera/OcSupportPkg}{OcSupportPkg} - \texttt{OcBootManagementLib} to implement a user friendly boot picker oneself. - Reference example of external graphics interface is provided in - \href{https://github.com/acidanthera/OcSupportPkg/tree/master/Tests/ExternalUi}{ExternalUi} + \texttt{PickerMode}\\ + \textbf{Type}: \texttt{plist\ string}\\ + \textbf{Failsafe}: \texttt{Builtin}\\ + \textbf{Description}: Choose boot picker used for boot management. + + Picker describes underlying boot management with an optional user interface + responsible for handling boot options. The following values are supported: + + \begin{itemize} + \tightlist + \item \texttt{Builtin} --- boot management is handled by OpenCore, a simple + text only user interface is used. + \item \texttt{External} --- an external boot management protocol is used + if available. Otherwise \texttt{Builtin} mode is used. + \item \texttt{Apple} --- Apple boot management is used if available. + Otherwise \texttt{Builtin} mode is used. + \end{itemize} + + + Upon success \texttt{External} mode will entirely disable all boot management + in OpenCore except policy enforcement. In \texttt{Apple} mode it may additionally + bypass policy enforcement. To implement \texttt{External} mode a custom user interface may + utilise \href{https://github.com/acidanthera/OpenCorePkg}{OpenCorePkg} + \texttt{OcBootManagementLib}. Reference example of external graphics interface is provided in + \href{https://github.com/acidanthera/OpenCorePkg/tree/master/Tests/ExternalUi}{ExternalUi} test driver. OpenCore built-in boot picker contains a set of actions chosen during the boot process. @@ -2256,13 +2261,16 @@ behaviour that does not go to any other sections recovery. Hold \texttt{CMD+R} key combination to choose this option. \end{itemize} - \emph{Note}: Activated \texttt{KeySupport}, \texttt{AppleUsbKbDxe}, or similar driver is required + \emph{Note 1}: Activated \texttt{KeySupport}, \texttt{AppleUsbKbDxe}, or similar driver is required for key handling to work. On many firmwares it is not possible to get all the keys function. - In addition to \texttt{OPT} OpenCore supports \texttt{Escape} key - \texttt{ShowPicker}. This key exists 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. + \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. + + \emph{Note 3}: On Macs with problematic GOP it may be difficult to access Apple BootPicker. + To workaround this problem even without loading OpenCore \texttt{BootKicker} utility can be blessed. \end{enumerate} @@ -2444,17 +2452,36 @@ nvram 4D1FDA02-38C7-4A6A-9CC6-4BCCA8B30102:oem-board # SMBIOS Type2 ProductNam Possible values match \texttt{DisplayLevel} values. \item - \texttt{RequireSignature}\\ - \textbf{Type}: \texttt{plist\ boolean}\\ - \textbf{Failsafe}: \texttt{true}\\ - \textbf{Description}: Require \texttt{vault.sig} signature file for - \texttt{vault.plist} in \texttt{OC} directory. + \texttt{Vault}\\ + \textbf{Type}: \texttt{plist\ string}\\ + \textbf{Failsafe}: \texttt{Secure}\\ + \textbf{Description}: Enables vaulting mechanism in OpenCore. - This file should contain a raw 256 byte RSA-2048 signature from SHA-256 - hash of \texttt{vault.plist}. The signature is verified against the public - key embedded into \texttt{OpenCore.efi}. + Valid values: - To embed the public key you should do either of the following: + \begin{itemize} + \tightlist + \item \texttt{Optional} --- require nothing, no vault is enforced, insecure. + \item \texttt{Basic} --- require \texttt{vault.plist} file present + in \texttt{OC} directory. This provides basic filesystem integrity + verification and may protect from unintentional filesystem corruption. + \item \texttt{Secure} --- require \texttt{vault.sig} signature file for + \texttt{vault.plist} in \texttt{OC} directory. This includes \texttt{Basic} + integrity checking but also attempts to build a trusted bootchain. + \end{itemize} + + \texttt{vault.plist} file should contain SHA-256 hashes for all files used by OpenCore. + Presence of this file is highly recommended to ensure that unintentional + file modifications (including filesystem corruption) do not happen unnoticed. + To create this file automatically use + \href{https://github.com/acidanthera/OpenCorePkg/tree/master/Utilities/CreateVault}{\texttt{create\_vault.sh}} script. + Regardless of the underlying filesystem, path name and case must match + between \texttt{config.plist} and \texttt{vault.plist}. + + \texttt{vault.sig} file should contain a raw 256 byte RSA-2048 signature from SHA-256 + hash of \texttt{vault.plist}. The signature is verified against the public + key embedded into \texttt{OpenCore.efi}. To embed the public key you should + do either of the following: \begin{itemize} \tightlist @@ -2466,32 +2493,8 @@ nvram 4D1FDA02-38C7-4A6A-9CC6-4BCCA8B30102:oem-board # SMBIOS Type2 ProductNam RSA public key 520 byte format description can be found in Chromium OS documentation. To convert public key from X.509 certificate or from PEM file use - \href{https://github.com/acidanthera/OcSupportPkg/tree/master/Utilities/CreateVault}{RsaTool}. - - \emph{Note}: \texttt{vault.sig} is used regardless of this option when public key - is embedded into \texttt{OpenCore.efi}. Setting it to \texttt{true} will only ensure - configuration sanity, and abort the boot process when public key is not set but - was supposed to be used for verification. - -\item - \texttt{RequireVault}\\ - \textbf{Type}: \texttt{plist\ boolean}\\ - \textbf{Failsafe}: \texttt{true}\\ - \textbf{Description}: Require \texttt{vault.plist} file present - in \texttt{OC} directory. - - This file should contain SHA-256 hashes for all files used by OpenCore. - Presence of this file is highly recommended to ensure that unintentional - file modifications (including filesystem corruption) do not happen unnoticed. - To create this file automatically use - \href{https://github.com/acidanthera/OcSupportPkg/tree/master/Utilities/CreateVault}{\texttt{create\_vault.sh}} script. - - Regardless of the underlying filesystem, path name and case must match - between \texttt{config.plist} and \texttt{vault.plist}. + \href{https://github.com/acidanthera/OpenCorePkg/tree/master/Utilities/CreateVault}{RsaTool}. - \emph{Note}: \texttt{vault.plist} is tried to be read regardless of the value - of this option, but setting it to \texttt{true} will ensure configuration - sanity, and abort the boot process. The complete set of commands to: @@ -2513,7 +2516,7 @@ dd of=OpenCore.efi if=vault.pub bs=1 seek=$off count=528 conv=notrunc rm vault.pub \end{lstlisting} - \emph{Note}: While it may appear obvious, but you have to use an external + \emph{Note 1}: While it may appear obvious, but you have to use an external method to verify \texttt{OpenCore.efi} and \texttt{BOOTx64.efi} for secure boot path. For this you are recommended to at least enable UEFI SecureBoot with a custom certificate, and sign \texttt{OpenCore.efi} and \texttt{BOOTx64.efi} @@ -2521,6 +2524,11 @@ rm vault.pub 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 + option when \texttt{vault.plist} is present or public key is embedded into + \texttt{OpenCore.efi}. Setting this option will only ensure configuration sanity, + and abort the boot process otherwise. + \item \texttt{ScanPolicy}\\ \textbf{Type}: \texttt{plist\ integer}, 32 bit\\ @@ -2606,6 +2614,13 @@ rm vault.pub \textbf{Description}: Arbitrary ASCII string used as boot arguments (load options) of the specified entry. +\item + \texttt{Auxiliary}\\ + \textbf{Type}: \texttt{plist\ boolean}\\ + \textbf{Failsafe}: \texttt{false}\\ + \textbf{Description}: This entry will not be listed by default when + \texttt{HideAuxiliary} is set to \texttt{true}. + \item \texttt{Comment}\\ \textbf{Type}: \texttt{plist\ string}\\ @@ -2781,7 +2796,7 @@ use. \textbf{Type}: \texttt{plist\ boolean}\\ \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. @@ -2870,7 +2885,7 @@ improvements: e.g. \texttt{ru-RU:252} for Russian locale and ABC keyboard. Also accepts short forms: \texttt{ru:252} or \texttt{ru:0} (U.S. keyboard, compatible with 10.9). Full decoded keyboard list from \texttt{AppleKeyboardLayouts-L.dat} can be found - \href{https://github.com/acidanthera/OcSupportPkg/tree/master/Utilities/AppleKeyboardLayouts}{here}. Using non-latin keyboard on 10.14 + \href{https://github.com/acidanthera/OpenCorePkg/tree/master/Utilities/AppleKeyboardLayouts}{here}. Using non-latin keyboard on 10.14 will not enable ABC keyboard, unlike previous and subsequent macOS versions, and is thus not recommended in case you need 10.14. \item \texttt{7C436110-AB2A-4BBB-A880-FE41995C9F82:security-mode} @@ -2886,6 +2901,12 @@ improvements: \break One-byte data defining boot.efi user interface scaling. Should be \textbf{01} for normal screens and \textbf{02} for HiDPI screens. + \item + \texttt{4D1EDE05-38C7-4A6A-9CC6-4BCCA8B38C14:DefaultBackgroundColor} + \break + Four-byte \texttt{RGBA} data defining boot.efi user interface background colour. + Standard colours include \textbf{BF BF BF 00} (Light Gray) and \textbf{00 00 00 00} + (Syrah Black). Other colours may be set at user's preference. \end{itemize} \subsection{Other Variables}\label{nvramvarsother} @@ -2937,10 +2958,89 @@ troubleshooting: \texttt{7C436110-AB2A-4BBB-A880-FE41995C9F82:bootercfg} \break Booter arguments, similar to \texttt{boot-args} but for boot.efi. Accepts a set of - arguments, which are hexadecimal 64-bit values with or without 0x prefix primarily - for logging control: + arguments, which are hexadecimal 64-bit values with or without \texttt{0x}. + At different stages boot.efi will request different debugging (logging) + modes (e.g. after \texttt{ExitBootServices} it will only print to serial). + Several booter arguments control whether these requests will succeed. The + list of known requests is covered below: + \begin{itemize} - \item \texttt{log=VALUE} + \tightlist + \item \texttt{0x00} -- \texttt{INIT}. + \item \texttt{0x01} -- \texttt{VERBOSE} (e.g. \texttt{-v}, force console logging). + \item \texttt{0x02} -- \texttt{EXIT}. + \item \texttt{0x03} -- \texttt{RESET:OK}. + \item \texttt{0x04} -- \texttt{RESET:FAIL} (e.g. unknown \texttt{board-id}, hibernate mismatch, panic loop, etc.). + \item \texttt{0x05} -- \texttt{RESET:RECOVERY}. + \item \texttt{0x06} -- \texttt{RECOVERY}. + \item \texttt{0x07} -- \texttt{REAN:START}. + \item \texttt{0x08} -- \texttt{REAN:END}. + \item \texttt{0x09} -- \texttt{DT} (can no longer log to DeviceTree). + \item \texttt{0x0A} -- \texttt{EXITBS:START} (forced serial only). + \item \texttt{0x0B} -- \texttt{EXITBS:END} (forced serial only). + \item \texttt{0x0C} -- \texttt{UNKNOWN}. + \end{itemize} + + In 10.15 debugging support was mostly broken before 10.15.4 due to some + kind of refactoring and introduction of a + \href{https://github.com/acidanthera/EfiPkg/blob/master/Include/Protocol/AppleDebugLog.h}{new debug protocol}. + Some of the arguments and their values below may not be valid for versions prior + to 10.15.4. The list of known arguments is covered below: + + \begin{itemize} + \item \texttt{boot-save-log=VALUE} --- debug log save mode for normal boot. + \begin{itemize} + \item \texttt{0} + \item \texttt{1} + \item \texttt{2} --- (default). + \item \texttt{3} + \item \texttt{4} --- (save to file). + \end{itemize} + \item \texttt{wake-save-log=VALUE} --- debug log save mode for hibernation wake. + \begin{itemize} + \item \texttt{0} --- disabled. + \item \texttt{1} + \item \texttt{2} --- (default). + \item \texttt{3} --- (unavailable). + \item \texttt{4} --- (save to file, unavailable). + \end{itemize} + \item \texttt{breakpoint=VALUE} --- enables debug breaks (missing in production \texttt{boot.efi}). + \begin{itemize} + \item \texttt{0} --- disables debug breaks on errors (default). + \item \texttt{1} --- enables debug breaks on errors. + \end{itemize} + \item \texttt{console=VALUE} --- enables console logging. + \begin{itemize} + \item \texttt{0} --- disables console logging. + \item \texttt{1} --- enables console logging when debug protocol is missing (default). + \item \texttt{2} --- enables console logging unconditionally (unavailable). + \end{itemize} + \item \texttt{embed-log-dt=VALUE} --- enables DeviceTree logging. + \begin{itemize} + \item \texttt{0} --- disables DeviceTree logging (default). + \item \texttt{1} --- enables DeviceTree logging. + \end{itemize} + \item \texttt{kc-read-size=VALUE} --- Chunk size used for buffered I/O from network or + disk for prelinkedkernel reading and related. Set to 1MB (0x100000) by default, can be + tuned for faster booting. + \item \texttt{log-level=VALUE} --- log level bitmask. + \begin{itemize} + \item \texttt{0x01} --- enables trace logging (default). + \end{itemize} + \item \texttt{serial=VALUE} --- enables serial logging. + \begin{itemize} + \item \texttt{0} --- disables serial logging (default). + \item \texttt{1} --- enables serial logging for \texttt{EXITBS:END} onwards. + \item \texttt{1} --- enables serial logging for \texttt{EXITBS:START} onwards. + \item \texttt{3} --- enables serial logging when debug protocol is missing. + \item \texttt{4} --- enables serial logging unconditionally. + \end{itemize} + \item \texttt{timestamps=VALUE} --- enables timestamp logging. + \begin{itemize} + \item \texttt{0} --- disables timestamp logging. + \item \texttt{1} --- enables timestamp logging (default). + \end{itemize} + \item \texttt{log=VALUE} --- deprecated starting from 10.15. \begin{itemize} \item \texttt{1} --- AppleLoggingConOutOrErrSet/AppleLoggingConOutOrErrPrint (classical ConOut/StdErr) @@ -2948,19 +3048,20 @@ troubleshooting: \item \texttt{4} --- AppleLoggingFileSet/AppleLoggingFilePrint (BOOTER.LOG/BOOTER.OLD file on EFI partition) \end{itemize} - \item \texttt{debug=VALUE} + \item \texttt{debug=VALUE} --- deprecated starting from 10.15. \begin{itemize} \item \texttt{1} --- enables print something to BOOTER.LOG (stripped code implies there may be a crash) \item \texttt{2} --- enables perf logging to /efi/debug-log in the device three \item \texttt{4} --- enables timestamp printing for styled printf calls \end{itemize} - \item \texttt{level=VALUE} --- Verbosity level of DEBUG output. Everything but - \texttt{0x80000000} is stripped from the binary, and this is the default value. - \item \texttt{kc-read-size=VALUE} --- Chunk size used for buffered I/O from network or - disk for prelinkedkernel reading and related. Set to 1MB (0x100000) by default, can be - tuned for faster booting. -\end{itemize} + \item \texttt{level=VALUE} --- deprecated starting from 10.15. Verbosity level of + DEBUG output. Everything but \texttt{0x80000000} is stripped from the binary, + and this is the default value. + \end{itemize} + + \emph{Note}: To quickly see verbose output from \texttt{boot.efi} on versions before 10.15 + set \texttt{bootercfg} to \texttt{log=1}. \item \texttt{7C436110-AB2A-4BBB-A880-FE41995C9F82:bootercfg-once} \break Booter arguments override removed after first launch. Otherwise equivalent to \texttt{bootercfg}. @@ -2973,6 +3074,21 @@ troubleshooting: \break NVIDIA Web Driver control variable. Takes ASCII digit \texttt{1} or \texttt{0} to enable or disable installed driver. +\item + \texttt{7C436110-AB2A-4BBB-A880-FE41995C9F82:StartupMute} + \break + Mute startup chime sound in firmware audio support. 8-bit integer. + The value of \texttt{0x00} means unmuted. Missing variable or any + other value means muted. This variable only affects Gibraltar + machines (T2). +\item + \texttt{7C436110-AB2A-4BBB-A880-FE41995C9F82:SystemAudioVolume} + \break + System audio volume level for firmware audio support. 8-bit integer. + The bit of \texttt{0x80} means muted. Lower bits are used to encode + volume range specific to installed audio codec. The value is capped + by \texttt{MaximumBootBeepVolume} AppleHDA layout value to avoid + too loud audio playback in the firmware. \end{itemize} \section{PlatformInfo}\label{platforminfo} @@ -3281,7 +3397,7 @@ be used. Version with macOS specific enhancements can be downloaded from by CPU maximum bus ratio and is specified in Hz. Refer to \texttt{MSR\_NEHALEM\_PLATFORM\_INFO}~(\texttt{CEh}) MSR value to determine maximum bus ratio on modern Intel CPUs. - + \emph{Note}: This value is not used on Skylake and newer but is still provided to follow suit. \item @@ -3290,12 +3406,12 @@ be used. Version with macOS specific enhancements can be downloaded from \textbf{Failsafe}: Automatic\\ \textbf{Description}: Sets \texttt{ARTFrequency} in \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 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. - + \emph{Note}: On Intel Skylake X ART frequency may be a little less (approx. 0.25\%) than 24 or 25 MHz due to special EMI-reduction circuit as described in \href{https://github.com/acidanthera/bugtracker/issues/448#issuecomment-524914166}{Acidanthera Bugtracker}. @@ -3476,7 +3592,7 @@ Apple ROM Version \textbf{SMBIOS}: System Information (Type 1) --- Serial Number\\ \textbf{Description}: Product serial number in defined format. Known formats are described in - \href{https://github.com/acidanthera/macserial/blob/master/FORMAT.md}{macserial}. + \href{https://github.com/acidanthera/MacInfoPkg/blob/master/macserial/FORMAT.md}{macserial}. \item \texttt{SystemUUID}\\ \textbf{Type}: \texttt{plist\ string}, GUID\\ @@ -3660,16 +3776,58 @@ and supplementary utilities can be used. \subsection{Properties}\label{uefiprops} \begin{enumerate} +\item + \texttt{Audio}\\ + \textbf{Type}: \texttt{plist\ dict}\\ + \textbf{Failsafe}: None\\ + \textbf{Description}: Configure audio backend support described + in \hyperref[uefiaudioprops]{Audio Properties} section below. + + Audio support provides a way for upstream protocols to interact with the + selected hardware and audio resources. All audio resources should reside + in \texttt{\textbackslash EFI\textbackslash OC\textbackslash Resources\textbackslash Audio} + directory. Currently the only supported audio file format is WAVE PCM. While it is + driver-dependent which audio stream format is supported, most common audio cards + support 16-bit signed stereo audio at 44100 or 48000 Hz. + + Audio file path is determined by audio type, audio localisation, and audio path. Each filename + looks as follows: \texttt{[audio type]\_[audio localisation]\_[audio path].wav}. For unlocalised + files filename does not include the language code and looks as follows: + \texttt{[audio type]\_[audio path].wav}. + + \begin{itemize} + \tightlist + \item Audio type can be \texttt{OCEFIAudio} for OpenCore audio files or + \texttt{AXEFIAudio} for macOS bootloader audio files. + \item Audio localisation is a two letter language code (e.g. \texttt{en}) + with an exception for Chinese, Spanish, and Portuguese. Refer to + \href{https://github.com/acidanthera/EfiPkg/blob/master/Include/Protocol/AppleVoiceOver.h}{\texttt{APPLE\_VOICE\_OVER\_LANGUAGE\_CODE} definition} + for the list of all supported localisations. + \item Audio path is the base filename corresponding to a file identifier. For macOS bootloader audio paths refer to + \href{https://github.com/acidanthera/EfiPkg/blob/master/Include/Protocol/AppleVoiceOver.h}{\texttt{APPLE\_VOICE\_OVER\_AUDIO\_FILE} definition}. + For OpenCore audio paths refer to + \href{https://github.com/acidanthera/OpenCorePkg/blob/master/Include/Protocol/OcAudio.h}{\texttt{OC\_VOICE\_OVER\_AUDIO\_FILE} definition}. + The only exception is OpenCore boot chime file, which is \texttt{OCEFIAudio\_VoiceOver\_Boot.wav}. + \end{itemize} + + Audio localisation is determined separately for macOS bootloader and OpenCore. + For macOS bootloader it is set in \texttt{preferences.efires} archive in + \texttt{systemLanguage.utf8} file and is controlled by the operating system. + For OpenCore the value of \texttt{prev-lang:kbd} variable is used. + When native audio localisation of a particular file is missing, English language + (\texttt{en}) localisation is used. Sample audio files can be found in + \href{https://github.com/acidanthera/OcBinaryData}{OcBinaryData repository}. + \item \texttt{ConnectDrivers}\\ \textbf{Type}: \texttt{plist\ boolean}\\ \textbf{Failsafe}: \texttt{false}\\ \textbf{Description}: Perform UEFI controller connection after driver loading. - This option is useful for loading filesystem drivers, which - usually follow UEFI driver model, and may not start by themselves. - While effective, this option may not be necessary for drivers performing - automatic connection, and may slightly slowdown the boot. + This option is useful for loading drivers following UEFI driver model + as they may not start by themselves. Examples of such drivers are filesystem + 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 drive to speedup the boot process. Enable this option to be able to see all the @@ -3692,13 +3850,29 @@ and supplementary utilities can be used. \item \href{https://github.com/acidanthera/AppleSupportPkg}{\texttt{ApfsDriverLoader}} --- APFS file system bootstrap driver adding the support of embedded APFS drivers in bootable APFS containers in UEFI firmwares. - \item \href{https://github.com/acidanthera/OcSupportPkg}{\texttt{FwRuntimeServices}} + \item \href{https://github.com/acidanthera/AppleSupportPkg}{\texttt{AudioDxe}} + --- HDA audio support driver in UEFI firmwares for most Intel and some other analog audio controllers. + Refer to \href{https://github.com/acidanthera/bugtracker/issues/740}{acidanthera/bugtracker\#740} + for known issues in AudioDxe. + \item \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 + used due to the lack of \texttt{RDRAND} instruction support. + \item \href{https://github.com/acidanthera/OpenCorePkg}{\texttt{FwRuntimeServices}} --- \texttt{OC\_FIRMWARE\_RUNTIME} protocol implementation that increases the security - of OpenCore and Lilu by supporting read-only and write-only NVRAM variables. Some - quirks, like \texttt{RequestBootVarRouting}, require this driver for proper function. + of \mbox{OpenCore} and Lilu by supporting read-only and write-only NVRAM variables. Some + commonly used quirks, e.g. \texttt{RequestBootVarRouting}, require this driver for proper function. Due to the nature of being a runtime driver, i.e. functioning in parallel with the target operating system, it cannot be implemented within OpenCore itself, but is bundled with OpenCore releases. + \item \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 + used due to the lack of \texttt{RDRAND} instruction support. + \item \href{https://github.com/acidanthera/audk}{\texttt{HiiDatabase}} + --- 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. \item \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 @@ -3709,13 +3883,13 @@ and supplementary utilities can be used. --- NVMe support driver from \texttt{MdeModulePkg}. This driver is included in most firmwares starting with Broadwell generation. For Haswell and earlier embedding it within the firmware may be more favourable in case a NVMe SSD drive is installed. - \item \href{https://github.com/acidanthera/OcSupportPkg}{\texttt{AppleUsbKbDxe}} + \item \href{https://github.com/acidanthera/OpenCorePkg}{\texttt{AppleUsbKbDxe}} --- USB keyboard driver adding the support of \texttt{AppleKeyMapAggregator} protocols on top of a custom USB keyboard driver implementation. This is an alternative to builtin \texttt{KeySupport}, which may work better or worse depending on the firmware. \item \href{https://github.com/acidanthera/AppleSupportPkg}{\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 firmwares. While it is feature complete, it is approximately 3~times slower and is yet to undergo a security audit. \item \href{https://github.com/acidanthera/audk}{\texttt{XhciDxe}} @@ -3742,6 +3916,12 @@ build -a X64 -b RELEASE -t XCODE5 -p MdeModulePkg/MdeModulePkg.dsc \textbf{Description}: Apply individual settings designed for input (keyboard and mouse) in \hyperref[uefiinputprops]{Input Properties} section below. +\item + \texttt{Output}\\ + \textbf{Type}: \texttt{plist\ dict}\\ + \textbf{Failsafe}: None\\ + \textbf{Description}: Apply individual settings designed for output (text and graphics) in + \hyperref[uefioutputprops]{Output Properties} section below. \item \texttt{Protocols}\\ @@ -3761,6 +3941,110 @@ build -a X64 -b RELEASE -t XCODE5 -p MdeModulePkg/MdeModulePkg.dsc \end{enumerate} + +\subsection{Audio Properties}\label{uefiaudioprops} + +\begin{enumerate} + +\item + \texttt{AudioCodec}\\ + \textbf{Type}: \texttt{plist\ integer}\\ + \textbf{Failsafe}: empty string\\ + \textbf{Description}: Codec address on the specified audio controller for audio support. + + Normally this contains first audio codec address on the builtin analog audio controller (\texttt{HDEF}). + Audio codec addresses, e.g. \texttt{2}, can be found in the debug log (marked in bold): + + \texttt{OCAU: 1/3 PciRoot(0x0)/Pci(0x1,0x0)/Pci(0x0,0x1)/VenMsg(,\textbf{00000000}) (4 outputs)}\\ + \texttt{OCAU: 2/3 PciRoot(0x0)/Pci(0x3,0x0)/VenMsg(,\textbf{00000000}) (1 outputs)}\\ + \texttt{OCAU: 3/3 PciRoot(0x0)/Pci(0x1B,0x0)/VenMsg(,\textbf{02000000}) (7 outputs)} + + As an alternative this value can be obtained from \texttt{IOHDACodecDevice} class in I/O Registry + containing it in \texttt{IOHDACodecAddress} field. + +\item + \texttt{AudioDevice}\\ + \textbf{Type}: \texttt{plist\ string}\\ + \textbf{Failsafe}: \texttt{0}\\ + \textbf{Description}: Device path of the specified audio controller for audio support. + + Normally this contains builtin analog audio controller (\texttt{HDEF}) device path, + e.g. \texttt{PciRoot(0x0)/Pci(0x1b,0x0)}. The list of recognised audio controllers can be + found in the debug log (marked in bold): + + \texttt{OCAU: 1/3 \textbf{PciRoot(0x0)/Pci(0x1,0x0)/Pci(0x0,0x1)}/VenMsg(,00000000) (4 outputs)}\\ + \texttt{OCAU: 2/3 \textbf{PciRoot(0x0)/Pci(0x3,0x0)}/VenMsg(,00000000) (1 outputs)}\\ + \texttt{OCAU: 3/3 \textbf{PciRoot(0x0)/Pci(0x1B,0x0)}/VenMsg(,02000000) (7 outputs)} + + As an alternative \texttt{gfxutil -f HDEF} command can be used in macOS. Specifying empty device + path will result in the first available audio controller to be used. + +\item + \texttt{AudioOut}\\ + \textbf{Type}: \texttt{plist\ integer}\\ + \textbf{Failsafe}: \texttt{0}\\ + \textbf{Description}: Index of the output port of the specified codec starting from 0. + + Normally this contains the index of the green out of the builtin analog audio controller (\texttt{HDEF}). + The number of output nodes (\texttt{N}) in the debug log (marked in bold): + + \texttt{OCAU: 1/3 PciRoot(0x0)/Pci(0x1,0x0)/Pci(0x0,0x1)/VenMsg(,00000000) (\textbf{4 outputs})}\\ + \texttt{OCAU: 2/3 PciRoot(0x0)/Pci(0x3,0x0)/VenMsg(,00000000) (\textbf{1 outputs})}\\ + \texttt{OCAU: 3/3 PciRoot(0x0)/Pci(0x1B,0x0)/VenMsg(,02000000) (\textbf{7 outputs})} + + The quickest way to find the right port is to bruteforce the values from \texttt{0} to \texttt{N - 1}. + +\item + \texttt{AudioSupport}\\ + \textbf{Type}: \texttt{plist\ boolean}\\ + \textbf{Failsafe}: \texttt{false}\\ + \textbf{Description}: Activate audio support by connecting to a backend driver. + + Enabling this setting routes audio playback from builtin protocols to a dedicated + audio port (\texttt{AudioOut}) of the specified codec (\texttt{AudioCodec}) located + on the audio controller (\texttt{AudioDevice}). + +\item + \texttt{MinimumVolume}\\ + \textbf{Type}: \texttt{plist\ integer}\\ + \textbf{Failsafe}: \texttt{0}\\ + \textbf{Description}: Minimal heard volume level from \texttt{0} to \texttt{100}. + + Screen reader will use this volume level, when the calculated volume level is + less than \texttt{MinimumVolume}. Boot chime sound will not play if the calculated + volume level is less than \texttt{MinimumVolume}. + +\item + \texttt{PlayChime}\\ + \textbf{Type}: \texttt{plist\ boolean}\\ + \textbf{Failsafe}: \texttt{false}\\ + \textbf{Description}: Play chime sound at startup. + + Enabling this setting plays boot chime through builtin audio support. Volume level + is determined by \texttt{MinimumVolume} and \texttt{VolumeAmplifier} settings and + \texttt{SystemAudioVolume} NVRAM variable. + + \emph{Note}: this setting is separate from \texttt{StartupMute} NVRAM variable + to avoid conflicts when the firmware is able to play boot chime. + +\item + \texttt{VolumeAmplifier}\\ + \textbf{Type}: \texttt{plist\ integer}\\ + \textbf{Failsafe}: \texttt{0}\\ + \textbf{Description}: Multiplication coefficient for system volume to raw volume linear translation + from \texttt{0} to \texttt{1000}. + + Volume level range read from \texttt{SystemAudioVolume} varies depending on the codec. + To transform read value in \texttt{[0, 127]} range into raw volume range \texttt{[0, 100]} + the read value is scaled to \texttt{VolumeAmplifier} percents: + \begin{align*} + RawVolume &= MIN(\frac{SystemAudioVolume * VolumeAmplifier}{100}, 100) + \end{align*} + \emph{Note}: the transformation used in macOS is not linear, but it is very close + and this nuance is thus ignored. + +\end{enumerate} + \subsection{Input Properties}\label{uefiinputprops} \begin{enumerate} @@ -3876,10 +4160,214 @@ build -a X64 -b RELEASE -t XCODE5 -p MdeModulePkg/MdeModulePkg.dsc \end{enumerate} +\subsection{Output Properties}\label{uefioutputprops} + +\begin{enumerate} + +\item + \texttt{TextRenderer}\\ + \textbf{Type}: \texttt{plist\ string}\\ + \textbf{Failsafe}: \texttt{BuiltinGraphics}\\ + \textbf{Description}: Chooses renderer for text going through standard + console output. + + Currently two renderers are supported: \texttt{Builtin} and + \texttt{System}. \texttt{System} renderer uses firmware services + for text rendering. \texttt{Builtin} bypassing firmware services + and performs text rendering on its own. Different renderers support + 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 + 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. + + Valid values are combinations of text renderer and rendering mode: + + \begin{itemize} + \tightlist + \item \texttt{BuiltinGraphics} --- Switch to \texttt{Graphics} + mode and use \texttt{Builtin} renderer with + custom \texttt{ConsoleControl}. + \item \texttt{SystemGraphics} --- Switch to \texttt{Graphics} + mode and use \texttt{System} renderer with + custom \texttt{ConsoleControl}. + \item \texttt{SystemText} --- Switch to \texttt{Text} + mode and use \texttt{System} renderer with + custom \texttt{ConsoleControl}. + \item \texttt{SystemGeneric} --- Use \texttt{System} renderer with + system \texttt{ConsoleControl} assuming it behaves correctly. + \end{itemize} + + The use of \texttt{BuiltinGraphics} is generally straightforward. + For most platforms it is necessary to enable \texttt{ProvideConsoleGop}, + set \texttt{Resolution} to \texttt{Max}. + + The use of \texttt{System} protocols is more complicated. In general + the preferred setting is \texttt{SystemGraphics} or \texttt{SystemText}. + Enabling \texttt{ProvideConsoleGop}, setting \texttt{Resolution} to + \texttt{Max}, enabling \texttt{ReplaceTabWithSpace} is useful on almost + all platforms. \texttt{SanitiseClearScreen}, \texttt{IgnoreTextInGraphics}, + and \texttt{ClearScreenOnModeSwitch} are more specific, and their use + depends on the firmware. + + \emph{Note}: Some Macs, namely \texttt{MacPro5,1}, may have broken + console output with newer GPUs, and thus only \texttt{BuiltinGraphics} + may work for them. + +\item + \texttt{ConsoleMode}\\ + \textbf{Type}: \texttt{plist\ string}\\ + \textbf{Failsafe}: Empty string\\ + \textbf{Description}: Sets console output mode as specified + with the \texttt{WxH} (e.g. \texttt{80x24}) formatted string. + + Set to empty string not to change console mode. Set to \texttt{Max} + to try to use largest available console mode. Currently + \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. + +\item + \texttt{Resolution}\\ + \textbf{Type}: \texttt{plist\ string}\\ + \textbf{Failsafe}: Empty string\\ + \textbf{Description}: Sets console output screen resolution. + + \begin{itemize} + \tightlist + \item Set to \texttt{WxH@Bpp} (e.g. \texttt{1920x1080@32}) or \texttt{WxH} + (e.g. \texttt{1920x1080}) formatted string to request custom resolution + from GOP if available. + \item Set to empty string not to change screen resolution. + \item Set to \texttt{Max} to try to use largest available screen resolution. + \end{itemize} + + On HiDPI screens \texttt{APPLE\_VENDOR\_VARIABLE\_GUID} \texttt{UIScale} + NVRAM variable may need to be set to \texttt{02} to enable HiDPI scaling + in \texttt{Builtin} text renderer, FileVault 2 UEFI password interface, + and boot screen logo. Refer to \hyperref[nvramvarsrec]{Recommended Variables} + section for more details. + + \emph{Note}: This will fail when console handle has no GOP protocol. When + the firmware does not provide it, it can be added with \texttt{ProvideConsoleGop} + set to \texttt{true}. + +\item + \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. + This option fills the entire graphics screen with black color before switching to + text mode. + + \emph{Note}: This option only applies to \texttt{System} renderer. + +\item + \texttt{DirectGopRendering}\\ + \textbf{Type}: \texttt{plist\ boolean}\\ + \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. + +\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 + 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}. + + \emph{Note}: This option only applies to \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 + text editor to edit property lists and other documents. This option makes the console + output spaces instead of tabs. + + \emph{Note}: This option only applies to \texttt{System} renderer. + +\item + \texttt{ProvideConsoleGop}\\ + \textbf{Type}: \texttt{plist\ boolean}\\ + \textbf{Failsafe}: \texttt{false}\\ + \textbf{Description}: Ensure GOP (Graphics Output Protocol) on console handle. + + macOS bootloader requires GOP to be present on console handle, yet the exact + location of GOP is not covered by the UEFI specification. This option will + ensure GOP is installed on console handle if it is present. + + \emph{Note}: This option will also replace broken GOP protocol on console handle, + which may be the case on \texttt{MacPro5,1} with newer GPUs. + +\item + \texttt{ReconnectOnResChange}\\ + \textbf{Type}: \texttt{plist\ boolean}\\ + \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. + + \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 + was mandatory and not configurable. Please do not use this unless required. + +\item + \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 + when large display (e.g. 2K or 4K) is used. This option attempts to apply + a workaround. + + \emph{Note}: This option only applies to \texttt{System} renderer. + On all known affected systems \texttt{ConsoleMode} had to be set to + empty string for this to work. + +\end{enumerate} + + \subsection{Protocols Properties}\label{uefiprotoprops} \begin{enumerate} +\item + \texttt{AppleAudio}\\ + \textbf{Type}: \texttt{plist\ boolean}\\ + \textbf{Failsafe}: \texttt{false}\\ + \textbf{Description}: Reinstalls Apple audio protocols with builtin + versions. + + Apple audio protocols allow macOS bootloader and OpenCore to play + sounds and signals for screen reading or audible error reporting. + Supported protocols are beep generation and VoiceOver. VoiceOver protocol + is specific to Gibraltar machines (T2) and is not supported before + macOS High Sierra (10.13). Instead older macOS versions use AppleHDA protocol, + which is currently not implemented. + + Only one set of audio protocols can be available at a time, so in order + to get audio playback in OpenCore user interface on Mac system implementing some + of these protocols this setting should be enabled. + + \emph{Note}: Backend audio driver needs to be configured in \texttt{UEFI Audio} + section for these protocols to be able to stream audio. + \item \texttt{AppleBootPolicy}\\ \textbf{Type}: \texttt{plist\ boolean}\\ @@ -3930,18 +4418,6 @@ build -a X64 -b RELEASE -t XCODE5 -p MdeModulePkg/MdeModulePkg.dsc \textbf{Description}: Reinstalls Apple User Interface Theme protocol with a builtin version. -\item - \texttt{ConsoleControl}\\ - \textbf{Type}: \texttt{plist\ boolean}\\ - \textbf{Failsafe}: \texttt{false}\\ - \textbf{Description}: Replaces Console Control protocol with a builtin version. - - macOS bootloader requires console control protocol for text output, which some firmwares - miss. This option is required to be set when the protocol is already available in the - firmware, and other console control options are used, such as \texttt{IgnoreTextInGraphics}, - \texttt{SanitiseClearScreen}, and sometimes \texttt{ConsoleBehaviourOs} with - \texttt{ConsoleBehaviourUi}). - \item \texttt{DataHub}\\ \textbf{Type}: \texttt{plist\ boolean}\\ @@ -3965,6 +4441,9 @@ build -a X64 -b RELEASE -t XCODE5 -p MdeModulePkg/MdeModulePkg.dsc to support custom cursor images for File Vault 2. Should be set to \texttt{true} to ensure File Vault 2 compatibility on everything but VMs and legacy Macs. + \emph{Note}: Several virtual machines including VMware may have corrupted + cursor image in HiDPI mode and thus may also require this setting to be enabled. + \item \texttt{HashServices}\\ \textbf{Type}: \texttt{plist\ boolean}\\ @@ -3998,31 +4477,6 @@ build -a X64 -b RELEASE -t XCODE5 -p MdeModulePkg/MdeModulePkg.dsc \begin{enumerate} -\item - \texttt{AvoidHighAlloc}\\ - \textbf{Type}: \texttt{plist\ boolean}\\ - \textbf{Failsafe}: \texttt{false}\\ - \textbf{Description}: Advises allocators to avoid allocations above first 4 GBs of RAM. - - This is a workaround for select board firmwares, namely GA-Z77P-D3 (rev. 1.1), failing - to properly access higher memory in UEFI Boot Services. On these boards this quirk is - required for booting entries that need to allocate large memory chunks, such as macOS DMG - recovery entries. On unaffected boards it may cause boot failures, and thus strongly not - recommended. For known issues refer to - \href{https://github.com/acidanthera/bugtracker/issues/449}{\texttt{acidanthera/bugtracker\#449}}. - -\item - \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. - This option fills the entire graphics screen with black color before switching to - text mode. - - \emph{Note}: \texttt{ConsoleControl} should be set to - \texttt{true} for this to work. - \item \texttt{ExitBootServicesDelay}\\ \textbf{Type}: \texttt{plist\ integer}\\ @@ -4047,59 +4501,6 @@ build -a X64 -b RELEASE -t XCODE5 -p MdeModulePkg/MdeModulePkg.dsc \emph{Note}: While the option is not supposed to induce harm on unaffected firmwares, its usage is not recommended when it is not required. -\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 - 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}. - - \emph{Note}: While the option is not supposed to induce harm on unaffected firmwares, - its usage is not recommended when it is not required. This option may hide - onscreen error messages. \texttt{ConsoleControl} may need to be set to - \texttt{true} for this to work. - -\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 - text editor to edit property lists and other documents. This option makes the console - output spaces instead of tabs. - - \emph{Note}: \texttt{ConsoleControl} may need to be set to - \texttt{true} for this to work. - -\item - \texttt{ProvideConsoleGop}\\ - \textbf{Type}: \texttt{plist\ boolean}\\ - \textbf{Failsafe}: \texttt{false}\\ - \textbf{Description}: Ensure GOP (Graphics Output Protocol) on console handle. - - macOS bootloader requires GOP to be present on console handle, yet the exact - location of GOP is not covered by the UEFI specification. This option will - ensure GOP is installed on console handle if it is present. - - \emph{Note}: This option will also replace broken GOP protocol on console handle, - which may be the case on \texttt{MacPro5,1} with newer GPUs. - -\item - \texttt{ReconnectOnResChange}\\ - \textbf{Type}: \texttt{plist\ boolean}\\ - \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. - - \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 - was mandatory and not configurable. Please do not use this unless required. - \item \texttt{ReleaseUsbOwnership}\\ \textbf{Type}: \texttt{plist\ boolean}\\ @@ -4165,19 +4566,6 @@ build -a X64 -b RELEASE -t XCODE5 -p MdeModulePkg/MdeModulePkg.dsc use \href{https://support.apple.com/HT202796}{Startup Disk} preference pane in a firmware that is not compatible with macOS boot entries by design. -\item - \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 - when large display (e.g. 2K or 4K) is used. This option attempts to apply - a workaround. - - \emph{Note}: \texttt{ConsoleControl} may need to be set to - \texttt{true} for this to work. On all known affected systems - \texttt{ConsoleMode} had to be set to empty string for this to work. - \item \texttt{UnblockFsConnect}\\ \textbf{Type}: \texttt{plist\ boolean}\\ @@ -4252,7 +4640,7 @@ build -a X64 -b RELEASE -t XCODE5 -p MdeModulePkg/MdeModulePkg.dsc \item To access Apple filesystems like HFS and APFS separate software may need to be installed. Some of the known tools 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/page-4#post-24180079}{hack for Windows 10}), + (\href{https://forums.macrumors.com/threads/apple-hfs-windows-driver-download.1368010/post-24180079}{hack for Windows 10}), \href{http://www.catacombae.org/hfsexplorer}{HFSExplorer}, MacDrive, Paragon APFS, Paragon HFS+, TransMac, etc. Remember to never ever attempt to modify Apple file systems from Windows as this often leads to irrecoverable data loss. @@ -4322,7 +4710,7 @@ Similar to other projects working with hardware OpenCore supports auditing and d The use of \texttt{NOOPT} or \texttt{DEBUG} build modes instead of \texttt{RELEASE} can produce a lot more debug output. With \texttt{NOOPT} source level debugging with GDB or IDA Pro is also available. For GDB check -\href{https://github.com/acidanthera/OcSupportPkg/tree/master/Debug}{OcSupport Debug} +\href{https://github.com/acidanthera/OpenCorePkg/tree/master/Debug}{OcSupport Debug} page. For IDA Pro you will need IDA Pro 7.3 or newer, refer to \href{https://www.hex-rays.com/products/ida/support/tutorials/index.shtml}{Debugging the XNU Kernel with IDA Pro} for more details. @@ -4421,8 +4809,7 @@ you will need \texttt{debug=0x8} boot argument. \textbf{Why do online recovery images (\texttt{*.dmg}) fail to load?} This may be caused by missing HFS+ driver, as all presently known recovery volumes - have HFS+ filesystem. Another cause may be buggy firmware allocator, which can be - worked around with \texttt{AvoidHighAlloc} UEFI quirk. + have HFS+ filesystem. \item \textbf{Can I use this on Apple hardware or virtual machines?} diff --git a/Include/OpenCore.h b/Include/OpenCore.h index 2c71c86fc140a2e97a2009965cf2b7bf5b578020..af9458c59a25102d3c151891128370b597667f39 100644 --- a/Include/OpenCore.h +++ b/Include/OpenCore.h @@ -30,7 +30,7 @@ OpenCore version reported to log and NVRAM. OPEN_CORE_VERSION must follow X.Y.Z format, where X.Y.Z are single digits. **/ -#define OPEN_CORE_VERSION "0.5.6" +#define OPEN_CORE_VERSION "0.5.7" /** OpenCore build type reported to log and NVRAM.