Docs: Finish writing documentation for Booter section and others

Author: vit9696

Changelog.md

@@ -16,6 +16,7 @@ OpenCore Changelog
 - Significantly improved boot stability on APTIO
 - Added support for Windows & OpenCore on the same drive through `BlessOverride`
 - Added advanced user-specified boot entries through `Misc` -> `Entries`
+- Added `DisableVariableWrite` quirk to disable hardware NVRAM write in macOS
 
 #### v0.0.3
 - Added complete modern platform database (2012+)

Docs/Configuration.pdf

@@ -554,7 +554,6 @@ \subsection{Contribution}\label{configuration-comp}
 -I/UefiPackages/EfiPkg
 -I/UefiPackages/EfiPkg/Include
 -I/UefiPackages/EfiPkg/Include/X64
--I/UefiPackages/AptioFixPkg/Include
 -I/UefiPackages/AppleSupportPkg/Include
 -I/UefiPackages/OpenCorePkg/Include
 -I/UefiPackages/OcSupportPkg/Include
@@ -939,6 +938,59 @@ \subsection{Introduction}\label{booterintro}
 which is no longer maintained. See \hyperref[troubleshootingtricks]{Tips and Tricks}
 section for migration steps.
 
+If you are using this for the first time on a customised firmware, there is a
+list of checks to do first. Prior to starting please ensure that you have:
+
+\begin{itemize}
+\tightlist
+\item Most up-to-date UEFI firmware (check your motherboard vendor website).
+\item \texttt{Fast Boot} and \texttt{Hardware Fast Boot} disabled in firmware
+  settings if present.
+\item \texttt{Above 4G Decoding} or similar enabled in firmware
+  settings if present. Note, that on some motherboards (notably ASUS WS-X299-PRO) this
+  option causes adverse effects, and must be disabled. While no other motherboards
+  with the same issue are known, consider this option to be first to check if you
+  have erratic boot failures.
+\item \texttt{DisableIoMapper} quirk enabled, or \texttt{VT-d} disabled in
+  firmware settings if present, or ACPI DMAR table dropped.
+\item \textbf{No} `slide` boot argument present in NVRAM or anywhere else.
+  It is not necessary unless you cannot boot at all or see
+  \texttt{No slide values are usable! Use custom slide!} message in the log.
+\item \texttt{CFG Lock} (MSR \texttt{0xE2} write protection) disabled in
+  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.
+\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}
+  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.
+\item \texttt{VT-x}, \texttt{Hyper Threading}, \texttt{Execute Disable Bit} enabled
+  in firmware settings if present.
+\item While it may not be required, sometimes you have to disable
+  \texttt{Thunderbolt support}, \texttt{Intel SGX}, and \texttt{Intel Platform Trust}
+  in firmware settings present.
+\end{itemize}
+
+When debugging sleep issues you may want to (temporarily) disable Power Nap and
+automatic power off, which appear to sometimes cause wake to black screen or boot loop
+issues on older platforms. The particular issues may vary, but in general you should
+check ACPI tables first. Here is an example of a bug found in some
+\href{http://www.insanelymac.com/forum/topic/329624-need-cmos-reset-after-sleep-only-after-login/#entry2534645}{Z68 motherboards}.
+To turn Power Nap and the others off run the following commands in Terminal:
+\begin{lstlisting}[label=powernap, style=ocbash]
+sudo pmset autopoweroff 0
+sudo pmset powernap 0
+sudo pmset standby 0
+\end{lstlisting}
+
+\emph{Note}: these settings may reset at hardware change and in certain other circumstances.
+To view their current state use \texttt{pmset -g} command in Terminal.
+
 \subsection{Properties}\label{booterprops}
 
 \begin{enumerate}
@@ -1094,7 +1146,8 @@ \subsection{Quirks Properties}\label{booterpropsquirks}
   contiguous slots of similar types to prevent boot failures.
 
   \emph{Note}: The necessity of this quirk is determined by early boot failures.
-  Do not use this unless you fully understand the consequences.
+  It is rare to need this quirk on Haswell or newer. Do not use unless you fully
+  understand the consequences.
 
 \end{enumerate}
 
@@ -1263,7 +1316,7 @@ \subsection{Add Properties}\label{kernelpropsadd}
   \texttt{MatchKernel}\\
   \textbf{Type}: \texttt{plist\ string}\\
   \textbf{Failsafe}: Empty string\\
-  \textbf{Description}: Blocks kernel driver on selected macOS version only.
+  \textbf{Description}: Adds kernel driver on selected macOS version only.
   The selection happens based on prefix match with the kernel version, i.e.
   \texttt{16.7.0} will match macOS 10.12.6 and \texttt{16.} will match
   any macOS 10.12.x version.
@@ -1558,12 +1611,33 @@ \subsection{Properties}\label{miscprops}
   \textbf{Description}: Apply boot configuration described in
   \hyperref[miscbootprops]{Boot Properties} section below.
 
+\item
+  \texttt{BlessOverride}\\
+  \textbf{Type}: \texttt{plist\ array}\\
+  \textbf{Description}: Add custom scanning paths through bless model.
+
+  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}
+  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},
+  but unlike predefined bless paths they have highest priority.
+
 \item
   \texttt{Debug}\\
   \textbf{Type}: \texttt{plist\ dict}\\
   \textbf{Description}: Apply debug configuration described in
   \hyperref[miscdebugprops]{Debug Properties} section below.
 
+\item
+  \texttt{Entries}\\
+  \textbf{Type}: \texttt{plist\ array}\\
+  \textbf{Description}: Add boot entries to boot picker.
+
+  Designed to be filled with \texttt{plist\ dict} values, describing each load entry.
+  See \hyperref[miscentryprops]{Entry Properties} section below.
+
 \item
   \texttt{Security}\\
   \textbf{Type}: \texttt{plist\ dict}\\
@@ -1573,10 +1647,10 @@ \subsection{Properties}\label{miscprops}
 \item
   \texttt{Tools}\\
   \textbf{Type}: \texttt{plist\ array}\\
-  \textbf{Description}: Add new entries to boot picker.
+  \textbf{Description}: Add tool entries to boot picker.
 
-  Designed to be filled with \texttt{plist\ dict} values, describing each block entry.
-  See \hyperref[misctoolprops]{Tools Properties} section below.
+  Designed to be filled with \texttt{plist\ dict} values, describing each load entry.
+  See \hyperref[miscentryprops]{Entry Properties} section below.
 
   \emph{Note}: Select tools, for example,
   \href{https://github.com/acidanthera/OpenCoreShell}{UEFI Shell} or
@@ -1684,7 +1758,7 @@ \subsection{Boot Properties}\label{miscbootprops}
 
   \begin{itemize}
   \tightlist
-  \item Set to \texttt{WxH@Bpp} (e.g. \texttt{1920x1080@32}) \texttt{WxH}
+  \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.
@@ -2020,7 +2094,7 @@ \subsection{Security Properties}\label{miscsecurityprops}
 
 \end{enumerate}
 
-\subsection{Tools Properties}\label{misctoolprops}
+\subsection{Entry Properties}\label{miscentryprops}
 
 \begin{enumerate}
 \item
@@ -2035,21 +2109,30 @@ \subsection{Tools Properties}\label{misctoolprops}
   \texttt{Enabled}\\
   \textbf{Type}: \texttt{plist\ boolean}\\
   \textbf{Failsafe}: \texttt{false}\\
-  \textbf{Description}: This tool will not be listed unless set to
+  \textbf{Description}: This entry will not be listed unless set to
   \texttt{true}.
 
 \item
   \texttt{Name}\\
   \textbf{Type}: \texttt{plist\ string}\\
   \textbf{Failsafe}: Empty string\\
-  \textbf{Description}: Human readable tool name displayed in boot picker.
+  \textbf{Description}: Human readable entry name displayed in boot picker.
 
 \item
   \texttt{Path}\\
   \textbf{Type}: \texttt{plist\ string}\\
   \textbf{Failsafe}: Empty string\\
-  \textbf{Description}: File path to select UEFI tool relative to \texttt{OC/Tools}
-  directory.
+  \textbf{Description}: Entry location depending on entry type.
+
+  \begin{itemize}
+  \tightlist
+  \item \texttt{Entries} specify external boot options, and therefore take device
+  paths in \texttt{Path} key. These values are not checked, thus be extremely careful.
+  Example: \texttt{PciRoot(0x0)/Pci(0x1,0x1)/.../\textbackslash EFI\textbackslash COOL.EFI}
+  \item \texttt{Tools} specify internal boot options, which are part of bootloader
+  vault, and therefore take file paths relative to \texttt{OC/Tools} directory.
+  Example: \texttt{CleanNvram.efi}.
+  \end{itemize}
 
 \end{enumerate}
 
@@ -2281,21 +2364,31 @@ \subsection{Other Variables}\label{nvramvarsother}
   \item \texttt{acpi\_level=0xFFFF5F} (implies
     \href{https://github.com/acpica/acpica/blob/master/source/include/acoutput.h}
     {\texttt{ACPI\_ALL\_COMPONENTS}})
-  \item \texttt{cpus=VALUE}
-  \item \texttt{debug=VALUE}
-  \item \texttt{io=VALUE}
-  \item \texttt{keepsyms=1}
-  \item \texttt{kextlog=VALUE}
-  \item \texttt{nvda\_drv=1}
+  \item \texttt{batman=VALUE} (\texttt{AppleSmartBatteryManager} debug mask)
+  \item \texttt{batman-nosmc=1} (disable \texttt{AppleSmartBatteryManager} SMC interface)
+  \item \texttt{cpus=VALUE} (maximum number of CPUs used)
+  \item \texttt{debug=VALUE} (debug mask)
+  \item \texttt{io=VALUE} (\texttt{IOKit} debug mask)
+  \item \texttt{keepsyms=1} (show panic log debug symbols)
+  \item \texttt{kextlog=VALUE} (kernel extension loading debug mask)
+  \item \texttt{nv\_disable=1} (disables NVIDIA GPU acceleration)
+  \item \texttt{nvda\_drv=1} (legacy way to enable NVIDIA web driver, removed in 10.12)
+  \item \texttt{npci=0x2000} (\href{https://www.insanelymac.com/forum/topic/260539-1068-officially-released/?do=findComment&comment=1707972}{legacy}, disables \texttt{kIOPCIConfiguratorPFM64})
   \item \texttt{lapic\_dont\_panic=1}
-  \item \texttt{slide=VALUE}
+  \item \texttt{slide=VALUE} (manually set KASLR slide)
+  \item \texttt{smcdebug=VALUE} (\texttt{AppleSMC} debug mask)
+  \item \texttt{-amd\_no\_dgpu\_accel} (alternative to \href{https://github.com/acidanthera/WhateverGreen}{WhateverGreen}'s \texttt{-radvesa} for new GPUs)
   \item \texttt{-nehalem\_error\_disable}
-  \item \texttt{-no\_compat\_check}
-  \item \texttt{-s}
-  \item \texttt{-v}
-  \item \texttt{-x}
+  \item \texttt{-no\_compat\_check} (disable model checking)
+  \item \texttt{-s} (single mode)
+  \item \texttt{-v} (verbose mode)
+  \item \texttt{-x} (safe mode)
   \end{itemize}
 
+  There are multiple external places summarising macOS argument lists:
+  \href{https://osxeon.wordpress.com/2015/08/10/boot-argument-options-in-os-x}{example 1},
+  \href{https://superuser.com/questions/255176/is-there-a-list-of-available-boot-args-for-darwin-os-x}{example 2}.
+
 \item
   \texttt{7C436110-AB2A-4BBB-A880-FE41995C9F82:bootercfg}
   \break
@@ -3033,23 +3126,18 @@ \subsection{Properties}\label{uefiprops}
   quirks, like \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.
-  \item \href{https://github.com/tianocore/edk2/tree/UDK2018}{\texttt{EmuVariableRuntimeDxe}}
-  --- NVRAM emulation driver from \texttt{MdeModulePkg}. NVRAM is supported by most
-  modern firmwares. For firmwares with macOS incompatible NVRAM implementation an
-  emulated driver may be used. This driver will not preserve NVRAM contents across the
-  reboots.
-  \item \href{https://github.com/tianocore/edk2/tree/UDK2018}{\texttt{EnglishDxe}}
+  \item \href{https://github.com/acidanthera/audk}{\texttt{EnglishDxe}}
   --- Unicode collation driver from \texttt{MdeModulePkg}. This driver is a lightweight
   alternative to \texttt{AppleUiSupport}, which contains no Apple-specific code, and
   only provides unicode collation support. The driver is not recommended for use
   on any hardware but few original Macs.
-  \item \href{https://github.com/tianocore/edk2/tree/UDK2018}{\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
   on write attempt.  Embedding this driver within the firmware may be required in case
   writing to EFI partition is needed during the boot process.
-  \item \href{https://github.com/tianocore/edk2/tree/UDK2018}{\texttt{NvmExpressDxe}}
+  \item \href{https://github.com/acidanthera/audk}{\texttt{NvmExpressDxe}}
   --- 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.
@@ -3068,16 +3156,16 @@ \subsection{Properties}\label{uefiprops}
   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/tianocore/edk2/tree/UDK2018}{\texttt{XhciDxe}}
+  \item \href{https://github.com/acidanthera/audk}{\texttt{XhciDxe}}
   --- XHCI USB controller support driver from \texttt{MdeModulePkg}. This driver is
   included in most firmwares starting with Sandy Bridge generation. For earlier firmwares
   or legacy systems it may be used to support external USB 3.0 PCI cards.
   \end{itemize}
 
-  To compile the drivers from TianoCore UDK use the same command you do normally use
+  To compile the drivers from UDK (EDK II) use the same command you do normally use
   for OpenCore compilation, but choose a corresponding package:
 \begin{lstlisting}[label=compileudk, style=ocbash]
-git clone https://github.com/tianocore/edk2 -b UDK2018 UDK
+git clone https://github.com/acidanthera/audk UDK
 cd UDK
 source edksetup.sh
 make -C BaseTools
@@ -3154,8 +3242,11 @@ \subsection{Quirks Properties}\label{uefiquirkprops}
   \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. Not recommended unless required
-  for booting. May cause recovery boot failures on unaffected boards.
+  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{ExitBootServicesDelay}\\
@@ -3247,11 +3338,13 @@ \subsection{Windows support}\label{troubleshootingwin}
   above) prepared with Boot Camp are supposed to work. Third-party UEFI installations
   as well as systems partially supporting UEFI boot, like Windows 7, might work with
   some extra precautions. Things to keep in mind:
-  
+
   \begin{itemize}
   \item MBR (Master Boot Record) installations are legacy and will not be supported.
-  \item Installing Windows and macOS on the same drive is currently unsupported but
-  will be addressed later.
+  \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})
+  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.
   This enables Boot Camp software experience on Windows.
@@ -3288,7 +3381,7 @@ \subsection{Windows support}\label{troubleshootingwin}
 
   While Windows support software from Boot Camp solves most of compatibility problems,
   sometimes you may have to address some of them manually:
-  
+
   \begin{itemize}
   \item To invert mouse wheel scroll direction \texttt{FlipFlopWheel} must be set
   to \texttt{1} as explained on \href{https://superuser.com/a/364353}{SuperUser}.
@@ -3461,6 +3554,27 @@ \subsection{Tips and Tricks}\label{troubleshootingtricks}
   thus not implemented. More detailed explanation can be found on
   \href{https://applelife.ru/posts/819790}{AppleLife.ru}.
 
+\item
+  \textbf{How can I migrate from \texttt{AptioMemoryFix}?}
+
+  Behaviour similar to that of \texttt{AptioMemoryFix} can be obtained by
+  installing \texttt{FwRuntimeServices} driver and enabling the quirks listed below.
+  Please note, that most of these are not necessary to be enabled. Refer to their
+  individual descriptions in this document for more details.
+  \begin{itemize}
+  \tightlist
+  \item \texttt{ProvideConsoleGop} (UEFI quirk)
+  \item \texttt{AvoidRuntimeDefrag}
+  \item \texttt{DiscardHibernateMap}
+  \item \texttt{EnableSafeModeSlide}
+  \item \texttt{EnableWriteUnprotector}
+  \item \texttt{ForceExitBootServices}
+  \item \texttt{ProtectCsmRegion}
+  \item \texttt{ProvideCustomSlide}
+  \item \texttt{SetupVirtualMap}
+  \item \texttt{ShrinkMemoryMap}
+  \end{itemize}
+
 \end{enumerate}
 
 \end{document}