diff --git a/Docs/Configuration.pdf b/Docs/Configuration.pdf index 33b00cb4..66e09441 100644 Binary files a/Docs/Configuration.pdf and b/Docs/Configuration.pdf differ diff --git a/Docs/Differences/Differences.pdf b/Docs/Differences/Differences.pdf index 8f4fde9e..8eac1a69 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 6b92b6d1..109962ad 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 Fri Nov 1 01:52:01 2019 -%DIF ADD ../Configuration.tex Fri Nov 1 01:39:07 2019 +%DIF DEL PreviousConfiguration.tex Fri Nov 1 12:48:55 2019 +%DIF ADD ../Configuration.tex Fri Nov 1 12:49:08 2019 \usepackage{lmodern} \usepackage{amssymb,amsmath} @@ -1080,60 +1080,55 @@ To view their current state use \texttt{pmset -g} command in Terminal. \begin{enumerate} \item - \DIFaddbegin \texttt{\DIFadd{MmioWhitelist}}\\ - \textbf{\DIFadd{Type}}\DIFadd{: }\texttt{\DIFadd{plist\ array}}\\ - \textbf{\DIFadd{Description}}\DIFadd{: Designed to be filled with }\texttt{\DIFadd{plist\ dict}} \DIFadd{values, + \texttt{MmioWhitelist}\\ + \textbf{Type}: \texttt{plist\ array}\\ + \textbf{Description}: Designed to be filled with \texttt{plist\ dict} values, describing addresses critical for particular firmware functioning when - }\texttt{\DIFadd{DevirtualiseMmio}} \DIFadd{quirk is in use. See }\hyperref[booterpropsmmio]{MmioWhitelist Properties} - \DIFadd{section below. -} + \texttt{DevirtualiseMmio} quirk is in use. See \hyperref[booterpropsmmio]{MmioWhitelist Properties} + section below. \item - \DIFaddend \texttt{Quirks}\\ + \texttt{Quirks}\\ \textbf{Type}: \texttt{plist\ dict}\\ \textbf{Description}: Apply individual booter quirks described in \hyperref[booterpropsquirks]{Quirks Properties} section below. \end{enumerate} -\DIFaddbegin \subsection{\DIFadd{MmioWhitelist Properties}}\label{booterpropsmmio} +\subsection{MmioWhitelist Properties}\label{booterpropsmmio} \begin{enumerate} \item - \texttt{\DIFadd{Address}}\\ - \textbf{\DIFadd{Type}}\DIFadd{: }\texttt{\DIFadd{plist\ integer}}\\ - \textbf{\DIFadd{Failsafe}}\DIFadd{: }\texttt{\DIFadd{0}}\\ - \textbf{\DIFadd{Description}}\DIFadd{: Exceptional MMIO address, which memory descriptor should be left - virtualised (unchanged) by }\texttt{\DIFadd{DevirtualiseMmio}}\DIFadd{. This means that the firmware will + \texttt{Address}\\ + \textbf{Type}: \texttt{plist\ integer}\\ + \textbf{Failsafe}: \texttt{0}\\ + \textbf{Description}: Exceptional MMIO address, which memory descriptor should be left + virtualised (unchanged) by \texttt{DevirtualiseMmio}. This means that the firmware will be able to directly communicate with this memory region during operating system functioning, because the region this value is in will be assigned a virtual address. -} - \DIFadd{The addresses written here must be part of the memory map, have }\texttt{\DIFadd{EfiMemoryMappedIO}} - \DIFadd{type and }\texttt{\DIFadd{EFI\_MEMORY\_RUNTIME}} \DIFadd{attribute (highest bit) set. To find the list of the + The addresses written here must be part of the memory map, have \texttt{EfiMemoryMappedIO} + type and \texttt{EFI\_MEMORY\_RUNTIME} attribute (highest bit) set. To find the list of the candidates the debug log can be used. -} \item - \texttt{\DIFadd{Comment}}\\ - \textbf{\DIFadd{Type}}\DIFadd{: }\texttt{\DIFadd{plist\ string}}\\ - \textbf{\DIFadd{Failsafe}}\DIFadd{: Empty string}\\ - \textbf{\DIFadd{Description}}\DIFadd{: Arbitrary ASCII string used to provide human readable + \texttt{Comment}\\ + \textbf{Type}: \texttt{plist\ string}\\ + \textbf{Failsafe}: Empty string\\ + \textbf{Description}: Arbitrary ASCII string used to provide human readable reference for the entry. It is implementation defined whether this value is used. -} \item - \texttt{\DIFadd{Enabled}}\\ - \textbf{\DIFadd{Type}}\DIFadd{: }\texttt{\DIFadd{plist\ boolean}}\\ - \textbf{\DIFadd{Failsafe}}\DIFadd{: }\texttt{\DIFadd{false}}\\ - \textbf{\DIFadd{Description}}\DIFadd{: This address will be devirtualised unless set to }\texttt{\DIFadd{true}}\DIFadd{. -} + \texttt{Enabled}\\ + \textbf{Type}: \texttt{plist\ boolean}\\ + \textbf{Failsafe}: \texttt{false}\\ + \textbf{Description}: This address will be devirtualised unless set to \texttt{true}. \end{enumerate} -\DIFaddend \subsection{Quirks Properties}\label{booterpropsquirks} +\subsection{Quirks Properties}\label{booterpropsquirks} \begin{enumerate} @@ -1158,18 +1153,14 @@ To view their current state use \texttt{pmset -g} command in Terminal. This option reduces stolen memory footprint from the memory map by removing runtime bit for known memory regions. This quirk may result in the increase of KASLR slides available, but is not necessarily compatible with the target - board. \DIFaddbegin \DIFadd{In general this frees from 64 to 256 megabytes of memory (present in + board. In general this frees from 64 to 256 megabytes of memory (present in the debug log), and on some platforms it is the only way to boot macOS, which otherwise fails with allocation error at bootloader stage. -}\DIFaddend - \DIFdelbegin \emph{\DIFdel{Note}}%DIFAUXCMD -\DIFdel{: }\DIFdelend This option is generally useful on \DIFdelbegin \DIFdel{APTIO V firmwares (Broadwell and - newer). }\DIFdelend \DIFaddbegin \DIFadd{all firmwares except some very old ones, + This option is generally useful on all firmwares except some very old ones, like Sandy Bridge. On select firmwares it may require a list of exceptional addresses that still need to get their virtual addresses for proper NVRAM and - hibernation functioning. Use }\texttt{\DIFadd{MmioWhitelist}} \DIFadd{section to do this. -}\DIFaddend + hibernation functioning. Use \texttt{MmioWhitelist} section to do this. \item \texttt{DisableSingleUser}\\ @@ -1798,21 +1789,19 @@ blocking. log preventing from observing panic details. Affects 10.13 and above. \item - \DIFaddbegin \texttt{\DIFadd{PowerTimeoutKernelPanic}}\\ - \textbf{\DIFadd{Type}}\DIFadd{: }\texttt{\DIFadd{plist\ boolean}}\\ - \textbf{\DIFadd{Failsafe}}\DIFadd{: }\texttt{\DIFadd{false}}\\ - \textbf{\DIFadd{Description}}\DIFadd{: Disables kernel panic on setPowerState timeout. -} + \texttt{PowerTimeoutKernelPanic}\\ + \textbf{Type}: \texttt{plist\ boolean}\\ + \textbf{Failsafe}: \texttt{false}\\ + \textbf{Description}: Disables kernel panic on setPowerState timeout. - \DIFadd{An additional security measure was added to macOS Catalina (10.15) causing + An additional security measure was added to macOS Catalina (10.15) causing kernel panic on power change timeout for Apple drivers. Sometimes it may cause issues on misconfigured hardware, notably digital audio, which sometimes fails - to wake up. For debug kernels }\texttt{\DIFadd{setpowerstate\_panic=0}} \DIFadd{boot argument + to wake up. For debug kernels \texttt{setpowerstate\_panic=0} boot argument should be used, which is otherwise equivalent to this quirk. -} \item - \DIFaddend \texttt{ThirdPartyTrim}\\ + \texttt{ThirdPartyTrim}\\ \textbf{Type}: \texttt{plist\ boolean}\\ \textbf{Failsafe}: \texttt{false}\\ \textbf{Description}: Patch IOAHCIBlockStorage.kext to force TRIM command support @@ -1862,7 +1851,7 @@ behaviour that does not go to any other sections Designed to be filled with \texttt{plist\ string} entries containing absolute UEFI paths to customised bootloaders, for example, - \texttt{\textbackslash EFI\textbackslash Microsoft\textbackslash \DIFaddbegin \DIFadd{Boot\textbackslash }\DIFaddend bootmgfw.efi} + \texttt{\textbackslash EFI\textbackslash Microsoft\textbackslash Boot\textbackslash bootmgfw.efi} for Microsoft bootloader. This allows unusual boot paths to be automaticlly discovered by the boot picker. Designwise they are equivalent to predefined blessed path, such as \texttt{\textbackslash System\textbackslash Library\textbackslash CoreServices\textbackslash boot.efi}, @@ -2057,8 +2046,7 @@ behaviour that does not go to any other sections \textbf{Type}: \texttt{plist\ integer}, 32 bit\\ \textbf{Failsafe}: \texttt{0}\\ \textbf{Description}: Timeout in seconds in boot picker before - automatic booting of the default boot entry. \DIFaddbegin \DIFadd{Use 0 to disable timer. -}\DIFaddend + automatic booting of the default boot entry. Use 0 to disable timer. \item \texttt{UsePicker}\\ @@ -2221,15 +2209,15 @@ nvram 4D1FDA02-38C7-4A6A-9CC6-4BCCA8B30102:boot-log | \item \texttt{ExposeSensitiveData}\\ \textbf{Type}: \texttt{plist\ integer}\\ - \textbf{Failsafe}: \texttt{\DIFdelbegin \DIFdel{2}\DIFdelend \DIFaddbegin \DIFadd{0x6}\DIFaddend }\\ + \textbf{Failsafe}: \texttt{0x6}\\ \textbf{Description}: Sensitive data exposure bitmask (sum) to operating system. \begin{itemize} \tightlist \item \texttt{0x01} --- Expose printable booter path as an UEFI variable. \item \texttt{0x02} --- Expose OpenCore version as an UEFI variable. - \DIFaddbegin \item \texttt{\DIFadd{0x04}} \DIFadd{--- Expose OpenCore version in boot picker menu title. - }\DIFaddend \end{itemize} + \item \texttt{0x04} --- Expose OpenCore version in boot picker menu title. + \end{itemize} Exposed booter path points to OpenCore.efi or its booter depending on the load order. To obtain booter path use the following command in macOS: @@ -3807,24 +3795,21 @@ build -a X64 -b RELEASE -t XCODE5 -p MdeModulePkg/MdeModulePkg.dsc to be present on console handle. This option will install it if missing. \item - \DIFaddbegin \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 - \DIFaddend \texttt{ReleaseUsbOwnership}\\ + \texttt{ReleaseUsbOwnership}\\ \textbf{Type}: \texttt{plist\ boolean}\\ \textbf{Failsafe}: \texttt{false}\\ \textbf{Description}: Attempt to detach USB controller ownership from @@ -3888,7 +3873,7 @@ build -a X64 -b RELEASE -t XCODE5 -p MdeModulePkg/MdeModulePkg.dsc \item MBR (Master Boot Record) installations are legacy and will not be supported. \item To install Windows, macOS, and OpenCore on the same drive you can specify Windows bootloader path - (\texttt{\textbackslash EFI\textbackslash Microsoft\textbackslash \DIFaddbegin \DIFadd{Boot\textbackslash }\DIFaddend bootmgfw.efi}) + (\texttt{\textbackslash EFI\textbackslash Microsoft\textbackslash Boot\textbackslash bootmgfw.efi}) in \texttt{BlessOverride} section. \item All the modifications applied (to ACPI, NVRAM, SMBIOS, etc.) are supposed to be operating system agnostic, i.e. apply equally regardless of the OS booted. @@ -3898,7 +3883,7 @@ build -a X64 -b RELEASE -t XCODE5 -p MdeModulePkg/MdeModulePkg.dsc \href{https://github.com/acidanthera/bugtracker/issues/327}{workaround} for this, it is highly recommend not to rely on it and install properly. \item Windows may need to be reactivated. To avoid it consider - \DIFdelbegin \DIFdel{leaving SystemUUID field empty, so that }\DIFdelend \DIFaddbegin \DIFadd{setting SystemUUID to }\DIFaddend the original firmware UUID\DIFdelbegin \DIFdel{is used}\DIFdelend . Be warned, + setting SystemUUID to the original firmware UUID. Be warned, on old firmwares it may be invalid, i.e. not random. In case you still have issues, consider using HWID or KMS38 license. The nuances of Windows activation are out of the scope of this document and can be found online. diff --git a/Docs/Differences/PreviousConfiguration.tex b/Docs/Differences/PreviousConfiguration.tex index a668f23f..ed7f253c 100755 --- a/Docs/Differences/PreviousConfiguration.tex +++ b/Docs/Differences/PreviousConfiguration.tex @@ -1019,6 +1019,14 @@ To view their current state use \texttt{pmset -g} command in Terminal. \begin{enumerate} +\item + \texttt{MmioWhitelist}\\ + \textbf{Type}: \texttt{plist\ array}\\ + \textbf{Description}: Designed to be filled with \texttt{plist\ dict} values, + describing addresses critical for particular firmware functioning when + \texttt{DevirtualiseMmio} quirk is in use. See \hyperref[booterpropsmmio]{MmioWhitelist Properties} + section below. + \item \texttt{Quirks}\\ \textbf{Type}: \texttt{plist\ dict}\\ @@ -1027,6 +1035,39 @@ To view their current state use \texttt{pmset -g} command in Terminal. \end{enumerate} +\subsection{MmioWhitelist Properties}\label{booterpropsmmio} + +\begin{enumerate} + +\item + \texttt{Address}\\ + \textbf{Type}: \texttt{plist\ integer}\\ + \textbf{Failsafe}: \texttt{0}\\ + \textbf{Description}: Exceptional MMIO address, which memory descriptor should be left + virtualised (unchanged) by \texttt{DevirtualiseMmio}. This means that the firmware will + be able to directly communicate with this memory region during operating system functioning, + because the region this value is in will be assigned a virtual address. + + The addresses written here must be part of the memory map, have \texttt{EfiMemoryMappedIO} + type and \texttt{EFI\_MEMORY\_RUNTIME} attribute (highest bit) set. To find the list of the + candidates the debug log can be used. + +\item + \texttt{Comment}\\ + \textbf{Type}: \texttt{plist\ string}\\ + \textbf{Failsafe}: Empty string\\ + \textbf{Description}: Arbitrary ASCII string used to provide human readable + reference for the entry. It is implementation defined whether this value is + used. + +\item + \texttt{Enabled}\\ + \textbf{Type}: \texttt{plist\ boolean}\\ + \textbf{Failsafe}: \texttt{false}\\ + \textbf{Description}: This address will be devirtualised unless set to \texttt{true}. + +\end{enumerate} + \subsection{Quirks Properties}\label{booterpropsquirks} \begin{enumerate} @@ -1052,10 +1093,14 @@ To view their current state use \texttt{pmset -g} command in Terminal. This option reduces stolen memory footprint from the memory map by removing runtime bit for known memory regions. This quirk may result in the increase of KASLR slides available, but is not necessarily compatible with the target - board. - - \emph{Note}: This option is generally useful on APTIO V firmwares (Broadwell and newer). + board. In general this frees from 64 to 256 megabytes of memory (present in + the debug log), and on some platforms it is the only way to boot macOS, which + otherwise fails with allocation error at bootloader stage. + This option is generally useful on all firmwares except some very old ones, + like Sandy Bridge. On select firmwares it may require a list of exceptional + addresses that still need to get their virtual addresses for proper NVRAM and + hibernation functioning. Use \texttt{MmioWhitelist} section to do this. \item \texttt{DisableSingleUser}\\ @@ -1683,6 +1728,18 @@ blocking. \textbf{Description}: Prevent kernel from printing kext dump in the panic log preventing from observing panic details. Affects 10.13 and above. +\item + \texttt{PowerTimeoutKernelPanic}\\ + \textbf{Type}: \texttt{plist\ boolean}\\ + \textbf{Failsafe}: \texttt{false}\\ + \textbf{Description}: Disables kernel panic on setPowerState timeout. + + An additional security measure was added to macOS Catalina (10.15) causing + kernel panic on power change timeout for Apple drivers. Sometimes it may cause + issues on misconfigured hardware, notably digital audio, which sometimes fails + to wake up. For debug kernels \texttt{setpowerstate\_panic=0} boot argument + should be used, which is otherwise equivalent to this quirk. + \item \texttt{ThirdPartyTrim}\\ \textbf{Type}: \texttt{plist\ boolean}\\ @@ -1734,7 +1791,7 @@ behaviour that does not go to any other sections Designed to be filled with \texttt{plist\ string} entries containing absolute UEFI paths to customised bootloaders, for example, - \texttt{\textbackslash EFI\textbackslash Microsoft\textbackslash bootmgfw.efi} + \texttt{\textbackslash EFI\textbackslash Microsoft\textbackslash Boot\textbackslash bootmgfw.efi} for Microsoft bootloader. This allows unusual boot paths to be automaticlly discovered by the boot picker. Designwise they are equivalent to predefined blessed path, such as \texttt{\textbackslash System\textbackslash Library\textbackslash CoreServices\textbackslash boot.efi}, @@ -1929,7 +1986,7 @@ behaviour that does not go to any other sections \textbf{Type}: \texttt{plist\ integer}, 32 bit\\ \textbf{Failsafe}: \texttt{0}\\ \textbf{Description}: Timeout in seconds in boot picker before - automatic booting of the default boot entry. + automatic booting of the default boot entry. Use 0 to disable timer. \item \texttt{UsePicker}\\ @@ -2092,13 +2149,14 @@ nvram 4D1FDA02-38C7-4A6A-9CC6-4BCCA8B30102:boot-log | \item \texttt{ExposeSensitiveData}\\ \textbf{Type}: \texttt{plist\ integer}\\ - \textbf{Failsafe}: \texttt{2}\\ + \textbf{Failsafe}: \texttt{0x6}\\ \textbf{Description}: Sensitive data exposure bitmask (sum) to operating system. \begin{itemize} \tightlist \item \texttt{0x01} --- Expose printable booter path as an UEFI variable. \item \texttt{0x02} --- Expose OpenCore version as an UEFI variable. + \item \texttt{0x04} --- Expose OpenCore version in boot picker menu title. \end{itemize} Exposed booter path points to OpenCore.efi or its booter depending on the load order. @@ -3676,6 +3734,20 @@ build -a X64 -b RELEASE -t XCODE5 -p MdeModulePkg/MdeModulePkg.dsc \textbf{Description}: macOS bootloader requires GOP (Graphics Output Protocol) to be present on console handle. This option will install it if missing. +\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}\\ @@ -3741,7 +3813,7 @@ build -a X64 -b RELEASE -t XCODE5 -p MdeModulePkg/MdeModulePkg.dsc \item MBR (Master Boot Record) installations are legacy and will not be supported. \item To install Windows, macOS, and OpenCore on the same drive you can specify Windows bootloader path - (\texttt{\textbackslash EFI\textbackslash Microsoft\textbackslash bootmgfw.efi}) + (\texttt{\textbackslash EFI\textbackslash Microsoft\textbackslash Boot\textbackslash bootmgfw.efi}) in \texttt{BlessOverride} section. \item All the modifications applied (to ACPI, NVRAM, SMBIOS, etc.) are supposed to be operating system agnostic, i.e. apply equally regardless of the OS booted. @@ -3751,7 +3823,7 @@ build -a X64 -b RELEASE -t XCODE5 -p MdeModulePkg/MdeModulePkg.dsc \href{https://github.com/acidanthera/bugtracker/issues/327}{workaround} for this, it is highly recommend not to rely on it and install properly. \item Windows may need to be reactivated. To avoid it consider - leaving SystemUUID field empty, so that the original firmware UUID is used. Be warned, + setting SystemUUID to the original firmware UUID. Be warned, on old firmwares it may be invalid, i.e. not random. In case you still have issues, consider using HWID or KMS38 license. The nuances of Windows activation are out of the scope of this document and can be found online.