mirror of
https://github.com/acidanthera/OpenCorePkg.git
synced 2025-12-08 19:25:01 +00:00
Docs: Version dump to 0.5.0
This commit is contained in:
vit9696
parent
12cc51b466
commit
c34bde5a87
@ -1,6 +1,8 @@
|
||||
OpenCore Changelog
|
||||
==================
|
||||
|
||||
#### v0.5.0
|
||||
|
||||
#### v0.0.4
|
||||
- Fixed kext injection issues with dummy dependencies
|
||||
- Fixed kext injection issues with reused vtables
|
||||
|
||||
@ -15,6 +15,8 @@ if [ "$(which pdflatex)" = "" ]; then
|
||||
abort "pdflatex is missing, check your TeX Live installation"
|
||||
fi
|
||||
|
||||
rm -f *.aux *.log *.out *.pdf *.toc
|
||||
|
||||
pdflatex Configuration.tex || \
|
||||
abort "Unable to create configuration pdf"
|
||||
pdflatex Configuration.tex || \
|
||||
@ -22,6 +24,8 @@ pdflatex Configuration.tex || \
|
||||
|
||||
cd Differences || abort "Unable to process annotations"
|
||||
|
||||
rm -f *.aux *.log *.out *.pdf *.toc
|
||||
|
||||
latexdiff -s ONLYCHANGEDPAGE PreviousConfiguration.tex ../Configuration.tex \
|
||||
> Differences.tex || \
|
||||
abort "Unable to differentiate"
|
||||
|
||||
Binary file not shown.
@ -80,7 +80,7 @@
|
||||
|
||||
\vspace{0.2in}
|
||||
|
||||
Reference Manual (0.0.4)
|
||||
Reference Manual (0.5.0)
|
||||
|
||||
\vspace{0.2in}
|
||||
|
||||
|
||||
Binary file not shown.
File diff suppressed because it is too large
Load Diff
@ -66,15 +66,21 @@
|
||||
|
||||
\begin{titlepage}
|
||||
\begin{center}
|
||||
\vspace*{3.5in}
|
||||
\vspace*{2.0in}
|
||||
|
||||
\Huge
|
||||
|
||||
\IfFileExists{Logos/Logo.pdf}
|
||||
{\includegraphics[width=160pt, height=160pt]{Logos/Logo.pdf}}
|
||||
{\includegraphics[width=160pt, height=160pt]{../Logos/Logo.pdf}}
|
||||
|
||||
\sffamily
|
||||
|
||||
\textbf{OpenCore}
|
||||
|
||||
\vspace{0.2in}
|
||||
|
||||
Reference Manual (0.0.3)
|
||||
Reference Manual (0.0.4)
|
||||
|
||||
\vspace{0.2in}
|
||||
|
||||
@ -84,6 +90,8 @@
|
||||
|
||||
\vfill
|
||||
|
||||
\rmfamily
|
||||
|
||||
Copyright \textcopyright 2018-2019 vit9696
|
||||
|
||||
\end{center}
|
||||
@ -103,7 +111,7 @@ operating system.
|
||||
For OpenCore issues please refer to
|
||||
\href{https://github.com/acidanthera/bugtracker}{Acidanthera Bugtracker}.
|
||||
|
||||
\section{Generic Terms}\label{generic-terms}
|
||||
\subsection{Generic Terms}\label{generic-terms}
|
||||
|
||||
\begin{itemize}
|
||||
\item
|
||||
@ -169,7 +177,7 @@ For OpenCore issues please refer to
|
||||
larger integers invoke undefined behaviour.
|
||||
\end{itemize}
|
||||
|
||||
\section{Overview}\label{configuration-overview}
|
||||
\section{Configuration}\label{configuration-overview}
|
||||
|
||||
\subsection{Configuration Terms}\label{configuration-terms}
|
||||
|
||||
@ -313,6 +321,8 @@ Root configuration entries consist of the following:
|
||||
\tightlist
|
||||
\item
|
||||
\hyperref[acpi]{\texttt{ACPI}}
|
||||
\item
|
||||
\hyperref[booter]{\texttt{Booter}}
|
||||
\item
|
||||
\hyperref[devprops]{\texttt{DeviceProperties}}
|
||||
\item
|
||||
@ -331,64 +341,10 @@ Root configuration entries consist of the following:
|
||||
specified in the configuration for safety reasons. This behaviour should not
|
||||
be relied upon, and all fields must be properly specified in the configuration.
|
||||
|
||||
\section{Setup}\label{setup-overview}
|
||||
|
||||
\subsection{Directory Structure}\label{directory-structure}
|
||||
|
||||
When directory boot is used the directory structure used should follow
|
||||
the description on \hyperref[fig:DS]{Directory Structure} figure. Available
|
||||
entries include:
|
||||
|
||||
\begin{itemize}
|
||||
\tightlist
|
||||
\item
|
||||
\texttt{BOOTx64.efi}
|
||||
\break
|
||||
Initial booter, which loads \texttt{OpenCore.efi} unless it was
|
||||
already started as a driver.
|
||||
\item
|
||||
\texttt{ACPI}
|
||||
\break
|
||||
Directory used for storing supplemental ACPI information
|
||||
for \hyperref[acpi]{\texttt{ACPI}} section.
|
||||
\item
|
||||
\texttt{Drivers}
|
||||
\break
|
||||
Directory used for storing supplemental \texttt{UEFI}
|
||||
drivers for \hyperref[uefi]{\texttt{UEFI}} section.
|
||||
\item
|
||||
\texttt{Kexts}
|
||||
\break
|
||||
Directory used for storing supplemental kernel information
|
||||
for \hyperref[kernel]{\texttt{Kernel}} section.
|
||||
\item
|
||||
\texttt{Tools}
|
||||
\break
|
||||
Directory used for storing supplemental tools.
|
||||
\item
|
||||
\texttt{OpenCore.efi}
|
||||
\break
|
||||
Main booter driver responsible for operating system loading.
|
||||
\item
|
||||
\texttt{vault.plist}
|
||||
\break
|
||||
Hashes for all files potentially loadable by \texttt{OC Config}.
|
||||
\item
|
||||
\texttt{config.plist}
|
||||
\break
|
||||
\texttt{OC Config}.
|
||||
\item
|
||||
\texttt{vault.sig}
|
||||
\break
|
||||
Signature for \texttt{vault.plist}.
|
||||
\item
|
||||
\texttt{nvram.plist}
|
||||
\break
|
||||
OpenCore variable import file.
|
||||
\item
|
||||
\texttt{opencore.log}
|
||||
\break
|
||||
OpenCore log file.
|
||||
\end{itemize}
|
||||
|
||||
\begin{center}
|
||||
\begin{tikzpicture}[%
|
||||
grow via three points={one child at (0.5,-0.7) and
|
||||
@ -451,7 +407,7 @@ entries include:
|
||||
child [missing] {}
|
||||
child [missing] {}
|
||||
child { node [optional] {nvram.plist}}
|
||||
child { node [optional] {opencore.log}}
|
||||
child { node [optional] {opencore-YYYY-MM-DD-HHMMSS.txt}}
|
||||
;
|
||||
\end{tikzpicture}
|
||||
\break
|
||||
@ -459,6 +415,62 @@ entries include:
|
||||
Figure 1. Directory Structure
|
||||
\end{center}
|
||||
|
||||
When directory boot is used the directory structure used should follow
|
||||
the description on \hyperref[fig:DS]{Directory Structure} figure. Available
|
||||
entries include:
|
||||
|
||||
\begin{itemize}
|
||||
\tightlist
|
||||
\item
|
||||
\texttt{BOOTx64.efi}
|
||||
\break
|
||||
Initial booter, which loads \texttt{OpenCore.efi} unless it was
|
||||
already started as a driver.
|
||||
\item
|
||||
\texttt{ACPI}
|
||||
\break
|
||||
Directory used for storing supplemental ACPI information
|
||||
for \hyperref[acpi]{\texttt{ACPI}} section.
|
||||
\item
|
||||
\texttt{Drivers}
|
||||
\break
|
||||
Directory used for storing supplemental \texttt{UEFI}
|
||||
drivers for \hyperref[uefi]{\texttt{UEFI}} section.
|
||||
\item
|
||||
\texttt{Kexts}
|
||||
\break
|
||||
Directory used for storing supplemental kernel information
|
||||
for \hyperref[kernel]{\texttt{Kernel}} section.
|
||||
\item
|
||||
\texttt{Tools}
|
||||
\break
|
||||
Directory used for storing supplemental tools.
|
||||
\item
|
||||
\texttt{OpenCore.efi}
|
||||
\break
|
||||
Main booter driver responsible for operating system loading.
|
||||
\item
|
||||
\texttt{vault.plist}
|
||||
\break
|
||||
Hashes for all files potentially loadable by \texttt{OC Config}.
|
||||
\item
|
||||
\texttt{config.plist}
|
||||
\break
|
||||
\texttt{OC Config}.
|
||||
\item
|
||||
\texttt{vault.sig}
|
||||
\break
|
||||
Signature for \texttt{vault.plist}.
|
||||
\item
|
||||
\texttt{nvram.plist}
|
||||
\break
|
||||
OpenCore variable import file.
|
||||
\item
|
||||
\texttt{opencore-YYYY-MM-DD-HHMMSS.txt}
|
||||
\break
|
||||
OpenCore log file.
|
||||
\end{itemize}
|
||||
|
||||
\subsection{Installation and Upgrade}\label{configuration-install}
|
||||
|
||||
To install OpenCore reflect the
|
||||
@ -530,12 +542,6 @@ make -C BaseTools
|
||||
build -a X64 -b RELEASE -t XCODE5 -p OpenCorePkg/OpenCorePkg.dsc
|
||||
\end{lstlisting}
|
||||
|
||||
\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}
|
||||
page. For IDA Pro you will need IDA Pro 7.3 or newer.
|
||||
|
||||
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.
|
||||
@ -548,7 +554,6 @@ Add \texttt{.clang\_complete} file with similar content to your UDK root:
|
||||
-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
|
||||
@ -585,7 +590,7 @@ ACPI (Advanced Configuration and Power Interface) is an open standard to
|
||||
discover and configure computer hardware.
|
||||
\href{https://uefi.org/specifications}{ACPI specification} defines the
|
||||
standard tables (e.g.~\texttt{DSDT}, \texttt{SSDT}, \texttt{FACS}, \texttt{DMAR})
|
||||
and various methods (e.g. \texttt{\_DSM}, \texttt{\_PWR}) for implementation.
|
||||
and various methods (e.g. \texttt{\_DSM}, \texttt{\_PRW}) for implementation.
|
||||
Modern hardware needs little changes to maintain ACPI compatibility, yet
|
||||
some of those are provided as a part of OpenCore.
|
||||
|
||||
@ -826,7 +831,7 @@ In the majority of the cases ACPI patches are not useful and harmful:
|
||||
generally do not need it at all, and those that do are fine with much
|
||||
smaller patches.
|
||||
\item
|
||||
Try to avoid hacky changes like renaming \texttt{\_PWR} or \texttt{\_DSM}
|
||||
Try to avoid hacky changes like renaming \texttt{\_PRW} or \texttt{\_DSM}
|
||||
whenever possible.
|
||||
\end{itemize}
|
||||
|
||||
@ -921,6 +926,231 @@ source file may help understanding ACPI opcodes.
|
||||
\end{enumerate}
|
||||
|
||||
|
||||
\section{Booter}\label{booter}
|
||||
|
||||
\subsection{Introduction}\label{booterintro}
|
||||
|
||||
This section allows to apply different kinds of UEFI modifications on
|
||||
Apple bootloader (\texttt{boot.efi}). The modifications currently provide
|
||||
various patches and environment alterations for different firmwares. Some
|
||||
of these features were originally implemented as a part of
|
||||
\href{https://github.com/acidanthera/AptioFixPkg}{\text{AptioMemoryFix.efi}},
|
||||
which is no longer maintained. See \hyperref[troubleshootingtricks]{Tips and Tricks}
|
||||
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}
|
||||
|
||||
\item
|
||||
\texttt{Quirks}\\
|
||||
\textbf{Type}: \texttt{plist\ dict}\\
|
||||
\textbf{Description}: Apply individual booter quirks described
|
||||
in \hyperref[booterpropsquirks]{Quirks Properties} section below.
|
||||
|
||||
\end{enumerate}
|
||||
|
||||
\subsection{Quirks Properties}\label{booterpropsquirks}
|
||||
|
||||
\begin{enumerate}
|
||||
|
||||
\item
|
||||
\texttt{AvoidRuntimeDefrag}\\
|
||||
\textbf{Type}: \texttt{plist\ boolean}\\
|
||||
\textbf{Failsafe}: \texttt{false}\\
|
||||
\textbf{Description}: Protect from boot.efi runtime memory defragmentation.
|
||||
|
||||
This option fixes UEFI runtime services (date, time, NVRAM, power control, etc.)
|
||||
support on many firmwares using SMM backing for select services like variable
|
||||
storage. SMM may try to access physical addresses, but they get moved by boot.efi.
|
||||
|
||||
\emph{Note}: Most but Apple and VMware firmwares need this quirk.
|
||||
|
||||
\item
|
||||
\texttt{DisableVariableWrite}\\
|
||||
\textbf{Type}: \texttt{plist\ boolean}\\
|
||||
\textbf{Failsafe}: \texttt{false}\\
|
||||
\textbf{Description}: Protect from macOS NVRAM write access.
|
||||
|
||||
This is a security option allowing one to restrict NVRAM access in macOS.
|
||||
This quirk requires \texttt{OC\_FIRMWARE\_RUNTIME} protocol implemented
|
||||
in \texttt{FwRuntimeServices.efi}.
|
||||
|
||||
\emph{Note}: This quirk can also be used as an ugly workaround to buggy UEFI
|
||||
runtime services implementations that fail to write variables to NVRAM and
|
||||
break the rest of the operating system.
|
||||
|
||||
\item
|
||||
\texttt{DiscardHibernateMap}\\
|
||||
\textbf{Type}: \texttt{plist\ boolean}\\
|
||||
\textbf{Failsafe}: \texttt{false}\\
|
||||
\textbf{Description}: Reuse original hibernate memory map.
|
||||
|
||||
This option forces XNU kernel to ignore newly supplied memory map and assume
|
||||
that it did not change after waking from hibernation. This behaviour is required
|
||||
to work by Windows, which mandates to
|
||||
\href{https://docs.microsoft.com/en-us/windows-hardware/design/device-experiences/oem-uefi#hibernation-state-s4-transition-requirements}{preserve}
|
||||
runtime memory size and location after S4 wake.
|
||||
|
||||
\emph{Note}: This may be used to workaround buggy memory maps on older hardware,
|
||||
and is now considered rare legacy. Do not use this unless you fully understand
|
||||
the consequences.
|
||||
|
||||
\item
|
||||
\texttt{EnableSafeModeSlide}\\
|
||||
\textbf{Type}: \texttt{plist\ boolean}\\
|
||||
\textbf{Failsafe}: \texttt{false}\\
|
||||
\textbf{Description}: Patch bootloader to have KASLR enabled in safe mode.
|
||||
|
||||
This option is relevant to the users that have issues booting to safe mode
|
||||
(e.g. by holding \texttt{shift} or using \texttt{-x} boot argument). By default
|
||||
safe mode forces \texttt{0} slide as if the system was launched with \texttt{slide=0}
|
||||
boot argument. This quirk tries to patch \texttt{boot.efi} to lift that limitation
|
||||
and let some other value (from \texttt{1} to \texttt{255}) be used. This quirk requires
|
||||
\texttt{ProvideCustomSlide} to be enabled.
|
||||
|
||||
\emph{Note}: The necessity of this quirk is determined by safe mode availability. If
|
||||
booting to safe mode fails, this option can be tried to be enabled.
|
||||
|
||||
\item
|
||||
\texttt{EnableWriteUnprotector}\\
|
||||
\textbf{Type}: \texttt{plist\ boolean}\\
|
||||
\textbf{Failsafe}: \texttt{false}\\
|
||||
\textbf{Description}: Permit write access to UEFI runtime services code.
|
||||
|
||||
This option bypasses \texttt{R\^X} permissions in code pages of UEFI runtime
|
||||
services by removing write protection (\texttt{WP}) bit from \texttt{CR0}
|
||||
register during their execution. This quirk requires \texttt{OC\_FIRMWARE\_RUNTIME}
|
||||
protocol implemented in \texttt{FwRuntimeServices.efi}.
|
||||
|
||||
\emph{Note}: The necessity of this quirk is determined by early boot crashes
|
||||
of the firmware.
|
||||
|
||||
\item
|
||||
\texttt{ForceExitBootServices}\\
|
||||
\textbf{Type}: \texttt{plist\ boolean}\\
|
||||
\textbf{Failsafe}: \texttt{false}\\
|
||||
\textbf{Description}: Retry \texttt{ExitBootServices} with new memory map on failure.
|
||||
|
||||
Try to ensure that \texttt{ExitBootServices} call succeeds even with outdated MemoryMap
|
||||
key argument by obtaining current memory map and retrying \texttt{ExitBootServices} call.
|
||||
|
||||
\emph{Note}: The necessity of this quirk is determined by early boot crashes
|
||||
of the firmware. Do not use this unless you fully understand the consequences.
|
||||
|
||||
\item
|
||||
\texttt{ProtectCsmRegion}\\
|
||||
\textbf{Type}: \texttt{plist\ boolean}\\
|
||||
\textbf{Failsafe}: \texttt{false}\\
|
||||
\textbf{Description}: Protect CSM region areas from relocation.
|
||||
|
||||
Ensure that CSM memory regions are marked as ACPI NVS to prevent boot.efi or XNU from
|
||||
relocating or using them.
|
||||
|
||||
\emph{Note}: The necessity of this quirk is determined by artifacts and sleep wake issues.
|
||||
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{ProvideCustomSlide}\\
|
||||
\textbf{Type}: \texttt{plist\ boolean}\\
|
||||
\textbf{Failsafe}: \texttt{false}\\
|
||||
\textbf{Description}: Provide custom KASLR slide on low memory.
|
||||
|
||||
This option performs memory map analysis of your firmware and checks whether
|
||||
all slides (from \texttt{1} to \texttt{255}) can be used. As \texttt{boot.efi}
|
||||
generates this value randomly with \texttt{rdrand} or pseudo randomly \texttt{rdtsc},
|
||||
there is a chance of boot failure when it chooses a conflicting slide. In case
|
||||
potential conflicts exist, this option forces macOS to use a pseudo random value
|
||||
among the available ones. This also ensures that \texttt{slide=} argument is never
|
||||
passed to the operating system for security reasons.
|
||||
|
||||
\emph{Note}: The necessity of this quirk is determined by \texttt{OCABC: Only N/256
|
||||
slide values are usable!} message in the debug log. If the message is present,
|
||||
this option is to be enabled.
|
||||
|
||||
\item
|
||||
\texttt{SetupVirtualMap}\\
|
||||
\textbf{Type}: \texttt{plist\ boolean}\\
|
||||
\textbf{Failsafe}: \texttt{false}\\
|
||||
\textbf{Description}: Setup virtual memory at \texttt{SetVirtualAddresses}.
|
||||
|
||||
Select firmwares access memory by virtual addresses after \texttt{SetVirtualAddresses}
|
||||
call, which results in early boot crashes. This quirk workarounds the problem by
|
||||
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.
|
||||
|
||||
\item
|
||||
\texttt{ShrinkMemoryMap}\\
|
||||
\textbf{Type}: \texttt{plist\ boolean}\\
|
||||
\textbf{Failsafe}: \texttt{false}\\
|
||||
\textbf{Description}: Attempt to join similar memory map entries.
|
||||
|
||||
Select firmwares have very large memory maps, which do not fit Apple kernel,
|
||||
permitting up to \texttt{64} slots for runtime memory. This quirk attempts to unify
|
||||
contiguous slots of similar types to prevent boot failures.
|
||||
|
||||
\emph{Note}: The necessity of this quirk is determined by early boot failures.
|
||||
It is rare to need this quirk on Haswell or newer. Do not use unless you fully
|
||||
understand the consequences.
|
||||
|
||||
\end{enumerate}
|
||||
|
||||
\section{DeviceProperties}\label{devprops}
|
||||
|
||||
\subsection{Introduction}\label{devpropsintro}
|
||||
@ -1086,7 +1316,7 @@ blocking.
|
||||
\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.
|
||||
@ -1152,8 +1382,8 @@ blocking.
|
||||
\textbf{Type}: \texttt{plist\ data}, 16 bytes\\
|
||||
\textbf{Failsafe}: All zero\\
|
||||
\textbf{Description}: Bit mask of active bits in \texttt{Cpuid1Data}. When
|
||||
each \texttt{Cpuid1Mask} is set to 0, the original CPU bit is used, otherwise
|
||||
.
|
||||
each \texttt{Cpuid1Mask} bit is set to 0, the original CPU bit is used,
|
||||
otherwise set bits take the value of \texttt{Cpuid1Data}.
|
||||
|
||||
\end{enumerate}
|
||||
|
||||
@ -1269,7 +1499,7 @@ blocking.
|
||||
\emph{Note}: This option should avoided whenever possible. Modern firmwares provide
|
||||
\texttt{CFG Lock} setting, disabling which is much cleaner. More details
|
||||
about the issue can be found in
|
||||
\href{https://github.com/acidanthera/AptioFixPkg#verifymsre2}{VerifyMsrE2} notes.
|
||||
\href{https://github.com/acidanthera/AppleSupportPkg#verifymsre2}{VerifyMsrE2} notes.
|
||||
|
||||
\item
|
||||
\texttt{AppleXcpmCfgLock}\\
|
||||
@ -1282,7 +1512,7 @@ blocking.
|
||||
\emph{Note}: This option should avoided whenever possible. Modern firmwares provide
|
||||
\texttt{CFG Lock} setting, disabling which is much cleaner. More details
|
||||
about the issue can be found in
|
||||
\href{https://github.com/acidanthera/AptioFixPkg#verifymsre2}{VerifyMsrE2} notes.
|
||||
\href{https://github.com/acidanthera/AppleSupportPkg#verifymsre2}{VerifyMsrE2} notes.
|
||||
|
||||
\item
|
||||
\texttt{AppleXcpmExtraMsrs}\\
|
||||
@ -1381,12 +1611,33 @@ behaviour that does not go to any other sections
|
||||
\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}\\
|
||||
@ -1396,12 +1647,14 @@ behaviour that does not go to any other sections
|
||||
\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, UEFI Shell or NVRAM cleaning are very
|
||||
\emph{Note}: Select tools, for example,
|
||||
\href{https://github.com/acidanthera/OpenCoreShell}{UEFI Shell} or
|
||||
\href{https://github.com/acidanthera/AppleSupportPkg#cleannvram}{CleanNvram} are very
|
||||
dangerous and \textbf{MUST NOT} appear in production configurations, especially
|
||||
in vaulted ones and protected with secure boot, as they may be used to easily
|
||||
bypass secure boot chain.
|
||||
@ -1465,8 +1718,8 @@ behaviour that does not go to any other sections
|
||||
\texttt{Text} is supposed to work best.
|
||||
\end{itemize}
|
||||
|
||||
\emph{Note}: \texttt{IgnoreTextInGraphics} may need to be enabled for select
|
||||
firmware implementations.
|
||||
\emph{Note}: \texttt{IgnoreTextInGraphics} and \texttt{SanitiseClearScreen} may need to be enabled for select
|
||||
firmware implementations. Particularly APTIO firmwares.
|
||||
|
||||
\item
|
||||
\texttt{ConsoleBehaviourUi}\\
|
||||
@ -1505,7 +1758,7 @@ behaviour that does not go to any other sections
|
||||
|
||||
\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.
|
||||
@ -1642,10 +1895,11 @@ nvram 4D1FDA02-38C7-4A6A-9CC6-4BCCA8B30102:boot-log |
|
||||
date, this data may also be found in NVRAM in \texttt{opencore-version} variable
|
||||
even with boot log disabled.
|
||||
|
||||
File logging will create a file named \texttt{opencore.log} at EFI volume root with
|
||||
log contents. Please be warned that some file system drivers present in firmwares are
|
||||
not reliable, and may corrupt data when writing files through UEFI. Log is attempted
|
||||
to be written in the safest manner, and thus is very slow. Ensure that
|
||||
File logging will create a file named \texttt{opencore-YYYY-MM-DD-HHMMSS.txt} at EFI
|
||||
volume root with log contents (the upper case letter sequence is replaced with date
|
||||
and time from the firmware). Please be warned that some file system drivers present
|
||||
in firmwares are not reliable, and may corrupt data when writing files through UEFI.
|
||||
Log is attempted to be written in the safest manner, and thus is very slow. Ensure that
|
||||
\texttt{DisableWatchDog} is set to \texttt{true} when you use a slow drive.
|
||||
|
||||
\end{enumerate}
|
||||
@ -1840,7 +2094,7 @@ rm vault.pub
|
||||
|
||||
\end{enumerate}
|
||||
|
||||
\subsection{Tools Properties}\label{misctoolprops}
|
||||
\subsection{Entry Properties}\label{miscentryprops}
|
||||
|
||||
\begin{enumerate}
|
||||
\item
|
||||
@ -1855,21 +2109,30 @@ rm vault.pub
|
||||
\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}
|
||||
|
||||
@ -1958,9 +2221,9 @@ as behaviour is undefined otherwise.
|
||||
Variable loading happens prior to \texttt{Block} (and \texttt{Add}) phases, and will not
|
||||
overwrite any existing variable. Variables allowed to be set must be specified in
|
||||
\texttt{LegacySchema}. Third-party scripts may be used to create \texttt{nvram.plist}
|
||||
file. Example can be found in \texttt{Tools}. The use of third-party scripts may
|
||||
require \texttt{ExposeSensitiveData} set to \texttt{0x3} to provide \texttt{boot-path}
|
||||
variable with OpenCore EFI partition UUID.
|
||||
file. An example of such script can be found in \texttt{Utilities}. The use of third-party
|
||||
scripts may require \texttt{ExposeSensitiveData} set to \texttt{0x3} to provide
|
||||
\texttt{boot-path} variable with OpenCore EFI partition UUID.
|
||||
|
||||
\textbf{WARNING}: This feature is very dangerous as it passes unprotected data to your
|
||||
firmware variable services. Use it only when no hardware NVRAM implementation is provided
|
||||
@ -2101,21 +2364,31 @@ troubleshooting:
|
||||
\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
|
||||
@ -2842,33 +3115,29 @@ and supplementary utilities can be used.
|
||||
for FileVault 2 GUI, hotkey parsing (shift, cmd+v, etc.), language collation support,
|
||||
and certain other features important for normal macOS functioning. For hotkey support
|
||||
\texttt{AppleKeyMapAggregator}-compatible driver is required.
|
||||
\item \href{https://github.com/acidanthera/AptioFixPkg}{\texttt{AptioInputFix}}
|
||||
\item \href{https://github.com/acidanthera/AppleSupportPkg}{\texttt{AppleGenericInput}}
|
||||
--- user input driver adding the support of \texttt{AppleKeyMapAggregator} protocols
|
||||
on top of different UEFI input protocols. Additionally resolves mouse input issues
|
||||
on select firmwares. This is an alternative to \texttt{UsbKbDxe}, which may work
|
||||
better or worse depending on the firmware.
|
||||
\item \href{https://github.com/acidanthera/AptioFixPkg}{\texttt{AptioMemoryFix}}
|
||||
--- a set of quirks for various firmwares. While it primarily targets APTIO
|
||||
firmwares, other firmwares may be compatible as well. Among the resolved issues
|
||||
are hibernation support, KASLR, Lilu NVRAM security enhancements, NVRAM, and UEFI
|
||||
Boot entry preservation.
|
||||
\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/AppleSupportPkg}{\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.
|
||||
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/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.
|
||||
@ -2887,16 +3156,16 @@ and supplementary utilities can be used.
|
||||
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
|
||||
@ -2966,6 +3235,19 @@ 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{ExitBootServicesDelay}\\
|
||||
\textbf{Type}: \texttt{plist\ integer}\\
|
||||
@ -3011,10 +3293,6 @@ 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.
|
||||
|
||||
\emph{Note}: Some drivers, like AptioMemoryFix, may provide equivalent functionality.
|
||||
These drivers are not guaranteed to adhere to the same logic, and if a quirk is
|
||||
necessary, this option is preferred.
|
||||
|
||||
\item
|
||||
\texttt{ReleaseUsbOwnership}\\
|
||||
\textbf{Type}: \texttt{plist\ boolean}\\
|
||||
@ -3028,13 +3306,15 @@ build -a X64 -b RELEASE -t XCODE5 -p MdeModulePkg/MdeModulePkg.dsc
|
||||
\texttt{RequestBootVarRouting}\\
|
||||
\textbf{Type}: \texttt{plist\ boolean}\\
|
||||
\textbf{Failsafe}: \texttt{false}\\
|
||||
\textbf{Description}: Request NVRAM driver (or AptioMemoryFix) to redirect
|
||||
\texttt{Boot} prefixed variables from \texttt{EFI\_GLOBAL\_VARIABLE\_GUID}
|
||||
to \texttt{OC\_VENDOR\_VARIABLE\_GUID}.
|
||||
\textbf{Description}: Request redirect\texttt{Boot} prefixed variables from
|
||||
\texttt{EFI\_GLOBAL\_VARIABLE\_GUID} to \texttt{OC\_VENDOR\_VARIABLE\_GUID}.
|
||||
|
||||
This will set special \texttt{boot-redirect} variable, which a compatible
|
||||
driver will abide after booter start. The quirk lets default boot entry
|
||||
This quirk requires \texttt{OC\_FIRMWARE\_RUNTIME} protocol implemented
|
||||
in \texttt{FwRuntimeServices.efi}. The quirk lets default boot entry
|
||||
preservation at times when firmwares delete incompatible boot entries.
|
||||
Simply said, you are required to enable this quirk to be able to reliably
|
||||
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}\\
|
||||
@ -3061,11 +3341,13 @@ build -a X64 -b RELEASE -t XCODE5 -p MdeModulePkg/MdeModulePkg.dsc
|
||||
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.
|
||||
@ -3102,7 +3384,7 @@ build -a X64 -b RELEASE -t XCODE5 -p MdeModulePkg/MdeModulePkg.dsc
|
||||
|
||||
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}.
|
||||
@ -3118,7 +3400,7 @@ build -a X64 -b RELEASE -t XCODE5 -p MdeModulePkg/MdeModulePkg.dsc
|
||||
from Windows as this often leads to irrecoverable data loss.
|
||||
\end{itemize}
|
||||
|
||||
\textbf{Why do I see \texttt{Basic data partition} in Boot Camp Control panel?}
|
||||
\textbf{Why do I see \texttt{Basic data partition} in Boot Camp Startup Disk control panel?}
|
||||
|
||||
Boot Camp control panel uses GPT partition table to obtain each boot option name.
|
||||
After installing Windows separately you will have to relabel the partition manually.
|
||||
@ -3160,6 +3442,45 @@ The operation has completed successfully.
|
||||
\end{lstlisting}
|
||||
|
||||
|
||||
\textbf{How to choose Windows BOOTCAMP with custom NTFS drivers?}
|
||||
|
||||
Third-party drivers providing NTFS support, such as
|
||||
\href{https://www.tuxera.com/community/open-source-ntfs-3g}{NTFS-3G}, Paragon NTFS,
|
||||
Tuxera NTFS or \href{https://www.seagate.com/support/software/paragon}{Seagate Paragon Driver}
|
||||
break certain macOS functionality, including
|
||||
\href{https://support.apple.com/HT202796}{Startup Disk} preference
|
||||
pane normally used for operating system selection. While the recommended option
|
||||
remains not to use such drivers as they commonly corrupt the filesystem, and prefer
|
||||
the driver bundled with macOS with optional write support (
|
||||
\href{http://osxdaily.com/2013/10/02/enable-ntfs-write-support-mac-os-x}{command} or
|
||||
\href{https://mounty.app}{GUI}),
|
||||
there still exist vendor-specific workarounds for their products:
|
||||
\href{https://www.tuxera.com/products/tuxera-ntfs-for-mac/faq}{Tuxera},
|
||||
\href{https://kb.paragon-software.com/article/6604}{Paragon}, etc.
|
||||
|
||||
\subsection{Debugging}\label{troubleshootingdebug}
|
||||
|
||||
Similar to other projects working with hardware OpenCore supports auditing and debugging.
|
||||
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}
|
||||
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.
|
||||
|
||||
To obtain the log during boot you can make the use of serial port debugging. Serial port
|
||||
debugging is enabled in \texttt{Target}, e.g. \texttt{0xB} for onscreen with serial. OpenCore
|
||||
uses \texttt{115200} baud rate, \texttt{8} data bits, no parity, and \texttt{1} stop bit.
|
||||
For macOS your best choice are CP2102-based UART devices. Connect motherboard \texttt{TX}
|
||||
to USB UART \texttt{GND}, and motherboard \texttt{GND} to USB UART \texttt{RX}. Use
|
||||
\texttt{screen} utility to get the output, or download GUI software, such as
|
||||
\href{https://freeware.the-meiers.org}{CoolTerm}.
|
||||
|
||||
Remember to enable \texttt{COM} port in firmware settings, and never use USB cables longer
|
||||
than 1 meter to avoid output corruption. To additionally enable XNU kernel serial output
|
||||
you will need \texttt{debug=0x8} boot argument.
|
||||
|
||||
\subsection{Tips and Tricks}\label{troubleshootingtricks}
|
||||
|
||||
\begin{enumerate}
|
||||
@ -3183,7 +3504,7 @@ The operation has completed successfully.
|
||||
\texttt{Misc} $\rightarrow$ \texttt{Security}
|
||||
$\rightarrow$ \texttt{HaltLevel} $=$ \texttt{0x80000000}.
|
||||
\item Watch Dog is disabled to prevent automatic reboot:
|
||||
\texttt{Uefi} $\rightarrow$ \texttt{Quirks} $\rightarrow$
|
||||
\texttt{Misc} $\rightarrow$ \texttt{Debug} $\rightarrow$
|
||||
\texttt{DisableWatchDog} $=$ \texttt{true}.
|
||||
\item Boot Picker (entry selector) is enabled: \texttt{Misc}
|
||||
$\rightarrow$ \texttt{Boot} $\rightarrow$ \texttt{ShowPicker} $=$ \texttt{true}.
|
||||
@ -3212,6 +3533,13 @@ The operation has completed successfully.
|
||||
\href{https://github.com/acidanthera/OcSupportPkg/tree/master/Utilities/Recovery}{Recovery}
|
||||
tool from \href{https://github.com/acidanthera/OcSupportPkg}{OcSupportPkg}.
|
||||
|
||||
\item
|
||||
\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.
|
||||
|
||||
\item
|
||||
\textbf{Can I use this on Apple hardware or virtual machines?}
|
||||
|
||||
@ -3220,6 +3548,36 @@ The operation has completed successfully.
|
||||
Mac hardware, some ongoing instructions can be found in
|
||||
\href{https://github.com/acidanthera/bugtracker/issues/377}{acidanthera/bugtracker\#377}.
|
||||
|
||||
\item
|
||||
\textbf{Why do Find\&Replace patches must equal in length?}
|
||||
|
||||
For machine code (x86 code) it is not possible to do such replacements due to
|
||||
\href{https://en.wikipedia.org/w/index.php?title=Relative_addressing}{relative addressing}.
|
||||
For ACPI code this is risky, and is technically equivalent to ACPI table replacement,
|
||||
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}
|
||||
|
||||
@ -28,7 +28,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.0.4"
|
||||
#define OPEN_CORE_VERSION "0.5.0"
|
||||
|
||||
/**
|
||||
OpenCore build type reported to log and NVRAM.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user