OpenCorePkg/Docs/Configuration.tex

\documentclass[]{article}

\usepackage{lmodern}
\usepackage{amssymb,amsmath}
\usepackage{ifxetex,ifluatex}
\usepackage[T1]{fontenc}
\usepackage[utf8]{inputenc}
\usepackage{upquote}
\usepackage{microtype}
\usepackage[unicode=true]{hyperref}
\usepackage{longtable,booktabs}
\usepackage{footnote}
\usepackage{listings}
\usepackage{mathtools}
\usepackage{parskip}
\usepackage[margin=0.7in]{geometry}
\usepackage{titlesec}
\usepackage[yyyymmdd,hhmmss]{datetime}
\usepackage{textcomp}
\usepackage{tikz}

\setcounter{tocdepth}{2}
\usetikzlibrary{trees}
\tikzstyle{every node}=[draw=black,thick,anchor=west]
\tikzstyle{selected}=[draw=blue]
\tikzstyle{optional}=[dashed,fill=gray!50]

\renewcommand{\dateseparator}{.}

\makeatletter
\newcommand*{\bdiv}{%
  \nonscript\mskip-\medmuskip\mkern5mu%
  \mathbin{\operator@font div}\penalty900\mkern5mu%
  \nonscript\mskip-\medmuskip
}
\makeatother

% Newer LaTeX versions should not add ligatures to listings, but for some reason
% it is not the case for me. As a result select PDF viewers copy wrong data.
\lstdefinestyle{ocbash}{
  language=bash,
  frame=tb,
  columns=fullflexible,
  captionpos=b,
  basicstyle=\ttfamily\normalsize,
  keepspaces=true,
  morekeywords={git, make, build, ioreg, grep, nvram, sort, sudo, diskutil, gfxutil, strings, dd, cut, python},
  literate =
    {"}{{\textquotedbl}}1
    {'}{{\textquotesingle}}1
    {-}{{-}}1
    {~}{{\texttildelow}}1
    {*}{{*}}1
    {fl}{{f{}l}}2
    {fi}{{f{}i}}2
    ,
}

\UseMicrotypeSet[protrusion]{basicmath} % disable protrusion for tt fonts
\PassOptionsToPackage{hyphens}{url} % url is loaded by hyperref

\makesavenoteenv{long table} % Fix footnotes in tables

% set default figure placement to htbp
\makeatletter
\def\fps@figure{htbp}
\makeatother

\providecommand{\tightlist}{%
  \setlength{\itemsep}{0pt}\setlength{\parskip}{0pt}}

\newcommand{\sectionbreak}{\clearpage}

% Fix spacing for subsections in table of contents.
\makeatletter
\renewcommand{\l@subsection}{\@dottedtocline{2}{1.5em}{2.8em}}
\makeatother

\begin{document}

\begin{titlepage}
   \begin{center}
       \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.6.7)

       \vspace{0.2in}

        {[}\today{]}

       \normalsize

       \vfill

       \rmfamily

       Copyright \textcopyright 2018-2021 vit9696

   \end{center}
\end{titlepage}

\tableofcontents

\section{Introduction}\label{introduction}

This document provides information on
\href{https://github.com/acidanthera/OpenCorePkg}{OpenCore} user
configuration file format used to set up the correct functioning of the macOS
operating system. It is to be read as the official clarification of expected
OpenCore behaviour. All deviations, if found in published OpenCore releases,
shall be considered to be documentation or implementation bugs which should be
reported via the \href{https://github.com/acidanthera/bugtracker}{Acidanthera Bugtracker}.
An errata sheet is available in
\href{https://github.com/acidanthera/OpenCorePkg/blob/master/Docs/Errata/Errata.pdf}{OpenCorePkg repository}.

This document is structured as a specification and is not meant to provide a step-by-step
guide to configuring an end-user Board Support Package (BSP). The intended audience
of the document is anticipated to be programmers and engineers with a basic understanding of macOS internals
and UEFI functionality. For these reasons, this document is available exclusively in English,
and all other sources or translations of this document are unofficial and may
contain errors.

Third-party articles, utilities, books, and similar, may be more useful for a wider audience as
they could provide guide-like material. However, they are subject to their authors' preferences,
tastes, misinterpretations of this document, and unavoidable obsolescence.
In cases of using such sources, such as \href{https://dortania.github.io}{Dortania}'s
\href{https://dortania.github.io/OpenCore-Install-Guide}{OpenCore Install Guide}
and \href{https://dortania.github.io/getting-started}{related material},
please refer back to this document on every decision made and re-evaluate potential consequences.

Please note that regardless of the sources used, users are required to fully understand every
OpenCore configuration option, and the principles behind them, before posting issues to the
\href{https://github.com/acidanthera/bugtracker}{Acidanthera Bugtracker}.

\emph{Note}: Creating this document would not have been possible without the invaluable
contributions from other people: Andrey1970, Goldfish64, dakanji, PMheart, and several others,
with the full list available in
\href{https://github.com/acidanthera/OpenCorePkg/commits/master/Docs}{OpenCorePkg history}.

\subsection{Generic Terms}\label{generic-terms}

\begin{itemize}
\item
  \texttt{plist} --- Subset of ASCII Property List format written in
  XML, also know as XML plist format version 1. Uniform Type Identifier
  (UTI): \texttt{com.apple.property-list}. Plists consist of
  \texttt{plist\ objects}, which are combined to form a hierarchical
  structure. Due to plist format not being well-defined, all the
  definitions of this document may only be applied after plist is
  considered valid by running \texttt{plutil\ -lint}. External
  references: https://www.apple.com/DTDs/PropertyList-1.0.dtd,
  \texttt{man\ plutil}.
\item
  \texttt{plist\ type} --- plist collections (\texttt{plist\ array},
  \texttt{plist\ dictionary}, \texttt{plist\ key}) and primitives
  (\texttt{plist\ string}, \texttt{plist\ data}, \texttt{plist\ date},
  \texttt{plist\ boolean}, \texttt{plist\ integer},
  \texttt{plist\ real}).
\item
  \texttt{plist\ object} --- definite realisation of
  \texttt{plist\ type}, which may be interpreted as value.
\item
  \texttt{plist\ array} --- array-like collection, conforms to
  \texttt{array}. Consists of zero or more \texttt{plist\ objects}.
\item
  \texttt{plist\ dictionary} --- map-like (associative array)
  collection, conforms to \texttt{dict}. Consists of zero or more
  \texttt{plist\ keys}.
\item
  \texttt{plist\ key} --- contains one \texttt{plist\ object} going by
  the name of \texttt{plist\ key}, conforms to \texttt{key}. Consists of
  printable 7-bit ASCII characters.
\item
  \texttt{plist\ string} --- printable 7-bit ASCII string, conforms to
  \texttt{string}.
\item
  \texttt{plist\ data} --- base64-encoded blob, conforms to
  \texttt{data}.
\item
  \texttt{plist\ date} --- ISO-8601 date, conforms to \texttt{date},
  unsupported.
\item
  \texttt{plist\ boolean} --- logical state object, which is either true
  (1) or false (0), conforms to \texttt{true} and \texttt{false}.
\item
  \texttt{plist\ integer} --- possibly signed integer number in base 10,
  conforms to \texttt{integer}. Fits in 64-bit unsigned integer in two's
  complement representation, unless a smaller signed or unsigned
  integral type is explicitly mentioned in specific
  \texttt{plist\ object} description.
\item
  \texttt{plist\ real} --- floating point number, conforms to
  \texttt{real}, unsupported.
\item
  \texttt{plist\ metadata} --- value cast to data by the implementation.
  Permits passing \texttt{plist\ string}, in which case the result is
  represented by a null-terminated sequence of bytes (aka C string),
  \texttt{plist\ integer}, in which case the result is represented by
  \emph{32-bit} little endian sequence of bytes in two's complement
  representation, \texttt{plist\ boolean}, in which case the value is
  one byte: \texttt{01} for \texttt{true} and \texttt{00} for
  \texttt{false}, and \texttt{plist\ data} itself. All other types or
  larger integers invoke undefined behaviour.
\end{itemize}

\section{Configuration}\label{configuration-overview}

\subsection{Configuration Terms}\label{configuration-terms}

\begin{itemize}
\item
  \texttt{OC\ config} --- OpenCore Configuration file in \texttt{plist}
  format named \texttt{config.plist}. It has to provide extensible way
  to configure OpenCore and is structured to be separated into multiple
  named sections situated in the root \texttt{plist\ dictionary}. These
  sections are permitted to have \texttt{plist\ array} or
  \texttt{plist\ dictionary} types and are described in corresponding
  sections of this document.
\item
  \texttt{valid\ key} --- \texttt{plist\ key} object of
  \texttt{OC\ config} described in this document or its future
  revisions. Besides explicitly described \texttt{valid\ keys}, keys
  starting with \texttt{\#} symbol (e.g. \texttt{\#Hello}) are also
  considered \texttt{valid\ keys} and behave as comments, effectively
  discarding their value, which is still required to be a valid
  \texttt{plist\ object}. All other \texttt{plist\ keys} are not valid,
  and their presence yields to \texttt{undefined\ behaviour}.
\item
  \texttt{valid\ value} --- valid \texttt{plist\ object} of
  \texttt{OC\ config} described in this document that matches all the
  additional requirements in specific \texttt{plist\ object} description
  if any.
\item
  \texttt{invalid\ value} --- valid \texttt{plist\ object} of
  \texttt{OC\ config} described in this document that is of other
  \texttt{plist\ type}, does not conform to additional requirements
  found in specific \texttt{plist\ object} description (e.g.~value
  range), or missing from the corresponding collection.
  \texttt{Invalid\ value} is read with or without an error message as
  any possible value of this \texttt{plist\ object} in an undetermined
  manner (i.e.~the values may not be same across the reboots). Whilst
  reading an \texttt{invalid\ value} is equivalent to reading certain
  defined \texttt{valid\ value}, applying incompatible value to the host
  system may yield to \texttt{undefined\ behaviour}.
\item
  \texttt{optional\ value} --- \texttt{valid\ value} of
  \texttt{OC\ config} described in this document that reads in a certain
  defined manner provided in specific \texttt{plist\ object} description
  (instead of \texttt{invalid\ value}) when not present in
  \texttt{OC\ config}. All other cases of \texttt{invalid\ value} do
  still apply. Unless explicitly marked as \texttt{optional\ value}, any
  other value is required to be present and reads to
  \texttt{invalid\ value} if missing.
\item
  \texttt{fatal\ behaviour} --- behaviour leading to boot termination.
  Implementation must stop the boot process from going any further until
  next host system boot. It is allowed but not required to perform cold
  reboot or show any warning message.
\item
  \texttt{undefined\ behaviour} --- behaviour not prescribed by this
  document. Implementation is allowed to take any measures including but
  not limited to \texttt{fatal\ behaviour}, assuming any states or
  values, or ignoring, unless these measures negatively affect system
  security in general.
\end{itemize}

\subsection{Configuration Processing}\label{configuration-processing}

\texttt{OC\ config} is guaranteed to be processed at least once if it
was found. Depending on OpenCore bootstrapping mechanism multiple
\texttt{OC\ config} files may lead to reading any of them. No
\texttt{OC\ Config} may be present on disk, in which case all the values
read follow the rules of \texttt{invalid\ value} and
\texttt{optional\ value}.

\texttt{OC\ config} has size, nesting, and key amount limitations.
\texttt{OC\ config} size does not exceed \texttt{16\ MBs}.
\texttt{OC\ config} has no more than \texttt{8} nesting levels.
\texttt{OC\ config} has up to \texttt{16384} XML nodes (i.e.~one
\texttt{plist\ dictionary} item is counted as a pair of nodes) within
each \texttt{plist\ object}.

Reading malformed \texttt{OC\ config} file leads to
\texttt{undefined\ behaviour}. Examples of malformed \texttt{OC\ config}
cover at least the following cases:

\begin{itemize}
\tightlist
\item
  files non-conformant to \texttt{plist} DTD
\item
  files with unsupported or non-conformant \texttt{plist\ objects} found
  in this document
\item
  files violating size, nesting, and key amount limitations
\end{itemize}

It is recommended but not required to abort loading malformed
\texttt{OC\ config} and continue as if no \texttt{OC\ config} was
present. For forward compatibility it is recommended but not required
for the implementation to warn about the use of
\texttt{invalid\ values}. Recommended practice of interpreting
\texttt{invalid\ values} is to conform to the following convention where
applicable:

\begin{center}
\begin{tabular}{|l|l|}
\hline
\textbf{Type} & \textbf{Value} \\
\hline
\texttt{plist\ string} & Empty string
(\texttt{\textless{}string\textgreater{}\textless{}/string\textgreater{}}) \\
\hline
\texttt{plist\ data} & Empty data
(\texttt{\textless{}data\textgreater{}\textless{}/data\textgreater{}}) \\
\hline
\texttt{plist\ integer} & 0
(\texttt{\textless{}integer\textgreater{}0\textless{}/integer\textgreater{}}) \\
\hline
\texttt{plist\ boolean} & False
(\texttt{\textless{}false/\textgreater{}}) \\
\hline
\texttt{plist\ tristate} & False
(\texttt{\textless{}false/\textgreater{}}) \\
\hline
\end{tabular}
\end{center}

\subsection{Configuration Structure}\label{configuration-structure}

\texttt{OC\ config} is separated into following sections, which are described
in separate sections of this document. By default it is tried to not enable
anything and optionally provide kill switches with \texttt{Enable} property
for \texttt{plist dict} entries. In general the configuration is written
idiomatically to group similar actions in subsections:

\begin{itemize}
\tightlist
\item
  \texttt{Add} provides support for data addition. Existing data will
  not be overridden, and needs to be handled separately with
  \texttt{Delete} if necessary.
\item
  \texttt{Delete} provides support for data removal.
\item
  \texttt{Patch} provides support for data modification.
\item
  \texttt{Quirks} provides support for specific hacks.
\end{itemize}

Root configuration entries consist of the following:

\begin{itemize}
\tightlist
\item
  \hyperref[acpi]{\texttt{ACPI}}
\item
  \hyperref[booter]{\texttt{Booter}}
\item
  \hyperref[devprops]{\texttt{DeviceProperties}}
\item
  \hyperref[kernel]{\texttt{Kernel}}
\item
  \hyperref[misc]{\texttt{Misc}}
\item
  \hyperref[nvram]{\texttt{NVRAM}}
\item
  \hyperref[platforminfo]{\texttt{PlatformInfo}}
\item
  \hyperref[uefi]{\texttt{UEFI}}
\end{itemize}

It is possible to perform basic validation of the configuration by using
\texttt{ocvalidate} utility. Please note, that \texttt{ocvalidate}
must match the used OpenCore release and may not be able to detect all
configuration flaws present in the file.

\emph{Note}: Currently most properties try to have defined values even if not
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}

\begin{center}
\begin{tikzpicture}[%
  grow via three points={one child at (0.5,-0.6) and
  two children at (0.5,-0.6) and (0.5,-1.2)},
  edge from parent path={(\tikzparentnode.south) |- (\tikzchildnode.west)}]
  \node {ESP}
    child { node {EFI}
      child { node {BOOT}
        child { node [selected] {BOOTx64.efi}}
      }
      child [missing] {}
      child { node {OC}
        child { node {ACPI}
          child { node [optional] {DSDT.aml}}
          child { node [optional] {SSDT-1.aml}}
          child { node [optional] {MYTABLE.aml}}
        }
        child [missing] {}
        child [missing] {}
        child [missing] {}
        child [missing] {}
        child { node {Drivers}
          child { node [optional] {MyDriver.efi}}
          child { node [optional] {OtherDriver.efi}}
        }
        child [missing] {}
        child [missing] {}
        child { node {Kexts}
          child { node [optional] {MyKext.kext}}
          child { node [optional] {OtherKext.kext}}
        }
        child [missing] {}
        child [missing] {}
        child { node [optional] {Resources}
          child { node [optional] {Audio}}
          child { node [optional] {Font}}
          child { node [optional] {Image}}
          child { node [optional] {Label}}
        }
        child [missing] {}
        child [missing] {}
        child [missing] {}
        child [missing] {}
        child { node  {Tools}
          child { node [optional] {Tool.efi}}
        }
        child [missing] {}
        child { node [selected] {OpenCore.efi}}
        child { node {config.plist}}
        child { node [optional] {vault.plist}}
        child { node [optional] {vault.sig}}
      }
    }
    child [missing] {}
    child [missing] {}
    child [missing] {}
    child [missing] {}
    child [missing] {}
    child [missing] {}
    child [missing] {}
    child [missing] {}
    child [missing] {}
    child [missing] {}
    child [missing] {}
    child [missing] {}
    child [missing] {}
    child [missing] {}
    child [missing] {}
    child [missing] {}
    child [missing] {}
    child [missing] {}
    child [missing] {}
    child [missing] {}
    child [missing] {}
    child [missing] {}
    child [missing] {}
    child [missing] {}
    child [missing] {}
    child { node [optional] {boot}}
    child { node [optional] {nvram.plist}}
    child { node [optional] {opencore-YYYY-MM-DD-HHMMSS.txt}}
    child { node [optional] {panic-YYYY-MM-DD-HHMMSS.txt}}
    child { node [optional] {SysReport}}
  ;
\end{tikzpicture}
\break
\label{fig:DS}
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} or \texttt{BOOTIa32.efi} \\
  Initial bootstrap loaders, which load \texttt{OpenCore.efi}. \texttt{BOOTx64.efi}
  is loaded by the firmware by default according to UEFI specification, yet it can
  also be renamed and put to a custom location to let OpenCore coexist with operating
  systems using \texttt{BOOTx64.efi} as their own loaders (e.g. Windows), see
  \texttt{LauncherOption} for more details.
\item
  \texttt{boot} \\
  Duet bootstrap loader, which initialises UEFI environment on legacy BIOS firmware
  and loads \texttt{OpenCore.efi} similarly to other bootstrap loaders. Modern Duet
  bootstrap loader will default to \texttt{OpenCore.efi} on the same partition when
  present.
\item
  \texttt{ACPI} \\
  Directory used for storing supplemental ACPI information
  for \hyperref[acpi]{\texttt{ACPI}} section.
\item
  \texttt{Drivers} \\
  Directory used for storing supplemental \texttt{UEFI}
  drivers for \hyperref[uefi]{\texttt{UEFI}} section.
\item
  \texttt{Kexts} \\
  Directory used for storing supplemental kernel information
  for \hyperref[kernel]{\texttt{Kernel}} section.
\item
  \texttt{Resources} \\
  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. This directory also contains image files
  for graphical user interface. See \hyperref[ueficanopy]{OpenCanopy} section for more details.
\item
  \texttt{Tools} \\
  Directory used for storing supplemental tools.
\item
  \texttt{OpenCore.efi} \\
  Main booter application responsible for operating system loading. The directory
  \texttt{OpenCore.efi} resides is called the \texttt{root directory}.
  By default \texttt{root directory} is set to \texttt{EFI\textbackslash OC},
  however, when launching \texttt{OpenCore.efi} directly or through
  a custom launcher, other directories containing \texttt{OpenCore.efi}
  can also be supported.
\item
  \texttt{config.plist} \\
  \texttt{OC Config}.
\item
  \texttt{vault.plist} \\
  Hashes for all files potentially loadable by \texttt{OC Config}.
\item
  \texttt{vault.sig} \\
  Signature for \texttt{vault.plist}.
\item
  \texttt{SysReport} \\
  Directory containing system reports generated by \texttt{SysReport} option.
\item
  \texttt{nvram.plist} \\
  OpenCore variable import file.
\item
  \texttt{opencore-YYYY-MM-DD-HHMMSS.txt} \\
  OpenCore log file.
\item
  \texttt{panic-YYYY-MM-DD-HHMMSS.txt} \\
  Kernel panic log file.
\end{itemize}

\emph{Note}: It is not guaranteed that paths longer than
\texttt{OC\_STORAGE\_SAFE\_PATH\_MAX} (128 characters including
the \texttt{\\0}-terminator) will be accessible within OpenCore.

\subsection{Installation and Upgrade}\label{configuration-install}

To install OpenCore, replicate the
\hyperref[configuration-structure]{Configuration Structure} described
in the previous section on a EFI volume of a GPT partition. While
corresponding sections of this document do provide some information
regarding external resources such as ACPI tables, UEFI drivers,
or kernel extensions (kexts), completeness of the matter is out of
the scope of this document. Information about kernel extensions may
be found in a separate
\href{https://github.com/acidanthera/OpenCorePkg/blob/master/Docs/Kexts.md}{Kext List}
document available in the OpenCore repository. Vaulting information is provided in
the \hyperref[miscsecurityprops]{Security Properties} section of this document.

The \texttt{OC\ config} file, as with any property list file, can be edited with
any text editor such as nano and vim. However, specialised software may provide
a better experience. On macOS, the preferred GUI application is
\href{https://developer.apple.com/xcode}{Xcode}. For a lightweight
cross-platform and open-source alternative, the
\href{https://github.com/corpnewt/ProperTree}{ProperTree} editor can be
utilised.

For BIOS booting, a third-party UEFI environment provider will have to
be used. \texttt{OpenDuetPkg} is one of the known UEFI environment providers
for legacy systems. To run OpenCore on such a legacy system, \texttt{OpenDuetPkg}
can be installed with a dedicated tool --- BootInstall (bundled with OpenCore).
\href{https://github.com/corpnewt/gibMacOS}{Third-party utilities} can be used to
perform this on systems other than macOS.

For upgrade purposes, refer to the \texttt{Differences.pdf} document which provides
information about changes to the configuration as compared to the previous release
as well as to the \texttt{Changelog.md} document, which contains a list of
modifications across all published updates.

\subsection{Contribution}\label{configuration-comp}

OpenCore can be compiled as an ordinary
\href{https://github.com/tianocore/tianocore.github.io/wiki/EDK-II}{EDK II} package.
Since \href{https://github.com/tianocore/tianocore.github.io/wiki/UDK}{UDK}
development was abandoned by TianoCore, OpenCore requires the use of
\href{https://github.com/tianocore/tianocore.github.io/wiki/EDK-II#stable-tags}{EDK II Stable}.
The currently supported EDK II release is hosted in
\href{https://github.com/acidanthera/audk}{acidanthera/audk}. Required patches
for this package can be found in the \texttt{Patches} directory.

The only officially supported toolchain is \texttt{XCODE5}. Other toolchains
might work but are neither supported nor recommended. Contributions of clean
patches are welcome. Please do follow
\href{https://github.com/tianocore/tianocore.github.io/wiki/Code-Style-C}{EDK II C Codestyle}.

To compile with \texttt{XCODE5}, besides \href{https://developer.apple.com/xcode}{Xcode},
users should also install \href{https://www.nasm.us}{NASM} and
\href{https://github.com/acidanthera/ocbuild/tree/master/external}{MTOC}.
The latest Xcode version is recommended for use despite the toolchain name.
An example command sequence is as follows:

\begin{lstlisting}[caption=Compilation Commands, label=compile, style=ocbash]
git clone --depth=1 https://github.com/acidanthera/audk UDK
cd UDK
git submodule update --init --recommend-shallow
git clone --depth=1 https://github.com/acidanthera/OpenCorePkg
source edksetup.sh
make -C BaseTools
build -a X64 -b RELEASE -t XCODE5 -p OpenCorePkg/OpenCorePkg.dsc
\end{lstlisting}

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 the UDK root:

\begin{lstlisting}[caption=ECC Configuration, label=eccfile, style=ocbash]
-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/OpenCorePkg/Include/AMI
-I/UefiPackages/OpenCorePkg/Include/Acidanthera
-I/UefiPackages/OpenCorePkg/Include/Apple
-I/UefiPackages/OpenCorePkg/Include/Apple/X64
-I/UefiPackages/OpenCorePkg/Include/Duet
-I/UefiPackages/OpenCorePkg/Include/Generic
-I/UefiPackages/OpenCorePkg/Include/Intel
-I/UefiPackages/OpenCorePkg/Include/Microsoft
-I/UefiPackages/OpenCorePkg/Include/VMware
-I/UefiPackages/OvmfPkg/Include
-I/UefiPackages/UefiCpuPkg/Include
-IInclude
-include
/UefiPackages/MdePkg/Include/Uefi.h
-fshort-wchar
-Wall
-Wextra
-Wno-unused-parameter
-Wno-missing-braces
-Wno-missing-field-initializers
-Wno-tautological-compare
-Wno-sign-compare
-Wno-varargs
-Wno-unused-const-variable
-DOC_TARGET_NOOPT=1
-DNO_MSABI_VA_FUNCS=1
\end{lstlisting}

\textbf{Warning}: Tool developers modifying \texttt{config.plist} or any other OpenCore
files must ensure that their tool checks the \texttt{opencore-version} NVRAM variable
(see \hyperref[miscdebugprops]{Debug Properties} section below) and warns users
if the version listed is unsupported or prerelease. The OpenCore configuration may change
across releases and such tools shall ensure they carefully follow this document. Failure
to do so may result in such tools being considered to be malware and blocked by any means.

\subsection{Coding conventions}\label{configuration-conv}

As with any other project, we have conventions that we follow during development.
All third-party contributors are advised to adhere to the conventions listed below
before submitting patches. To minimise abortive work and the potential rejection of
submissions, third-party contributors should initially raise issues to the
\href{https://github.com/acidanthera/bugtracker}{Acidanthera Bugtracker}
for feedback before submitting patches.

\textbf{Organisation}. The codebase is contained in the \texttt{OpenCorePkg} repository,
which is the primary EDK II package.
\begin{itemize}
\tightlist
\item Whenever changes are required in multiple repositories, separate pull requests should
be sent to each.
\item Committing the changes should happen firstly to dependent repositories, secondly to
primary repositories to avoid automatic build errors.
\item Each unique commit should compile with \texttt{XCODE5} and preferably with other
toolchains. In the majority of the cases it can be checked by accessing the
\href{https://travis-ci.com/acidanthera}{CI interface}. Ensuring that static analysis finds
no warnings is preferred.
\item External pull requests and tagged commits must be validated. That said, commits in
master may build but may not necessarily work.
\item Internal branches should be named as follows: \texttt{author-name-date}, e.g.
\texttt{vit9696-ballooning-20191026}.
\item Commit messages should be prefixed with the primary module (e.g. library or code module) the
changes were made in. For example, \texttt{OcGuardLib: Add OC\_ALIGNED macro}. For non-library changes
\texttt{Docs} or \texttt{Build} prefixes are used.
\end{itemize}

\textbf{Design}. The codebase is written in a subset of freestanding C11 (C17) supported by
most modern toolchains used by EDK II. Applying common software development practices or requesting
clarification is recommended if any particular case is not discussed below.
\begin{itemize}
\tightlist
\item Never rely on undefined behaviour and try to avoid implementation defined behaviour unless
explicitly covered below (feel free to create an issue when a relevant case is not present).
\item Use \texttt{OcGuardLib} to ensure safe integral arithmetics avoiding overflows. Unsigned
wraparound should be relied on with care and reduced to the necessary amount.
\item Check pointers for correct alignment with \texttt{OcGuardLib} and do not rely on the architecture
being able to dereference unaligned pointers.
\item Use flexible array members instead of zero-length or one-length arrays where necessary.
\item Use static assertions (\texttt{STATIC\_ASSERT}) for type and value assumptions, and runtime
assertions (\texttt{ASSERT}) for precondition and invariant sanity checking. Do not use runtime
assertions to check for errors as they should never alter control flow and potentially be excluded.
\item Assume \texttt{UINT32}/\texttt{INT32} to be \texttt{int}-sized and use \texttt{\%u},
\texttt{\%d}, and \texttt{\%x} to print them.
\item Assume \texttt{UINTN}/\texttt{INTN} to be of unspecified size, and cast them to
\texttt{UINT64}/\texttt{INT64} for printing with \texttt{\%Lu}, \texttt{\%Ld} and so on as normal.
\item Do not rely on integer promotions for numeric literals. Use explicit casts when the type is
implementation-dependent or suffixes when type size is known. Assume \texttt{U} for \texttt{UINT32}
and \texttt{ULL} for \texttt{UINT64}.
\item Do ensure unsigned arithmetics especially in bitwise maths, shifts in particular.
\item \texttt{sizeof} operator should take variables instead of types where possible to be error prone.
Use \texttt{ARRAY\_SIZE} to obtain array size in elements. Use \texttt{L\_STR\_LEN} and
\texttt{L\_STR\_SIZE} macros from \texttt{OcStringLib} to obtain string literal sizes to ensure compiler
optimisation.
\item Do not use \texttt{goto} keyword. Prefer early \texttt{return}, \texttt{break}, or \texttt{continue}
after failing to pass error checking instead of nesting conditionals.
\item Use \texttt{EFIAPI}, force UEFI calling convention, only in protocols, external callbacks between
modules, and functions with variadic arguments.
\item Provide inline documentation to every added function, at least describing its inputs, outputs,
precondition, postcondition, and giving a brief description.
\item Do not use \texttt{RETURN\_STATUS}. Assume \texttt{EFI\_STATUS} to be a matching superset that is
to be always used when \texttt{BOOLEAN} is not enough.
\item Security violations should halt the system or cause a forced reboot.
\end{itemize}

\textbf{Codestyle}. The codebase follows
\href{https://github.com/tianocore/tianocore.github.io/wiki/Code-Style-C}{EDK II codestyle} with few changes
and clarifications.
\begin{itemize}
\tightlist
\item Write inline documentation for the functions and variables only once: in headers, where a header prototype
is available, and inline for \texttt{static} variables and functions.
\item Use line length of 120 characters or less, preferably 100 characters.
\item Use spaces after casts, e.g. \texttt{(VOID *)(UINTN) Variable}.
\item Use two spaces to indent function arguments when splitting lines.
\item Prefix public functions with either \texttt{Oc} or another distinct name.
\item Do not prefix private \texttt{static} functions, but prefix private \texttt{non-static} functions with \texttt{Internal}.
\item Use SPDX license headers as shown in
\href{https://github.com/acidanthera/bugtracker/issues/483}{acidanthera/bugtracker\#483}.
\end{itemize}

\subsection{Debugging}\label{configuration-debug}

The codebase incorporates EDK II debugging and few custom features to improve the experience.
\begin{itemize}
\tightlist
\item Use module prefixes, 2-5 letters followed by a colon (\texttt{:}), for debug messages. For \texttt{OpenCorePkg}
use \texttt{OC:}, for libraries and drivers use their own unique prefixes.
\item Do not use dots (\texttt{.}) in the end of debug messages and separate \texttt{EFI\_STATUS}, printed by
\texttt{\%r}, with a hyphen (e.g. \texttt{OCRAM: Allocation of \%u bytes failed - \%r\textbackslash n}).
\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}.
\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}
for extensive messages that should not appear in NVRAM log that is heavily limited in size. These messages are ignored in
\texttt{RELEASE} builds.
\item Use \texttt{DEBUG\_ERROR} to print critical human visible messages that may potentially halt the boot process, and
\texttt{DEBUG\_WARN} for all other human visible errors, \texttt{RELEASE} builds included.
\end{itemize}

When trying to find the problematic change it is useful to rely on
\href{https://git-scm.com/docs/git-bisect}{\texttt{git-bisect}} functionality.
There also are some unofficial resources that provide per-commit binary
builds of OpenCore, such as \href{https://dortania.github.io/builds}{Dortania}.

\section{ACPI}\label{acpi}

\subsection{Introduction}\label{acpiintro}

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{\_PRW}) for implementation.
Modern hardware needs little changes to maintain ACPI compatibility, yet
some of those are provided as a part of OpenCore.

To compile and disassemble ACPI tables \href{https://github.com/acpica/acpica}{iASL compiler}
can be used developed by \href{https://www.acpica.org}{ACPICA}. GUI front-end to iASL compiler
can be downloaded from \href{https://github.com/acidanthera/MaciASL/releases}{Acidanthera/MaciASL}.

ACPI changes apply globally (to every operating system) with the following effective order:

\begin{itemize}
\tightlist
\item \texttt{Patch} is processed.
\item \texttt{Delete} is processed.
\item \texttt{Add} is processed.
\item \texttt{Quirks} are processed.
\end{itemize}

Applying the changes globally resolves the problems of incorrect operating system
detection, which is not possible before the operating system boots according to
the ACPI specification, operating system chainloading, and harder ACPI debugging.
For this reason it may be required to carefully use \texttt{\_OSI} method when
writing the changes.

Applying the patches early makes it possible to write so called ``proxy'' patches,
where the original method is patched in the original table and is implemented in
the patched table.

There are many places providing ACPI tables and workarounds. Commonly used
ACPI tables are provided with OpenCore, VirtualSMC, VoodooPS2, and WhateverGreen
releases. Besides those there are several third-party instructions commonly found
on AppleLife in \href{https://applelife.ru/forums/xakintosh.67}{Laboratory}
and \href{https://applelife.ru/forums/dsdt.129}{DSDT} subforums
(e.g. \href{https://applelife.ru/posts/498967}{Battery register splitting} guide).
A slightly more user-friendly explanation of some tables included with OpenCore
can also be found in \href{https://dortania.github.io}{Dortania}'s
\href{https://dortania.github.io/Getting-Started-With-ACPI}{Getting started with ACPI} guide.
For more exotic cases there also are several other places including
\href{https://github.com/daliansky}{daliansky}'s
\href{https://github.com/daliansky/OC-little}{ACPI sample collection}, but the quality
of the suggested solutions will vary from case to case.

\subsection{Properties}\label{acpiprops}

\begin{enumerate}
\item
  \texttt{Add}\\
  \textbf{Type}: \texttt{plist\ array}\\
  \textbf{Failsafe}: Empty\\
  \textbf{Description}: Load selected tables from \texttt{OC/ACPI}
  directory.

  Designed to be filled with \texttt{plist\ dict} values, describing each add entry.
  See \hyperref[acpipropsadd]{Add Properties} section below.

\item
  \texttt{Delete}\\
  \textbf{Type}: \texttt{plist\ array}\\
  \textbf{Failsafe}: Empty\\
  \textbf{Description}: Remove selected tables from ACPI stack.

  Designed to be filled with \texttt{plist\ dict} values, describing each delete entry.
  See \hyperref[acpipropsdelete]{Delete Properties} section below.

\item
  \texttt{Patch}\\
  \textbf{Type}: \texttt{plist\ array}\\
  \textbf{Failsafe}: Empty\\
  \textbf{Description}: Perform binary patches in ACPI tables before
  table addition or removal.

  Designed to be filled with \texttt{plist\ dictionary} values describing each
  patch entry. See \hyperref[acpipropspatch]{Patch Properties} section below.

\item
  \texttt{Quirks}\\
  \textbf{Type}: \texttt{plist\ dict}\\
  \textbf{Description}: Apply individual ACPI quirks described
  in \hyperref[acpipropsquirks]{Quirks Properties} section below.

\end{enumerate}

\subsection{Add Properties}\label{acpipropsadd}

\begin{enumerate}
\item
  \texttt{Comment}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: Empty\\
  \textbf{Description}: Arbitrary ASCII string used to provide human readable
  reference for the entry. Whether this value is used is implementation defined.

\item
  \texttt{Enabled}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: This ACPI table will not be added unless set to
  \texttt{true}.

\item
  \texttt{Path}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: Empty\\
  \textbf{Description}: File paths meant to be loaded as ACPI tables.
  Example values include \texttt{DSDT.aml}, \texttt{SubDir/SSDT-8.aml},
  \texttt{SSDT-USBX.aml}, etc.

  ACPI table load order follows the item order in the array. All ACPI tables
  load from \texttt{OC/ACPI} directory.

  \textbf{Note}: All tables but tables with \texttt{DSDT} table identifier
  (determined by parsing data not by filename) insert new tables into ACPI stack.
  \texttt{DSDT}, unlike the rest, performs replacement of DSDT table.

\end{enumerate}

\subsection{Delete Properties}\label{acpipropsdelete}

\begin{enumerate}
\item
  \texttt{All}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: If set to \texttt{true}, all ACPI tables matching the
  condition will be deleted. Otherwise only first matched table.

\item
  \texttt{Comment}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: Empty\\
  \textbf{Description}: Arbitrary ASCII string used to provide human readable
  reference for the entry. Whether this value is used is implementation defined.

\item
  \texttt{Enabled}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: This ACPI table will not be removed unless set to
  \texttt{true}.

\item
  \texttt{OemTableId}\\
  \textbf{Type}: \texttt{plist\ data}, 8 bytes\\
  \textbf{Failsafe}: All zero\\
  \textbf{Description}: Match table OEM ID to be equal to this value
  unless all zero.

\item
  \texttt{TableLength}\\
  \textbf{Type}: \texttt{plist\ integer}\\
  \textbf{Failsafe}: \texttt{0}\\
  \textbf{Description}: Match table size to be equal to this value
  unless \texttt{0}.

\item
  \texttt{TableSignature}\\
  \textbf{Type}: \texttt{plist\ data}, 4 bytes\\
  \textbf{Failsafe}: All zero\\
  \textbf{Description}: Match table signature to be equal to this value
  unless all zero.

  \emph{Note}: Make sure not to specify table signature when the sequence
  needs to be replaced in multiple places. Especially when performing
  different kinds of renames.

\end{enumerate}

\subsection{Patch Properties}\label{acpipropspatch}

\begin{enumerate}

\item
  \texttt{Comment}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: Empty\\
  \textbf{Description}: Arbitrary ASCII string used to provide human readable
  reference for the entry. Whether this value is used is implementation defined.

\item
  \texttt{Count}\\
  \textbf{Type}: \texttt{plist\ integer}\\
  \textbf{Failsafe}: \texttt{0}\\
  \textbf{Description}: Number of patch occurrences to apply. \texttt{0} applies
  the patch to all occurrences found.

\item
  \texttt{Enabled}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: This ACPI patch will not be used unless set to
  \texttt{true}.

\item
  \texttt{Find}\\
  \textbf{Type}: \texttt{plist\ data}\\
  \textbf{Failsafe}: Empty\\
  \textbf{Description}: Data to find. Must be equal to \texttt{Replace} in size if set.

\item
  \texttt{Limit}\\
  \textbf{Type}: \texttt{plist\ integer}\\
  \textbf{Failsafe}: \texttt{0} (Search entire ACPI table)\\
  \textbf{Description}: Maximum number of bytes to search for.

\item
  \texttt{Mask}\\
  \textbf{Type}: \texttt{plist\ data}\\
  \textbf{Failsafe}: Empty (Ignored)\\
  \textbf{Description}: Data bitwise mask used during find comparison.
  Allows fuzzy search by ignoring not masked (set to zero) bits.
  Must be equal to \texttt{Replace} in size if set.

\item
  \texttt{OemTableId}\\
  \textbf{Type}: \texttt{plist\ data}, 8 bytes\\
  \textbf{Failsafe}: All zero\\
  \textbf{Description}: Match table OEM ID to be equal to this value
  unless all zero.

\item
  \texttt{Replace}\\
  \textbf{Type}: \texttt{plist\ data}\\
  \textbf{Failsafe}: Empty\\
  \textbf{Description}: Replacement data of one or more bytes.

\item
  \texttt{ReplaceMask}\\
  \textbf{Type}: \texttt{plist\ data}\\
  \textbf{Failsafe}: Empty (Ignored)\\
  \textbf{Description}: Data bitwise mask used during replacement.
  Allows fuzzy replacement by updating masked (set to non-zero) bits.
  Must be equal to \texttt{Replace} in size if set.

\item
  \texttt{Skip}\\
  \textbf{Type}: \texttt{plist\ integer}\\
  \textbf{Failsafe}: \texttt{0}\\
  \textbf{Description}: Number of found occurrences to be skipped before replacement
  is done.

\item
  \texttt{TableLength}\\
  \textbf{Type}: \texttt{plist\ integer}\\
  \textbf{Failsafe}: \texttt{0}\\
  \textbf{Description}: Match table size to be equal to this value
  unless \texttt{0}.

\item
  \texttt{TableSignature}\\
  \textbf{Type}: \texttt{plist\ data}, 4 bytes\\
  \textbf{Failsafe}: All zero\\
  \textbf{Description}: Match table signature to be equal to this value
  unless all zero.

\end{enumerate}

In the majority of the cases ACPI patches are not useful and harmful:

\begin{itemize}
\item
  Avoid renaming devices with ACPI patches. This may fail or perform
  improper renaming of unrelated devices (e.g. \texttt{EC} and
  \texttt{EC0}), be unnecessary, or even fail to rename devices in select tables. For
  ACPI consistency it is much safer to rename devices at I/O Registry
  level, as done by
  \href{https://github.com/acidanthera/WhateverGreen}{WhateverGreen}.
\item
  Try to avoid patching \texttt{\_OSI} to support a higher level of feature sets
  whenever possible. Commonly this enables a number of hacks on APTIO
  firmware, which result in the need to add more patches. Modern firmware
  generally does not need it, and those that do are fine with much
  smaller patches. However, laptop vendors usually rely on this method to
  determine the availability of functions such as modern I2C input support, thermal
  adjustment and custom feature additions.
\item
  Avoid patching embedded controller event \texttt{\_Qxx} just for enabling
  brightness keys. The conventional process to find these keys usually involves
  massive modification on DSDT and SSDTs and the debug kext is not stable on
  newer systems. Please switch to built-in brightness key discovery of
  \href{https://github.com/acidanthera/BrightnessKeys}{BrightnessKeys} instead.
\item
  Avoid making ad hoc changes such as renaming \texttt{\_PRW} or \texttt{\_DSM}
  whenever possible.
\end{itemize}

Several cases, where patching actually does make sense, include:

\begin{itemize}
\item
  Refreshing \texttt{HPET} (or another device) method header to avoid
  compatibility checks by \texttt{\_OSI} on legacy hardware. \texttt{\_STA}
  method with \texttt{if ((OSFL () == Zero)) \{ If (HPTE)  ...  Return (Zero)}
  content may be forced to always return 0xF by replacing
  \texttt{A0 10 93 4F 53 46 4C 00} with \texttt{A4 0A 0F A3 A3 A3 A3 A3}.
\item
  To provide custom method implementation with in an SSDT, for instance,
  to inject shutdown fix on certain computers, the original method can be
  replaced with a dummy name by patching \texttt{\_PTS} with \texttt{ZPTS}
  and adding a callback to original method.
\end{itemize}

Tianocore \href{https://github.com/acidanthera/audk/blob/master/MdePkg/Include/IndustryStandard/AcpiAml.h}{AcpiAml.h}
source file may help understanding ACPI opcodes.

\emph{Note}: Patches of different \texttt{Find} and \texttt{Replace} lengths
are unsupported as they may corrupt ACPI tables and make the system unstable
due to area relocation. If such changes are needed, the utilisation of ``proxy''
patching or the padding of \texttt{NOP} to the remaining area might be taken into account.

\subsection{Quirks Properties}\label{acpipropsquirks}

\begin{enumerate}

\item
  \texttt{FadtEnableReset}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Provide reset register and flag in FADT table to enable
  reboot and shutdown.

  Mainly required on legacy hardware and few laptops. Can also fix power-button
  shortcuts. Not recommended unless required.

\item
  \texttt{NormalizeHeaders}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Cleanup ACPI header fields to workaround macOS
  ACPI implementation bug causing boot crashes. Reference:
  \href{https://alextjam.es/debugging-appleacpiplatform/}{Debugging
  AppleACPIPlatform on 10.13} by Alex James aka theracermaster. The
  issue is fixed in macOS Mojave (10.14).

\item
  \texttt{RebaseRegions}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Attempt to heuristically relocate ACPI memory
  regions. Not recommended.

  ACPI tables are often generated dynamically by underlying firmware
  implementation. Among the position-independent code, ACPI tables may
  contain physical addresses of MMIO areas used for device
  configuration, usually grouped in regions (e.g.
  \texttt{OperationRegion}). Changing firmware settings or hardware
  configuration, upgrading or patching the firmware inevitably leads to
  changes in dynamically generated ACPI code, which sometimes lead to
  the shift of the addresses in aforementioned \texttt{OperationRegion}
  constructions.

  For this reason it is very dangerous to apply any kind of
  modifications to ACPI tables. The most reasonable approach is to make
  as few as possible changes to ACPI and try to not replace any tables,
  especially DSDT. When this is not possible, then at least attempt to
  ensure that custom DSDT is based on the most recent DSDT or remove
  writes and reads for the affected areas.

  When nothing else helps this option could be tried to avoid stalls at
  \texttt{PCI\ Configuration\ Begin} phase of macOS booting by
  attempting to fix the ACPI addresses. It does not do magic, and only
  works with most common cases. Do not use unless absolutely required.

\item
  \texttt{ResetHwSig}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Reset \texttt{FACS} table \texttt{HardwareSignature}
  value to \texttt{0}.

  This works around firmware that fail to maintain hardware signature across
  the reboots and cause issues with waking from hibernation.

\item
  \texttt{ResetLogoStatus}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Reset \texttt{BGRT} table \texttt{Displayed}
  status field to \texttt{false}.

  This works around firmware that provide a \texttt{BGRT} table but
  fail to handle screen updates afterwards.

\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 firmware. 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 this is used for the first time on a customised firmware, there is a
list of checks to do first. Prior to starting, the following requirements should be fulfilled:

\begin{itemize}
\tightlist
\item Most up-to-date UEFI firmware (check the 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, this option should be checked first whenever erratic boot
  failures are encountered.
\item \texttt{DisableIoMapper} quirk enabled, or \texttt{VT-d} disabled in
  firmware settings if present, or ACPI DMAR table deleted.
\item \textbf{No} `slide` boot argument present in NVRAM or anywhere else.
  It is not necessary unless the system cannot be booted at all or
  \texttt{No slide values are usable! Use custom slide!} message can be seen in the log.
\item \texttt{CFG Lock} (MSR \texttt{0xE2} write protection) disabled in
  firmware settings if present. Consider
\href{https://github.com/LongSoft/UEFITool/blob/master/UEFIPatch/patches.txt}{patching it}
  if no option is available (for advanced users only). See
\hyperref[kernelpropsquirks]{VerifyMsrE2}
  notes for more details.
\item \texttt{CSM} (Compatibility Support Module) disabled in firmware settings
  if present. On NVIDIA 6xx/AMD 2xx or older, GOP ROM may have to be flashed first. Use
  \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 of any potential confusion.
\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
  \texttt{Thunderbolt support}, \texttt{Intel SGX}, and \texttt{Intel Platform Trust}
  may have to be disabled in firmware settings present.
\end{itemize}

When debugging sleep issues Power Nap and automatic power off may be (temporarily) disabled,
which appear to sometimes cause wake to black screen or boot loop
issues on older platforms. The particular issues may vary, but in general ACPI tables should be looked up 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{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{Patch}\\
  \textbf{Type}: \texttt{plist\ array}\\
  \textbf{Failsafe}: Empty\\
  \textbf{Description}: Perform binary patches in booter.

  Designed to be filled with \texttt{plist\ dictionary} values, describing each
  patch. See \hyperref[booterpropspatch]{Patch Properties} section below.

\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{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\\
  \textbf{Description}: Arbitrary ASCII string used to provide human readable
  reference for the entry. Whether this value is used is implementation defined.

\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{Patch Properties}\label{booterpropspatch}

\begin{enumerate}
\item
  \texttt{Arch}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: \texttt{Any}\\
  \textbf{Description}: Booter patch architecture (\texttt{Any}, \texttt{i386}, \texttt{x86\_64}).

\item
  \texttt{Comment}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: Empty\\
  \textbf{Description}: Arbitrary ASCII string used to provide human readable
  reference for the entry. Whether this value is used is implementation defined.

\item
  \texttt{Count}\\
  \textbf{Type}: \texttt{plist\ integer}\\
  \textbf{Failsafe}: \texttt{0}\\
  \textbf{Description}: Number of patch occurrences to apply. \texttt{0} applies
  the patch to all occurrences found.

\item
  \texttt{Enabled}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: This booter patch will not be used unless set to
  \texttt{true}.

\item
  \texttt{Find}\\
  \textbf{Type}: \texttt{plist\ data}\\
  \textbf{Failsafe}: Empty\\
  \textbf{Description}: Data to find. Must be equal to \texttt{Replace} in size if set.

\item
  \texttt{Identifier}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}:  \texttt{Any} (Match any booter)\\
  \textbf{Description}: \texttt{Apple} for macOS booter (generally \texttt{boot.efi});
  or a name with a suffix, such as \texttt{bootmgfw.efi}, for a specific booter.

\item
  \texttt{Limit}\\
  \textbf{Type}: \texttt{plist\ integer}\\
  \textbf{Failsafe}: \texttt{0} (Search the entire booter)\\
  \textbf{Description}: Maximum number of bytes to search for.

\item
  \texttt{Mask}\\
  \textbf{Type}: \texttt{plist\ data}\\
  \textbf{Failsafe}: Empty (Ignored)\\
  \textbf{Description}: Data bitwise mask used during find comparison.
  Allows fuzzy search by ignoring not masked (set to zero) bits.
  Must be equal to \texttt{Find} in size if set.

\item
  \texttt{Replace}\\
  \textbf{Type}: \texttt{plist\ data}\\
  \textbf{Failsafe}: Empty\\
  \textbf{Description}: Replacement data of one or more bytes.

\item
  \texttt{ReplaceMask}\\
  \textbf{Type}: \texttt{plist\ data}\\
  \textbf{Failsafe}: Empty (Ignored)\\
  \textbf{Description}: Data bitwise mask used during replacement.
  Allows fuzzy replacement by updating masked (set to non-zero) bits.
  Must be equal to \texttt{Replace} in size if set.

\item
  \texttt{Skip}\\
  \textbf{Type}: \texttt{plist\ integer}\\
  \textbf{Failsafe}: \texttt{0}\\
  \textbf{Description}: Number of found occurrences to be skipped before replacement
  is done.

\end{enumerate}

\subsection{Quirks Properties}\label{booterpropsquirks}

\begin{enumerate}

\item
  \texttt{AllowRelocationBlock}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Allows booting macOS through a relocation block.

  Relocation block is a scratch buffer allocated in lower 4 GB to be used for
  loading the kernel and related structures by EfiBoot on firmwares where
  lower memory is otherwise occupied by the (assumed to be) non-runtime data.
  Right before kernel startup the relocation block is copied back to lower
  addresses. Similarly all the other addresses pointing to relocation block
  are also carefully adjusted. Relocation block can be used when:

  \begin{itemize}
    \tightlist
    \item No better slide exists (all the memory is used)
    \item \texttt{slide=0} is forced (by an argument or safe mode)
    \item KASLR (slide) is unsupported (this is macOS 10.7 or older)
  \end{itemize}

  This quirk requires \texttt{ProvideCustomSlide} to also be enabled
  and generally needs \texttt{AvoidRuntimeDefrag} to work correctly.
  Hibernation is not supported when booting with a relocation block
  (but relocation block is not always used when the quirk is enabled).

  \emph{Note}: While this quirk is required to run older macOS versions
  on platforms with used lower memory it is not compatible with some
  hardware and macOS 11. In such cases, consider using
  \texttt{EnableSafeModeSlide} instead.

\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 firmware that uses SMM backing for select services such as variable
  storage. SMM may try to access physical addresses, but they get moved by boot.efi.

  \emph{Note}: Most types of firmware, apart from Apple and VMware, need this quirk.

\item
  \texttt{DevirtualiseMmio}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Remove runtime attribute from select MMIO regions.

  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 without additional measures. 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 types of firmware, except some very old ones
  such as Sandy Bridge. On some types of firmware, a list of addresses that need virtual
  addresses for proper NVRAM and hibernation functionality may be required.
  Use the \texttt{MmioWhitelist} section for this.

\item
  \texttt{DisableSingleUser}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Disable single user mode.

  This is a security option that restricts the activation of single user mode
  by ignoring \texttt{CMD+S} hotkey and \texttt{-s} boot argument. The
  behaviour with this quirk enabled is supposed to match T2-based model
  behaviour. Refer to \href{https://web.archive.org/web/20200517125051/https://support.apple.com/en-us/HT201573}{this archived article} to understand how to use single user mode with this quirk enabled.

\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 that restricts NVRAM access in macOS.
  This quirk requires \texttt{OC\_FIRMWARE\_RUNTIME} protocol implemented
  in \texttt{OpenRuntime.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. Examples of such hardware are Ivy Bridge laptops
  with Insyde firmware, such as Acer V3-571G. Do not use this unless a complete understanding of
  the consequences can be ensured.

\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{OpenRuntime.efi}.

  \emph{Note}: This quirk may potentially weaken firmware security, please use
  \texttt{RebuildAppleMemoryMap} if the firmware supports memory attributes table (MAT).
  Refer to \texttt{OCABC: MAT support is 1/0} log entry to determine whether MAT is supported.

\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 without a full understanding of the consequences.

\item
  \texttt{ProtectMemoryRegions}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Protect memory regions from incorrect access.

  Some types of firmware incorrectly map select memory regions:

  \begin{itemize}
    \tightlist
    \item CSM region can be marked as boot services code or data, which
      leaves it as free memory for XNU kernel.
    \item MMIO regions can be marked as reserved memory and stay unmapped,
      but may be required to be accessible at runtime for NVRAM support.
  \end{itemize}

  This quirk attempts to fix types of these regions, e.g. ACPI NVS for
  CSM or MMIO for MMIO.

  \emph{Note}: The necessity of this quirk is determined by artifacts, sleep
  wake issues, and boot failures. Only very old firmware typically need
  this quirk.

\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{ProtectUefiServices}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Protect UEFI services from being overridden by the firmware.

  Some modern firmware, including on virtual machines such as VMware,
  may update pointers to UEFI services during driver loading and related actions.
  Consequentially this directly breaks other quirks that affect memory management,
  such as \texttt{DevirtualiseMmio}, \texttt{ProtectMemoryRegions}, or \texttt{RebuildAppleMemoryMap},
  and may also break other quirks depending on the effects of these.

  \emph{Note}: On VMware the need for this quirk may be diagnosed by ``Your Mac OS guest
  might run unreliably with more than one virtual core.'' message.

\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 the 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{ProvideMaxSlide}\\
  \textbf{Type}: \texttt{plist\ integer}\\
  \textbf{Failsafe}: \texttt{0}\\
  \textbf{Description}: Provide maximum KASLR slide when higher ones are unavailable.

  This option overrides the maximum slide of 255 by a user specified value between 1 and 254 inclusive
  when \texttt{ProvideCustomSlide} is enabled.
  It is believed that modern firmware allocates pool memory from top to bottom, effectively resulting in
  free memory when slide scanning is used later as temporary memory during kernel loading.
  When such memory is not available, this option can stop the evaluation of higher slides.

  \emph{Note}: The necessity of this quirk is determined by random boot failure
  when \texttt{ProvideCustomSlide} is enabled and the randomized slide fall
  into the unavailable range. When \texttt{AppleDebug} is enabled, usually the
  debug log may contain messages such as \texttt{AAPL: [EB|`LD:LKC] \} Err(0x9)}.
  To find the optimal value, manually append \texttt{slide=X} to \texttt{boot-args}
  and log the largest one that will not result in boot failures.

\item
  \texttt{RebuildAppleMemoryMap}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Generate Memory Map compatible with macOS.

  Apple kernel has several limitations in parsing UEFI memory map:

  \begin{itemize}
  \tightlist
  \item Memory map size must not exceed 4096 bytes as Apple kernel maps
    it as a single 4K page. Since some types of firmware can have very large memory maps,
    potentially over 100 entries, the Apple kernel will crash on boot.
  \item Memory attributes table is ignored. \texttt{EfiRuntimeServicesCode}
    memory statically gets \texttt{RX} permissions, and all other memory types
    get \texttt{RW} permissions. Since some firmware drivers may write to global
    variables at runtime, Apple kernel will crash at calling UEFI runtime services,
    unless driver \texttt{.data} section has \texttt{EfiRuntimeServicesData}
    type.
  \end{itemize}

  To workaround these limitations, this quirk applies memory attribute table
  permissions to the memory map passed to the Apple kernel and optionally attempts
  to unify contiguous slots of similar types if the resulting memory map exceeds
  4 KB.

  \emph{Note 1}: Since several types of firmware come with incorrect memory protection
  tables, this quirk often comes paired with \texttt{SyncRuntimePermissions}.

  \emph{Note 2}: The necessity of this quirk is determined by early boot failures.
  This quirk replaces \texttt{EnableWriteUnprotector} on firmware supporting
  Memory Attribute Tables (MAT). This quirk is usually unnecessary when using
  \texttt{OpenDuetPkg}, but may be required to boot macOS 10.6, and earlier, for
  reasons that are not clear.

\item
  \texttt{SetupVirtualMap}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Setup virtual memory at \texttt{SetVirtualAddresses}.

  Some types of firmware access memory by virtual addresses after a \texttt{SetVirtualAddresses}
  call, resulting in early boot crashes. This quirk workarounds the problem by
  performing early boot identity mapping of assigned virtual addresses to physical
  memory.

  \emph{Note}: The necessity of this quirk is determined by early boot failures. Currently,
  new firmware with memory protection support (such as OVMF) do not support this quirk. See
  \href{https://github.com/acidanthera/bugtracker/issues/719}{acidanthera/bugtracker\#719}.

\item
  \texttt{SignalAppleOS}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Report macOS being loaded through OS Info for any OS.

  This quirk is useful on Mac firmware, which behaves differently in different OS.
  For example, it is supposed to enable Intel GPU in Windows and Linux in some
  dual-GPU MacBook models.

\item
  \texttt{SyncRuntimePermissions}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Update memory permissions for runtime environment.

  Some types of firmware fail to properly handle runtime permissions:
  \begin{itemize}
    \tightlist
    \item They incorrectly mark \texttt{OpenRuntime} as not executable in the memory map.
    \item They incorrectly mark \texttt{OpenRuntime} as not executable in the memory
    attributes table.
    \item They lose entries from the memory attributes table after \texttt{OpenRuntime}
    is loaded.
    \item They mark items in the memory attributes table as read-write-execute.
  \end{itemize}

  This quirk tries to update memory map and memory attributes table to correct this.

  \emph{Note}: The need for this quirk is indicated by early boot failures.
  Only firmware released after 2017 is typically affected.

\end{enumerate}

\section{DeviceProperties}\label{devprops}

\subsection{Introduction}\label{devpropsintro}

Device configuration is provided to macOS with a dedicated buffer,
called \texttt{EfiDevicePathPropertyDatabase}. This buffer is a serialised
map of DevicePaths to a map of property names and their values.

Property data can be debugged with
\href{https://github.com/acidanthera/gfxutil}{gfxutil}.
To obtain current property data use the following command in macOS:
\begin{lstlisting}[label=gfxutil, style=ocbash]
ioreg -lw0 -p IODeviceTree -n efi -r -x | grep device-properties |
  sed 's/.*<//;s/>.*//' > /tmp/device-properties.hex &&
  gfxutil /tmp/device-properties.hex /tmp/device-properties.plist &&
  cat /tmp/device-properties.plist
\end{lstlisting}

Device properties are part of the \texttt{IODeviceTree} (\texttt{gIODT})
plane of macOS I/O Registry. This plane has several construction stages
relevant for the platform initialisation. While the early construction
stage is performed by the XNU kernel in the \texttt{IODeviceTreeAlloc}
method, the majority of the construction is performed by the platform expert,
implemented in \texttt{AppleACPIPlatformExpert.kext}.

AppleACPIPlatformExpert incorporates two stages of \texttt{IODeviceTree}
construction implemented by calling \\
\texttt{AppleACPIPlatformExpert::mergeDeviceProperties}:

\begin{enumerate}
  \tightlist
  \item During ACPI table initialisation through the recursive ACPI namespace scanning
  by the calls to \\
  \texttt{AppleACPIPlatformExpert::createDTNubs}.
  \item During IOService registration (\texttt{IOServices::registerService}) callbacks
  implemented as a part of \\
  \texttt{AppleACPIPlatformExpert::platformAdjustService}
  function and its private worker method \\
  \texttt{AppleACPIPlatformExpert::platformAdjustPCIDevice}
  specific to the PCI devices.
\end{enumerate}

The application of the stages depends on the device presence in ACPI tables.
The first stage applies very early but exclusively to the devices present in ACPI tables.
The second stage applies to all devices much later after the PCI configuration
and may repeat the first stage if the device was not present in ACPI.

For all kernel drivers, which may inspect the \texttt{IODeviceTree} plane without
probing (e.g. \texttt{Lilu} and its plugins such as \texttt{WhateverGreen}) it is particularly
important to ensure device presence in the ACPI tables. Failing to do so may result
\textbf{in all kinds of erratic behaviour} caused by ignoring the injected device properties
as they were not constructed at the first stage. See \texttt{SSDT-IMEI.dsl} and
\texttt{SSDT-BRG0.dsl} for an example.

\subsection{Properties}\label{devpropsprops}

\begin{enumerate}
\item
  \texttt{Add}\\
  \textbf{Type}: \texttt{plist\ dict}\\
  \textbf{Description}: Sets device properties from a map (\texttt{plist\ dict})
  of device paths to a map (\texttt{plist\ dict}) of variable names and their values
  in \texttt{plist\ metadata} format. Device paths must be provided in canonic string
  format (e.g. \texttt{PciRoot(0x0)/Pci(0x1,0x0)/Pci(0x0,0x0)}). Properties will only
  be set if not present and not deleted.

  \emph{Note}: Currently properties may only be (formerly) added by the original driver,
  so unless a separate driver was installed, there is no reason to delete the variables.

\item
  \texttt{Delete}\\
  \textbf{Type}: \texttt{plist\ dict}\\
  \textbf{Description}: Removes device properties from a map (\texttt{plist\ dict})
  of device paths to an array (\texttt{plist\ array}) of variable names in
  \texttt{plist\ string} format.

\end{enumerate}

\subsection{Common Properties}\label{devpropscommon}

Some known properties include:

\begin{itemize}
\tightlist
\item
  \texttt{device-id}
  \break
  User-specified device identifier used for I/O Kit matching. Has 4 byte data type.
\item
  \texttt{vendor-id}
  \break
  User-specified vendor identifier used for I/O Kit matching. Has 4 byte data type.
\item
  \texttt{AAPL,ig-platform-id}
  \break
  Intel GPU framebuffer identifier used for framebuffer selection on Ivy Bridge and newer.
  Has 4 byte data type.
\item
  \texttt{AAPL,snb-platform-id}
  \break
  Intel GPU framebuffer identifier used for framebuffer selection on Sandy Bridge.
  Has 4 byte data type.
\item
  \texttt{layout-id}
  \break
  Audio layout used for AppleHDA layout selection. Has 4 byte data type.
\end{itemize}


\section{Kernel}\label{kernel}

\subsection{Introduction}\label{kernelintro}

This section allows to apply different kinds of kernelspace modifications on
Apple Kernel (\href{https://opensource.apple.com/source/xnu}{XNU}). The modifications
currently provide driver (kext) injection, kernel and driver patching, and driver
blocking.

\subsection{Properties}\label{kernelprops}

\begin{enumerate}
\item
  \texttt{Add}\\
  \textbf{Type}: \texttt{plist\ array}\\
  \textbf{Failsafe}: Empty\\
  \textbf{Description}: Load selected kernel drivers from \texttt{OC/Kexts} directory.

  Designed to be filled with \texttt{plist\ dict} values, describing each driver.
  See \hyperref[kernelpropsadd]{Add Properties} section below. Kernel driver load
  order follows the item order in the array, thus the dependencies should be written
  prior to their consumers.

  To track the dependency order, inspect the \texttt{OSBundleLibraries} key
  in the \texttt{Info.plist} of the kext. Any kext mentioned in the
  \texttt{OSBundleLibraries} of the other kext must precede this kext.

  \emph{Note}: Kexts may have inner kexts (\texttt{Plug-Ins}) in their bundle. Each
  inner kext must be added separately.

\item
  \texttt{Block}\\
  \textbf{Type}: \texttt{plist\ array}\\
  \textbf{Failsafe}: Empty\\
  \textbf{Description}: Remove selected kernel drivers from prelinked kernel.

  Designed to be filled with \texttt{plist\ dictionary} values, describing each
  blocked driver. See \hyperref[kernelpropsblock]{Block Properties} section below.

\item
  \texttt{Emulate}\\
  \textbf{Type}: \texttt{plist\ dict}\\
  \textbf{Description}: Emulate select hardware in kernelspace via parameters
  described in \hyperref[kernelpropsemu]{Emulate Properties} section below.

\item
  \texttt{Force}\\
  \textbf{Type}: \texttt{plist\ array}\\
  \textbf{Failsafe}: Empty\\
  \textbf{Description}: Load kernel drivers from system volume if they are not cached.

  Designed to be filled with \texttt{plist\ dict} values, describing each driver.
  See \hyperref[kernelpropsforce]{Force Properties} section below.
  This section resolves the problem of injecting drivers that depend on other
  drivers, which are not cached otherwise. The issue normally affects older
  operating systems, where various dependency kexts, such as \texttt{IOAudioFamily}
  or \texttt{IONetworkingFamily} may not be present in the kernel cache by default.
  Kernel driver load order follows the item order in the array, thus the dependencies
  should be written prior to their consumers. \texttt{Force} happens before
  \texttt{Add}.

  \emph{Note}: The signature of the ``forced'' kernel drivers is not checked anyhow,
  making the use of this feature extremely dangerous and undesired for secure boot.
  This feature may not work on encrypted partitions in newer operating systems.

\item
  \texttt{Patch}\\
  \textbf{Type}: \texttt{plist\ array}\\
  \textbf{Failsafe}: Empty\\
  \textbf{Description}: Perform binary patches in kernel and drivers prior to
  driver addition and removal.

  Designed to be filled with \texttt{plist\ dictionary} values, describing each
  patch. See \hyperref[kernelpropspatch]{Patch Properties} section below.

\item
  \texttt{Quirks}\\
  \textbf{Type}: \texttt{plist\ dict}\\
  \textbf{Description}: Apply individual kernel and driver quirks described
  in \hyperref[kernelpropsquirks]{Quirks Properties} section below.

\item
  \texttt{Scheme}\\
  \textbf{Type}: \texttt{plist\ dict}\\
  \textbf{Description}: Define kernelspace operation mode via parameters
  described in \hyperref[kernelpropsscheme]{Scheme Properties} section below.


\end{enumerate}

\subsection{Add Properties}\label{kernelpropsadd}

\begin{enumerate}
\item
  \texttt{Arch}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: \texttt{Any}\\
  \textbf{Description}: Kext architecture (\texttt{Any}, \texttt{i386}, \texttt{x86\_64}).

\item
  \texttt{BundlePath}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: Empty\\
  \textbf{Description}: Kext bundle path (e.g. \texttt{Lilu.kext}
  or \texttt{MyKext.kext/Contents/PlugIns/MySubKext.kext}).

\item
  \texttt{Comment}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: Empty\\
  \textbf{Description}: Arbitrary ASCII string used to provide human readable
  reference for the entry. Whether this value is used is implementation defined.

\item
  \texttt{Enabled}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: This kernel driver will not be added unless set to
  \texttt{true}.

\item
  \texttt{ExecutablePath}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: Empty\\
  \textbf{Description}: Kext executable path relative to bundle
  (e.g. \texttt{Contents/MacOS/Lilu}).

\item
  \texttt{MaxKernel}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: Empty\\
  \textbf{Description}: Adds kernel driver on specified macOS version or older.

  \hypertarget{kernmatch}Kernel version can be obtained with \texttt{uname -r} command,
  and should look like 3 numbers separated by dots, for example \texttt{18.7.0} is the
  kernel version for \texttt{10.14.6}. Kernel version interpretation is implemented as follows:
  \begin{align*}
    \begin{aligned}
      ParseDarwinVersion(\kappa,\lambda,\mu)&=\kappa \cdot10000 &&
        \text{Where }\kappa\in(0,99)\text{ is kernel version major} \\
      &+ \lambda\cdot100 &&
        \text{Where }\lambda\in(0,99)\text{ is kernel version minor} \\
      &+ \mu &&
        \text{Where }\mu\in(0,99)\text{ is kernel version patch}
    \end{aligned}
  \end{align*}
  Kernel version comparison is implemented as follows:
  \begin{align*}
    \alpha&=\begin{cases}
      \vspace{-0.5cm}\mbox{\hspace{8cm}} & \mbox{\hspace{5cm}} \\
      ParseDarwinVersion(\texttt{MinKernel}), & \text{If } \texttt{MinKernel} \text{ is valid} \\
      0 & Otherwise
    \end{cases} \\
    \beta&=\begin{cases}
      \vspace{-0.5cm}\mbox{\hspace{8cm}} & \mbox{\hspace{5cm}} \\
      ParseDarwinVersion(\texttt{MaxKernel}), & \text{If } \texttt{MaxKernel} \text{ is valid} \\
      \infty & Otherwise
    \end{cases} \\
    \gamma&=\begin{cases}
      \vspace{-0.5cm}\mbox{\hspace{8cm}} & \mbox{\hspace{5cm}} \\
      ParseDarwinVersion(FindDarwinVersion()), & \text{If valid } \texttt{"Darwin Kernel Version"} \text{ is found} \\
      \infty & Otherwise
    \end{cases} \\
    & \hspace{5cm} f(\alpha,\beta,\gamma)=\alpha\leq\gamma\leq\beta
  \end{align*}
  Here $ParseDarwinVersion$ argument is assumed to be 3 integers obtained by splitting Darwin kernel version
  string from left to right by the \texttt{.} symbol. $FindDarwinVersion$ function looks up
  Darwin kernel version by locating \texttt{"Darwin Kernel Version $\kappa$.$\lambda$.$\mu$"} string
  in the kernel image.

\item
  \texttt{MinKernel}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: Empty\\
  \textbf{Description}: Adds kernel driver on specified macOS version or newer.

  \emph{Note}: Refer to \hyperlink{kernmatch}{\texttt{Add} \texttt{MaxKernel} description} for matching logic.

\item
  \texttt{PlistPath}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: Empty\\
  \textbf{Description}: Kext \texttt{Info.plist} path relative to bundle
  (e.g. \texttt{Contents/Info.plist}).

\end{enumerate}

\subsection{Block Properties}\label{kernelpropsblock}

\begin{enumerate}
\item
  \texttt{Arch}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: \texttt{Any}\\
  \textbf{Description}: Kext block architecture (\texttt{Any}, \texttt{i386}, \texttt{x86\_64}).

\item
  \texttt{Comment}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: Empty\\
  \textbf{Description}: Arbitrary ASCII string used to provide human readable
  reference for the entry. Whether this value is used is implementation defined.

\item
  \texttt{Enabled}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: This kernel driver will not be blocked unless set to
  \texttt{true}.

\item
  \texttt{Identifier}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: Empty\\
  \textbf{Description}: Kext bundle identifier
    (e.g. \texttt{com.apple.driver.AppleTyMCEDriver}).

\item
  \texttt{MaxKernel}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: Empty\\
  \textbf{Description}: Blocks kernel driver on specified macOS version or older.

  \emph{Note}: Refer to \hyperlink{kernmatch}{\texttt{Add} \texttt{MaxKernel} description} for matching logic.

\item
  \texttt{MinKernel}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: Empty\\
  \textbf{Description}: Blocks kernel driver on specified macOS version or newer.

  \emph{Note}: Refer to \hyperlink{kernmatch}{\texttt{Add} \texttt{MaxKernel} description} for matching logic.

\end{enumerate}

\subsection{Emulate Properties}\label{kernelpropsemu}

\begin{enumerate}
\item
  \texttt{Cpuid1Data}\\
  \textbf{Type}: \texttt{plist\ data}, 16 bytes\\
  \textbf{Failsafe}: All zero\\
  \textbf{Description}: Sequence of \texttt{EAX}, \texttt{EBX}, \texttt{ECX},
  \texttt{EDX} values to replace \texttt{CPUID (1)} call in XNU kernel.

  This property primarily serves for three needs:

  \begin{itemize}
    \tightlist
    \item Enabling support of an unsupported CPU model (e.g. Intel Pentium).
    \item Enabling support of a CPU model that is not yet supported by a specific version of macOS which usually is old.
    \item Enabling XCPM support for an unsupported CPU variant.
  \end{itemize}

  \emph{Note 1}: It may also be the case that the CPU model is supported but there is no power management supported
  (e.g. virtual machines). In this case, \texttt{MinKernel} and \texttt{MaxKernel} can be set to restrict CPU virtualisation and dummy power
  management patches to the particular macOS kernel version.

  \emph{Note 2}: Normally it is only the value of \texttt{EAX} that needs to be taken care of,
  since it represents the full CPUID. The remaining bytes are to be left as zeroes.
  Byte order is Little Endian, so for example, \texttt{C3 06 03 00} stands for CPUID
  \texttt{0x0306C3} (Haswell).

  \emph{Note 3}: For XCPM support it is recommended to use the following combinations.

  \begin{itemize}
    \tightlist
    \item Haswell-E (\texttt{0x0306F2}) to Haswell (\texttt{0x0306C3}):\\
    \texttt{Cpuid1Data}: \texttt{C3 06 03 00 00 00 00 00 00 00 00 00 00 00 00 00}\\
    \texttt{Cpuid1Mask}: \texttt{FF FF FF FF 00 00 00 00 00 00 00 00 00 00 00 00}
    \item Broadwell-E (\texttt{0x0406F1}) to Broadwell (\texttt{0x0306D4}):\\
    \texttt{Cpuid1Data}: \texttt{D4 06 03 00 00 00 00 00 00 00 00 00 00 00 00 00}\\
    \texttt{Cpuid1Mask}: \texttt{FF FF FF FF 00 00 00 00 00 00 00 00 00 00 00 00}
  \end{itemize}

  \emph{Note 4}: Note that the following configurations are unsupported by XCPM (at least out of the box):

  \begin{itemize}
    \tightlist
    \item Consumer Ivy Bridge (\texttt{0x0306A9}) as Apple disabled XCPM for Ivy Bridge
      and recommends legacy power management for these CPUs. \texttt{\_xcpm\_bootstrap}
      should manually be patched to enforce XCPM on these CPUs instead of this option.
    \item Low-end CPUs (e.g. Haswell+ Pentium) as they are not supported properly by macOS.
      Legacy hacks for older models can be found in the \texttt{Special NOTES} section of
      \href{https://github.com/acidanthera/bugtracker/issues/365}{acidanthera/bugtracker\#365}.
  \end{itemize}

\item
  \texttt{Cpuid1Mask}\\
  \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} bit is set to 0, the original CPU bit is used,
  otherwise set bits take the value of \texttt{Cpuid1Data}.

\item
  \texttt{DummyPowerManagement}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Requirement}: 10.4\\
  \textbf{Description}: Disables \texttt{AppleIntelCpuPowerManagement}.

  \emph{Note 1}: This option is a preferred alternative to
  \texttt{NullCpuPowerManagement.kext} for CPUs without native power
  management driver in macOS.

  \emph{Note 2}: While this option is usually needed to disable \texttt{AppleIntelCpuPowerManagement}
  on unsupported platforms, it can also be used to disable this kext in other situations
  (e.g. with \texttt{Cpuid1Data} left blank).

\item
  \texttt{MaxKernel}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: Empty\\
  \textbf{Description}: Emulates CPUID and applies \texttt{DummyPowerManagement} on specified macOS version or older.

  \emph{Note}: Refer to \hyperlink{kernmatch}{\texttt{Add} \texttt{MaxKernel} description} for matching logic.

\item
  \texttt{MinKernel}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: Empty\\
  \textbf{Description}: Emulates CPUID and applies \texttt{DummyPowerManagement} on specified macOS version or newer.

  \emph{Note}: Refer to \hyperlink{kernmatch}{\texttt{Add} \texttt{MaxKernel} description} for matching logic.

\end{enumerate}

\subsection{Force Properties}\label{kernelpropsforce}

\begin{enumerate}
\item
  \texttt{Arch}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: \texttt{Any}\\
  \textbf{Description}: Kext architecture (\texttt{Any}, \texttt{i386}, \texttt{x86\_64}).

\item
  \texttt{BundlePath}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: Empty\\
  \textbf{Description}: Kext bundle path (e.g.
  \texttt{System\textbackslash Library \textbackslash Extensions \textbackslash IONetworkingFamily.kext}).

\item
  \texttt{Comment}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: Empty\\
  \textbf{Description}: Arbitrary ASCII string used to provide human readable
  reference for the entry. Whether this value is used is implementation defined.

\item
  \texttt{Enabled}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: This kernel driver will not be added when not present
  unless set to \texttt{true}.

\item
  \texttt{ExecutablePath}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: Empty\\
  \textbf{Description}: Kext executable path relative to bundle
  (e.g. \texttt{Contents/MacOS/IONetworkingFamily}).

\item
  \texttt{Identifier}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: Empty\\
  \textbf{Description}: Kext identifier to perform presence checking
  before adding (e.g. \texttt{com.apple.iokit.IONetworkingFamily}).
  Only drivers which identifiers are not be found in the cache will be added.

\item
  \texttt{MaxKernel}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: Empty\\
  \textbf{Description}: Adds kernel driver on specified macOS version or older.

  \emph{Note}: Refer to \hyperlink{kernmatch}{\texttt{Add} \texttt{Add MaxKernel} description} for matching logic.

\item
  \texttt{MinKernel}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: Empty\\
  \textbf{Description}: Adds kernel driver on specified macOS version or newer.

  \emph{Note}: Refer to \hyperlink{kernmatch}{\texttt{Add} \texttt{Add MaxKernel} description} for matching logic.

\item
  \texttt{PlistPath}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: Empty\\
  \textbf{Description}: Kext \texttt{Info.plist} path relative to bundle
  (e.g. \texttt{Contents/Info.plist}).

\end{enumerate}


\subsection{Patch Properties}\label{kernelpropspatch}

\begin{enumerate}
\item
  \texttt{Arch}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: \texttt{Any}\\
  \textbf{Description}: Kext patch architecture (\texttt{Any}, \texttt{i386}, \texttt{x86\_64}).

\item
  \texttt{Base}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: Empty (Ignored)\\
  \textbf{Description}: Selects symbol-matched base for patch lookup (or immediate
  replacement) by obtaining the address of the provided symbol name.

\item
  \texttt{Comment}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: Empty\\
  \textbf{Description}: Arbitrary ASCII string used to provide human readable
  reference for the entry. Whether this value is used is implementation defined.

\item
  \texttt{Count}\\
  \textbf{Type}: \texttt{plist\ integer}\\
  \textbf{Failsafe}: \texttt{0}\\
  \textbf{Description}: Number of patch occurrences to apply. \texttt{0} applies
  the patch to all occurrences found.

\item
  \texttt{Enabled}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: This kernel patch will not be used unless set to
  \texttt{true}.

\item
  \texttt{Find}\\
  \textbf{Type}: \texttt{plist\ data}\\
  \textbf{Failsafe}: Empty (Immediate replacement at \texttt{Base})\\
  \textbf{Description}: Data to find. Must be equal to \texttt{Replace}
  in size if set.

\item
  \texttt{Identifier}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: Empty\\
  \textbf{Description}: Kext bundle identifier (e.g. \texttt{com.apple.driver.AppleHDA})
  or \texttt{kernel} for kernel patch.

\item
  \texttt{Limit}\\
  \textbf{Type}: \texttt{plist\ integer}\\
  \textbf{Failsafe}: \texttt{0} (Search entire kext or kernel)\\
  \textbf{Description}: Maximum number of bytes to search for.

\item
  \texttt{Mask}\\
  \textbf{Type}: \texttt{plist\ data}\\
  \textbf{Failsafe}: Empty (Ignored)\\
  \textbf{Description}: Data bitwise mask used during find comparison.
  Allows fuzzy search by ignoring not masked (set to zero) bits.
  Must be equal to \texttt{Replace} in size if set.

\item
  \texttt{MaxKernel}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: Empty\\
  \textbf{Description}: Patches data on specified macOS version or older.

  \emph{Note}: Refer to \hyperlink{kernmatch}{\texttt{Add} \texttt{MaxKernel} description} for matching logic.

\item
  \texttt{MinKernel}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: Empty\\
  \textbf{Description}: Patches data on specified macOS version or newer.

  \emph{Note}: Refer to \hyperlink{kernmatch}{\texttt{Add} \texttt{MaxKernel} description} for matching logic.

\item
  \texttt{Replace}\\
  \textbf{Type}: \texttt{plist\ data}\\
  \textbf{Failsafe}: Empty\\
  \textbf{Description}: Replacement data of one or more bytes.

\item
  \texttt{ReplaceMask}\\
  \textbf{Type}: \texttt{plist\ data}\\
  \textbf{Failsafe}: Empty (Ignored)\\
  \textbf{Description}: Data bitwise mask used during replacement.
  Allows fuzzy replacement by updating masked (set to non-zero) bits.
  Must be equal to \texttt{Replace} in size if set.

\item
  \texttt{Skip}\\
  \textbf{Type}: \texttt{plist\ integer}\\
  \textbf{Failsafe}: \texttt{0}\\
  \textbf{Description}: Number of found occurrences to be skipped before replacement
  is done.

\end{enumerate}

\subsection{Quirks Properties}\label{kernelpropsquirks}

\begin{enumerate}

\item
  \texttt{AppleCpuPmCfgLock}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Requirement}: 10.4\\
  \textbf{Description}: Disables \texttt{PKG\_CST\_CONFIG\_CONTROL} (\texttt{0xE2})
  MSR modification in AppleIntelCPUPowerManagement.kext, commonly causing early
  kernel panic, when it is locked from writing.

  Some types of firmware lock the \texttt{PKG\_CST\_CONFIG\_CONTROL} MSR register and the bundled
  \texttt{VerifyMsrE2} tool can be used to check its state. Note that some types of firmware only
  have this register locked on some cores.

  As modern firmware provide a \texttt{CFG Lock} setting that allows configuring the
  \texttt{PKG\_CST\_CONFIG\_CONTROL} MSR register lock, this option should be avoided
  whenever possible. On APTIO firmware that do not provide a \texttt{CFG Lock}
  setting in the GUI, it is possible to access the option directly:

  \begin{enumerate}
    \tightlist
    \item Download \href{https://github.com/LongSoft/UEFITool/releases}{UEFITool} and
      \href{https://github.com/LongSoft/Universal-IFR-Extractor/releases}{IFR-Extractor}.
    \item Open the firmware image in UEFITool and find \texttt{CFG Lock} unicode string.
      If it is not present, the firmware may not have this option and the process should therefore be discontinued.
    \item Extract the \texttt{Setup.bin} PE32 Image Section (the UEFITool found) through the
      \texttt{Extract Body} menu option.
    \item Run IFR-Extractor on the extracted file (e.g. \texttt{./ifrextract Setup.bin Setup.txt}).
    \item Find \texttt{CFG Lock, VarStoreInfo (VarOffset/VarName):} in \texttt{Setup.txt} and
      remember the offset right after it (e.g. \texttt{0x123}).
    \item Download and run \href{http://brains.by/posts/bootx64.7z}{Modified GRUB Shell} compiled by
      \href{https://geektimes.com/post/258090}{brainsucker} or use
      \href{https://github.com/datasone/grub-mod-setup_var}{a newer version} by
      \href{https://github.com/datasone}{datasone}.
    \item Enter \texttt{setup\_var 0x123 0x00} command, where \texttt{0x123} should be replaced by
      the actual offset, and reboot.
  \end{enumerate}

  \textbf{Warning}: Variable offsets are unique not only to each motherboard but even to its firmware
  version. Never ever try to use an offset without checking.

\item
  \texttt{AppleXcpmCfgLock}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Requirement}: 10.8 (not required for older)\\
  \textbf{Description}: Disables \texttt{PKG\_CST\_CONFIG\_CONTROL} (\texttt{0xE2})
  MSR modification in XNU kernel, commonly causing early kernel panic, when it is
  locked from writing (XCPM power management).

  \emph{Note}: This option should be avoided whenever possible. See \texttt{AppleCpuPmCfgLock}
  description for more details.

\item
  \texttt{AppleXcpmExtraMsrs}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Requirement}: 10.8 (not required for older)\\
  \textbf{Description}: Disables multiple MSR access critical for select CPUs,
  which have no native XCPM support.

  This is normally used in conjunction with \texttt{Emulate} section on Haswell-E,
  Broadwell-E, Skylake-SP, and similar CPUs. More details on the XCPM patches are outlined in
  \href{https://github.com/acidanthera/bugtracker/issues/365}{acidanthera/bugtracker\#365}.

  \emph{Note}: Additional not provided patches will be required for Ivy Bridge or Pentium
  CPUs. It is recommended to use \texttt{AppleIntelCpuPowerManagement.kext} for the former.

\item
  \texttt{AppleXcpmForceBoost}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Requirement}: 10.8 (not required for older)\\
  \textbf{Description}: Forces maximum performance in XCPM mode.

  This patch writes \texttt{0xFF00} to \texttt{MSR\_IA32\_PERF\_CONTROL} (\texttt{0x199}),
  effectively setting maximum multiplier for all the time.

  \emph{Note}: While this may increase the performance, this patch is strongly discouraged
  on all systems but those explicitly dedicated to scientific or media calculations.
  In general only certain Xeon models benefit from the patch.

\item
  \texttt{CustomSMBIOSGuid}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Requirement}: 10.4\\
  \textbf{Description}: Performs GUID patching for \texttt{UpdateSMBIOSMode}
  \texttt{Custom} mode. Usually relevant for Dell laptops.

\item
  \texttt{DisableIoMapper}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Requirement}: 10.8 (not required for older)\\
  \textbf{Description}: Disables \texttt{IOMapper} support in XNU (VT-d),
  which may conflict with the firmware implementation.

  \emph{Note}: This option is a preferred alternative to deleting \texttt{DMAR}
  ACPI table and disabling VT-d in firmware preferences, which does not break
  VT-d support in other systems in case they need it.

\item
  \texttt{DisableLinkeditJettison}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Requirement}: 11\\
  \textbf{Description}: Disables \texttt{\_\_LINKEDIT} jettison code.

  This option lets \texttt{Lilu.kext} and possibly some others function
  in macOS Big Sur with best performance without \texttt{keepsyms=1}
  boot argument.

\item
  \texttt{DisableRtcChecksum}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Requirement}: 10.4\\
  \textbf{Description}: Disables primary checksum (\texttt{0x58}-\texttt{0x59})
  writing in AppleRTC.

  \emph{Note 1}: This option will not protect other areas from being overwritten,
  see \href{https://github.com/acidanthera/RTCMemoryFixup}{RTCMemoryFixup}
  kernel extension if this is desired.

  \emph{Note 2}: This option will not protect areas from being overwritten
  at firmware stage (e.g. macOS bootloader), see \texttt{AppleRtcRam} protocol
  description if this is desired.

\item
  \texttt{ExtendBTFeatureFlags}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Requirement}: 10.8\\
  \textbf{Description}: Set \texttt{FeatureFlags} to \texttt{0x0F} for full
  functionality of Bluetooth, including Continuity.

  \emph{Note}: This option is a substitution for BT4LEContinuityFixup.kext,
  which does not function properly due to late patching progress.

\item
  \texttt{ExternalDiskIcons}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Requirement}: 10.4\\
  \textbf{Description}: Apply icon type patches to AppleAHCIPort.kext to force
  internal disk icons for all AHCI disks.

  \emph{Note}: This option should be avoided whenever possible. Modern firmware
  usually have compatible AHCI controllers.

\item
  \texttt{ForceSecureBootScheme}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Requirement}: 11\\
  \textbf{Description}: Force \texttt{x86} scheme for IMG4 verification.

  \emph{Note}: This option is required on virtual machines when using
  \texttt{SecureBootModel} different from \texttt{x86legacy}.

\item
  \texttt{IncreasePciBarSize}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Requirement}: 10.10\\
  \textbf{Description}: Increases 32-bit PCI bar size in IOPCIFamily from 1 to 4 GBs.

  \emph{Note}: This option should be avoided whenever possible. In general the necessity
  of this option means misconfigured or broken firmware.

\item
  \texttt{LapicKernelPanic}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Requirement}: 10.6 (64-bit)\\
  \textbf{Description}: Disables kernel panic on LAPIC interrupts.

\item
  \texttt{LegacyCommpage}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Requirement}: 10.4 - 10.6\\
  \textbf{Description}: Replaces the default 64-bit commpage bcopy implementation with
  one that does not require SSSE3, useful for legacy platforms. This prevents a
  \texttt{commpage no match for last} panic due to no available 64-bit bcopy functions
  that do not require SSSE3.

\item
  \texttt{PanicNoKextDump}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Requirement}: 10.13 (not required for older)\\
  \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{Requirement}: 10.15 (not required for older)\\
  \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{SetApfsTrimTimeout}\\
  \textbf{Type}: \texttt{plist\ integer}\\
  \textbf{Failsafe}: \texttt{-1}\\
  \textbf{Requirement}: 10.14 (not required for older)\\
  \textbf{Description}: Set trim timeout in microseconds for APFS filesystems on SSDs.

  APFS filesystem is designed in a way that the space controlled via
  spaceman structure is either used or free. This may be different in
  other filesystems where the areas can be marked as used, free, and
  \emph{unmapped}. All free space is trimmed (unmapped/deallocated)
  at macOS startup. The trimming procedure for NVMe drives happens
  in LBA ranges due to the nature of \texttt{DSM} command with
  up to 256 ranges per command. The more fragmented the memory
  on the drive is, the more commands are necessary to trim all the
  free space.

  Depending on the SSD controller and the drive fragmenation trim procedure
  may take considerable amount of time, causing noticeable boot slowdown
  APFS driver explicitly ignores previously unmapped areas and trims
  them on boot again and again. To workaround boot slowdown macOS
  driver introduced a timeout (\texttt{9.999999} seconds) that stops
  trim operation when it did not manage to complete in time. On many
  controllers, such as Samsung, where the deallocation is not very fast,
  the timeout is reached very quickly. Essentially it means that
  macOS will try to trim all the same lower blocks that have already been
  deallocated, but will never have enough time to deallocate higher blocks
  once the fragmentation increases. This means that trimming on these SSDs
  will be broken soon after the installation, causing extra wear to the flash.

  One way to workaround the problem is to increase the timeout to a very
  high value, which at the cost of slow boot times (extra minutes)
  will ensure that all the blocks are trimmed. Set this option to a high value,
  such as \texttt{4294967295}, to ensure all the blocks are trimmed.

  Another way is to utilise over-provisioning if it is supported or create
  a dedicated unmapped partition where the reserve blocks can be found
  by the controller. In this case the trim operation can also be disabled
  by setting a very low timeout. e.g. \texttt{999}. See more details
  in this \href{https://interface31.ru/tech_it/2015/04/mozhno-li-effektivno-ispolzovat-ssd-bez-podderzhki-trim.html}{article}.

\item
  \texttt{ThirdPartyDrives}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Requirement}: 10.6 (not required for older)\\
  \textbf{Description}: Apply vendor patches to IOAHCIBlockStorage.kext to enable
  native features for third-party drives, such as TRIM on SSDs or hibernation
  support on 10.15 and newer.

  \emph{Note}: This option may be avoided on user preference. NVMe SSDs are
  compatible without the change. For AHCI SSDs on modern macOS version there
  is a dedicated built-in utility called \texttt{trimforce}. Starting from 10.15
  this utility creates \texttt{EnableTRIM} variable in \texttt{APPLE\_BOOT\_VARIABLE\_GUID}
  namespace with \texttt{01 00 00 00} value.

\item
  \texttt{XhciPortLimit}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Requirement}: 10.11 (not required for older)\\
  \textbf{Description}: Patch various kexts (AppleUSBXHCI.kext, AppleUSBXHCIPCI.kext,
  IOUSBHostFamily.kext) to remove USB port count limit of 15 ports.

  \emph{Note}: This option should be avoided whenever possible. USB port limit
  is imposed by the amount of used bits in locationID format and there is no
  possible way to workaround this without heavy OS modification. The only
  valid solution is to limit the amount of used ports to 15 (discarding some).
  More details can be found on \href{https://applelife.ru/posts/550233}{AppleLife.ru}.

\end{enumerate}

\subsection{Scheme Properties}\label{kernelpropsscheme}

These properties are particularly relevant for older macOS operating systems.
For more details on how to install and troubleshoot such macOS installation
refer to \hyperref[legacyapple]{Legacy Apple OS}.

\begin{enumerate}

\item
  \texttt{FuzzyMatch}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Use \texttt{kernelcache} with different checksums when available.

  On macOS 10.6 and earlier \texttt{kernelcache} filename has a checksum, which essentially
  is \texttt{adler32} from SMBIOS product name and EfiBoot device path. On some types of firmware,
  the EfiBoot device path differs between UEFI and macOS due to ACPI or hardware specifics,
  rendering \texttt{kernelcache} checksum as always different.

  This setting allows matching the latest \texttt{kernelcache} with a suitable architecture
  when the \texttt{kernelcache} without suffix is unavailable, improving macOS 10.6 boot
  performance on several platforms.

\item
  \texttt{KernelArch}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: \texttt{Auto}\\
  \textbf{Description}: Prefer specified kernel architecture (\texttt{Auto}, \texttt{i386},
  \texttt{i386-user32}, \texttt{x86\_64}) when available.

  On macOS 10.7 and earlier XNU kernel can boot with architectures different from
  the usual \texttt{x86\_64}. This setting will use the specified architecture to boot
  macOS when it is supported by the macOS and the configuration:

  \begin{itemize}
    \tightlist
    \item \texttt{Auto} --- Choose the preferred architecture automatically.
    \item \texttt{i386} --- Use \texttt{i386} (32-bit) kernel when available.
    \item \texttt{i386-user32} --- Use \texttt{i386} (32-bit) kernel when available
      and force the use of 32-bit userspace on 64-bit capable processors if supported
      by the operating system. On macOS 64-bit capable processors are assumed to
      support \texttt{SSSE3}. This is not the case for older 64-bit capable Pentium
      processors, which cause some applications to crash on macOS~10.6. This behaviour
      corresponds to \texttt{-legacy} kernel boot argument. This option is unavailable
      for 10.4 and 10.5 when running on 64-bit firmware due to an uninitialised 64-bit
      segment in the XNU kernel, which causes AppleEFIRuntime to incorrectly execute
      64-bit code as 16-bit code.
    \item \texttt{x86\_64} --- Use \texttt{x86\_64} (64-bit) kernel when available.
  \end{itemize}

  Below is the algorithm determining the kernel architecture.

  \begin{enumerate}
    \tightlist
    \item \texttt{arch} argument in image arguments (e.g. when launched
    via UEFI Shell) or in \texttt{boot-args} variable overrides any compatibility
    checks and forces the specified architecture, completing this algorithm.
    \item OpenCore build architecture restricts capabilities to \texttt{i386}
      and \texttt{i386-user32} mode for the 32-bit firmware variant.
    \item Determined EfiBoot version restricts architecture choice:
      \begin{itemize}
      \item 10.4-10.5 --- \texttt{i386} or \texttt{i386-user32} (only on 32-bit firmware)
      \item 10.6 --- \texttt{i386}, \texttt{i386-user32}, or \texttt{x86\_64}
      \item 10.7 --- \texttt{i386} or \texttt{x86\_64}
      \item 10.8 or newer --- \texttt{x86\_64}
      \end{itemize}
    \item If \texttt{KernelArch} is set to \texttt{Auto} and \texttt{SSSE3}
      is not supported by the CPU, capabilities are restricted to \texttt{i386-user32}
      if supported by EfiBoot.
    \item Board identifier (from SMBIOS) based on EfiBoot version
      disables \texttt{x86\_64} support on an unsupported model
      if any \texttt{i386} variant is supported. \texttt{Auto}
      is not consulted here as the list is not overridable in EfiBoot.
    \item \texttt{KernelArch} restricts the support to the explicitly
      specified architecture (when not set to \texttt{Auto}) if
      the architecture remains present in the capabilities.
    \item The best supported architecture is chosen in this order:
      \texttt{x86\_64}, \texttt{i386}, \texttt{i386-user32}.
  \end{enumerate}

  Unlike macOS~10.7, where select boards identifiers are treated as the \texttt{i386}
  only machines, and macOS~10.5 or earlier, where \texttt{x86\_64} is not supported
  by the macOS kernel, macOS~10.6 is very special. The architecture choice on macOS~10.6
  depends on many factors including not only the board identifier, but also macOS
  product type (client vs server), macOS point release, and RAM amount. The detection
  of them all is complicated and not practical, because several point releases had genuine
  bugs and failed to properly perform the server detection in the first place.
  For this reason OpenCore on macOS~10.6 will fallback to \texttt{x86\_64}
  architecture whenever it is supported by the board at all, as on macOS~10.7.
  As a reference here is the 64-bit Mac model compatibility corresponding to actual
  EfiBoot behaviour on macOS 10.6.8 and 10.7.5.

  \begin{center}
  \begin{tabular}{|p{0.9in}|c|c|c|c|}
  \hline
  \textbf{Model} & \textbf{10.6 (minimal)} & \textbf{10.6 (client)} & \textbf{10.6 (server)} & \textbf{10.7 (any)} \\
  \hline
  Macmini & 4,x (Mid 2010) & 5,x (Mid 2011) & 4,x (Mid 2010) & 3,x (Early 2009) \\
  \hline
  MacBook & Unsupported & Unsupported & Unsupported & 5,x (2009/09) \\
  \hline
  MacBookAir & Unsupported & Unsupported & Unsupported & 2,x (Late 2008) \\
  \hline
  MacBookPro & 4,x (Early 2008) & 8,x (Early 2011) & 8,x (Early 2011) & 3,x (Mid 2007) \\
  \hline
  iMac & 8,x (Early 2008) & 12,x (Mid 2011) & 12,x (Mid 2011) & 7,x (Mid 2007) \\
  \hline
  MacPro & 3,x (Early 2008) & 5,x (Mid 2010) & 3,x (Early 2008) & 3,x (Early 2008) \\
  \hline
  Xserve & 2,x (Early 2008) & 2,x (Early 2008) & 2,x (Early 2008) & 2,x (Early 2008) \\
  \hline
  \end{tabular}
  \end{center}

  \emph{Note}: \texttt{3+2} and \texttt{6+4} hotkeys to choose the preferred
  architecture are unsupported due to being handled by EfiBoot and thus
  being hard to properly detect.

\item
  \texttt{KernelCache}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: \texttt{Auto}\\
  \textbf{Description}: Prefer specified kernel cache type (\texttt{Auto}, \texttt{Cacheless},
  \texttt{Mkext}, \texttt{Prelinked}) when available.

  Different variants of macOS support different kernel caching variants designed to improve
  boot performance. This setting prevents the use of faster kernel caching variants
  if slower variants are available for debugging and stability reasons. I.e., by
  specifying \texttt{Mkext}, \texttt{Prelinked} will be disabled for e.g. 10.6 but not for 10.7.

  The list of available kernel caching types and its current support in OpenCore is listed below.

  \begin{center}
  \begin{tabular}{|p{0.67in}|c|c|c|c|c|c|c|}
  \hline
  \textbf{macOS} & \textbf{i386 NC} & \textbf{i386 MK} & \textbf{i386 PK} & \textbf{x86\_64 NC} & \textbf{x86\_64 MK} & \textbf{x86\_64 PK} & \textbf{x86\_64 KC} \\
  \hline
  10.4 & YES & YES (V1) & NO (V1) & --- & --- & --- & --- \\
  \hline
  10.5 & YES & YES (V1) & NO (V1) & --- & --- & --- & --- \\
  \hline
  10.6 & YES & YES (V2) & YES (V2) & YES & YES (V2) & YES (V2) & --- \\
  \hline
  10.7 & YES & --- & YES (V3) & YES & --- & YES (V3) & --- \\
  \hline
  10.8-10.9 & --- & --- & --- & YES & --- & YES (V3) & --- \\
  \hline
  10.10-10.15 & --- & --- & --- & --- & --- & YES (V3) & --- \\
  \hline
  11+ & --- & --- & --- & --- & --- & YES (V3) & YES \\
  \hline
  \end{tabular}
  \end{center}

  \emph{Note}: First version (V1) of 32-bit \texttt{prelinkedkernel} is unsupported
  due to kext symbol tables being corrupted by the tools. On these versions \texttt{Auto}
  will block \texttt{prelinkedkernel} booting. This also makes \texttt{keepsyms=1} for kext frames
  broken on these systems.

\end{enumerate}


\section{Misc}\label{misc}

\subsection{Introduction}\label{miscintro}

This section contains miscellaneous configuration affecting OpenCore operating system loading behaviour
as well as other entries, which do not go to any other section.

OpenCore tries to follow ``bless'' model also known as ``Apple Boot Policy''. The primary specialty of
``bless'' model is to allow embedding boot options within the file system (and be accessible through a
specialised driver) as well as supporting a broader range of predefined boot paths compared to the
removable media list found in the UEFI specification.

Each partition will only be used for booting when it corresponds to ``Scan policy'': a set of restrictions
to only use partitions with specific file systems and from specific device types. Scan policy behaviour is
discussed in \texttt{ScanPolicy} property description.

Scan process starts with obtaining all the partitions filtered with ``Scan policy''. Each partition may
produce multiple primary and alternate options. Primary options describe operating systems installed
on this media. Alternate options describe recovery options for the operating systems on the media.
It is possible for alternate options to exist without primary options and vice versa. Be warned
that the options may not necessarily describe the operating systems on the same partition.
Each primary and alternate option can be an auxiliary option or not, refer to \texttt{HideAuxiliary}
for more details. Algorithm to determine boot options behaves as follows:

\begin{enumerate}
\tightlist
\item Obtain all available partition handles filtered by ``Scan policy'' (and driver availability).
\item Obtain all available boot options from \texttt{BootOrder} UEFI variable.
\item For each found boot option:
  \begin{itemize}
  \item Retrieve device path of the boot option.
  % Scan policy restrictions are actually checked here as we want the function to be self-contained
  % for non-scan based startup.
  \item Perform fixups (e.g. NVMe subtype correction) and expansion (e.g. for Boot Camp) of the device path.
  \item Obtain device handle by locating device path of the resulting device path (ignore it on failure).
  \item Find device handle in the list of partition handles (ignore it if missing).
  % To determine device path type we can use LocateDevicePath RemainingDevicePath argument. Just check whether
  % it points to the END device path.
  \item For disk device paths (not specifying a bootloader) execute ``bless'' (may return > 1 entry).
  \item For file device paths check presence on the file system directly.
  % Just kill all \EFI\APPLE\ paths.
  \item On OpenCore boot partition exclude all OpenCore bootstrap files by header checks.
  \item Mark device handle as \textit{used} in the list of partition handles if any.
  % Each partition handle will basically have a list of boot option entries for later quick lookup.
  \item Register the resulting entries as primary options and determine their types. \\
  The option will become auxiliary for some types (e.g. Apple HFS recovery).
  \end{itemize}
\item For each partition handle:
  \begin{itemize}
  \item If partition handle is marked as \textit{unused} execute ``bless'' primary option list retrieval. \\
    In case \texttt{BlessOverride} list is set, not only standard ``bless'' paths will be found but
    also custom ones.
  \item On OpenCore boot partition exclude all OpenCore bootstrap files by header checks.
  \item Register the resulting entries as primary options and determine their types if found. \\
  The option will become auxiliary for some types (e.g. Apple HFS recovery).
  % Looking up primary and alternate handles could be done per handle to make sure the list is ordered.
  \item If partition already has primary options of ``Apple Recovery'' type proceed to next handle.
  \item Lookup alternate entries by ``bless'' recovery option list retrieval and predefined paths.
  \item Register the resulting entries as alternate auxiliary options and determine their types if found.
  \end{itemize}
\item Custom entries and tools are added as primary options without any checks with respect to \texttt{Auxiliary}.
\item System entries (e.g. \texttt{Reset NVRAM}) are added as primary auxiliary options.
\end{enumerate}

The display order of the boot options in the picker and the boot process are determined separately from the scanning
algorithm. The display order as follows:

\begin{itemize}
\tightlist
\item Alternate options follow corresponding primary options, i.e. Apple recovery will be following the
  relevant macOS option whenever possible.
\item Options will be listed in file system handle firmware order to maintain an established order across
  the reboots regardless of the chosen operating system for loading.
\item Custom entries, tools, and system entries will be added after all other options.
\item Auxiliary options will only show upon entering ``Advanced Mode'' in the picker (usually by pressing ``Space'').
\end{itemize}

The boot process is as follows:
\begin{itemize}
\tightlist
\item Try looking up first valid primary option through \texttt{BootNext} UEFI variable.
\item On failure looking up first valid primary option through \texttt{BootOrder} UEFI variable.
\item Mark the option as the default option to boot.
\item Boot option through the picker or without it depending on the \texttt{ShowPicker} option.
\item Show picker on failure otherwise.
\end{itemize}

\emph{Note 1}: This process is meant to work reliably only when \texttt{RequestBootVarRouting}
option is enabled or the firmware does not control UEFI boot options (\texttt{OpenDuetPkg} or
custom BDS). Without \texttt{LauncherOption} it also is possible that other operating systems
overwrite OpenCore, make sure to enable it when planning to use them.

\emph{Note 2}: UEFI variable boot options' boot arguments will be removed if present as they
may contain arguments compromising the operating system, which is undesired once secure boot
is enabled.

\emph{Note 3}: Some operating systems, namely Windows, will create their boot option and
mark it as top most upon first boot or after NVRAM Reset. When this happens default boot
entry choice will update till next manual reconfiguration.

\subsection{Properties}\label{miscprops}

\begin{enumerate}
\item
  \texttt{Boot}\\
  \textbf{Type}: \texttt{plist\ dict}\\
  \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 debian\textbackslash grubx64.efi}
  for Debian bootloader. This allows unusual boot paths to be automatically
  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}
  or \texttt{\textbackslash EFI\textbackslash Microsoft\textbackslash Boot\textbackslash bootmgfw.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}\\
  \textbf{Description}: Apply security configuration described in
  \hyperref[miscsecurityprops]{Security Properties} section below.

\item
  \texttt{Tools}\label{misctools}\\
  \textbf{Type}: \texttt{plist\ array}\\
  \textbf{Description}: Add tool entries to boot picker.

  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, 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. For tool examples check the \hyperref[uefitools]{UEFI}
  section of this document.

\end{enumerate}

\subsection{Boot Properties}\label{miscbootprops}

\begin{enumerate}

\item
  \texttt{ConsoleAttributes}\\
  \textbf{Type}: \texttt{plist\ integer}\\
  \textbf{Failsafe}: \texttt{0}\\
  \textbf{Description}: Sets specific attributes for console.

  Text renderer supports colour arguments as a sum of foreground and background
  colours 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{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{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{None} --- Avoid hibernation (Recommended).
    \item \texttt{Auto} --- Use RTC and NVRAM detection.
    \item \texttt{RTC} --- Use RTC detection.
    \item \texttt{NVRAM} --- Use NVRAM detection.
  \end{itemize}

\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 Entry is macOS recovery.
    \item Entry is macOS Time Machine.
    \item Entry is explicitly marked as \texttt{Auxiliary}.
    \item Entry is system (e.g. \texttt{Reset 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{LauncherOption}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: \texttt{Disabled}\\
  \textbf{Description}: Register launcher option in firmware preferences for persistence.

  Valid values:

  \begin{itemize}
  \tightlist
  \item \texttt{Disabled} --- do nothing.
  \item \texttt{Full} --- create or update top-priority
  boot option in UEFI variable storage at bootloader startup. For this option
  to work \texttt{RequestBootVarRouting} is required to be enabled.
  \item \texttt{Short} --- create a short boot option instead of a complete one.
  This variant is useful for some older firmwares, Insyde in particular,
  but possibly others, which cannot handle full device paths.
  \end{itemize}

  This option provides integration with third-party operating system installation and upgrade
  at the times they overwrite
  \texttt{\textbackslash EFI\textbackslash BOOT\textbackslash BOOTx64.efi}
  file. By creating a custom option in this file path becomes no longer
  used for bootstrapping OpenCore. The path used for bootstrapping is specified
  in \texttt{LauncherPath} option.

  \emph{Note 1}: Some types of firmware may have faulty NVRAM, no boot option support, or other
  incompatibilities. While unlikely, the use of this option may even cause boot failures.
  This option should be used without any warranty exclusively on the boards known to be compatible.
  Check \href{https://github.com/acidanthera/bugtracker/issues/1222}{acidanthera/bugtracker\#1222}
  for some known issues with Haswell and other boards.

  \emph{Note 2}: Be aware that while NVRAM reset executed from OpenCore should not erase the boot
  option created in \texttt{Bootstrap}, executing NVRAM reset prior to loading OpenCore will remove it. For significant implementation updates (e.g. in OpenCore 0.6.4) make sure to perform
  NVRAM reset with \texttt{Bootstrap} disabled before reenabling.

\item
  \texttt{LauncherPath}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: \texttt{Default}\\
  \textbf{Description}: Launch path for \texttt{LauncherOption}.

  \texttt{Default} stays for launched \texttt{OpenCore.efi},
  any other path, e.g. \texttt{\textbackslash EFI\textbackslash Launcher.efi},
  can be used to provide custom loaders, which are supposed to
  load \texttt{OpenCore.efi} themselves.

\item
  \texttt{PickerAttributes}\\
  \textbf{Type}: \texttt{plist\ integer}\\
  \textbf{Failsafe}: \texttt{0}\\
  \textbf{Description}: Sets specific attributes for picker.

  Different pickers may be configured through the attribute mask containing
  OpenCore-reserved (\texttt{BIT0}\textasciitilde\texttt{BIT15}) and OEM-specific
  (\texttt{BIT16}\textasciitilde\texttt{BIT31}) values.

  Current OpenCore values include:

  \begin{itemize}
  \tightlist
  \item \texttt{0x0001} --- \texttt{OC\_ATTR\_USE\_VOLUME\_ICON}, provides custom icons
    for boot entries:

    For \texttt{Tools} OpenCore will try to load a custom icon and fallback to the default icon:
    \begin{itemize}
    \tightlist
      \item \texttt{ResetNVRAM} --- \texttt{Resources\textbackslash Image\textbackslash ResetNVRAM.icns}
        --- \texttt{ResetNVRAM.icns} from icons directory.
      \item \texttt{Tools\textbackslash <TOOL\_RELATIVE\_PATH>.icns}
        --- icon near the tool file with appended \texttt{.icns} extension.
    \end{itemize} \medskip

    For custom boot \texttt{Entries} OpenCore will try to load a custom icon and fallback
    to the volume icon or the default icon:
    \begin{itemize}
    \tightlist
      \item \texttt{<ENTRY\_PATH>.icns} --- icon near the entry file with appended \texttt{.icns} extension.
    \end{itemize} \medskip

    For all other entries OpenCore will try to load a volume icon by searching
    as follows, and will fallback to the default icon otherwise:
    \begin{itemize}
    \tightlist
      \item \texttt{.VolumeIcon.icns} file at \texttt{Preboot} volume in per-volume directory
       (\texttt{/System/Volumes/Preboot/\{GUID\}/} when mounted at default location within
       macOS) for APFS (if present).
      \item \texttt{.VolumeIcon.icns} file at \texttt{Preboot} root
      (\texttt{/System/Volumes/Preboot/} when mounted at default location within macOS)
      for APFS (otherwise).
      \item \texttt{.VolumeIcon.icns} file at volume root for other filesystems.
    \end{itemize} \medskip

    \emph{Note 1}: Apple's boot picker partially supports placing a volume icon file
    at the operating system's \texttt{Data} volume root (\texttt{/System/Volumes/Data/} when
    mounted at default location within macOS). This approach is broken: that file is not
    accessible either by OpenCanopy or by Apple's own boot picker when FileVault 2 is
    enabled, which should be most people's default choice. Therefore OpenCanopy does not
    try to support it. You may place a volume icon file at \texttt{Preboot} root for
    compatibility with both the Apple and OpenCanopy boot pickers, or use the \texttt{Preboot}
    per-volume location as above with OpenCanopy as a preferred alternative to Apple's
    existing approach. \medskip

    \emph{Note 2}: Be aware that using a volume icon on any drive overrides the normal
    boot picker behaviour for that drive of selecting the appropriate icon depending on
    whether the drive is internal or external. \medskip

  \item \texttt{0x0002} --- \texttt{OC\_ATTR\_USE\_DISK\_LABEL\_FILE}, provides custom
    rendered titles for boot entries:
    \begin{itemize}
    \tightlist
      \item \texttt{.disk\_label} (\texttt{.disk\_label\_2x}) file near bootloader for all filesystems.
      \item \texttt{<TOOL\_NAME>.lbl} (\texttt{<TOOL\_NAME>.l2x}) file near tool for \texttt{Tools}.
    \end{itemize}
    Prerendered labels can be generated via \texttt{disklabel} utility or \texttt{bless} command.
    When disabled or missing text labels (\texttt{.contentDetails} or \texttt{.disk\_label.contentDetails})
    are to be rendered instead.
  \item \texttt{0x0004} --- \texttt{OC\_ATTR\_USE\_GENERIC\_LABEL\_IMAGE}, provides predefined
    label images for boot entries without custom entries. May give less detail for the actual
    boot entry.
  \item \texttt{0x0008} --- \texttt{OC\_ATTR\_HIDE\_THEMED\_ICONS}, prefers builtin icons
    for certain icon categories to match the theme style. For example, this could force
    displaying the builtin Time Machine icon. Requires \texttt{OC\_ATTR\_USE\_VOLUME\_ICON}.
  \item \texttt{0x0010} --- \texttt{OC\_ATTR\_USE\_POINTER\_CONTROL}, enable pointer control
  in the picker when available. For example, this could make use of mouse or trackpad to
  control UI elements.
  \end{itemize}

\item
  \texttt{PickerAudioAssist}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \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}\\
  \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{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.

  On some types of firmware, it may be problematic to use modifier keys due to driver
  incompatibilities. To workaround this problem this option allows registering select hotkeys
  in a more permissive manner from within boot picker. Such extensions include the support
  of tapping on keys in addition to holding and pressing \texttt{Shift} along with
  other keys instead of just \texttt{Shift} alone, which is not detectable on many
  PS/2 keyboards. This list of known \texttt{modifier hotkeys} includes:
  \begin{itemize}
  \tightlist
  \item \texttt{CMD+C+MINUS} --- disable board compatibility checking.
  \item \texttt{CMD+K} --- boot release kernel, similar to \texttt{kcsuffix=release}.
  \item \texttt{CMD+S} --- single user mode.
  \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{ShowPicker}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Show simple boot picker to allow boot entry selection.

\item
  \texttt{TakeoffDelay}\\
  \textbf{Type}: \texttt{plist\ integer}, 32 bit\\
  \textbf{Failsafe}: \texttt{0}\\
  \textbf{Description}: Delay in microseconds performed before handling
  picker startup and \texttt{action hotkeys}.

  Introducing a delay may give extra time to hold the right \texttt{action hotkey}
  sequence to e.g. boot to recovery mode. On some platforms setting this option to
  at least \texttt{5000-10000} microseconds may be necessary to access
  \texttt{action hotkeys} at all due to the nature of the keyboard driver.

\item
  \texttt{Timeout}\\
  \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. Use 0 to disable timer.

\item
  \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. See \hyperref[ueficanopy]{OpenCanopy} plugin
  for an example of a custom user interface.

  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
  holding \texttt{action hotkeys} during boot process. Currently the following actions are
  considered:

  \begin{itemize}
  \tightlist
  \item \texttt{Default} --- this is the default option, and it lets OpenCore built-in
  boot picker to loads the default boot option as specified in
  \href{https://support.apple.com/HT202796}{Startup Disk} preference pane.
  \item \texttt{ShowPicker} --- this option forces picker to show. Normally it can be
  achieved by holding \texttt{OPT} key during boot. Setting \texttt{ShowPicker} to
  \texttt{true} will make \texttt{ShowPicker} the default option.
  \item \texttt{ResetNvram} --- this option performs select UEFI variable erase and is
  normally achieved by holding \texttt{CMD+OPT+P+R} key combination during boot.
  Another way to erase UEFI variables is to choose \texttt{Reset NVRAM} in the picker.
  This option requires \texttt{AllowNvramReset} to be set to \texttt{true}.
  \item \texttt{BootApple} --- this options performs booting to the first found Apple
  operating system unless the default chosen operating system is already made by Apple.
  Hold \texttt{X} key to choose this option.
  \item \texttt{BootAppleRecovery} --- this option performs booting to Apple operating
  system recovery. Either the one related to the default chosen operating system,
  or first found in case default chosen operating system is not made by Apple or has no
  recovery. Hold \texttt{CMD+R} key combination to choose this option.
  \end{itemize}

  \emph{Note 1}: Activated \texttt{KeySupport}, \texttt{OpenUsbKbDxe}, or similar driver is required
  for key handling to work. On several types of firmware, it is not possible to get all the key functions.

  \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 the \texttt{Apple} picker mode and for
  firmware with PS/2 keyboards that fail to report held \texttt{OPT} keys and requiring continual
  presses of the \texttt{Escape} key to access the boot menu.

  \emph{Note 3}: On Macs with problematic GOP, it may be difficult to access the Apple BootPicker.
  The \texttt{BootKicker} utility can be blessed to workaround this problem even without loading
  OpenCore. On some Macs however, the \texttt{BootKicker} utility cannot be run from OpenCore.

\item
  \texttt{PickerVariant}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: \texttt{Auto}\\
  \textbf{Description}: Choose specific icon set used for boot management.

  The following values are supported:
  \begin{itemize}
  \tightlist
  \item \texttt{Auto} --- Automatically select one set of icons based on \texttt{DefaultBackground}
  colour.
  \item \texttt{Default} --- Normal icon set (without prefix).
  \item \texttt{Old} --- Vintage icon set (\texttt{Old} filename prefix).
  \item \texttt{Modern} --- Nouveau icon set (\texttt{Modern} filename prefix).
  \item Other value --- Custom icon set if supported by the resources.
  \end{itemize}

\end{enumerate}

\subsection{Debug Properties}\label{miscdebugprops}

\begin{enumerate}

\item
  \texttt{AppleDebug}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Enable \texttt{boot.efi} debug log saving to OpenCore log.

  \emph{Note}: This option only applies to 10.15.4 and newer.

\item
  \texttt{ApplePanic}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Save macOS kernel panic to OpenCore root partition.

  The file is saved as \texttt{panic-YYYY-MM-DD-HHMMSS.txt}. It is strongly
  recommended to have \texttt{keepsyms=1} boot argument to see debug symbols
  in the panic log. In case it was not present \texttt{kpdescribe.sh} utility
  (bundled with OpenCore) may be used to partially recover the stacktrace.

  Development and debug kernels produce more helpful kernel panics.
  Consider downloading and installing \texttt{KernelDebugKit} from
  \href{https://developer.apple.com}{developer.apple.com} when debugging a problem.
  To activate a development kernel the boot argument \texttt{kcsuffix=development} should be added.
  Use \texttt{uname -a} command to ensure that the current loaded
  kernel is a development (or a debug) kernel.

  In case OpenCore kernel panic saving mechanism was not used, kernel panics may
  still be found in \\
  \texttt{/Library/Logs/DiagnosticReports} directory.
  Starting with macOS Catalina kernel panics are stored in JSON format, so they
  need to be preprocessed before passing to \texttt{kpdescribe.sh}:

\begin{lstlisting}[label=kpanic, style=ocbash]
cat Kernel.panic | grep macOSProcessedStackshotData |
  python -c 'import json,sys;print(json.load(sys.stdin)["macOSPanicString"])'
\end{lstlisting}

\item
  \texttt{DisableWatchDog}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Some types of firmware may not succeed in booting
  the operating system quickly, especially in debug mode, which results in the watchdog
  timer aborting the process. This option turns off the watchdog timer.

\item
  \texttt{DisplayDelay}\\
  \textbf{Type}: \texttt{plist\ integer}\\
  \textbf{Failsafe}: \texttt{0}\\
  \textbf{Description}: Delay in microseconds performed after
  every printed line visible onscreen (i.e. console).

\item
  \texttt{DisplayLevel}\\
  \textbf{Type}: \texttt{plist\ integer}, 64 bit\\
  \textbf{Failsafe}: \texttt{0}\\
  \textbf{Description}: EDK II debug level bitmask (sum) showed onscreen.
  Unless \texttt{Target} enables console (onscreen) printing,
  onscreen debug output will not be visible. The following levels
  are supported (discover more in
  \href{https://github.com/acidanthera/audk/blob/master/MdePkg/Include/Library/DebugLib.h}{DebugLib.h}):

  \begin{itemize}
  \tightlist
    \item \texttt{0x00000002} (bit \texttt{1}) --- \texttt{DEBUG\_WARN} in \texttt{DEBUG},
      \texttt{NOOPT}, \texttt{RELEASE}.
    \item \texttt{0x00000040} (bit \texttt{6}) --- \texttt{DEBUG\_INFO} in \texttt{DEBUG},
      \texttt{NOOPT}.
    \item \texttt{0x00400000} (bit \texttt{22}) --- \texttt{DEBUG\_VERBOSE} in custom builds.
    \item \texttt{0x80000000} (bit \texttt{31}) --- \texttt{DEBUG\_ERROR} in \texttt{DEBUG},
      \texttt{NOOPT}, \texttt{RELEASE}.
  \end{itemize}

\item
  \texttt{SerialInit}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Perform serial port initialisation.

  This option will perform serial port initialisation within OpenCore prior to enabling
  (any) debug logging. Serial port configuration is defined via PCDs at compile time
  in \texttt{gEfiMdeModulePkgTokenSpaceGuid} GUID. Default values as found in
  \texttt{MdeModulePkg.dec} are as follows:

  \begin{itemize}
  \tightlist
    \item \texttt{PcdSerialBaudRate} --- Baud rate: \texttt{115200}.
    \item \texttt{PcdSerialLineControl} --- Line control: no parity, 8 data bits, 1 stop bit.
  \end{itemize}

  See more details in \hyperref[troubleshootingdebug]{\texttt{Debugging}} section.

\item
  \texttt{SysReport}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Produce system report on ESP folder.

  This option will create a \texttt{SysReport} directory on ESP partition
  unless it is already present. The directory will contain ACPI, SMBIOS, and audio codec dumps.
  Audio codec dumps require an audio backend driver to be loaded.

  \emph{Note}: For security reasons \texttt{SysReport} option is \textbf{not} available
  in \texttt{RELEASE} builds. Use a \texttt{DEBUG} build if this option is needed.

\item
  \texttt{Target}\\
  \textbf{Type}: \texttt{plist\ integer}\\
  \textbf{Failsafe}: \texttt{0}\\
  \textbf{Description}: A bitmask (sum) of enabled logging targets.
  By default all the logging output is hidden, so this option is
  required to be set when debugging is necessary.

  The following logging targets are supported:

  \begin{itemize}
  \tightlist
    \item \texttt{0x01} (bit \texttt{0}) --- Enable logging, otherwise all log is discarded.
    \item \texttt{0x02} (bit \texttt{1}) --- Enable basic console (onscreen) logging.
    \item \texttt{0x04} (bit \texttt{2}) --- Enable logging to Data Hub.
    \item \texttt{0x08} (bit \texttt{3}) --- Enable serial port logging.
    \item \texttt{0x10} (bit \texttt{4}) --- Enable UEFI variable logging.
    \item \texttt{0x20} (bit \texttt{5}) --- Enable non-volatile UEFI variable logging.
    \item \texttt{0x40} (bit \texttt{6}) --- Enable logging to file.
  \end{itemize}

  Console logging prints less than all the other variants.
  Depending on the build type (\texttt{RELEASE}, \texttt{DEBUG}, or
  \texttt{NOOPT}) different amount of logging may be read (from least to most).

  Data Hub log will not log kernel and kext patches. To obtain Data Hub log use
  the following command in macOS:
\begin{lstlisting}[label=dhublog, style=ocbash]
ioreg -lw0 -p IODeviceTree | grep boot-log | sort | sed 's/.*<\(.*\)>.*/\1/' | xxd -r -p
\end{lstlisting}

  UEFI variable log does not include some messages and has no performance data. For safety
  reasons log size is limited to 32 kilobytes. Some types of firmware may truncate it much earlier
  or drop completely if they have no memory. Using non-volatile flag will write the log to
  NVRAM flash after every printed line. To obtain UEFI variable log use the following command
  in macOS:
\begin{lstlisting}[label=nvramlog, style=ocbash]
nvram 4D1FDA02-38C7-4A6A-9CC6-4BCCA8B30102:boot-log |
  awk '{gsub(/%0d%0a%00/,"");gsub(/%0d%0a/,"\n")}1'
\end{lstlisting}

  \textbf{Warning}: Some types of firmware appear to have flawed NVRAM garbage collection.
  This means that they may not be able to always free space after variable deletion.
  Do not use non-volatile NVRAM logging without extra need on such devices.

  While OpenCore boot log already contains basic version information with build type and
  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-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 firmware are not reliable and may corrupt data when writing files through UEFI.
  Log writing is attempted in the safest manner and thus, is very slow. Ensure that
  \texttt{DisableWatchDog} is set to \texttt{true} when a slow drive is used. Try to
  avoid frequent use of this option when dealing with flash drives as large I/O
  amounts may speedup memory wear and render the flash drive unusable quicker.

  When interpreting the log, note that the lines are prefixed with a tag describing
  the relevant location (module) of the log line allowing better attribution of the line
  to the functionality. The list of currently used tags is provided below.

  \textbf{Drivers and tools}:
  \begin{itemize}
  \tightlist
  \item \texttt{BMF} --- OpenCanopy, bitmap font
  \item \texttt{BS} --- Bootstrap
  \item \texttt{GSTT} --- GoptStop
  \item \texttt{HDA} --- AudioDxe
  \item \texttt{KKT} --- KeyTester
  \item \texttt{MMDD} --- MmapDump
  \item \texttt{OCPAVP} --- PavpProvision
  \item \texttt{OCRST} --- ResetSystem
  \item \texttt{OCUI} --- OpenCanopy
  \item \texttt{OC} --- OpenCore main, also OcMainLib
  \item \texttt{VMOPT} --- VerifyMemOpt
  \end{itemize}

  \textbf{Libraries}:
  \begin{itemize}
  \tightlist
  \item \texttt{AAPL} --- OcDebugLogLib, Apple EfiBoot logging
  \item \texttt{OCABC} --- OcAfterBootCompatLib
  \item \texttt{OCAE} --- OcAppleEventLib
  \item \texttt{OCAK} --- OcAppleKernelLib
  \item \texttt{OCAU} --- OcAudioLib
  \item \texttt{OCA} ---- OcAcpiLib
  \item \texttt{OCBP} --- OcAppleBootPolicyLib
  \item \texttt{OCB} --- OcBootManagementLib
  \item \texttt{OCCL} --- OcAppleChunkListLib
  \item \texttt{OCCPU} --- OcCpuLib
  \item \texttt{OCC} --- OcConsoleLib
  \item \texttt{OCDC} --- OcDriverConnectionLib
  \item \texttt{OCDH} --- OcDataHubLib
  \item \texttt{OCDI} --- OcAppleDiskImageLib
  \item \texttt{OCFS} --- OcFileLib
  \item \texttt{OCFV} --- OcFirmwareVolumeLib
  \item \texttt{OCHS} --- OcHashServicesLib
  \item \texttt{OCI4} --- OcAppleImg4Lib
  \item \texttt{OCIC} --- OcImageConversionLib
  \item \texttt{OCII} --- OcInputLib
  \item \texttt{OCJS} --- OcApfsLib
  \item \texttt{OCKM} --- OcAppleKeyMapLib
  \item \texttt{OCL} --- OcDebugLogLib
  \item \texttt{OCMCO} --- OcMachoLib
  \item \texttt{OCME} --- OcHeciLib
  \item \texttt{OCMM} --- OcMemoryLib
  \item \texttt{OCPE} --- OcPeCoffLib, OcPeCoffExtLib
  \item \texttt{OCPI} --- OcFileLib, partition info
  \item \texttt{OCPNG} --- OcPngLib
  \item \texttt{OCRAM} --- OcAppleRamDiskLib
  \item \texttt{OCRTC} --- OcRtcLib
  \item \texttt{OCSB} --- OcAppleSecureBootLib
  \item \texttt{OCSMB} --- OcSmbiosLib
  \item \texttt{OCSMC} --- OcSmcLib
  \item \texttt{OCST} --- OcStorageLib
  \item \texttt{OCS} --- OcSerializedLib
  \item \texttt{OCTPL} --- OcTemplateLib
  \item \texttt{OCUC} --- OcUnicodeCollationLib
  \item \texttt{OCUT} --- OcAppleUserInterfaceThemeLib
  \item \texttt{OCXML} --- OcXmlLib
  \end{itemize}

\end{enumerate}

\subsection{Security Properties}\label{miscsecurityprops}

\begin{enumerate}

\item
  \texttt{AllowNvramReset}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Allow \texttt{CMD+OPT+P+R} handling and enable
  showing \texttt{NVRAM Reset} entry in boot picker.

  \emph{Note 1}: It is known that some Lenovo laptops have a firmware
  bug, which makes them unbootable after performing NVRAM reset. See
  \href{https://github.com/acidanthera/bugtracker/issues/995}{acidanthera/bugtracker\#995}
  for more details.

  \emph{Note 2}: Resetting NVRAM will also erase all the boot options
  otherwise not backed up with bless (e.g. Linux).

\item
  \texttt{AllowSetDefault}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Allow \texttt{CTRL+Enter} and \texttt{CTRL+Index} handling
  to set the default boot option in boot picker.

\item
  \texttt{ApECID}\\
  \textbf{Type}: \texttt{plist\ integer}, 64 bit\\
  \textbf{Failsafe}: \texttt{0}\\
  \textbf{Description}: Apple Enclave Identifier.

  Setting this value to any non-zero 64-bit integer will allow using
  personalised Apple Secure Boot identifiers. To use this setting,
  make sure to generate a random 64-bit number with a cryptographically secure
  random number generator. As an alternative, first 8 bytes of \texttt{SystemUUID}
  can be used for \texttt{ApECID}, this is found in macOS 11 for Macs without
  the T2 chip.

  With this value set and \texttt{SecureBootModel} valid
  and not \texttt{Disabled} it is possible to achieve
  \href{https://support.apple.com/en-us/HT208330}{\texttt{Full Security}} of Apple
  Secure Boot.

  To start using personalised Apple Secure Boot, the operating system will have
  to be reinstalled or personalised. Unless the operating system is personalised,
  macOS DMG recovery cannot be loaded. If DMG recovery is missing,
  it can be downloaded with \texttt{macrecovery} utility and put to
  \texttt{com.apple.recovery.boot} as explained in
  \hyperref[reinstallmacos]{Tips and Tricks} section. Note that
  \hyperref[securedmgloading]{DMG loading} needs to be set to \texttt{Signed}
  to use any DMG with Apple Secure Boot.

  To personalise an existing operating system use \texttt{bless} command
  after loading to macOS DMG recovery. Mount the system volume partition,
  unless it has already been mounted, and execute the following command:

\begin{lstlisting}[label=blesspersona, style=ocbash]
bless bless --folder "/Volumes/Macintosh HD/System/Library/CoreServices" \
  --bootefi --personalize
\end{lstlisting}

  Before macOS 11, which introduced a dedicated \texttt{x86legacy}
  model for models without the T2 chip, personalised Apple Secure Boot
  may not work as expected. When reinstalling the operating system, macOS Installer
  from macOS 10.15 and older, will usually run out of free memory
  on the \texttt{/var/tmp} partition when trying to install macOS
  with the personalised Apple Secure Boot. Soon after downloading the macOS installer
  image an \texttt{Unable to verify macOS} error message will appear. To workaround
  this issue allocate a dedicated RAM disk of 2 MBs for macOS personalisation
  by entering the following commands in macOS recovery terminal before starting the
  installation:

\begin{lstlisting}[label=secureboot, style=ocbash]
disk=$(hdiutil attach -nomount ram://4096)
diskutil erasevolume HFS+ SecureBoot $disk
diskutil unmount $disk
mkdir /var/tmp/OSPersonalizationTemp
diskutil mount -mountpoint /var/tmp/OSPersonalizationTemp $disk
\end{lstlisting}

\item
  \texttt{AuthRestart}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Enable \texttt{VirtualSMC}-compatible authenticated restart.

  Authenticated restart is a way to reboot FileVault 2 enabled macOS without entering
  the password. A dedicated terminal command can be used to perform authenticated restarts:
  \texttt{sudo fdesetup authrestart}. It is also used when installing operating system updates.

  VirtualSMC performs authenticated restart by saving disk encryption key split in
  NVRAM and RTC, which despite being removed as soon as OpenCore starts, may be
  considered a security risk and thus is optional.

\item
  \texttt{BlacklistAppleUpdate}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Ignore boot options trying to update Apple peripheral firmware
  (e.g. \texttt{MultiUpdater.efi}).

  \emph{Note}: This option exists due to some operating systems, namely macOS Big Sur,
  being \href{https://github.com/acidanthera/bugtracker/issues/1255}{incapable} of
  disabling firmware updates with the NVRAM variable (\texttt{run-efi-updater}).

\item \label{securedmgloading}
  \texttt{DmgLoading}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: \texttt{Signed}\\
  \textbf{Description}: Define Disk Image (DMG) loading policy used for macOS Recovery.

  Valid values:

  \begin{itemize}
  \tightlist
  \item \texttt{Disabled} --- loading DMG images will fail. \texttt{Disabled}
    policy will still let macOS Recovery to load in most cases as there
    usually are \texttt{boot.efi} files compatible with Apple Secure Boot.
    Manually downloaded DMG images stored in \texttt{com.apple.recovery.boot}
    directories will not load, however.
  \item \texttt{Signed} --- only Apple-signed DMG images will load. Due to
    Apple Secure Boot design \texttt{Signed} policy will let any Apple-signed
    macOS Recovery to load regardless of Apple Secure Boot state, which may
    not always be desired.
  \item \texttt{Any} --- any DMG images will mount as normal filesystems.
    \texttt{Any} policy is strongly not recommended and will cause a boot failure
    when Apple Secure Boot is activated.
  \end{itemize}

\item
  \texttt{EnablePassword}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Enable password protection to allow sensitive operations.

  Password protection ensures that sensitive operations such as booting a non-default
  operating system (e.g. macOS recovery or a tool), resetting NVRAM storage,
  trying to boot into a non-default mode (e.g. verbose mode or safe mode) are not
  allowed without explicit user authentication by a custom password. Currently
  password and salt are hashed with 5000000 iterations of SHA-512.

  \emph{Note}: This functionality is currently in development and is not ready for
  daily usage.

\item
  \texttt{ExposeSensitiveData}\\
  \textbf{Type}: \texttt{plist\ integer}\\
  \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.
    \item \texttt{0x08} --- Expose OEM information as a set of UEFI variables.
  \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:
\begin{lstlisting}[label=nvrampath, style=ocbash]
nvram 4D1FDA02-38C7-4A6A-9CC6-4BCCA8B30102:boot-path
\end{lstlisting}

  To use booter path for mounting booter volume use the following command in macOS:
\begin{lstlisting}[label=nvrampathmount, style=ocbash]
u=$(nvram 4D1FDA02-38C7-4A6A-9CC6-4BCCA8B30102:boot-path | sed 's/.*GPT,\([^,]*\),.*/\1/'); \
  if [ "$u" != "" ]; then sudo diskutil mount $u ; fi
\end{lstlisting}

  To obtain OpenCore version use the following command in macOS:
\begin{lstlisting}[label=nvramver, style=ocbash]
nvram 4D1FDA02-38C7-4A6A-9CC6-4BCCA8B30102:opencore-version
\end{lstlisting}

  To obtain OEM information use the following commands in macOS:
\begin{lstlisting}[label=nvramoem, style=ocbash]
nvram 4D1FDA02-38C7-4A6A-9CC6-4BCCA8B30102:oem-product # SMBIOS Type1 ProductName
nvram 4D1FDA02-38C7-4A6A-9CC6-4BCCA8B30102:oem-vendor  # SMBIOS Type2 Manufacturer
nvram 4D1FDA02-38C7-4A6A-9CC6-4BCCA8B30102:oem-board   # SMBIOS Type2 ProductName
\end{lstlisting}

\item
  \texttt{HaltLevel}\\
  \textbf{Type}: \texttt{plist\ integer}, 64 bit\\
  \textbf{Failsafe}: \texttt{0x80000000} (\texttt{DEBUG\_ERROR})\\
  \textbf{Description}: EDK II debug level bitmask (sum) causing CPU to
  halt (stop execution) after obtaining a message of \texttt{HaltLevel}.
  Possible values match \texttt{DisplayLevel} values.

\item
  \texttt{PasswordHash}\\
  \textbf{Type}: \texttt{plist\ data} 64 bytes\\
  \textbf{Failsafe}: all zero\\
  \textbf{Description}: Password hash used when \texttt{EnabledPassword} is set.

\item
  \texttt{PasswordSalt}\\
  \textbf{Type}: \texttt{plist\ data}\\
  \textbf{Failsafe}: empty\\
  \textbf{Description}: Password salt used when \texttt{EnabledPassword} is set.

\item \label{securevaulting}
  \texttt{Vault}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: \texttt{Secure}\\
  \textbf{Description}: Enables vaulting mechanism in OpenCore.

  Valid values:

  \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 either of the following should be performed:

  \begin{itemize}
  \tightlist
  \item Provide public key during the \texttt{OpenCore.efi} compilation in
  \href{https://github.com/acidanthera/OpenCorePkg/blob/master/Platform/OpenCore/OpenCoreVault.c}{\texttt{OpenCoreVault.c}} file.
  \item Binary patch \texttt{OpenCore.efi} replacing zeroes with the public key
  between \texttt{=BEGIN OC VAULT=} and \texttt{==END OC VAULT==} ASCII markers.
  \end{itemize}

  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/OpenCorePkg/tree/master/Utilities/CreateVault}{RsaTool}.


  The complete set of commands to:

  \begin{itemize}
  \tightlist
  \item Create \texttt{vault.plist}.
  \item Create a new RSA key (always do this to avoid loading old configuration).
  \item Embed RSA key into \texttt{OpenCore.efi}.
  \item Create \texttt{vault.sig}.
  \end{itemize}

  Can look as follows:
\begin{lstlisting}[label=createvault, style=ocbash]
cd /Volumes/EFI/EFI/OC
/path/to/create_vault.sh .
/path/to/RsaTool -sign vault.plist vault.sig vault.pub
off=$(($(strings -a -t d OpenCore.efi | grep "=BEGIN OC VAULT=" | cut -f1 -d' ')+16))
dd of=OpenCore.efi if=vault.pub bs=1 seek=$off count=528 conv=notrunc
rm vault.pub
\end{lstlisting}

  \emph{Note 1}: While it may appear obvious, an external
  method is required to verify \texttt{OpenCore.efi} and \texttt{BOOTx64.efi} for
  secure boot path. For this, it is recommended to enable UEFI SecureBoot
  using a custom certificate and to sign \texttt{OpenCore.efi} and \texttt{BOOTx64.efi}
  with a custom key. More details on customising secure boot on modern firmware
  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\\
  \textbf{Failsafe}: \texttt{0x10F0103}\\
  \textbf{Description}: Define operating system detection policy.

  This value allows to prevent scanning (and booting) from untrusted
  source based on a bitmask (sum) of select flags. As it is not possible
  to reliably detect every file system or device type, this feature
  cannot be fully relied upon in open environments, and the additional
  measures are to be applied.

  Third party drivers may introduce additional security (and performance)
  measures following the provided scan policy. Scan policy is exposed
  in \texttt{scan-policy} variable of \texttt{4D1FDA02-38C7-4A6A-9CC6-4BCCA8B30102}
  GUID for UEFI Boot Services only.

  \begin{itemize}
  \tightlist
    \item \texttt{0x00000001} (bit \texttt{0}) --- \texttt{OC\_SCAN\_FILE\_SYSTEM\_LOCK}, restricts
    scanning to only known file systems defined as a part of this policy. File system
    drivers may not be aware of this policy, and to avoid mounting of undesired file
    systems it is best not to load its driver. This bit does not affect dmg mounting,
    which may have any file system. Known file systems are prefixed with
    \texttt{OC\_SCAN\_ALLOW\_FS\_}.
    \item \texttt{0x00000002} (bit \texttt{1}) --- \texttt{OC\_SCAN\_DEVICE\_LOCK}, restricts scanning
    to only known device types defined as a part of this policy. This is not always possible
    to detect protocol tunneling, so be aware that on some systems it may be possible for
    e.g. USB HDDs to be recognised as SATA. Cases like this must be reported. Known device
    types are prefixed with \texttt{OC\_SCAN\_ALLOW\_DEVICE\_}.
    \item \texttt{0x00000100} (bit \texttt{8}) --- \texttt{OC\_SCAN\_ALLOW\_FS\_APFS}, allows scanning
    of APFS file system.
    \item \texttt{0x00000200} (bit \texttt{9}) --- \texttt{OC\_SCAN\_ALLOW\_FS\_HFS}, allows scanning
    of HFS file system.
    \item \texttt{0x00000400} (bit \texttt{10}) --- \texttt{OC\_SCAN\_ALLOW\_FS\_ESP}, allows scanning
    of EFI System Partition file system.
    \item \texttt{0x00000800} (bit \texttt{11}) --- \texttt{OC\_SCAN\_ALLOW\_FS\_NTFS}, allows scanning
    of NTFS (Msft Basic Data) file system.
    \item \texttt{0x00001000} (bit \texttt{12}) --- \texttt{OC\_SCAN\_ALLOW\_FS\_EXT}, allows scanning
    of EXT (Linux Root) file system.
    \item \texttt{0x00010000} (bit \texttt{16}) --- \texttt{OC\_SCAN\_ALLOW\_DEVICE\_SATA}, allow
    scanning SATA devices.
    \item \texttt{0x00020000} (bit \texttt{17}) --- \texttt{OC\_SCAN\_ALLOW\_DEVICE\_SASEX}, allow
    scanning SAS and Mac NVMe devices.
    \item \texttt{0x00040000} (bit \texttt{18}) --- \texttt{OC\_SCAN\_ALLOW\_DEVICE\_SCSI}, allow
    scanning SCSI devices.
    \item \texttt{0x00080000} (bit \texttt{19}) --- \texttt{OC\_SCAN\_ALLOW\_DEVICE\_NVME}, allow
    scanning NVMe devices.
    \item \texttt{0x00100000} (bit \texttt{20}) --- \texttt{OC\_SCAN\_ALLOW\_DEVICE\_ATAPI}, allow
    scanning CD/DVD devices and old SATA.
    \item \texttt{0x00200000} (bit \texttt{21}) --- \texttt{OC\_SCAN\_ALLOW\_DEVICE\_USB}, allow
    scanning USB devices.
    \item \texttt{0x00400000} (bit \texttt{22}) --- \texttt{OC\_SCAN\_ALLOW\_DEVICE\_FIREWIRE}, allow
    scanning FireWire devices.
    \item \texttt{0x00800000} (bit \texttt{23}) --- \texttt{OC\_SCAN\_ALLOW\_DEVICE\_SDCARD}, allow
    scanning card reader devices.
    \item \texttt{0x01000000} (bit \texttt{24}) --- \texttt{OC\_SCAN\_ALLOW\_DEVICE\_PCI}, allow
    scanning devices directly connected to PCI bus (e.g. VIRTIO).
  \end{itemize}

  \emph{Note}: Given the above description, \texttt{0xF0103} value is expected to allow
  scanning of SATA, SAS, SCSI, and NVMe devices with APFS file system, and prevent scanning
  of any devices with HFS or FAT32 file systems in addition to not scanning APFS file systems
  on USB, CD, and FireWire drives. The combination reads as:
  \begin{itemize}
  \tightlist
  \item \texttt{OC\_SCAN\_FILE\_SYSTEM\_LOCK}
  \item \texttt{OC\_SCAN\_DEVICE\_LOCK}
  \item \texttt{OC\_SCAN\_ALLOW\_FS\_APFS}
  \item \texttt{OC\_SCAN\_ALLOW\_DEVICE\_SATA}
  \item \texttt{OC\_SCAN\_ALLOW\_DEVICE\_SASEX}
  \item \texttt{OC\_SCAN\_ALLOW\_DEVICE\_SCSI}
  \item \texttt{OC\_SCAN\_ALLOW\_DEVICE\_NVME}
  \end{itemize}

\item \label{secureapplesb}
  \texttt{SecureBootModel}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: \texttt{Default}\\
  \textbf{Description}: Apple Secure Boot hardware model.

  Sets Apple Secure Boot hardware model and policy. Specifying
  this value defines which operating systems will be bootable.
  Operating systems shipped before the specified model was released
  will not boot. Valid values:

  \begin{itemize}
  \tightlist
  \item \texttt{Default} --- Recent available model, currently set to \texttt{j137}.
  \item \texttt{Disabled} --- No model, Secure Boot will be disabled.
  \item \texttt{j137} --- \texttt{iMacPro1,1 (December 2017). Minimum macOS 10.13.2 (17C2111)}
  \item \texttt{j680} --- \texttt{MacBookPro15,1 (July 2018). Minimum macOS 10.13.6 (17G2112)}
  \item \texttt{j132} --- \texttt{MacBookPro15,2 (July 2018). Minimum macOS 10.13.6 (17G2112)}
  \item \texttt{j174} --- \texttt{Macmini8,1 (October 2018). Minimum macOS 10.14 (18A2063)}
  \item \texttt{j140k} --- \texttt{MacBookAir8,1 (October 2018). Minimum macOS 10.14.1 (18B2084)}
  \item \texttt{j780} --- \texttt{MacBookPro15,3 (May 2019). Minimum macOS 10.14.5 (18F132)}
  \item \texttt{j213} --- \texttt{MacBookPro15,4 (July 2019). Minimum macOS 10.14.5 (18F2058)}
  \item \texttt{j140a} --- \texttt{MacBookAir8,2 (July 2019). Minimum macOS 10.14.5 (18F2058)}
  \item \texttt{j152f} --- \texttt{MacBookPro16,1 (November 2019). Minimum macOS 10.15.1 (19B2093)}
  \item \texttt{j160} --- \texttt{MacPro7,1 (December 2019). Minimum macOS 10.15.1 (19B88)}
  \item \texttt{j230k} --- \texttt{MacBookAir9,1 (March 2020). Minimum macOS 10.15.3 (19D2064)}
  \item \texttt{j214k} --- \texttt{MacBookPro16,2 (May 2020). Minimum macOS 10.15.4 (19E2269)}
  \item \texttt{j223} --- \texttt{MacBookPro16,3 (May 2020). Minimum macOS 10.15.4 (19E2265)}
  \item \texttt{j215} --- \texttt{MacBookPro16,4 (June 2020). Minimum macOS 10.15.5 (19F96)}
  \item \texttt{j185} --- \texttt{iMac20,1 (August 2020). Minimum macOS 10.15.6 (19G2005)}
  \item \texttt{j185f} --- \texttt{iMac20,2 (August 2020). Minimum macOS 10.15.6 (19G2005)}
  \item \texttt{x86legacy} --- \texttt{Macs without T2 chip and VMs. Minimum macOS 11.0.1 (20B29)}
  \end{itemize}

  Apple Secure Boot appeared in macOS 10.13 on models with T2 chips.
  Since \texttt{PlatformInfo} and \texttt{SecureBootModel} are independent,
  Apple Secure Boot can be used with any SMBIOS with and without T2.
  Setting \texttt{SecureBootModel} to any valid value but \texttt{Disabled}
  is equivalent to
  \href{https://support.apple.com/en-us/HT208330}{\texttt{Medium Security}}
  of Apple Secure Boot. The \texttt{ApECID} value must also be specified to
  achieve \texttt{Full Security}. Check \texttt{ForceSecureBootScheme}
  when using Apple Secure Boot on a virtual machine.

  Enabling Apple Secure Boot is more demanding to incorrect configurations,
  buggy macOS installations, and unsupported setups. Things to consider:

  \begin{enumerate}
    \tightlist
    \item As with T2 Macs, unsigned kernel drivers and several signed kernel
      drivers, including NVIDIA Web Drivers, cannot be installed.
    \item The list of cached drivers may be different, resulting in the need
      to change the list of \texttt{Added} or \texttt{Forced} kernel drivers.
      For example, \texttt{IO80211Family} cannot be injected in this case.
    \item System volume alterations on operating systems with sealing, such as
      macOS~11, may result in the operating system being unbootable. Do not
      try to disable system volume encryption unless Apple Secure Boot is disabled.
    \item If the platform requires certain settings, but they were not enabled,
      because the obvious issues did not trigger before, boot failure might occur.
      Be extra careful with \texttt{IgnoreInvalidFlexRatio} or \texttt{HashServices}.
    \item Operating systems released before Apple Secure Boot landed (e.g.
      macOS~10.12 or earlier) will still boot until UEFI Secure Boot is enabled.
      This is so, because from Apple Secure Boot point they are treated as incompatible
      and are assumed to be handled by the firmware as Microsoft Windows is.
    \item On older CPUs (e.g. before Sandy Bridge) enabling Apple Secure Boot
      might cause slightly slower loading by up to 1 second.
    \item Since \texttt{Default} value will increase with time to support the latest
      major release operating system, it is not recommended to use \texttt{ApECID}
      and \texttt{Default} value together.
    \item Installing macOS with Apple Secure Boot enabled is not possible while using HFS+
      target volume. This may include HFS+ formatted drives when no spare APFS drive is available.
  \end{enumerate}

  Sometimes the already installed operating system may have outdated Apple Secure
  Boot manifests on the \texttt{Preboot} partition causing boot failure. If there is
  ``OCB: Apple Secure Boot prohibits this boot entry, enforcing!'' message,
  it is likely the case. When this happens, either reinstall the operating
  system or copy the manifests (files with \texttt{.im4m} extension, such as
  \texttt{boot.efi.j137.im4m}) from \texttt{/usr/standalone/i386} to
  \texttt{/Volumes/Preboot/<UUID>/System/Library/CoreServices}. Here \texttt{<UUID>}
  is the system volume identifier. On HFS+ installations the manifests should be
  copied to \texttt{/System/Library/CoreServices} on the system volume.

  For more details on how to configure Apple Secure Boot with UEFI Secure Boot
  refer to \hyperref[uefisecureboot]{UEFI Secure Boot} section.

\end{enumerate}

\subsection{Entry Properties}\label{miscentryprops}

\begin{enumerate}
\item
  \texttt{Arguments}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: Empty\\
  \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}\\
  \textbf{Failsafe}: Empty\\
  \textbf{Description}: Arbitrary ASCII string used to provide human readable
  reference for the entry. Whether this value is used is implementation defined.

\item
  \texttt{Enabled}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: This entry will not be listed unless set to
  \texttt{true}.

\item
  \texttt{Name}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: Empty\\
  \textbf{Description}: Human readable entry name displayed in boot picker.

\item
  \texttt{Path}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: Empty\\
  \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{OpenShell.efi}.
  \end{itemize}

\item
  \texttt{RealPath}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Pass full path to the tool when launching.

  Passing tool directory may be unsafe for tool accidentally trying to access
  files without checking their integrity and thus should generally be disabled.
  Reason to enable this property may include cases where tools cannot work
  without external files or may need them for better function (e.g.
  \texttt{memtest86} for logging and configuration or \texttt{Shell} for
  automatic script execution).

  \emph{Note}: This property is only valid for \texttt{Tools}. For \texttt{Entries}
  this property cannot be specified and is always \texttt{true}.

\item
  \texttt{TextMode}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Run the entry in text mode instead of graphics mode.

  This setting may be benefitial to some older tools that require text output.
  By default all the tools are launched in graphics mode. Read more about text
  modes in \hyperref[uefioutputprops]{Output Properties} section below.

\end{enumerate}

\section{NVRAM}\label{nvram}

\subsection{Introduction}\label{nvramintro}

Has \texttt{plist\ dict} type and allows to set volatile UEFI variables
commonly referred as NVRAM variables. Refer to \texttt{man\ nvram} for
more details. macOS extensively uses NVRAM variables for OS --- Bootloader
--- Firmware intercommunication, and thus supplying several NVRAM is
required for proper macOS functioning.

Each NVRAM variable consists of its name, value, attributes (refer to
UEFI specification), and its
\href{https://en.wikipedia.org/wiki/Universally_unique_identifier}{GUID},
representing which `section' NVRAM variable belongs to. macOS uses
several GUIDs, including but not limited to:

\begin{itemize}
\tightlist
\item
  \texttt{4D1EDE05-38C7-4A6A-9CC6-4BCCA8B38C14}
  (\texttt{APPLE\_VENDOR\_VARIABLE\_GUID})
\item
  \texttt{7C436110-AB2A-4BBB-A880-FE41995C9F82}
  (\texttt{APPLE\_BOOT\_VARIABLE\_GUID})
\item
  \texttt{8BE4DF61-93CA-11D2-AA0D-00E098032B8C}
  (\texttt{EFI\_GLOBAL\_VARIABLE\_GUID})
\item
  \texttt{4D1FDA02-38C7-4A6A-9CC6-4BCCA8B30102}
  (\texttt{OC\_VENDOR\_VARIABLE\_GUID})
\end{itemize}

\emph{Note}: Some of the variables may be added by
\hyperref[platforminfonvram]{PlatformNVRAM} or
\hyperref[platforminfogeneric]{Generic} subsections of
\hyperref[platforminfo]{PlatformInfo} section.
Please ensure that variables of this section never collide with them,
as behaviour is undefined otherwise.

For proper macOS functioning it is often required to use \texttt{OC\_FIRMWARE\_RUNTIME}
protocol implementation currently offered as a part of \texttt{OpenRuntime} driver.
While it brings any benefits, there are certain limitations which arise depending on the
use.

\begin{enumerate}
\item Not all tools may be aware of protected namespaces.\\
  When \texttt{RequestBootVarRouting} is used \texttt{Boot}-prefixed variable access
  is restricted and protected in a separate namespace. To access the original variables
  tools have to be aware of \texttt{OC\_FIRMWARE\_RUNTIME} logic.
\end{enumerate}

\subsection{Properties}\label{nvramprops}

\begin{enumerate}
\item
  \texttt{Add}\\
  \textbf{Type}: \texttt{plist\ dict}\\
  \textbf{Description}: Sets NVRAM variables from a map (\texttt{plist\ dict})
  of GUIDs to a map (\texttt{plist\ dict}) of variable names and their values
  in \texttt{plist\ metadata} format. GUIDs must be provided in canonic string
  format in upper or lower case (e.g. \texttt{8BE4DF61-93CA-11D2-AA0D-00E098032B8C}).

  Created variables get \texttt{EFI\_VARIABLE\_BOOTSERVICE\_ACCESS} and
  \texttt{EFI\_VARIABLE\_RUNTIME\_ACCESS} attributes set.
  Variables will only be set if not present or deleted. I.e. to overwrite
  an existing variable value add the variable name to the \texttt{Delete} section.
  This approach enables to provide default values till the operating system
  takes the lead.

  \emph{Note}: If \texttt{plist\ key} does not conform to GUID format,
  behaviour is undefined.

\item
  \texttt{Delete}\\
  \textbf{Type}: \texttt{plist\ dict}\\
  \textbf{Description}: Removes NVRAM variables from a map (\texttt{plist\ dict})
  of GUIDs to an array (\texttt{plist\ array}) of variable names in
  \texttt{plist\ string} format.

\item
  \texttt{LegacyEnable}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Enables loading of NVRAM variable file named \texttt{nvram.plist}
  from EFI volume root.

  This file must have root \texttt{plist\ dictionary} type and contain two fields:
  \begin{itemize}
  \tightlist
  \item \texttt{Version} --- \texttt{plist\ integer}, file version, must be set to 1.
  \item \texttt{Add} --- \texttt{plist\ dictionary}, equivalent to \texttt{Add} from
  \texttt{config.plist}.
  \end{itemize}

  Variable loading happens prior to \texttt{Delete} (and \texttt{Add}) phases. Unless
  \texttt{LegacyOverwrite} is enabled, it 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. 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
  firmware variable services. Use it only when no hardware NVRAM implementation is provided
  by the firmware or it is incompatible.

\item
  \texttt{LegacyOverwrite}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Permits overwriting firmware variables from \texttt{nvram.plist}.

  \emph{Note}: Only variables accessible from the operating system will be overwritten.

\item
  \texttt{LegacySchema}\\
  \textbf{Type}: \texttt{plist\ dict}\\
  \textbf{Description}: Allows setting select NVRAM variables from a map
  (\texttt{plist\ dict}) of GUIDs to an array (\texttt{plist\ array}) of
  variable names in \texttt{plist\ string} format.

  \texttt{*} value can be used to accept all variables for select GUID.

  \textbf{WARNING}: Choose variables very carefully, as nvram.plist is not vaulted.
  For instance, do not put \texttt{boot-args} or \texttt{csr-active-config}, as
  this can bypass SIP.

\item
  \texttt{WriteFlash}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Enables writing to flash memory for all added variables.

  \emph{Note}: It is recommended to have this value enabled on most types of firmware but it is
  left configurable for firmware that may have issues with NVRAM variable storage
  garbage collection or similar.

\end{enumerate}

To read NVRAM variable value from macOS, \texttt{nvram} could be used
by concatenating GUID and name variables separated by a \texttt{:} symbol.
For example, \texttt{nvram 7C436110-AB2A-4BBB-A880-FE41995C9F82:boot-args}.

A continuously updated variable list can be found in a corresponding document:
\href{https://docs.google.com/spreadsheets/d/1HTCBwfOBkXsHiK7os3b2CUc6k68axdJYdGl-TyXqLu0}{NVRAM Variables}.

\subsection{Mandatory Variables}\label{nvramvars}

\textbf{Warning}: These variables may be added by
\hyperref[platforminfonvram]{PlatformNVRAM} or
\hyperref[platforminfogeneric]{Generic} subsections of
\hyperref[platforminfo]{PlatformInfo} section.
Using \texttt{PlatformInfo} is the recommended way of setting these variables.

The following variables are mandatory for macOS functioning:

\begin{itemize}
\tightlist
\item
  \texttt{4D1EDE05-38C7-4A6A-9CC6-4BCCA8B38C14:FirmwareFeatures}
  \break
  32-bit \texttt{FirmwareFeatures}. Present on all Macs to avoid extra parsing of SMBIOS tables.
\item
  \texttt{4D1EDE05-38C7-4A6A-9CC6-4BCCA8B38C14:FirmwareFeaturesMask}
  \break
  32-bit \texttt{FirmwareFeaturesMask}. Present on all Macs to avoid extra parsing
  of SMBIOS tables.
\item
  \texttt{4D1EDE05-38C7-4A6A-9CC6-4BCCA8B38C14:MLB}
  \break
  \texttt{BoardSerialNumber}. Present on newer Macs (2013+ at least) to avoid extra parsing
  of SMBIOS tables, especially in \texttt{boot.efi}.
\item
  \texttt{4D1EDE05-38C7-4A6A-9CC6-4BCCA8B38C14:ROM}
  \break
  Primary network adapter MAC address or replacement value. Present on newer Macs
  (2013+ at least) to avoid accessing special memory region, especially in \texttt{boot.efi}.
\end{itemize}

\subsection{Recommended Variables}\label{nvramvarsrec}

The following variables are recommended for faster startup or other
improvements:

\begin{itemize}
\tightlist
\item
  \texttt{7C436110-AB2A-4BBB-A880-FE41995C9F82:csr-active-config}
  \break
  32-bit System Integrity Protection bitmask. Declared in XNU source code in
  \href{https://opensource.apple.com/source/xnu/xnu-4570.71.2/bsd/sys/csr.h.auto.html}{csr.h}.
\item
  \texttt{4D1EDE05-38C7-4A6A-9CC6-4BCCA8B38C14:ExtendedFirmwareFeatures}
  \break
  Combined \texttt{FirmwareFeatures} and \texttt{ExtendedFirmwareFeatures}. Present on
  newer Macs to avoid extra parsing of SMBIOS tables.
\item
  \texttt{4D1EDE05-38C7-4A6A-9CC6-4BCCA8B38C14:ExtendedFirmwareFeaturesMask}
  \break
  Combined \texttt{FirmwareFeaturesMask} and \texttt{ExtendedFirmwareFeaturesMask}.
  Present on newer Macs to avoid extra parsing of SMBIOS tables.
\item
  \texttt{4D1EDE05-38C7-4A6A-9CC6-4BCCA8B38C14:HW\_BID}
  \break
  Hardware \texttt{BoardProduct} (e.g. \texttt{Mac-35C1E88140C3E6CF}). Not present on
  real Macs, but used to avoid extra parsing of SMBIOS tables, especially in \texttt{boot.efi}.
\item
  \texttt{4D1EDE05-38C7-4A6A-9CC6-4BCCA8B38C14:HW\_MLB}
  \break
  Hardware \texttt{BoardSerialNumber}. Override for MLB. Present on newer Macs (2013+ at least).
\item
  \texttt{4D1EDE05-38C7-4A6A-9CC6-4BCCA8B38C14:HW\_ROM}
  \break
  Hardware ROM. Override for ROM. Present on newer Macs (2013+ at least).
\item
  \texttt{7C436110-AB2A-4BBB-A880-FE41995C9F82:prev-lang:kbd}
  \break
  ASCII string defining default keyboard layout. Format is \texttt{lang-COUNTRY:keyboard},
  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/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 10.14 is needed.
\item
  \texttt{7C436110-AB2A-4BBB-A880-FE41995C9F82:security-mode}
  \break
  ASCII string defining FireWire security mode. Legacy, can be found in IOFireWireFamily
  source code in
  \href{https://opensource.apple.com/source/IOFireWireFamily/IOFireWireFamily-473/IOFireWireFamily.kmodproj/IOFireWireController.cpp.auto.html}{IOFireWireController.cpp}.
  It is recommended not to set this variable, which may speedup system startup. Setting to
  \texttt{full} is equivalent to not setting the variable and \texttt{none} disables
  FireWire security.
 \item
  \texttt{4D1EDE05-38C7-4A6A-9CC6-4BCCA8B38C14:UIScale}
  \break
  One-byte data defining \texttt{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{BGRA} data defining \texttt{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}

The following variables may be useful for certain configurations or
troubleshooting:

\begin{itemize}
\tightlist
\item
  \texttt{7C436110-AB2A-4BBB-A880-FE41995C9F82:boot-args}
  \break
  Kernel arguments, used to pass configuration to Apple kernel and drivers.
  There are many arguments, which may be found by looking for the use of
  \texttt{PE\_parse\_boot\_argn} function in the kernel or driver code.
  Some of the known boot arguments include:

  \begin{itemize}
  \item \texttt{acpi\_layer=0xFFFFFFFF}
  \item \texttt{acpi\_level=0xFFFF5F} (implies
    \href{https://github.com/acpica/acpica/blob/master/source/include/acoutput.h}
    {\texttt{ACPI\_ALL\_COMPONENTS}})
  \item \texttt{arch=i386} (force kernel architecture to \texttt{i386}, see \texttt{KernelArch})
  \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{ioaccel\_debug=VALUE} (\texttt{IOAccelerator} debug mask)
  \item \texttt{keepsyms=1} (show panic log debug symbols)
  \item \texttt{kextlog=VALUE} (kernel extension loading debug mask)
  \item \texttt{nvram-log=1} (enables AppleEFINVRAM logs)
  \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} (disable lapic spurious interrupt panic on AP cores)
  \item \texttt{panic\_on\_display\_hang=1} (trigger panic on display hang)
  \item \texttt{panic\_on\_gpu\_hang=1} (trigger panic on GPU hang)
  \item \texttt{slide=VALUE} (manually set KASLR slide)
  \item \texttt{smcdebug=VALUE} (\texttt{AppleSMC} debug mask)
  \item \texttt{spin\_wait\_for\_gpu=1} (reduces GPU timeout on high load)
  \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} (disable model checking on 10.7+)
  \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
  Booter arguments, similar to \texttt{boot-args} but for \texttt{boot.efi}. Accepts a set of
  arguments, which are hexadecimal 64-bit values with or without \texttt{0x}.
  At different stages \texttt{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}
  \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/OpenCorePkg/blob/master/Include/Apple/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{2} --- 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} --- 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}  --- 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 see verbose output from \texttt{boot.efi} on modern macOS versions
  enable \texttt{AppleDebug} option. This will save the log to general OpenCore log.
  For versions before 10.15.4 set \texttt{bootercfg} to \texttt{log=1}. This will
  print verbose output onscreen.
\item \texttt{7C436110-AB2A-4BBB-A880-FE41995C9F82:bootercfg-once}
  \break
  Booter arguments override removed after first launch. Otherwise equivalent to \texttt{bootercfg}.
\item
  \texttt{7C436110-AB2A-4BBB-A880-FE41995C9F82:efiboot-perf-record}
  \break
  Enable performance log saving in \texttt{boot.efi}. Performance log is saved to physical
  memory and is pointed by \texttt{efiboot-perf-record-data} and \texttt{efiboot-perf-record-size}
  variables. Starting from 10.15.4 it can also be saved to OpenCore log by \texttt{AppleDebug} option.
\item
  \texttt{7C436110-AB2A-4BBB-A880-FE41995C9F82:fmm-computer-name}
  \break
  Current saved host name. ASCII string.
\item
  \texttt{7C436110-AB2A-4BBB-A880-FE41995C9F82:nvda\_drv}
  \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:run-efi-updater}
  \break
  Override EFI firmware updating support in macOS (MultiUpdater, ThorUtil, and so on).
  Setting this to \texttt{No} or alternative boolean-castable value will prevent
  any firmware updates in macOS starting with 10.10 at least.
\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.
\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}

Platform information is comprised of several identification fields
generated or filled manually to be compatible with macOS services. The
base part of the configuration may be obtained from
\href{https://github.com/acidanthera/OpenCorePkg/blob/master/AppleModels}{\texttt{AppleModels}},
which itself generates a set of interfaces based on a database
in \href{https://yaml.org/spec/1.2/spec.html}{YAML} format. These fields
are written to three select destinations:

\begin{itemize}
\tightlist
\item
  \href{https://www.dmtf.org/standards/smbios}{SMBIOS}
\item
  \href{https://github.com/acidanthera/OpenCorePkg/blob/master/Include/Intel/Protocol/DataHub.h}{Data
  Hub}
\item
  NVRAM
\end{itemize}

Most of the fields specify the overrides in SMBIOS, and their field
names conform to EDK2
\href{https://github.com/acidanthera/audk/blob/master/MdePkg/Include/IndustryStandard/SmBios.h}{SmBios.h}
header file. However, several important fields reside in Data Hub and
NVRAM. Some of the values can be found in more than one field and/or
destination, so there are two ways to control their update process:
manual, where all the values are specified (the default), and semi-automatic,
where (\texttt{Automatic}) only select values are specified, and later used
for system configuration.

To inspect SMBIOS contents \href{http://www.nongnu.org/dmidecode}{dmidecode} utility can
be used. Version with macOS specific enhancements can be downloaded from
\href{https://github.com/acidanthera/dmidecode/releases}{Acidanthera/dmidecode}.

\subsection{Properties}\label{platforminfoprops}

\begin{enumerate}
\item
  \texttt{Automatic}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Generate PlatformInfo based on \texttt{Generic}
  section instead of using values from \texttt{DataHub}, \texttt{NVRAM},
  and \texttt{SMBIOS} sections.

  Enabling this option is useful when \texttt{Generic} section is flexible
  enough:
  \begin{itemize}
  \tightlist
  \item When enabled \texttt{SMBIOS}, \texttt{DataHub}, and
  \texttt{PlatformNVRAM} data is unused.
  \item When disabled \texttt{Generic} section is unused.
  \end{itemize}

  \textbf{Warning}: It is strongly discouraged set this option to \texttt{false}
  when intending to update platform information. The only reason to do that is
  when doing minor correction of the SMBIOS present and similar. In all other
  cases not using \texttt{Automatic} may lead to hard to debug errors.

\item
  \texttt{CustomMemory}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Use custom memory configuration defined in the
  \texttt{Memory} section. This completely replaces any existing memory
  configuration in SMBIOS, and is only active when \texttt{UpdateSMBIOS}
  is set to \texttt{true}.

\item
  \texttt{UpdateDataHub}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Update Data Hub fields. These fields are read
  from \texttt{Generic} or \texttt{DataHub} sections depending on
  \texttt{Automatic} value.

  \emph{Note}: The implementation of the Data Hub protocol in EFI firmware on
  essentially all systems, including Apple hardware, means that existing Data Hub
  entries cannot be overridden, while new entries are added to the end with
  macOS ignoring them. You can work around this by reinstalling the Data Hub
  protocol using the \texttt{ProtocolOverrides} section. Refer to the \texttt{DataHub}
  protocol override description for details.
\item
  \texttt{UpdateNVRAM}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Update NVRAM fields related to platform information.

  These fields are read from \texttt{Generic} or \texttt{PlatformNVRAM} sections
  depending on \texttt{Automatic} value. All the other fields are
  to be specified with \texttt{NVRAM} section.

  If \texttt{UpdateNVRAM} is set to \texttt{false} the aforementioned
  variables can be updated with \hyperref[nvram]{\texttt{NVRAM}}
  section. If \texttt{UpdateNVRAM} is set to \texttt{true} the behaviour is
  undefined when any of the fields are present in \texttt{NVRAM} section.
\item
  \texttt{UpdateSMBIOS}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Update SMBIOS fields. These fields are read from
  \texttt{Generic} or \texttt{SMBIOS} sections depending on
  \texttt{Automatic} value.
\item
  \texttt{UpdateSMBIOSMode}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: \texttt{Create}\\
  \textbf{Description}: Update SMBIOS fields approach:

  \begin{itemize}
  \tightlist
  \item
    \texttt{TryOverwrite} --- \texttt{Overwrite} if new size is \textless{}= than
    the page-aligned original and there are no issues with legacy region
    unlock. \texttt{Create} otherwise. Has issues on some types of firmware.
  \item
    \texttt{Create} --- Replace the tables with newly allocated
    EfiReservedMemoryType at AllocateMaxAddress without any fallbacks.
  \item
    \texttt{Overwrite} --- Overwrite existing gEfiSmbiosTableGuid and
    gEfiSmbiosTable3Guid data if it fits new size. Abort with
    unspecified state otherwise.
  \item
    \texttt{Custom} --- Write SMBIOS tables
    (\texttt{gEfiSmbios(3)TableGuid}) to \texttt{gOcCustomSmbios(3)TableGuid}
    to workaround firmware overwriting SMBIOS contents at
    ExitBootServices. Otherwise equivalent to \texttt{Create}. Requires
    patching AppleSmbios.kext and AppleACPIPlatform.kext to read from
    another GUID: \texttt{"EB9D2D31"} - \texttt{"EB9D2D35"} (in ASCII),
    done automatically by \texttt{CustomSMBIOSGuid} quirk.
  \end{itemize}

  \emph{Note}: A side effect of using \texttt{Custom} approach is making
  SMBIOS updates exclusive to macOS, avoiding a collision with existing
  Windows activation and custom OEM software but potentially breaking
  Apple-specific tools.
\item
  \texttt{UseRawUuidEncoding}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Use raw encoding for SMBIOS UUIDs.

  Each UUID \texttt{AABBCCDD-EEFF-GGHH-IIJJ-KKLLMMNNOOPP} is
  essentially a hexadecimal 16-byte number. It can be encoded
  in two ways:

  \begin{itemize}
    \tightlist
    \item \texttt{Big Endian} --- by writing all the bytes as they are without making
      any order changes (\texttt{\{AA BB CC DD EE FF GG HH II JJ KK LL MM NN OO PP\}}).
      This method is also known as \href{https://tools.ietf.org/html/rfc4122}{RFC 4122}
      encoding or \texttt{Raw} encoding.
    \item \texttt{Little Endian} --- by interpreting the bytes as numbers and using
      Little Endian byte representation
      (\texttt{\{DD CC BB AA FF EE HH GG II JJ KK LL MM NN OO PP\}}).
  \end{itemize}

  SMBIOS specification did not explicitly specify the encoding format for the
  UUID up to SMBIOS 2.6, where it stated that \texttt{Little Endian} encoding
  shall be used. This led to the confusion in both firmware implementations
  and system software as different vendors used different encodings prior to that.

  \begin{itemize}
    \tightlist
    \item Apple uses \texttt{Big Endian} format everywhere but it ignores SMBIOS UUID within macOS.
    \item \texttt{dmidecode} uses \texttt{Big Endian} format for SMBIOS 2.5.x or lower
    and \texttt{Little Endian} for 2.6 and newer. Acidanthera
    \href{https://github.com/acidanthera/dmidecode}{dmidecode} prints all the three.
    \item Windows uses \texttt{Little Endian} format everywhere, but it only affects
    the visual representation of the values.
  \end{itemize}

  OpenCore always sets a recent SMBIOS version (currently 3.2) when generating
  the modified DMI tables. If \texttt{UseRawUuidEncoding} is enabled, then \texttt{Big Endian}
  format is used to store the \texttt{SystemUUID} data. Otherwise
  \texttt{Little Endian} is used.

  \emph{Note}: Since UUIDs used in DataHub and NVRAM are not standardised
  and are added by Apple, this preference does not affect them. Unlike
  SMBIOS they are always stored in the \texttt{Big Endian} format.

\item
  \texttt{Generic}\\
  \textbf{Type}: \texttt{plist\ dictionary}\\
  \textbf{Description}: Update all fields in \texttt{Automatic} mode.

  \emph{Note}: This section is ignored but may not be removed when
  \texttt{Automatic} is \texttt{false}.
\item
  \texttt{DataHub}\\
  \textbf{Type}: \texttt{plist\ dictionary}\\
  \textbf{Description}: Update Data Hub fields in non-\texttt{Automatic} mode.

  \emph{Note}: This section is ignored and may be removed when
  \texttt{Automatic} is \texttt{true}.
\item
  \texttt{Memory}\\
  \textbf{Type}: \texttt{plist\ dictionary}\\
  \textbf{Description}: Define custom memory configuration.

  \emph{Note}: This section is ignored and may be removed when
  \texttt{CustomMemory} is \texttt{false}.
\item
  \texttt{PlatformNVRAM}\\
  \textbf{Type}: \texttt{plist\ dictionary}\\
  \textbf{Description}: Update platform NVRAM fields in non-\texttt{Automatic} mode.

  \emph{Note}: This section is ignored and may be removed when
  \texttt{Automatic} is \texttt{true}.
\item
  \texttt{SMBIOS}\\
  \textbf{Type}: \texttt{plist\ dictionary}\\
  \textbf{Description}: Update SMBIOS fields in non-\texttt{Automatic} mode.

  \emph{Note}: This section is ignored and may be removed when
  \texttt{Automatic} is \texttt{true}.
\end{enumerate}

\subsection{Generic Properties}\label{platforminfogeneric}

\begin{enumerate}
\item
  \texttt{SpoofVendor}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Sets SMBIOS vendor fields to \texttt{Acidanthera}.

  It is dangerous to use Apple in SMBIOS vendor fields for reasons given
  in \texttt{SystemManufacturer} description. However, certain firmware
  may not provide valid values otherwise, which could break some software.

\item
  \texttt{AdviseWindows}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Forces Windows support in \texttt{FirmwareFeatures}.

  Added bits to \texttt{FirmwareFeatures}:

  \begin{itemize}
    \item \texttt{FW\_FEATURE\_SUPPORTS\_CSM\_LEGACY\_MODE} (\texttt{0x1})
    - Without this bit it is not possible to reboot to Windows installed on
      a drive with EFI partition being not the first partition on the disk.
    \item \texttt{FW\_FEATURE\_SUPPORTS\_UEFI\_WINDOWS\_BOOT} (\texttt{0x20000000})
    - Without this bit it is not possible to reboot to Windows installed on
      a drive with EFI partition being the first partition on the disk.
  \end{itemize}

\item
  \texttt{MaxBIOSVersion}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Sets \texttt{BIOSVersion} to \texttt{9999.999.999.999.999}, recommended for legacy
  Macs when using \texttt{Automatic} PlatformInfo to avoid BIOS updates in unofficially supported macOS
  versions.

\item
  \texttt{SystemMemoryStatus}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: \texttt{Auto}\\
  \textbf{Description}: Indicates whether system memory is upgradable in \texttt{PlatformFeature}.
  This controls the visibility of the Memory tab in About This Mac.

  Valid values:

  \begin{itemize}
    \tightlist
    \item \texttt{Auto} --- use the original \texttt{PlatformFeature} value.
    \item \texttt{Upgradable} --- explicitly unset \texttt{PT\_FEATURE\_HAS\_SOLDERED\_SYSTEM\_MEMORY}
    (\texttt{0x2}) in \texttt{PlatformFeature}.
    \item \texttt{Soldered} --- explicitly set \texttt{PT\_FEATURE\_HAS\_SOLDERED\_SYSTEM\_MEMORY}
    (\texttt{0x2}) in \texttt{PlatformFeature}.
  \end{itemize}

  \emph{Note}: On certain Mac models (namely \texttt{MacBookPro10,x} and any \texttt{MacBookAir}),
  SPMemoryReporter.spreporter will ignore \texttt{PT\_FEATURE\_HAS\_SOLDERED\_SYSTEM\_MEMORY}
  and assume that system memory is non-upgradable.

\item
  \texttt{ProcessorType}\\
  \textbf{Type}: \texttt{plist\ integer}\\
  \textbf{Failsafe}: \texttt{0} (Automatic)\\
  \textbf{Description}: Refer to SMBIOS \texttt{ProcessorType}.
\item
  \texttt{SystemProductName}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: Empty (OEM specified or not installed)\\
  \textbf{Description}: Refer to SMBIOS \texttt{SystemProductName}.
\item
  \texttt{SystemSerialNumber}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: Empty (OEM specified or not installed)\\
  \textbf{Description}: Refer to SMBIOS \texttt{SystemSerialNumber}.

  Specify special string value \texttt{OEM} to extract current value from SMBIOS
  and use it throughout the sections. This feature can only be
  used on Mac-compatible firmwares.
\item
  \texttt{SystemUUID}\\
  \textbf{Type}: \texttt{plist\ string}, GUID\\
  \textbf{Failsafe}: Empty (OEM specified or not installed)\\
  \textbf{Description}: Refer to SMBIOS \texttt{SystemUUID}.

  Specify special string value \texttt{OEM} to extract current value from SMBIOS
  and use it throughout the sections. Since not all firmwares
  have valid (and unique) values, this feature is not applicable
  to some setups, and may provide unexpected results. It is highly
  recommended to specify the UUID explicitly. Refer to
  \texttt{UseRawUuidEncoding} to determine how SMBIOS value is parsed.
\item
  \texttt{MLB}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: Empty (OEM specified or not installed)\\
  \textbf{Description}: Refer to SMBIOS \texttt{BoardSerialNumber}.

  Specify special string value \texttt{OEM} to extract current value from NVRAM
  (\texttt{MLB} variable) or SMBIOS and use it throughout the sections.
  This feature can only be used on Mac-compatible firmwares.
\item
  \texttt{ROM}\\
  \textbf{Type}: \texttt{plist\ metadata}, 6 bytes\\
  \textbf{Failsafe}: Empty (OEM specified or not installed)\\
  \textbf{Description}: Refer to
  \texttt{4D1EDE05-38C7-4A6A-9CC6-4BCCA8B38C14:ROM}.

  Specify special string value \texttt{OEM} to extract current value from NVRAM
  (\texttt{ROM} variable) and use it throughout the sections.
  This feature can only be used on Mac-compatible firmwares.

\end{enumerate}

\subsection{DataHub Properties}\label{platforminfodatahub}

\begin{enumerate}
\item
  \texttt{PlatformName}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: Empty (Not installed)\\
  \textbf{Description}: Sets \texttt{name} in
  \texttt{gEfiMiscSubClassGuid}. Value found on Macs is
  \texttt{platform} in ASCII.
\item
  \texttt{SystemProductName}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: Empty (Not installed)\\
  \textbf{Description}: Sets \texttt{Model} in
  \texttt{gEfiMiscSubClassGuid}. Value found on Macs is equal to SMBIOS
  \texttt{SystemProductName} in Unicode.
\item
  \texttt{SystemSerialNumber}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: Empty (Not installed)\\
  \textbf{Description}: Sets \texttt{SystemSerialNumber} in
  \texttt{gEfiMiscSubClassGuid}. Value found on Macs is equal to SMBIOS
  \texttt{SystemSerialNumber} in Unicode.
\item
  \texttt{SystemUUID}\\
  \textbf{Type}: \texttt{plist\ string}, GUID\\
  \textbf{Failsafe}: Empty (Not installed)\\
  \textbf{Description}: Sets \texttt{system-id} in
  \texttt{gEfiMiscSubClassGuid}. Value found on Macs is equal to SMBIOS
  \texttt{SystemUUID} (with swapped byte order).
\item
  \texttt{BoardProduct}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: Empty (Not installed)\\
  \textbf{Description}: Sets \texttt{board-id} in
  \texttt{gEfiMiscSubClassGuid}. Value found on Macs is equal to SMBIOS
  \texttt{BoardProduct} in ASCII.
\item
  \texttt{BoardRevision}\\
  \textbf{Type}: \texttt{plist\ data}, 1 byte\\
  \textbf{Failsafe}: \texttt{0}\\
  \textbf{Description}: Sets \texttt{board-rev} in
  \texttt{gEfiMiscSubClassGuid}. Value found on Macs seems to correspond
  to internal board revision (e.g. \texttt{01}).
\item
  \texttt{StartupPowerEvents}\\
  \textbf{Type}: \texttt{plist\ integer}, 64-bit\\
  \textbf{Failsafe}: \texttt{0}\\
  \textbf{Description}: Sets \texttt{StartupPowerEvents} in
  \texttt{gEfiMiscSubClassGuid}. Value found on Macs is power management
  state bitmask, normally 0. Known bits read by
  \texttt{X86PlatformPlugin.kext}:

  \begin{itemize}
  \tightlist
  \item
    \texttt{0x00000001} --- Shutdown cause was a \texttt{PWROK} event
    (Same as \texttt{GEN\_PMCON\_2} bit 0)
  \item
    \texttt{0x00000002} --- Shutdown cause was a \texttt{SYS\_PWROK}
    event (Same as \texttt{GEN\_PMCON\_2} bit 1)
  \item
    \texttt{0x00000004} --- Shutdown cause was a \texttt{THRMTRIP\#}
    event (Same as \texttt{GEN\_PMCON\_2} bit 3)
  \item
    \texttt{0x00000008} --- Rebooted due to a SYS\_RESET\# event (Same
    as \texttt{GEN\_PMCON\_2} bit 4)
  \item
    \texttt{0x00000010} --- Power Failure (Same as
    \texttt{GEN\_PMCON\_3} bit 1 \texttt{PWR\_FLR})
  \item
    \texttt{0x00000020} --- Loss of RTC Well Power (Same as
    \texttt{GEN\_PMCON\_3} bit 2 \texttt{RTC\_PWR\_STS})
  \item
    \texttt{0x00000040} --- General Reset Status (Same as
    \texttt{GEN\_PMCON\_3} bit 9 \texttt{GEN\_RST\_STS})
  \item
    \texttt{0xffffff80} --- SUS Well Power Loss (Same as
    \texttt{GEN\_PMCON\_3} bit 14)
  \item
    \texttt{0x00010000} --- Wake cause was a ME Wake event (Same as
    PRSTS bit 0, \texttt{ME\_WAKE\_STS})
  \item
    \texttt{0x00020000} --- Cold Reboot was ME Induced event (Same as
    \texttt{PRSTS} bit 1 \texttt{ME\_HRST\_COLD\_STS})
  \item
    \texttt{0x00040000} --- Warm Reboot was ME Induced event (Same as
    \texttt{PRSTS} bit 2 \texttt{ME\_HRST\_WARM\_STS})
  \item
    \texttt{0x00080000} --- Shutdown was ME Induced event (Same as
    \texttt{PRSTS} bit 3 \texttt{ME\_HOST\_PWRDN})
  \item
    \texttt{0x00100000} --- Global reset ME Watchdog Timer event (Same as
    \texttt{PRSTS} bit 6)
  \item
    \texttt{0x00200000} --- Global reset PowerManagement Watchdog Timer
    event (Same as \texttt{PRSTS} bit 15)
  \end{itemize}
\item
  \texttt{InitialTSC}\\
  \textbf{Type}: \texttt{plist\ integer}, 64-bit\\
  \textbf{Failsafe}: \texttt{0}\\
  \textbf{Description}: Sets \texttt{InitialTSC} in
  \texttt{gEfiProcessorSubClassGuid}. Sets initial TSC value, normally
  0.
\item
  \texttt{FSBFrequency}\\
  \textbf{Type}: \texttt{plist\ integer}, 64-bit\\
  \textbf{Failsafe}: \texttt{0} (Automatic)\\
  \textbf{Description}: Sets \texttt{FSBFrequency} in
  \texttt{gEfiProcessorSubClassGuid}.

  Sets CPU FSB frequency. This value equals to CPU nominal frequency divided
  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
  \texttt{ARTFrequency}\\
  \textbf{Type}: \texttt{plist\ integer}, 64-bit\\
  \textbf{Failsafe}: \texttt{0} (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 the 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}.
\item
  \texttt{DevicePathsSupported}\\
  \textbf{Type}: \texttt{plist\ integer}, 32-bit\\
  \textbf{Failsafe}: \texttt{0} (Not installed)\\
  \textbf{Description}: Sets \texttt{DevicePathsSupported} in
  \texttt{gEfiMiscSubClassGuid}. Must be set to \texttt{1} for
  AppleACPIPlatform.kext to append SATA device paths to
  \texttt{Boot\#\#\#\#} and \texttt{efi-boot-device-data} variables.
  Set to \texttt{1} on all modern Macs.
\item
  \texttt{SmcRevision}\\
  \textbf{Type}: \texttt{plist\ data}, 6 bytes\\
  \textbf{Failsafe}: Empty (Not installed)\\
  \textbf{Description}: Sets \texttt{REV} in
  \texttt{gEfiMiscSubClassGuid}. Custom property read by
  \texttt{VirtualSMC} or \texttt{FakeSMC} to generate SMC \texttt{REV}
  key.
\item
  \texttt{SmcBranch}\\
  \textbf{Type}: \texttt{plist\ data}, 8 bytes\\
  \textbf{Failsafe}: Empty (Not installed)\\
  \textbf{Description}: Sets \texttt{RBr} in
  \texttt{gEfiMiscSubClassGuid}. Custom property read by
  \texttt{VirtualSMC} or \texttt{FakeSMC} to generate SMC \texttt{RBr}
  key.
\item
  \texttt{SmcPlatform}\\
  \textbf{Type}: \texttt{plist\ data}, 8 bytes\\
  \textbf{Failsafe}: Empty (Not installed)\\
  \textbf{Description}: Sets \texttt{RPlt} in
  \texttt{gEfiMiscSubClassGuid}. Custom property read by
  \texttt{VirtualSMC} or \texttt{FakeSMC} to generate SMC \texttt{RPlt}
  key.
\end{enumerate}

\subsection{Memory Properties}\label{platforminfomemory}

\begin{enumerate}
\item
  \texttt{DataWidth}\\
  \textbf{Type}: \texttt{plist\ integer}, 16-bit\\
  \textbf{Failsafe}: \texttt{0xFFFF} (unknown)\\
  \textbf{SMBIOS}: Memory Device (Type 17) --- Data Width\\
  \textbf{Description}: Specifies the data width, in bits, of the
  memory. A \texttt{DataWidth} of \texttt{0} and a \texttt{TotalWidth} of \texttt{8}
  indicates that the device is being used solely to provide 8
  error-correction bits.

\item
  \texttt{Devices}\\
  \textbf{Type}: \texttt{plist\ array}\\
  \textbf{Failsafe}: Empty\\
  \textbf{Description}: Specifies the custom memory devices to be added.

  Designed to be filled with \texttt{plist\ dictionary} values, describing each
  memory device. See \hyperref[platforminfomemorydevice]{Memory Devices Properties}
  section below. This should include all memory slots, even if unpopulated.

\item
  \texttt{ErrorCorrection}\\
  \textbf{Type}: \texttt{plist\ integer}, 8-bit\\
  \textbf{Failsafe}: \texttt{0x03}\\
  \textbf{SMBIOS}: Physical Memory Array (Type 16) --- Memory Error Correction\\
  \textbf{Description}: Specifies the primary hardware error correction or
  detection method supported by the memory.

  \begin{itemize}
  \tightlist
  \item
    \texttt{0x01} --- Other
  \item
    \texttt{0x02} --- Unknown
  \item
    \texttt{0x03} --- None
  \item
    \texttt{0x04} --- Parity
  \item
    \texttt{0x05} --- Single-bit ECC
  \item
    \texttt{0x06} --- Multi-bit ECC
  \item
    \texttt{0x07} --- CRC
  \end{itemize}

\item
  \texttt{FormFactor}\\
  \textbf{Type}: \texttt{plist\ integer}, 8-bit\\
  \textbf{Failsafe}: \texttt{0x02}\\
  \textbf{SMBIOS}: Memory Device (Type 17) --- Form Factor\\
  \textbf{Description}: Specifies the form factor of the memory.
  On Macs this should usually be DIMM or SODIMM. Commonly used form
  factors are listed below.

  When \texttt{CustomMemory} is \texttt{false}, this value is automatically set
  based on Mac product name.

  \begin{itemize}
  \tightlist
  \item
    \texttt{0x01} --- Other
  \item
    \texttt{0x02} --- Unknown
  \item
    \texttt{0x09} --- DIMM
  \item
    \texttt{0x0D} --- SODIMM
  \item
    \texttt{0x0F} --- FB-DIMM
  \end{itemize}

\item
  \texttt{MaxCapacity}\\
  \textbf{Type}: \texttt{plist\ integer}, 64-bit\\
  \textbf{Failsafe}: \texttt{0}\\
  \textbf{SMBIOS}: Physical Memory Array (Type 16) --- Maximum Capacity\\
  \textbf{Description}: Specifies the maximum amount of memory, in bytes,
  supported by the system.

\item
  \texttt{TotalWidth}\\
  \textbf{Type}: \texttt{plist\ integer}, 16-bit\\
  \textbf{Failsafe}: \texttt{0xFFFF} (unknown)\\
  \textbf{SMBIOS}: Memory Device (Type 17) --- Total Width\\
  \textbf{Description}: Specifies the total width, in bits, of the
  memory, including any check or error-correction bits. If there are
  no error-correction bits, this value should be equal to \texttt{DataWidth}.

\item
  \texttt{Type}\\
  \textbf{Type}: \texttt{plist\ integer}, 8-bit\\
  \textbf{Failsafe}: \texttt{0x02}\\
  \textbf{SMBIOS}: Memory Device (Type 17) --- Memory Type\\
  \textbf{Description}: Specifies the memory type. Commonly used types are listed below.

  \begin{itemize}
  \tightlist
  \item
    \texttt{0x01} --- Other
  \item
    \texttt{0x02} --- Unknown
  \item
    \texttt{0x0F} --- SDRAM
  \item
    \texttt{0x12} --- DDR
  \item
    \texttt{0x13} --- DDR2
  \item
    \texttt{0x14} --- DDR2 FB-DIMM
  \item
    \texttt{0x18} --- DDR3
  \item
    \texttt{0x1A} --- DDR4
  \item
    \texttt{0x1B} --- LPDDR
  \item
    \texttt{0x1C} --- LPDDR2
  \item
    \texttt{0x1D} --- LPDDR3
  \item
    \texttt{0x1E} --- LPDDR4
  \end{itemize}

\item
  \texttt{TypeDetail}\\
  \textbf{Type}: \texttt{plist\ integer}, 16-bit\\
  \textbf{Failsafe}: \texttt{0x4}\\
  \textbf{SMBIOS}: Memory Device (Type 17) --- Type Detail\\
  \textbf{Description}: Specifies additional memory type information.

  \begin{itemize}
  \tightlist
  \item
    \texttt{Bit 0} --- Reserved, set to 0
  \item
    \texttt{Bit 1} --- Other
  \item
    \texttt{Bit 2} --- Unknown
  \item
    \texttt{Bit 7} --- Synchronous
  \item
    \texttt{Bit 13} --- Registered (buffered)
  \item
    \texttt{Bit 14} --- Unbuffered (unregistered)
  \end{itemize}

\end{enumerate}

\subsubsection{Memory Device Properties}\label{platforminfomemorydevice}

\begin{enumerate}
\item
  \texttt{AssetTag}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: \texttt{Unknown}\\
  \textbf{SMBIOS}: Memory Device (Type 17) --- Asset Tag\\
  \textbf{Description}: Specifies the asset tag of this memory device.

\item
  \texttt{BankLocator}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: \texttt{Unknown}\\
  \textbf{SMBIOS}: Memory Device (Type 17) --- Bank Locator\\
  \textbf{Description}: Specifies the physically labeled bank where the
  memory device is located.

\item
  \texttt{DeviceLocator}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: \texttt{Unknown}\\
  \textbf{SMBIOS}: Memory Device (Type 17) --- Device Locator\\
  \textbf{Description}: Specifies the physically-labeled socket or
  board position where the memory device is located.

\item
  \texttt{Manufacturer}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: \texttt{Unknown}\\
  \textbf{SMBIOS}: Memory Device (Type 17) --- Manufacturer\\
  \textbf{Description}: Specifies the manufacturer of this memory device.

\item
  \texttt{PartNumber}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: \texttt{Unknown}\\
  \textbf{SMBIOS}: Memory Device (Type 17) --- Part Number\\
  \textbf{Description}: Specifies the part number of this memory device.

\item
  \texttt{SerialNumber}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: \texttt{Unknown}\\
  \textbf{SMBIOS}: Memory Device (Type 17) --- Serial Number\\
  \textbf{Description}: Specifies the serial number of this memory device.

\item
  \texttt{Size}\\
  \textbf{Type}: \texttt{plist\ integer}, 32-bit\\
  \textbf{Failsafe}: \texttt{0}\\
  \textbf{SMBIOS}: Memory Device (Type 17) --- Size\\
  \textbf{Description}: Specifies the size of the memory device, in megabytes.
  \texttt{0} indicates this slot is not populated.

\item
  \texttt{Speed}\\
  \textbf{Type}: \texttt{plist\ integer}, 16-bit\\
  \textbf{Failsafe}: \texttt{0}\\
  \textbf{SMBIOS}: Memory Device (Type 17) --- Speed\\
  \textbf{Description}: Specifies the maximum capable speed of the device,
  in megatransfers per second (MT/s). \texttt{0} indicates an unknown speed.

\end{enumerate}

\subsection{PlatformNVRAM Properties}\label{platforminfonvram}

\begin{enumerate}
\item
  \texttt{BID}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: Empty (Not installed)\\
  \textbf{Description}: Specifies the value of NVRAM variable
  \texttt{4D1EDE05-38C7-4A6A-9CC6-4BCCA8B38C14:HW\_BID}.

\item
  \texttt{ROM}\\
  \textbf{Type}: \texttt{plist\ data}, 6 bytes\\
  \textbf{Failsafe}: Empty (Not installed)\\
  \textbf{Description}: Specifies the values of NVRAM variables
  \texttt{4D1EDE05-38C7-4A6A-9CC6-4BCCA8B38C14:HW\_ROM} and
  \texttt{4D1EDE05-38C7-4A6A-9CC6-4BCCA8B38C14:ROM}.

\item
  \texttt{MLB}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: Empty (Not installed)\\
  \textbf{Description}: Specifies the values of NVRAM variables
  \texttt{4D1EDE05-38C7-4A6A-9CC6-4BCCA8B38C14:HW\_MLB} and
  \texttt{4D1EDE05-38C7-4A6A-9CC6-4BCCA8B38C14:MLB}.

\item
  \texttt{FirmwareFeatures}\\
  \textbf{Type}: \texttt{plist\ data}, 8 bytes\\
  \textbf{Failsafe}: Empty (Not installed)\\
  \textbf{Description}: This variable comes in pair with \texttt{FirmwareFeaturesMask}.
  Specifies the values of NVRAM variables:
  \begin{itemize}
  \tightlist
  \item \texttt{4D1EDE05-38C7-4A6A-9CC6-4BCCA8B38C14:FirmwareFeatures}
  \item \texttt{4D1EDE05-38C7-4A6A-9CC6-4BCCA8B38C14:ExtendedFirmwareFeatures}
  \end{itemize}

\item
  \texttt{FirmwareFeaturesMask}\\
  \textbf{Type}: \texttt{plist\ data}, 8 bytes\\
  \textbf{Failsafe}: Empty (Not installed)\\
  \textbf{Description}: This variable comes in pair with \texttt{FirmwareFeatures}.
  Specifies the values of NVRAM variables:
  \begin{itemize}
  \tightlist
  \item \texttt{4D1EDE05-38C7-4A6A-9CC6-4BCCA8B38C14:FirmwareFeaturesMask}
  \item \texttt{4D1EDE05-38C7-4A6A-9CC6-4BCCA8B38C14:ExtendedFirmwareFeaturesMask}
  \end{itemize}

\item
  \texttt{SystemUUID}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: Empty (Not installed)\\
  \textbf{Description}: Specifies the value of NVRAM variable
  \texttt{4D1EDE05-38C7-4A6A-9CC6-4BCCA8B38C14:system-id}
  for boot services only. Value found on Macs is equal to SMBIOS
  \texttt{SystemUUID}.

\end{enumerate}

\subsection{SMBIOS Properties}\label{platforminfosmbios}

\begin{enumerate}
\item
  \texttt{BIOSVendor}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: Empty (OEM specified)\\
  \textbf{SMBIOS}: BIOS Information (Type 0) --- Vendor\\
  \textbf{Description}: BIOS Vendor. All rules of
  \texttt{SystemManufacturer} do apply.
\item
  \texttt{BIOSVersion}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: Empty (OEM specified)\\
  \textbf{SMBIOS}: BIOS Information (Type 0) --- BIOS Version\\
  \textbf{Description}: Firmware version. This value gets updated and
  takes part in update delivery configuration and macOS version
  compatibility. This value could look like
  \texttt{MM71.88Z.0234.B00.1809171422} in older firmware and is
  described in
  \href{https://github.com/acidanthera/OpenCorePkg/blob/master/Include/Apple/Guid/BiosId.h}{BiosId.h}.
  In newer firmware, it should look like \texttt{236.0.0.0.0} or
  \texttt{220.230.16.0.0\ (iBridge:\ 16.16.2542.0.0,0)}. iBridge version
  is read from \texttt{BridgeOSVersion} variable, and is only present on
  macs with T2.

\begin{verbatim}
Apple ROM Version
 BIOS ID:      MBP151.88Z.F000.B00.1811142212
 Model:        MBP151
 EFI Version:  220.230.16.0.0
 Built by:     root@quinoa
 Date:         Wed Nov 14 22:12:53 2018
 Revision:     220.230.16 (B&I)
 ROM Version:  F000_B00
 Build Type:   Official Build, RELEASE
 Compiler:     Apple LLVM version 10.0.0 (clang-1000.2.42)
 UUID:         E5D1475B-29FF-32BA-8552-682622BA42E1
 UUID:         151B0907-10F9-3271-87CD-4BF5DBECACF5
\end{verbatim}
\item
  \texttt{BIOSReleaseDate}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: Empty (OEM specified)\\
  \textbf{SMBIOS}: BIOS Information (Type 0) --- BIOS Release Date\\
  \textbf{Description}: Firmware release date. Similar to
  \texttt{BIOSVersion}. May look like \texttt{12/08/2017}.
\item
  \texttt{SystemManufacturer}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: Empty (OEM specified)\\
  \textbf{SMBIOS}: System Information (Type 1) --- Manufacturer\\
  \textbf{Description}: OEM manufacturer of the particular board. Use failsafe
  unless strictly required. Do not override to contain \texttt{Apple\ Inc.}
  on non-Apple hardware, as this confuses numerous services present in
  the operating system, such as firmware updates, eficheck, as well as
  kernel extensions developed in Acidanthera, such as Lilu and its
  plugins. In addition it will also make some operating systems
  such as Linux unbootable.
\item
  \texttt{SystemProductName}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: Empty (OEM specified)\\
  \textbf{SMBIOS}: System Information (Type 1), Product Name\\
  \textbf{Description}: Preferred Mac model used to mark the device as
  supported by the operating system. This value must be specified by any
  configuration for later automatic generation of the related values in
  this and other SMBIOS tables and related configuration parameters. If
  \texttt{SystemProductName} is not compatible with the target operating
  system, \texttt{-no\_compat\_check} boot argument may be used as an
  override.

  \emph{Note}: If \texttt{SystemProductName} is unknown, and related
  fields are unspecified, default values should be assumed as being set
  to \texttt{MacPro6,1} data. The list of known products can be found in
  \texttt{AppleModels}.
\item
  \texttt{SystemVersion}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: Empty (OEM specified)\\
  \textbf{SMBIOS}: System Information (Type 1) --- Version\\
  \textbf{Description}: Product iteration version number. May look like
  \texttt{1.1}.
\item
  \texttt{SystemSerialNumber}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: Empty (OEM specified)\\
  \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/OpenCorePkg/blob/master/Utilities/macserial/FORMAT.md}{macserial}.
\item
  \texttt{SystemUUID}\\
  \textbf{Type}: \texttt{plist\ string}, GUID\\
  \textbf{Failsafe}: Empty (OEM specified)\\
  \textbf{SMBIOS}: System Information (Type 1) --- UUID\\
  \textbf{Description}: A UUID is an identifier that is designed to be
  unique across both time and space. It requires no central registration
  process.
\item
  \texttt{SystemSKUNumber}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: Empty (OEM specified)\\
  \textbf{SMBIOS}: System Information (Type 1) --- SKU Number\\
  \textbf{Description}: Mac Board ID (\texttt{board-id}). May look like
  \texttt{Mac-7BA5B2D9E42DDD94} or \texttt{Mac-F221BEC8} in older
  models. Sometimes it can be just empty.
\item
  \texttt{SystemFamily}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: Empty (OEM specified)\\
  \textbf{SMBIOS}: System Information (Type 1) --- Family\\
  \textbf{Description}: Family name. May look like \texttt{iMac\ Pro}.
\item
  \texttt{BoardManufacturer}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: Empty (OEM specified)\\
  \textbf{SMBIOS}: Baseboard (or Module) Information (Type 2) -
  Manufacturer\\
  \textbf{Description}: Board manufacturer. All rules of
  \texttt{SystemManufacturer} do apply.
\item
  \texttt{BoardProduct}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: Empty (OEM specified)\\
  \textbf{SMBIOS}: Baseboard (or Module) Information (Type 2) -
  Product\\
  \textbf{Description}: Mac Board ID (\texttt{board-id}). May look like
  \texttt{Mac-7BA5B2D9E42DDD94} or \texttt{Mac-F221BEC8} in older
  models.
\item
  \texttt{BoardVersion}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: Empty (OEM specified)\\
  \textbf{SMBIOS}: Baseboard (or Module) Information (Type 2) -
  Version\\
  \textbf{Description}: Board version number. Varies, may match
  \texttt{SystemProductName} or \texttt{SystemProductVersion}.
\item
  \texttt{BoardSerialNumber}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: Empty (OEM specified)\\
  \textbf{SMBIOS}: Baseboard (or Module) Information (Type 2) --- Serial
  Number\\
  \textbf{Description}: Board serial number in defined format. Known
  formats are described in
  \href{https://github.com/acidanthera/macserial/blob/master/FORMAT.md}{macserial}.
\item
  \texttt{BoardAssetTag}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: Empty (OEM specified)\\
  \textbf{SMBIOS}: Baseboard (or Module) Information (Type 2) --- Asset
  Tag\\
  \textbf{Description}: Asset tag number. Varies, may be empty or
  \texttt{Type2\ -\ Board\ Asset\ Tag}.
\item
  \texttt{BoardType}\\
  \textbf{Type}: \texttt{plist\ integer}\\
  \textbf{Failsafe}: \texttt{0} (OEM specified)\\
  \textbf{SMBIOS}: Baseboard (or Module) Information (Type 2) --- Board
  Type\\
  \textbf{Description}: Either \texttt{0xA} (Motherboard (includes
  processor, memory, and I/O) or \texttt{0xB} (Processor/Memory Module),
  refer to Table 15 -- Baseboard: Board Type for more details.
\item
  \texttt{BoardLocationInChassis}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: Empty (OEM specified)\\
  \textbf{SMBIOS}: Baseboard (or Module) Information (Type 2) --- Location
  in Chassis\\
  \textbf{Description}: Varies, may be empty or
  \texttt{Part\ Component}.
\item
  \texttt{ChassisManufacturer}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: Empty (OEM specified)\\
  \textbf{SMBIOS}: System Enclosure or Chassis (Type 3) --- Manufacturer\\
  \textbf{Description}: Board manufacturer. All rules of
  \texttt{SystemManufacturer} do apply.
\item
  \texttt{ChassisType}\\
  \textbf{Type}: \texttt{plist\ integer}\\
  \textbf{Failsafe}: \texttt{0} (OEM specified)\\
  \textbf{SMBIOS}: System Enclosure or Chassis (Type 3) --- Type\\
  \textbf{Description}: Chassis type, refer to Table 17 --- System
  Enclosure or Chassis Types for more details.
\item
  \texttt{ChassisVersion}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: Empty (OEM specified)\\
  \textbf{SMBIOS}: System Enclosure or Chassis (Type 3) --- Version\\
  \textbf{Description}: Should match \texttt{BoardProduct}.
\item
  \texttt{ChassisSerialNumber}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: Empty (OEM specified)\\
  \textbf{SMBIOS}: System Enclosure or Chassis (Type 3) --- Version\\
  \textbf{Description}: Should match \texttt{SystemSerialNumber}.
\item
  \texttt{ChassisAssetTag}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: Empty (OEM specified)\\
  \textbf{SMBIOS}: System Enclosure or Chassis (Type 3) --- Asset Tag
  Number\\
  \textbf{Description}: Chassis type name. Varies, could be empty or
  \texttt{MacBook-Aluminum}.
\item
  \texttt{PlatformFeature}\\
  \textbf{Type}: \texttt{plist\ integer}, 32-bit\\
  \textbf{Failsafe}: \texttt{0xFFFFFFFF}\\
  \textbf{SMBIOS}: \texttt{APPLE\_SMBIOS\_TABLE\_TYPE133} -
  \texttt{PlatformFeature}\\
  \textbf{Description}: Platform features bitmask. Refer to
  \href{https://github.com/acidanthera/OpenCorePkg/blob/master/Include/Apple/IndustryStandard/AppleFeatures.h}{AppleFeatures.h}
  for more details. Use \texttt{0xFFFFFFFF} value to not provide this table.
\item
  \texttt{SmcVersion}\\
  \textbf{Type}: \texttt{plist\ data}, 16 bytes\\
  \textbf{Failsafe}: All zero\\
  \textbf{SMBIOS}: \texttt{APPLE\_SMBIOS\_TABLE\_TYPE134} - \texttt{Version}\\
  \textbf{Description}: ASCII string containing SMC version in upper case.
  Missing on T2 based Macs. Ignored when zero.
\item
  \texttt{FirmwareFeatures}\\
  \textbf{Type}: \texttt{plist\ data}, 8 bytes\\
  \textbf{Failsafe}: \texttt{0}\\
  \textbf{SMBIOS}: \texttt{APPLE\_SMBIOS\_TABLE\_TYPE128} -
  \texttt{FirmwareFeatures} and \texttt{ExtendedFirmwareFeatures}\\
  \textbf{Description}: 64-bit firmware features bitmask. Refer to
  \href{https://github.com/acidanthera/OpenCorePkg/blob/master/Include/Apple/IndustryStandard/AppleFeatures.h}{AppleFeatures.h}
  for more details. Lower 32 bits match \texttt{FirmwareFeatures}. Upper
  64 bits match \texttt{ExtendedFirmwareFeatures}.
\item
  \texttt{FirmwareFeaturesMask}\\
  \textbf{Type}: \texttt{plist\ data}, 8 bytes\\
  \textbf{Failsafe}: \texttt{0}\\
  \textbf{SMBIOS}: \texttt{APPLE\_SMBIOS\_TABLE\_TYPE128} -
  \texttt{FirmwareFeaturesMask} and
  \texttt{ExtendedFirmwareFeaturesMask}\\
  \textbf{Description}: Supported bits of extended firmware features
  bitmask. Refer to
  \href{https://github.com/acidanthera/OpenCorePkg/blob/master/Include/Apple/IndustryStandard/AppleFeatures.h}{AppleFeatures.h}
  for more details. Lower 32 bits match \texttt{FirmwareFeaturesMask}.
  Upper 64 bits match \texttt{ExtendedFirmwareFeaturesMask}.
\item
  \texttt{ProcessorType}\\
  \textbf{Type}: \texttt{plist\ integer}, 16-bit\\
  \textbf{Failsafe}: \texttt{0} (Automatic)\\
  \textbf{SMBIOS}: \texttt{APPLE\_SMBIOS\_TABLE\_TYPE131} -
  \texttt{ProcessorType}\\
  \textbf{Description}: Combined of Processor Major and Minor types.

  Automatic value generation tries to provide most accurate value for
  the currently installed CPU. When this fails please make sure to create
  an \href{https://github.com/acidanthera/bugtracker/issues}{issue} and
  provide \texttt{sysctl machdep.cpu} and
  \href{https://github.com/acidanthera/dmidecode}{\texttt{dmidecode}} output.
  For a full list of available values and their limitations (the value will
  only apply if the CPU core count matches) refer to Apple SMBIOS definitions header
  \href{https://github.com/acidanthera/OpenCorePkg/blob/master/Include/Apple/IndustryStandard/AppleSmBios.h}{here}.
\end{enumerate}

\section{UEFI}\label{uefi}

\subsection{Introduction}\label{uefiintro}

\href{https://uefi.org/specifications}{UEFI} (Unified Extensible Firmware Interface)
is a specification that defines a software interface between an operating system and
platform firmware. This section allows to load additional UEFI modules and/or apply
tweaks for the onboard firmware. To inspect firmware contents, apply modifications
and perform upgrades \href{https://github.com/LongSoft/UEFITool/releases}{UEFITool}
and supplementary utilities can be used.

\subsection{Drivers}\label{uefidrivers}

Depending on the firmware a different set of drivers may be required.
Loading an incompatible driver may lead the system to unbootable state or
even cause permanent firmware damage. Some of the known drivers are listed below:

\begin{tabular}{p{1.3in}p{5.55in}}
\href{https://github.com/acidanthera/OpenCorePkg}{\texttt{AudioDxe}}\textbf{*}
& HDA audio support driver in UEFI firmware for most Intel and some other analog audio controllers.
  Staging driver, refer to \href{https://github.com/acidanthera/bugtracker/issues/740}{acidanthera/bugtracker\#740}
  for known issues in AudioDxe. \\
\href{https://github.com/acidanthera/OpenCorePkg}{\texttt{CrScreenshotDxe}}\textbf{*}
& Screenshot making driver saving images to the root of OpenCore partition (ESP) or
  any available writeable filesystem upon pressing \texttt{F10}.
  This is a modified version of \href{https://github.com/LongSoft/CrScreenshotDxe}{\texttt{CrScreenshotDxe}}
  driver by \href{https://github.com/NikolajSchlej}{Nikolaj Schlej}. \\
\href{https://github.com/acidanthera/OcBinaryData}{\texttt{ExFatDxe}}
& Proprietary ExFAT file system driver for Bootcamp support commonly found in Apple
  firmware. For Sandy Bridge and earlier CPUs \texttt{ExFatDxeLegacy} driver should be
  used due to the lack of \texttt{RDRAND} instruction support. \\
\href{https://github.com/acidanthera/OcBinaryData}{\texttt{HfsPlus}}
& Proprietary HFS file system driver with bless support commonly found in Apple
  firmware. For Sandy Bridge and earlier CPUs \texttt{HfsPlusLegacy} driver should be
  used due to the lack of \texttt{RDRAND} instruction support. \\
\href{https://github.com/acidanthera/audk}{\texttt{HiiDatabase}}\textbf{*}
& HII services support driver from \texttt{MdeModulePkg}. This driver is included in
  most types of firmware starting with the Ivy Bridge generation. Some applications with GUI,
  such as UEFI Shell, may need this driver to work properly. \\
\href{https://github.com/acidanthera/audk}{\texttt{EnhancedFatDxe}}
& FAT filesystem driver from \texttt{FatPkg}. This driver is embedded in all
  UEFI firmware and cannot be used from OpenCore. Sevaral firmware
  have a flawed FAT support implementation that may lead to corrupted filesystems
  on write attempts. Embedding this driver within the firmware may be required in case
  writing to the EFI partition is needed during the boot process. \\
\href{https://github.com/acidanthera/audk}{\texttt{NvmExpressDxe}}\textbf{*}
& NVMe support driver from \texttt{MdeModulePkg}. This driver is included in most
  firmware starting with the Broadwell generation. For Haswell and earlier, embedding it
  within the firmware may be more favourable in case a NVMe SSD drive is installed. \\
\href{https://github.com/acidanthera/OpenCorePkg}{\texttt{OpenCanopy}}\textbf{*}
& \hyperref[ueficanopy]{OpenCore plugin} implementing graphical interface. \\
\href{https://github.com/acidanthera/OpenCorePkg}{\texttt{OpenRuntime}}\textbf{*}
& \hyperref[uefiruntime]{OpenCore plugin} implementing \texttt{OC\_FIRMWARE\_RUNTIME} protocol. \\
\href{https://github.com/acidanthera/OpenCorePkg}{\texttt{OpenUsbKbDxe}}\textbf{*}
& 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. \\
\href{https://github.com/acidanthera/OcBinaryData}{\texttt{OpenPartitionDxe}}\textbf{*}
& Partition management driver with Apple Partitioning Scheme support.
  This driver can be used to support loading older DMG recoveries such as
  macOS 10.9 using Apple Partitioning Scheme. OpenDuet already includes this driver. \\
\href{https://github.com/acidanthera/audk}{\texttt{Ps2KeyboardDxe}}\textbf{*}
& PS/2 keyboard driver from \texttt{MdeModulePkg}. \texttt{OpenDuetPkg} and some types of firmware
  may not include this driver, but it is necessary for PS/2 keyboard to work.
  Note, unlike \texttt{OpenUsbKbDxe} this driver has no \texttt{AppleKeyMapAggregator}
  support and thus requires \texttt{KeySupport} to be enabled. \\
\href{https://github.com/acidanthera/audk}{\texttt{Ps2MouseDxe}}\textbf{*}
& PS/2 mouse driver from \texttt{MdeModulePkg}. Some very old laptop firmware
  may not include this driver but it is necessary for the touchpad to work
  in UEFI graphical interfaces such as \texttt{OpenCanopy}. \\
\href{https://github.com/acidanthera/OpenCorePkg}{\texttt{OpenHfsPlus}}\textbf{*}
& HFS file system driver with bless support. This driver is an alternative to
  a closed source \texttt{HfsPlus} driver commonly found in Apple firmware. While
  it is feature complete, it is approximately 3~times slower and is yet to undergo
  a security audit. \\
\href{https://github.com/acidanthera/audk}{\texttt{UsbMouseDxe}}\textbf{*}
& USB mouse driver from \texttt{MdeModulePkg}. Some virtual machine firmware
  such as OVMF may not include this driver but it is necessary for the mouse to work
  in UEFI graphical interfaces such as \texttt{OpenCanopy}. \\
\href{https://github.com/acidanthera/audk}{\texttt{XhciDxe}}\textbf{*}
& XHCI USB controller support driver from \texttt{MdeModulePkg}. This driver is
  included in most types of firmware starting with the Sandy Bridge generation. For earlier firmware
  or legacy systems, it may be used to support external USB 3.0 PCI cards.
\end{tabular}

Driver marked with \textbf{*} are bundled with OpenCore.
To compile the drivers from UDK (EDK II) the same command used for
OpenCore compilation can be taken, but choose a corresponding package:
\begin{lstlisting}[label=compileudk, style=ocbash]
git clone https://github.com/acidanthera/audk UDK
cd UDK
source edksetup.sh
make -C BaseTools
build -a X64 -b RELEASE -t XCODE5 -p FatPkg/FatPkg.dsc
build -a X64 -b RELEASE -t XCODE5 -p MdeModulePkg/MdeModulePkg.dsc
\end{lstlisting}

\subsection{Tools and Applications}\label{uefitools}

Standalone tools may help to debug firmware and hardware. Some of the known tools are listed below.
While some tools can be launched from within OpenCore, see more details in
the \hyperref[misctools]{Tools} subsection of the configuration, most should be run
separately either directly or from \texttt{Shell}.

To boot into OpenShell or any other tool directly save \texttt{OpenShell.efi}
under the name of \texttt{EFI\textbackslash BOOT\textbackslash BOOTX64.EFI}
on a FAT32 partition. In general it is unimportant whether the partition scheme
is \texttt{GPT} or \texttt{MBR}.

While the previous approach works both on Macs and other computers,
an alternative Mac-only approach to bless the tool on an HFS+ or APFS
volume:

\begin{lstlisting}[caption=Blessing tool, label=blesstool, style=ocbash]
sudo bless --verbose --file /Volumes/VOLNAME/DIR/OpenShell.efi \
  --folder /Volumes/VOLNAME/DIR/ --setBoot
\end{lstlisting}

\emph{Note 1}: \texttt{/System/Library/CoreServices/BridgeVersion.bin} should be copied
  to \texttt{/Volumes/VOLNAME/DIR}. \\
\emph{Note 2}: To be able to use \texttt{bless}
  \href{https://developer.apple.com/library/archive/documentation/Security/Conceptual/System_Integrity_Protection_Guide/ConfiguringSystemIntegrityProtection/ConfiguringSystemIntegrityProtection.html}{disabling System Integrity Protection} is necessary. \\
\emph{Note 3}: To be able to boot \href{https://support.apple.com/HT208330}{Secure Boot}
  might be disabled if present.

Some of the known tools are listed below (builtin tools are marked with \textbf{*}):

\begin{tabular}{p{1.3in}p{5.55in}}
\href{https://github.com/acidanthera/OpenCorePkg}{\texttt{BootKicker}}\textbf{*}
& Enter Apple BootPicker menu (exclusive for Macs with compatible GPUs). \\
\href{https://github.com/acidanthera/OpenCorePkg}{\texttt{ChipTune}}\textbf{*}
& Test BeepGen protocol and generate audio signals of different style and length. \\
\href{https://github.com/acidanthera/OpenCorePkg}{\texttt{CleanNvram}}\textbf{*}
& Reset NVRAM alternative bundled as a standalone tool. \\
\href{https://github.com/acidanthera/OpenCorePkg}{\texttt{GopStop}}\textbf{*}
& Test GraphicsOutput protocol with a
  \href{https://github.com/acidanthera/OpenCorePkg/tree/master/Application/GopStop}{simple scenario}. \\
\href{https://github.com/acidanthera/OpenCorePkg}{\texttt{KeyTester}}\textbf{*}
& Test keyboard input in \texttt{SimpleText} mode. \\
\href{https://www.memtest86.com}{\texttt{MemTest86}}
& Memory testing utility. \\
\href{https://github.com/acidanthera/OpenCorePkg}{\texttt{OpenControl}}\textbf{*}
& Unlock and lock back NVRAM protection for other tools to be able to get full NVRAM access
  when launching from OpenCore. \\
\href{https://github.com/acidanthera/OpenCorePkg}{\texttt{OpenShell}}\textbf{*}
& OpenCore-configured \href{http://github.com/tianocore/edk2}{\texttt{UEFI Shell}} for compatibility
  with a broad range of firmware. \\
\href{https://github.com/acidanthera/OpenCorePkg}{\texttt{PavpProvision}}
& Perform EPID provisioning (requires certificate data configuration). \\
\href{https://github.com/acidanthera/OpenCorePkg}{\texttt{ResetSystem}}\textbf{*}
& Utility to perform system reset. Takes reset type as an argument:
  \texttt{ColdReset}, \texttt{Firmware}, \texttt{Shutdown}, \texttt{WarmReset}.
  Defaults to \texttt{ColdReset}. \\
\href{https://github.com/acidanthera/OpenCorePkg}{\texttt{RtcRw}}\textbf{*}
& Utility to read and write RTC (CMOS) memory. \\
\href{https://github.com/acidanthera/OpenCorePkg}{\texttt{VerifyMsrE2}}\textbf{*}
& Check \texttt{CFG Lock} (MSR \texttt{0xE2} write protection) consistency across all cores.
\end{tabular}

\subsection{OpenCanopy}\label{ueficanopy}

OpenCanopy is a graphical OpenCore user interface that runs in
\texttt{External} \texttt{PickerMode} and relies on
\href{https://github.com/acidanthera/OpenCorePkg}{OpenCorePkg} \texttt{OcBootManagementLib}
similar to the builtin text interface.

OpenCanopy requires graphical resources located in \texttt{Resources} directory to run.
Sample resources (fonts and images) can be found in
\href{https://github.com/acidanthera/OcBinaryData}{OcBinaryData repository}. Customised icons can be found over the internet
(e.g. \href{https://github.com/blackosx/OpenCanopyIcons}{here} or \href{https://applelife.ru/threads/kastomizacija-opencanopy.2945020/}{there}).

OpenCanopy provides full support for \texttt{PickerAttributes} and offers a configurable
builtin icon set. The default chosen icon set depends on the \texttt{DefaultBackgroundColor}
variable value. For Light Gray \texttt{Old} icon set will be used, for other colours ---
the one without a prefix.

Predefined icons are put to \texttt{\textbackslash EFI\textbackslash OC\textbackslash Resources\textbackslash Image}
directory. Full list of supported icons (in \texttt{.icns} format) is provided below. Missing optional
icons will use the closest available icon. External entries will use \texttt{Ext}-prefixed
icon if available (e.g. \texttt{OldExtHardDrive.icns}).

\emph{Note}: In the following all dimensions are normative for the 1x scaling level and shall be
scaled accordingly for other levels.

\begin{itemize}
\tightlist
  \item \texttt{Cursor} --- Mouse cursor (mandatory, up to 144x144).
  \item \texttt{Selected} --- Selected item (mandatory, 144x144).
  \item \texttt{Selector} --- Selecting item (mandatory, up to 144x40).
  \item \texttt{Left} --- Scrolling left (mandatory, 40x40).
  \item \texttt{Right} --- Scrolling right (mandatory, 40x40).
  \item \texttt{HardDrive} --- Generic OS (mandatory, 128x128).
  \item \texttt{Background} --- Centred background image.
  \item \texttt{Apple} --- Apple OS (128x128).
  \item \texttt{AppleRecv} --- Apple Recovery OS (128x128).
  \item \texttt{AppleTM} --- Apple Time Machine (128x128).
  \item \texttt{Windows} --- Windows (128x128).
  \item \texttt{Other} --- Custom entry (see \texttt{Entries}, 128x128).
  \item \texttt{ResetNVRAM} --- Reset NVRAM system action or tool (128x128).
  \item \texttt{Shell} --- Entry with UEFI Shell name for e.g. \texttt{OpenShell} (128x128).
  \item \texttt{Tool} --- Any other tool (128x128).
\end{itemize}

Predefined labels are put to \texttt{\textbackslash EFI\textbackslash OC\textbackslash Resources\textbackslash Label}
directory. Each label has \texttt{.lbl} or \texttt{.l2x} suffix to represent the scaling level.
Full list of labels is provided below. All labels are mandatory.

\begin{itemize}
\tightlist
  \item \texttt{EFIBoot} --- Generic OS.
  \item \texttt{Apple} --- Apple OS.
  \item \texttt{AppleRecv} --- Apple Recovery OS.
  \item \texttt{AppleTM} --- Apple Time Machine.
  \item \texttt{Windows} --- Windows.
  \item \texttt{Other} --- Custom entry (see \texttt{Entries}).
  \item \texttt{ResetNVRAM} --- Reset NVRAM system action or tool.
  \item \texttt{Shell} --- Entry with UEFI Shell name (e.g. \texttt{OpenShell}).
  \item \texttt{Tool} --- Any other tool.
\end{itemize}

\emph{Note}: All labels must have a height of exactly 12 px. There is no limit for their width.

Label and icon generation can be performed with bundled utilities: \texttt{disklabel} and
\texttt{icnspack}. Font is Helvetica 12 pt times scale factor.

Font format corresponds to \href{https://www.angelcode.com/products/bmfont}{AngelCode binary BMF}.
While there are many utilities to generate font files, currently it is recommended to use
\href{https://github.com/danpla/dpfontbaker}{dpFontBaker} to generate bitmap font
(\href{https://github.com/danpla/dpfontbaker/pull/1}{using CoreText produces best results})
and \href{https://github.com/usr-sse2/fonverter}{fonverter} to export it to binary format.

\subsection{OpenRuntime}\label{uefiruntime}

\texttt{OpenRuntime} is an OpenCore plugin implementing \texttt{OC\_FIRMWARE\_RUNTIME} protocol.
This protocol implements multiple features required for OpenCore that are otherwise not possible
to implement in OpenCore itself as they are needed to work in runtime, i.e. during operating system
functioning. Feature highlights:

\begin{itemize}
  \item NVRAM namespaces, allowing to isolate operating systems from accessing select
  variables (e.g. \texttt{RequestBootVarRouting} or \texttt{ProtectSecureBoot}).
  \item Read-only and write-only NVRAM variables, enhancing the security of OpenCore,
  Lilu, and Lilu plugins, such as VirtualSMC, which implements \texttt{AuthRestart} support.
  \item NVRAM isolation, allowing to protect all variables from being written from
  an untrusted operating system (e.g. \texttt{DisableVariableWrite}).
  \item UEFI Runtime Services memory protection management to workaround read-only
  mapping (e.g. \texttt{EnableWriteUnprotector}).
\end{itemize}

\subsection{Properties}\label{uefiprops}

\begin{enumerate}
\item
  \texttt{APFS}\\
  \textbf{Type}: \texttt{plist\ dict}\\
  \textbf{Failsafe}: None\\
  \textbf{Description}: Provide APFS support as configured in
  \hyperref[uefiapfsprops]{APFS Properties} section below.

\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 supported audio file formats are MP3 and 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].[audio ext]}.
  For unlocalised files filename does not include the language code and looks as follows:
  \texttt{[audio type]\_[audio path].[audio ext]}. Audio extension can either be \texttt{mp3}
  or \texttt{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/OpenCorePkg/blob/master/Include/Apple/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/OpenCorePkg/blob/master/Include/Apple/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/Acidanthera/Protocol/OcAudio.h}{\texttt{OC\_VOICE\_OVER\_AUDIO\_FILE} definition}.
  The only exception is OpenCore boot chime file, which is \texttt{OCEFIAudio\_VoiceOver\_Boot.mp3}.
  \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 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 types of firmware, particularly those made by Apple, only connect the boot
  drive to speed up the boot process. Enable this option to be able to see all the
  boot options when running multiple drives.

\item
  \texttt{Drivers}\\
  \textbf{Type}: \texttt{plist\ array}\\
  \textbf{Failsafe}: None\\
  \textbf{Description}: Load selected drivers from \texttt{OC/Drivers}
  directory.

  Designed to be filled with string filenames meant to be loaded as UEFI
  drivers.

\item
  \texttt{Input}\\
  \textbf{Type}: \texttt{plist\ dict}\\
  \textbf{Failsafe}: None\\
  \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{ProtocolOverrides}\\
  \textbf{Type}: \texttt{plist\ dict}\\
  \textbf{Failsafe}: None\\
  \textbf{Description}: Force builtin versions of select protocols described
  in \hyperref[uefiprotoprops]{ProtocolOverrides Properties} section below.

  \emph{Note}: all protocol instances are installed prior to driver loading.

\item
  \texttt{Quirks}\\
  \textbf{Type}: \texttt{plist\ dict}\\
  \textbf{Failsafe}: None\\
  \textbf{Description}: Apply individual firmware quirks described in
  \hyperref[uefiquirkprops]{Quirks Properties} section below.

\item
  \texttt{ReservedMemory}\\
  \textbf{Type}: \texttt{plist\ array}\\
  \textbf{Description}: Designed to be filled with \texttt{plist\ dict} values,
  describing memory areas exquisite to particular firmware and hardware functioning,
  which should not be used by the operating system. An example of such memory region
  could be second 256 MB corrupted by Intel HD 3000 or an area with faulty RAM.
  See \hyperref[uefirsvdprops]{ReservedMemory Properties} section below.

\end{enumerate}

\subsection{APFS Properties}\label{uefiapfsprops}

\begin{enumerate}

\item
  \texttt{EnableJumpstart}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Load embedded APFS drivers from APFS containers.

  APFS EFI driver is bundled in all bootable APFS containers. This
  option performs loading of signed APFS drivers with respect to
  \texttt{ScanPolicy}. See more details in ``EFI Jumpstart'' section of
  \href{https://developer.apple.com/support/apple-file-system/Apple-File-System-Reference.pdf}{Apple File System Reference}.


\item
  \texttt{GlobalConnect}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Perform full device connection during APFS loading.

  Instead of partition handle connection normally used for APFS driver loading
  every handle is connected recursively. This may take more time than usual
  but can be the only way to access APFS partitions on some types of firmware such as
  those on older HP laptops.

\item
  \texttt{HideVerbose}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Hide verbose output from APFS driver.

  APFS verbose output can be useful for debugging.

\item
  \texttt{JumpstartHotPlug}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Load APFS drivers for newly connected devices.

  Performs APFS driver loading not only at OpenCore startup but also
  during boot picker. This permits APFS USB hot plug. Disable if not
  required.

\item
  \texttt{MinDate}\\
  \textbf{Type}: \texttt{plist\ integer}\\
  \textbf{Failsafe}: \texttt{0}\\
  \textbf{Description}: Minimal allowed APFS driver date.

  APFS driver date connects APFS driver with the calendar
  release date. Older versions of APFS drivers may contain unpatched
  vulnerabilities, which can be used to inflict harm to the computer.
  This option permits restricting APFS drivers to only recent releases.

  \begin{itemize}
    \tightlist
    \item \texttt{0} --- require the default supported release date of APFS
    in OpenCore. The default release date will increase with time and thus
    this setting is recommended. Currently set to 2018/06/21.
    \item \texttt{-1} --- permit any release date to load (strongly discouraged).
    \item Other --- use custom minimal APFS release date, e.g. \texttt{20200401}
    for 2020/04/01. APFS release dates can be found in OpenCore boot log
    and \href{https://github.com/acidanthera/OpenCorePkg/blob/master/Include/Acidanthera/Library/OcApfsLib.h}{\texttt{OcApfsLib}}.
  \end{itemize}

\item
  \texttt{MinVersion}\\
  \textbf{Type}: \texttt{plist\ integer}\\
  \textbf{Failsafe}: \texttt{0}\\
  \textbf{Description}: Minimal allowed APFS driver version.

  APFS driver version connects APFS driver with the macOS
  release. APFS drivers from older macOS releases will become
  unsupported and thus may contain unpatched vulnerabilities, which
  can be used to inflict harm to the computer. This option permits
  restricting APFS drivers to only modern macOS versions.

  \begin{itemize}
    \tightlist
    \item \texttt{0} --- require the default supported version of APFS
    in OpenCore. The default version will increase with time and thus
    this setting is recommended. Currently set to the latest point release
    from High Sierra from App Store (\texttt{748077008000000}).
    \item \texttt{-1} --- permit any version to load (strongly discouraged).
    \item Other --- use custom minimal APFS version, e.g. \texttt{1412101001000000}
    from macOS Catalina 10.15.4. APFS versions can be found in OpenCore boot log
    and \href{https://github.com/acidanthera/OpenCorePkg/blob/master/Include/Acidanthera/Library/OcApfsLib.h}{\texttt{OcApfsLib}}.
  \end{itemize}

\end{enumerate}


\subsection{Audio Properties}\label{uefiaudioprops}

\begin{enumerate}

\item
  \texttt{AudioCodec}\\
  \textbf{Type}: \texttt{plist\ integer}\\
  \textbf{Failsafe}: \texttt{0}\\
  \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-italic):

  \texttt{OCAU: 1/3 PciRoot(0x0)/Pci(0x1,0x0)/Pci(0x0,0x1)/VenMsg(<redacted>,\textit{\textbf{00000000}}) (4 outputs)}\\
  \texttt{OCAU: 2/3 PciRoot(0x0)/Pci(0x3,0x0)/VenMsg(<redacted>,\textit{\textbf{00000000}}) (1 outputs)}\\
  \texttt{OCAU: 3/3 PciRoot(0x0)/Pci(0x1B,0x0)/VenMsg(<redacted>,\textit{\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}: Empty\\
  \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-italic):

  \texttt{OCAU: 1/3 \textit{\textbf{PciRoot(0x0)/Pci(0x1,0x0)/Pci(0x0,0x1)}}/VenMsg(<redacted>,00000000) (4 outputs)}\\
  \texttt{OCAU: 2/3 \textit{\textbf{PciRoot(0x0)/Pci(0x3,0x0)}}/VenMsg(<redacted>,00000000) (1 outputs)}\\
  \texttt{OCAU: 3/3 \textit{\textbf{PciRoot(0x0)/Pci(0x1B,0x0)}}/VenMsg(<redacted>,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-italic):

  \texttt{OCAU: 1/3 PciRoot(0x0)/Pci(0x1,0x0)/Pci(0x0,0x1)/VenMsg(<redacted>,00000000) (\textit{\textbf{4 outputs}})}\\
  \texttt{OCAU: 2/3 PciRoot(0x0)/Pci(0x3,0x0)/VenMsg(<redacted>,00000000) (\textit{\textbf{1 outputs}})}\\
  \texttt{OCAU: 3/3 PciRoot(0x0)/Pci(0x1B,0x0)/VenMsg(<redacted>,02000000) (\textit{\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\ string}\\
  \textbf{Failsafe}: \texttt{Auto}\\
  \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. Possible values include:

  \begin{itemize}
    \tightlist
    \item \texttt{Auto} --- Enables chime when \texttt{StartupMute} NVRAM variable
      is not present or set to \texttt{00}.
    \item \texttt{Enabled} --- Enables chime unconditionally.
    \item \texttt{Disabled} --- Disables chime unconditionally.
  \end{itemize}

  \emph{Note}: \texttt{Enabled} can be used in separate from \texttt{StartupMute}
  NVRAM variable to avoid conflicts when the firmware is able to play boot chime.

\item
  \texttt{SetupDelay}\\
  \textbf{Type}: \texttt{plist\ integer}\\
  \textbf{Failsafe}: \texttt{0}\\
  \textbf{Description}: Audio codec reconfiguration delay in microseconds.

  Some codecs require a vendor-specific delay after the reconfiguration
  (e.g. volume setting). This option makes it configurable. In general
  the necessary delay may be as long as 0.5 seconds.

\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}

\item
  \texttt{KeyFiltering}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Enable keyboard input sanity checking.

  Apparently some boards such as the GA Z77P-D3 may return uninitialised data
  in \texttt{EFI\_INPUT\_KEY} with all input protocols.
  This option discards keys that are neither ASCII, nor are defined
  in the UEFI specification (see tables 107 and 108 in version 2.8).

\item
  \texttt{KeyForgetThreshold}\\
  \textbf{Type}: \texttt{plist\ integer}\\
  \textbf{Failsafe}: \texttt{0}\\
  \textbf{Description}: Remove key unless it was submitted during this timeout in milliseconds.

  \texttt{AppleKeyMapAggregator} protocol is supposed to contain a fixed length buffer
  of currently pressed keys. However, the majority of the drivers only report key
  presses as interrupts and pressing and holding the key on the keyboard results in
  subsequent submissions of this key with some defined time interval. As a result
  we use a timeout to remove once pressed keys from the buffer once the timeout
  expires and no new submission of this key happened.

  This option allows to set this timeout based on the platform. The recommended
  value that works on the majority of the platforms is \texttt{5} milliseconds.
  For reference, holding one key on VMware will repeat it roughly every \texttt{2}
  milliseconds and the same value for APTIO V is \texttt{3-4} milliseconds. Thus
  it is possible to set a slightly lower value on faster platforms
  and slightly higher value on slower platforms for more responsive input.

  \emph{Note}: Some platforms may require different values, higher or lower.
  For example, when detecting key misses in OpenCanopy try increasing this value
  (e.g. to \texttt{10}), and when detecting key stall, try decreasing this value.
  Since every platform is different it may be reasonable to check every value
  from \texttt{1} to \texttt{25}.

\item
  \texttt{KeyMergeThreshold}\\
  \textbf{Type}: \texttt{plist\ integer}\\
  \textbf{Failsafe}: \texttt{0}\\
  \textbf{Description}: Assume simultaneous combination for keys submitted within
  this timeout in milliseconds.

  Similarly to \texttt{KeyForgetThreshold}, this option works around the sequential
  nature of key submission. To be able to recognise simultaneously pressed keys
  in the situation when all keys arrive sequentially, we are required to set
  a timeout within which we assume the keys were pressed together.

  Holding multiple keys results in reports every \texttt{2} and \texttt{1} milliseconds
  for VMware and APTIO V respectively. Pressing keys one after the other results in
  delays of at least \texttt{6} and \texttt{10} milliseconds for the same platforms.
  The recommended value for this option is \texttt{2} milliseconds, but it may be
  decreased for faster platforms and increased for slower.

\item
  \texttt{KeySupport}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Enable internal keyboard input translation to
  \texttt{AppleKeyMapAggregator} protocol.

  This option activates the internal keyboard interceptor driver, based on
  \texttt{AppleGenericInput} aka (\texttt{AptioInputFix}), to fill
  \texttt{AppleKeyMapAggregator} database for input functioning. In case
  a separate driver is used, such as \texttt{OpenUsbKbDxe}, this option
  should never be enabled.

\item
  \texttt{KeySupportMode}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: \texttt{Auto}\\
  \textbf{Description}: Set internal keyboard input translation to
  \texttt{AppleKeyMapAggregator} protocol mode.

  \begin{itemize}
  \tightlist
  \item \texttt{Auto} --- Performs automatic choice as available with the following preference: \texttt{AMI}, \texttt{V2}, \texttt{V1}.
  \item \texttt{V1} --- Uses UEFI standard legacy input protocol \texttt{EFI\_SIMPLE\_TEXT\_INPUT\_PROTOCOL}.
  \item \texttt{V2} --- Uses UEFI standard modern input protocol \texttt{EFI\_SIMPLE\_TEXT\_INPUT\_EX\_PROTOCOL}.
  \item \texttt{AMI} --- Uses APTIO input protocol \texttt{AMI\_EFIKEYCODE\_PROTOCOL}.
  \end{itemize}

  \emph{Note}: Currently \texttt{V1}, \texttt{V2}, and \texttt{AMI} unlike \texttt{Auto} only do filtering of
  the particular specified protocol. This may change in the future versions.

\item
  \texttt{KeySwap}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Swap \texttt{Command} and \texttt{Option} keys during submission.

  This option may be useful for keyboard layouts with \texttt{Option} key situated to the right
  of \texttt{Command} key.

\item
  \texttt{PointerSupport}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Enable internal pointer driver.

  This option implements standard UEFI pointer protocol (\texttt{EFI\_SIMPLE\_POINTER\_PROTOCOL})
  through select OEM protocols. The option may be useful on Z87 ASUS boards, where
  \texttt{EFI\_SIMPLE\_POINTER\_PROTOCOL} is broken.

\item
  \texttt{PointerSupportMode}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: Empty\\
  \textbf{Description}: Set OEM protocol used for internal pointer driver.

  Currently the only supported variant is \texttt{ASUS}, using specialised protocol available
  on select Z87 and Z97 ASUS boards. More details can be found in
  \href{https://github.com/LongSoft/UEFITool/pull/116}{\texttt{LongSoft/UefiTool\#116}}.
  The value of this property cannot be empty if \texttt{PointerSupport} is enabled.

\item
  \texttt{TimerResolution}\\
  \textbf{Type}: \texttt{plist\ integer}\\
  \textbf{Failsafe}: \texttt{0}\\
  \textbf{Description}: Set architecture timer resolution.

  This option allows to update firmware architecture timer period with the specified value
  in \texttt{100} nanosecond units. Setting a lower value generally improves performance
  and responsiveness of the interface and input handling.

  The recommended value is \texttt{50000} (\texttt{5} milliseconds) or slightly higher. Select
  ASUS Z87 boards use \texttt{60000} for the interface. Apple boards use \texttt{100000}.
  In case of issues, this option can be left as \texttt{0}.

\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 firmware generally supports \texttt{ConsoleControl} with two
  rendering modes: \texttt{Graphics} and \texttt{Text}. Some types of firmware
  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{BuiltinText} --- Switch to \texttt{Text}
    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}. \texttt{BuiltinText} variant is
  an alternative \texttt{BuiltinGraphics} for some very old and buggy laptop
  firmware, which can only draw in \texttt{Text} mode.

  The use of \texttt{System} protocols is more complicated. In general
  the preferred setting is \texttt{SystemGraphics} or \texttt{SystemText}.
  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 (Maintain current console mode)\\
  \textbf{Description}: Sets console output mode as specified
  with the \texttt{WxH} (e.g. \texttt{80x24}) formatted string.

  Set to \texttt{Max} to attempt using the largest available console mode.
  This option is currently ignored as the \texttt{Builtin} text renderer
  only supports one console mode.

  \emph{Note}: This field is best left empty on most types of firmware.

\item
  \texttt{Resolution}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: Empty (Maintain current screen resolution)\\
  \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 \texttt{Max} to attempt using the 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{ForceResolution}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Forces \texttt{Resolution} to be set in cases where the desired
  resolution is not available by default, such as on legacy Intel GMA and first
  generation Intel HD Graphics (Ironlake/Arrandale). Setting \texttt{Resolution} to
  \texttt{Max} will try to pull the largest available resolution from the connected
  display's EDID.

  \emph{Note}: This option depends on the \href{https://github.com/acidanthera/OpenCorePkg/blob/master/Include/Acidanthera/Protocol/OcForceResolution.h}{\texttt{OC\_FORCE\_RESOLUTION\_PROTOCOL}}
  protocol being present. This protocol is currently only supported by \texttt{OpenDuetPkg}. The
  \texttt{OpenDuetPkg} implementation currently only supports Intel iGPUs.

\item
  \texttt{ClearScreenOnModeSwitch}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Some types of firmware only clear part of the screen when switching
  from graphics to text mode, leaving a fragment of previously drawn images visible.
  This option fills the entire graphics screen with black colour 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 types of firmware, such as on the \texttt{MacPro5,1}, this may provide better
  performance or fix rendering issues. However, this option is not recommended unless
  there is an obvious benefit as it may result in issues such as slower scrolling.

\item
  \texttt{IgnoreTextInGraphics}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Some types of firmware output text onscreen in both graphics and
  text mode. This is typically unexpected as 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 a different mode from \texttt{Text}.

  \emph{Note}: This option only applies to the \texttt{System} renderer.

\item
  \texttt{ReplaceTabWithSpace}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Some types of firmware do not print tab characters or everything
  that follows them, causing difficulties in using the UEFI Shell's 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 or UGA (for 10.4 EfiBoot) to be present on console
  handle, yet the exact location of the graphics protocol is not covered by the
  UEFI specification. This option will ensure GOP and UGA, if present, are available
  on the console handle.

  \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 types of firmware, the controllers that produce the console protocols
  (simple text out) must be reconnected when the screen resolution is changed via GOP.
  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 types of firmware reset screen resolutions to a failsafe
  value (such as \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 the \texttt{System} renderer.
   On all known affected systems, \texttt{ConsoleMode} must be set to
   an empty string for this option to work.

\item
  \texttt{UgaPassThrough}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Provide UGA protocol instances on top of GOP protocol instances.

  Some types of firmware do not implement the legacy UGA protocol but this may be required
  for screen output by older EFI applications such as EfiBoot from 10.4.

\end{enumerate}


\subsection{ProtocolOverrides Properties}\label{uefiprotoprops}

\begin{enumerate}

\item
  \texttt{AppleAudio}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Replaces 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}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Replaces the Apple Boot Policy protocol with a builtin
  version. This may be used to ensure APFS compatibility on VMs or legacy Macs.

  \emph{Note}: Some Macs, namely \texttt{MacPro5,1}, do have APFS compatibility,
  but their Apple Boot Policy protocol contains recovery detection issues, thus
  using this option is advised on them as well.

\item
  \texttt{AppleDebugLog}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Replaces the Apple Debug Log protocol with a builtin
  version.

\item
  \texttt{AppleEvent}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Replaces the Apple Event protocol with a builtin
  version. This may be used to ensure FileVault 2 compatibility on VMs or legacy Macs.

\item
  \texttt{AppleFramebufferInfo}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Replaces the Apple Framebuffer Info protocol with a builtin
  version. This may be used to override framebuffer information on VMs or legacy Macs
  to improve compatibility with legacy EfiBoot such as the one in macOS 10.4.

\item
  \texttt{AppleImageConversion}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Replaces the Apple Image Conversion protocol with a builtin
  version.

\item
  \texttt{AppleImg4Verification}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Replaces the Apple IMG4 Verification protocol with a builtin
  version. This protocol is used to verify \texttt{im4m} manifest files used by
  Apple Secure Boot.

\item
  \texttt{AppleKeyMap}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Replaces Apple Key Map protocols with builtin
  versions.

\item
  \texttt{AppleRtcRam}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Replaces the Apple RTC RAM protocol with a builtin
  version.

  \emph{Note}: Builtin version of Apple RTC RAM protocol may filter out
  I/O attempts to select RTC memory addresses. The list of addresses
  can be specified in \texttt{4D1FDA02-38C7-4A6A-9CC6-4BCCA8B30102:rtc-blacklist}
  variable as a data array.

\item
  \texttt{AppleSecureBoot}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Replaces the Apple Secure Boot protocol with a builtin
  version.

\item
  \texttt{AppleSmcIo}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Replaces the Apple SMC I/O protocol with a builtin
  version.

  This protocol replaces legacy \texttt{VirtualSmc} UEFI driver, and is compatible
  with any SMC kernel extension. However, in case \texttt{FakeSMC} kernel extension
  is used, manual NVRAM key variable addition may be needed.

\item
  \texttt{AppleUserInterfaceTheme}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Replaces the Apple User Interface Theme protocol with a builtin
  version.

\item
  \texttt{DataHub}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Replaces the Data Hub protocol with a builtin version.

  \emph{Note}: This will discard all previous entries if the protocol was already
  installed, so all properties required for safe operation of the system must be
  specified in your configuration.

\item
  \texttt{DeviceProperties}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Replaces the Device Property protocol with a builtin
  version. This may be used to ensure full compatibility on VMs or legacy Macs.

  \emph{Note}: This will discard all previous entries if the protocol was already
  installed, so all properties required for safe operation of the system must be
  specified in your configuration.

\item
  \texttt{FirmwareVolume}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Wraps Firmware Volume protocols or installs a new version
  to support custom cursor images for FileVault 2. Set to \texttt{true} to ensure
  FileVault 2 compatibility on anything other than VMs and legacy Macs.

  \emph{Note}: Several virtual machines including VMware may have corrupted
  cursor images in HiDPI mode and thus, may also require enabling this setting.

\item
  \texttt{HashServices}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Replaces Hash Services protocols with builtin versions.
  Set to \texttt{true} to ensure FileVault 2 compatibility on platforms with
  flawed SHA-1 hash implementations. This can be determined by an invalid
  cursor size when \texttt{UIScale} is set to \texttt{02}. Platforms earlier
  than APTIO V (Haswell and older) are typically affected.

\item
  \texttt{OSInfo}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Replaces the OS Info protocol with a builtin
  version. This protocol is typically used by the firmware and other
  applications to receive notifications from the macOS bootloader.

\item
  \texttt{UnicodeCollation}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Replaces unicode collation services with builtin
  versions. Set to \texttt{true} to ensure UEFI Shell compatibility on platforms
  with flawed unicode collation implementations. Legacy Insyde and APTIO platforms
  on Ivy Bridge, and earlier, are typically affected.

\end{enumerate}

\subsection{Quirks Properties}\label{uefiquirkprops}

\begin{enumerate}

\item
  \texttt{DisableSecurityPolicy}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Disable platform security policy.

  \emph{Note}: This setting disables various security features of the firmware,
  defeating the purpose of any kind of Secure Boot. Do NOT enable if you use
  UEFI Secure Boot.

\item
  \texttt{ExitBootServicesDelay}\\
  \textbf{Type}: \texttt{plist\ integer}\\
  \textbf{Failsafe}: \texttt{0}\\
  \textbf{Description}: Adds delay in microseconds after \texttt{EXIT\_BOOT\_SERVICES}
  event.

  This is a very rough workaround to circumvent the \texttt{Still\ waiting\ for\ root\ device} message
  on some APTIO IV firmware (ASUS Z87-Pro) particularly when using FileVault 2.
  It appears that for some reason, they execute code in parallel to \texttt{EXIT\_BOOT\_SERVICES},
  which results in the SATA controller being inaccessible from macOS. A better approach is required
  and Acidanthera is open to suggestions. Expect 3 to 5 seconds to be adequate when this quirk is needed.

\item
  \texttt{IgnoreInvalidFlexRatio}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Some types of firmware (such as APTIO IV) may contain invalid values in the
  \texttt{MSR\_FLEX\_RATIO} (\texttt{0x194}) MSR register. These values may cause
  macOS boot failures on Intel platforms.

  \emph{Note}: While the option is not expected to harm unaffected firmware,
  its use is recommended only when specifically required.

\item
  \texttt{ReleaseUsbOwnership}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Attempt to detach USB controller ownership from
  the firmware driver. While most types of firmware manage to do this properly,
  or at least have an option for this, some do not. As a result, the operating
  system may freeze upon boot. Not recommended unless specifically required.

\item
  \texttt{RequestBootVarRouting}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Request redirect of all \texttt{Boot} prefixed variables from
  \texttt{EFI\_GLOBAL\_VARIABLE\_GUID} to \newline \texttt{OC\_VENDOR\_VARIABLE\_GUID}.

  This quirk requires \texttt{OC\_FIRMWARE\_RUNTIME} protocol implemented
  in \texttt{OpenRuntime.efi}. The quirk lets default boot entry
  preservation at times when the firmware deletes incompatible boot entries.
  In summary, this quirk is required to reliably
  use the \href{https://support.apple.com/HT202796}{Startup Disk} preference
  pane in firmware that is not compatible with macOS boot entries by design.

  By redirecting \texttt{Boot} prefixed variables to a separate GUID namespace
  with the help of \texttt{RequestBootVarRouting} quirk we achieve multiple goals:
  \begin{itemize}
  \tightlist
  \item Operating systems are jailed and only controlled by OpenCore boot
  environment to enhance security.
  \item Operating systems do not mess with OpenCore boot priority, and guarantee
  fluent updates and hibernation wakes for cases that require reboots with OpenCore
  in the middle.
  \item Potentially incompatible boot entries, such as macOS entries, are not deleted
  or corrupted in any way.
  \end{itemize}

\item
  \texttt{TscSyncTimeout}\\
  \textbf{Type}: \texttt{plist\ integer}\\
  \textbf{Failsafe}: \texttt{0}\\
  \textbf{Description}: Attempts to perform TSC synchronisation with a specified timeout.

  The primary purpose of this quirk is to enable early bootstrap TSC synchronisation
  on some server and laptop models when running a debug XNU kernel. For the debug kernel
  the TSC needs to be kept in sync across the cores before any kext could kick in rendering
  all other solutions problematic. The timeout is specified in microseconds and depends on the
  amount of cores present on the platform, the recommended starting value is \texttt{500000}.

  This is an experimental quirk, which should only be used for the aforementioned problem.
  In all other cases, the quirk may render the operating system unstable and is not recommended.
  The recommended solution in the other cases is to install a kernel driver such as
  \href{https://github.com/RehabMan/VoodooTSCSync}{VoodooTSCSync},
  \href{https://github.com/interferenc/TSCAdjustReset}{TSCAdjustReset},
  or \href{https://github.com/lvs1974/CpuTscSync}{CpuTscSync} (a more specialised
  variant of VoodooTSCSync for newer laptops).

  \emph{Note}: This quirk cannot replace the kernel driver because it cannot operate in
  ACPI S3 (sleep wake) mode and because the UEFI firmware only provides very limited
  multicore support which prevents precise updates of the MSR registers.

\item
  \texttt{UnblockFsConnect}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: Some types of firmware block partition handles by opening them
  in \texttt{By\ Driver} mode, resulting in an inability to install File System protocols.

  \emph{Note}: This quirk is useful in cases where unsuccessful drive detection
  results in an absence of boot entries.

\end{enumerate}

\subsection{ReservedMemory Properties}\label{uefirsvdprops}

\begin{enumerate}

\item
  \texttt{Address}\\
  \textbf{Type}: \texttt{plist\ integer}\\
  \textbf{Failsafe}: \texttt{0}\\
  \textbf{Description}: Start address of the reserved memory region, which should be allocated
  as reserved effectively marking the memory of this type inaccessible to the operating system.

  The addresses written here must be part of the memory map, have a \texttt{EfiConventionalMemory}
  type, and be page-aligned (4 KBs).

  \emph{Note}: Some types of firmware may not allocate memory areas used by S3 (sleep) and S4 (hibernation)
  code unless CSM is enabled causing wake failures. After comparing the memory maps with CSM disabled
  and enabled, these areas can be found in the lower memory and can be fixed up by doing the reservation.
  See \texttt{Sample.plist} for more details.

\item
  \texttt{Comment}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: Empty\\
  \textbf{Description}: Arbitrary ASCII string used to provide human readable
  reference for the entry. Whether this value is used is implementation defined.

\item
  \texttt{Size}\\
  \textbf{Type}: \texttt{plist\ integer}\\
  \textbf{Failsafe}: \texttt{0}\\
  \textbf{Description}: Size of the reserved memory region, must be page-aligned (4 KBs).

\item
  \texttt{Type}\\
  \textbf{Type}: \texttt{plist\ string}\\
  \textbf{Failsafe}: \texttt{Reserved}\\
  \textbf{Description}: Memory region type matching the UEFI specification memory descriptor
  types. Mapping:

  \begin{itemize}
    \tightlist
    \item \texttt{Reserved} --- \texttt{EfiReservedMemoryType}
    \item \texttt{LoaderCode} --- \texttt{EfiLoaderCode}
    \item \texttt{LoaderData} --- \texttt{EfiLoaderData}
    \item \texttt{BootServiceCode} --- \texttt{EfiBootServicesCode}
    \item \texttt{BootServiceData} --- \texttt{EfiBootServicesData}
    \item \texttt{RuntimeCode} --- \texttt{EfiRuntimeServicesCode}
    \item \texttt{RuntimeData} --- \texttt{EfiRuntimeServicesData}
    \item \texttt{Available} --- \texttt{EfiConventionalMemory}
    \item \texttt{Persistent} --- \texttt{EfiPersistentMemory}
    \item \texttt{UnusableMemory} --- \texttt{EfiUnusableMemory}
    \item \texttt{ACPIReclaimMemory} --- \texttt{EfiACPIReclaimMemory}
    \item \texttt{ACPIMemoryNVS} --- \texttt{EfiACPIMemoryNVS}
    \item \texttt{MemoryMappedIO} --- \texttt{EfiMemoryMappedIO}
    \item \texttt{MemoryMappedIOPortSpace} --- \texttt{EfiMemoryMappedIOPortSpace}
    \item \texttt{PalCode} --- \texttt{EfiPalCode}
  \end{itemize}

\item
  \texttt{Enabled}\\
  \textbf{Type}: \texttt{plist\ boolean}\\
  \textbf{Failsafe}: \texttt{false}\\
  \textbf{Description}: This region will not be reserved unless set to \texttt{true}.

\end{enumerate}

\section{Troubleshooting}\label{troubleshooting}

\subsection{Legacy Apple OS}\label{legacyapple}

Older operating systems may be more complicated to install, but sometimes can
be necessary to use for all kinds of reasons. While a compatible board identifier
and CPUID are the obvious requirements for proper functioning of an older
operating system, there are many other less obvious things to consider.
This section tries to cover a common set of issues relevant to installing
older macOS operating systems.

While newer operating systems can be downloaded over the internet,
older operating systems did not have installation media for every minor
release. For compatible distributions of such, download a device-specific
image and modify it if necessary. Visit this archived Apple Support
\href{https://web.archive.org/web/20170705003629/https://support.apple.com/en-us/HT204319}{article}
for a list of the bundled device-specific builds for legacy operating systems.
However, as this may not always be accurate, the latest versions are listed below.

\subsubsection{macOS 10.8 and 10.9}\label{legacy108}

\begin{itemize}
  \item Disk images on these systems use Apple Partitioning Scheme
    and require \texttt{OpenPartitionDxe} driver to run DMG recovery
    and installation (included in OpenDuet). It is possible to set
    \texttt{DmgLoading} to \texttt{Disabled} to run the recovery
    without DMG loading avoiding the need for \texttt{OpenPartitionDxe}.
  \item Cached kernel images often do not contain family drivers
    for networking (\texttt{IONetworkingFamily}) or audio
    (\texttt{IOAudioFamily}) requiring the use of \texttt{Force}
    loading in order to inject networking or audio drivers.
\end{itemize}

\subsubsection{macOS 10.7}\label{legacy107}

\begin{itemize}
  \item All previous issues apply.
  \item \texttt{SSSE3} support (not to be confused with \texttt{SSE3} support)
    is a hard requirement for macOS 10.7 kernel.
  \item Many kexts, including \texttt{Lilu} when 32-bit kernel
    is used and a lot of \texttt{Lilu} plugins, are
    unsupported on macOS~10.7 and older as they require newer
    kernel APIs, which are not part of the macOS~10.7 SDK.
  \item Prior to macOS~10.8 KASLR sliding is not supported, which
    will result in memory allocation failures on firmware
    that utilise lower memory for their own purposes. Refer to
    \href{https://github.com/acidanthera/bugtracker/issues/1125}{acidanthera/bugtracker\#1125}
    for tracking.
\end{itemize}

\subsubsection{macOS 10.6}\label{legacy106}

\begin{itemize}
  \item All previous issues apply.
  \item \texttt{SSSE3} support is a requirement for macOS 10.6 kernel
    with 64-bit userspace enabled. This limitation can mostly be lifted
    by enabling the \texttt{LegacyCommpage} quirk.
  \item Last released installer images for macOS~10.6 are macOS~10.6.7
    builds \texttt{10J3250} (for \texttt{MacBookPro8,x}) and
    \texttt{10J4139} (for \texttt{iMac12,x}), without Xcode). These
    images are limited to their target model identifiers and have no
    \texttt{-no\_compat\_check} boot argument support. Modified images
    (with \texttt{ACDT} suffix) without model restrictions can be found
    \href{https://archive.org/details/10.6.7-10j3250-disk-images}{here}
    (\href{https://mega.nz/folder/z5YUhYTb#gA\_IRY5KMuYpnNCg7kR3ug}{MEGA Mirror}),
    assuming macOS~10.6 is legally owned. Read \texttt{DIGEST.txt}
    for more details. Note that these are the earliest tested
    versions of macOS~10.6 with OpenCore.
\end{itemize}

  Model checking may also be erased by editing \texttt{OSInstall.mpkg}
  with e.g. \texttt{Flat Package Editor} by making \texttt{Distribution}
  script to always return \texttt{true} in \texttt{hwbeModelCheck} function.
  Since updating the only file in the image and not corrupting other files
  can be difficult and may cause slow booting due to kernel cache date
  changes, it is recommended to script image rebuilding as shown below:

\begin{lstlisting}[label=snowrebuild, style=ocbash]
#!/bin/bash
# Original.dmg is original image, OSInstall.mpkg is patched package
mkdir RO
hdiutil mount Original.dmg -noverify -noautoopen -noautoopenrw -noautofsck -mountpoint RO
cp RO/.DS_Store DS_STORE
hdiutil detach RO -force
rm -rf RO
hdiutil convert Original.dmg -format UDRW -o ReadWrite.dmg
mkdir RW
xattr -c OSInstall.mpkg
hdiutil mount ReadWrite.dmg -noverify -noautoopen -noautoopenrw -noautofsck -mountpoint RW
cp OSInstall.mpkg RW/System/Installation/Packages/OSInstall.mpkg
killall Finder fseventsd
rm -rf RW/.fseventsd
cp DS_STORE RW/.DS_Store
hdiutil detach RW -force
rm -rf DS_STORE RW
hdiutil convert ReadWrite.dmg -format UDZO -o ReadOnly.dmg
\end{lstlisting}

\subsubsection{macOS 10.5}\label{legacy105}

\begin{itemize}
  \item All previous issues apply.
  \item This macOS version does not support \texttt{x86\_64} kernel
    and requires \texttt{i386} kernel extensions and patches.
  \item This macOS version uses the first (V1) version of \texttt{prelinkedkernel},
    which has kext symbol tables corrupted by the kext tools. This nuance
    renders \texttt{prelinkedkernel} kext injection impossible in OpenCore.
    \texttt{Mkext} kext injection will still work without noticeable
    performance drain and will be chosen automatically when
    \texttt{KernelCache} is set to \texttt{Auto}.
  \item Last released installer image for macOS~10.5 is macOS~10.5.7
    build \texttt{9J3050} (for \texttt{MacBookPro5,3}). Unlike the others,
    this image is not limited to the target model identifiers and can be used
    as is. The original \texttt{9J3050} image can be found
    \href{https://archive.org/details/10.5.7-9-j-3050}{here}
    (\href{https://mega.nz/folder/inRBTarD#zanf7fUbviwz3WHBU5xpCg}{MEGA Mirror}),
    assuming macOS~10.5 is legally owned. Read \texttt{DIGEST.txt}
    for more details. Note that this is the earliest tested
    version of macOS~10.5 with OpenCore.
\end{itemize}

\subsubsection{macOS 10.4}\label{legacy104}

\begin{itemize}
  \item All previous issues apply.
  \item This macOS version has a hard requirement to access all the optional
    packages on the second DVD disk installation media, requiring either two
    disks or USB media installation.
  \item Last released installer images for macOS~10.4 are macOS~10.4.10
    builds \texttt{8R4061a} (for \texttt{MacBookPro3,1}) and
    \texttt{8R4088} (for \texttt{iMac7,1})). These images are limited
    to their target model identifiers as on newer macOS versions.
    Modified \texttt{8R4088} images (with \texttt{ACDT} suffix) without
    model restrictions can be found
    \href{https://archive.org/details/10.4.10-8-r-4088-acdt}{here}
    (\href{https://mega.nz/folder/D3ASzLzA\#7sjYXE2X09f6aGjol\_C7dg}{MEGA Mirror}),
    assuming macOS~10.4 is legally owned. Read \texttt{DIGEST.txt}
    for more details. Note that these are the earliest tested
    versions of macOS~10.4 with OpenCore.
\end{itemize}

\subsection{UEFI Secure Boot}\label{uefisecureboot}

OpenCore is designed to provide a secure boot chain between firmware
and operating system. On most x86 platforms trusted loading is implemented
via \href{https://en.wikipedia.org/wiki/UEFI_Secure_Boot}{UEFI Secure Boot} model.
Not only OpenCore fully supports this model, but it also extends its capabilities
to ensure sealed configuration via \hyperref[securevaulting]{vaulting} and
provide trusted loading to the operating systems using custom verification,
such as \hyperref[secureapplesb]{Apple Secure Boot}. Proper secure boot chain
requires several steps and careful configuration of select settings as explained below:

\begin{enumerate}
\item Enable Apple Secure Boot by setting \texttt{SecureBootModel} to
  run macOS. Note, that not every macOS is compatible with Apple Secure Boot and
  there are several other restrictions as explained in
  \hyperref[secureapplesb]{Apple Secure Boot} section.
\item Disable DMG loading by setting \texttt{DmgLoading} to \texttt{Disabled}
  if users have concerns of loading old vulnerable DMG recoveries. This is
  \textbf{not} required, but recommended. For the actual tradeoffs
  see the details in \hyperref[securedmgloading]{DMG loading} section.
\item Make sure that APFS JumpStart functionality restricts the loading
  of old vulnerable drivers by setting \texttt{MinDate} and \texttt{MinVersion}
  to \texttt{0}. More details are provided in \hyperref[uefiapfsprops]{APFS JumpStart}
  section. An alternative is to install \texttt{apfs.efi} driver manually.
\item Make sure that \texttt{Force} driver loading is not needed and
  all the operating systems are still bootable.
\item Make sure that \texttt{ScanPolicy} restricts loading from undesired
  devices. It is a good idea to prohibit all removable drivers or unknown
  filesystems.
\item Sign all the installed drivers and tools with the private key. Do not sign
  tools that provide administrative access to the computer, such as UEFI Shell.
\item Vault the configuration as explained \hyperref[securevaulting]{Vaulting}
  section.
\item Sign all OpenCore binaries (\texttt{BOOTX64.efi}, \texttt{BOOTIa32.efi},
  \texttt{OpenCore.efi}, custom launchers) used on this system with
  the same private key.
\item Sign all third-party operating system (not made by Microsoft or Apple)
  bootloaders if needed. For Linux there is an option to install
  Microsoft-signed Shim bootloader as explained on e.g.
  \href{https://wiki.debian.org/SecureBoot}{Debian Wiki}.
\item Enable UEFI Secure Boot in firmware preferences and install the
  certificate with a private key. Details on how to generate a certificate
  can be found in various articles, such as \href{https://habr.com/en/post/273497}{this one},
  and are out of the scope of this document. If Windows is needed one
  will also need to add the
  \href{http://go.microsoft.com/fwlink/?LinkID=321192}{Microsoft Windows Production CA 2011}.
  To launch option ROMs or to use signed Linux drivers,
  \href{http://go.microsoft.com/fwlink/?LinkId=321194}{Microsoft UEFI Driver Signing CA} will also be needed.
\item Password-protect changing firmware settings to ensure that UEFI Secure Boot
  cannot be disabled without the user's knowledge.
\end{enumerate}

\subsection{Windows support}\label{troubleshootingwin}

  \textbf{Can I install Windows?}

  While no official Windows support is provided, 64-bit UEFI Windows installations (Windows 8 and
  above) prepared with Boot Camp are supposed to work. Third-party UEFI installations
  as well as systems partially supporting UEFI boot, such as Windows 7, might work with
  some extra precautions. Things to consider:

  \begin{itemize}
  \item MBR (Master Boot Record) installations are legacy and will not be supported.
  \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.
  \item macOS requires the first partition to be EFI System Partition, and does
  not support the default Windows layout. While OpenCore does have a
  \href{https://github.com/acidanthera/bugtracker/issues/327}{workaround}
  for this, it is highly recommend not to rely on it and install properly.
  \item Windows may need to be reactivated. To avoid it consider
  setting SystemUUID to the original firmware UUID. Be aware that it may be invalid
  on old firmware, i.e., not random. If there still are issues,
  consider using HWID or KMS38 license or making the use \texttt{Custom}
  \texttt{UpdateSMBIOSMode}. Other nuances of Windows activation are out of the
  scope of this document and can be found online.
  \end{itemize}

  \textbf{What additional software do I need?}

  To enable operating system switching and install relevant drivers in the majority of
  cases Windows support software from
  \href{https://support.apple.com/boot-camp}{Boot Camp} is required. For simplicity of the download
  process or when configuring an already installed Windows version a third-party utility,
  \href{https://github.com/timsutton/brigadier}{Brigadier}, can be used successfully.
  Note, that \href{https://www.7-zip.org}{7-Zip} may be downloaded and installed
  prior to using Brigadier.

  Remember to always use the latest version of Windows support software from Boot Camp,
  as versions prior to 6.1 do not support APFS, and thus will not function correctly.
  To download newest software pass most recent Mac model to Brigadier, for example
  \texttt{./brigadier.exe -m iMac19,1}. To install Boot Camp on an unsupported Mac model
  afterwards run PowerShell as Administrator and enter \texttt{msiexec /i BootCamp.msi}.
  If there is a previous version of Boot Camp installed it should be
  removed first by running \texttt{msiexec /x BootCamp.msi} command. \texttt{BootCamp.msi}
  file is located in \texttt{BootCamp/Drivers/Apple} directory and can be reached through
  Windows Explorer.

  While Windows support software from Boot Camp solves most of compatibility problems,
  the rest may still have to be addressed 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}.
  \item \texttt{RealTimeIsUniversal} must be set to \texttt{1} to avoid time
  desync between Windows and macOS as explained on
  \href{https://superuser.com/q/494432}{SuperUser} (this is usually not needed).
  \item To access Apple filesystems such as HFS+ and APFS, separate software may need to
  be installed. Some of the known utilities are:
  \href{https://forums.macrumors.com/threads/apple-hfs-windows-driver-download.1368010/}{Apple HFS+ driver}
  (\href{https://forums.macrumors.com/threads/apple-hfs-windows-driver-download.1368010/post-24180079}{hack for Windows 10}),
  \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.
  \end{itemize}

  \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 the partition will have to be relabelled manually.
  This can be done with many utilities including open-source
  \href{https://sourceforge.net/projects/gptfdisk}{gdisk} utility. Reference example:

\begin{lstlisting}[caption=Relabeling Windows volume, label=relabel, style=ocbash]
PS C:\gdisk> .\gdisk64.exe \\.\physicaldrive0
GPT fdisk (gdisk) version 1.0.4

Command (? for help): p
Disk \\.\physicaldrive0: 419430400 sectors, 200.0 GiB
Sector size (logical): 512 bytes
Disk identifier (GUID): DEC57EB1-B3B5-49B2-95F5-3B8C4D3E4E12
Partition table holds up to 128 entries
Main partition table begins at sector 2 and ends at sector 33
First usable sector is 34, last usable sector is 419430366
Partitions will be aligned on 2048-sector boundaries
Total free space is 4029 sectors (2.0 MiB)

Number  Start (sector)    End (sector)  Size       Code  Name
   1            2048         1023999   499.0 MiB   2700  Basic data partition
   2         1024000         1226751   99.0 MiB    EF00  EFI system partition
   3         1226752         1259519   16.0 MiB    0C01  Microsoft reserved ...
   4         1259520       419428351   199.4 GiB   0700  Basic data partition

Command (? for help): c
Partition number (1-4): 4
Enter name: BOOTCAMP

Command (? for help): w

Final checks complete. About to write GPT data. THIS WILL OVERWRITE EXISTING PARTITIONS!!

Do you want to proceed? (Y/N): Y
OK; writing new GUID partition table (GPT) to \\.\physicaldrive0.
Disk synchronization succeeded! The computer should now use the new partition table.
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/OpenCorePkg/tree/master/Debug}{OpenCore Debug}
page. For IDA Pro, version 7.3 or newer is needed, and
\href{https://www.hex-rays.com/products/ida/support/tutorials/index.shtml}{Debugging the XNU Kernel with IDA Pro}
may also help.

To obtain the log during boot serial port debugging can be used. Serial port
debugging is enabled in \texttt{Target}, e.g. \texttt{0xB} for onscreen with serial. To
initialise serial within OpenCore use \texttt{SerialInit} configuration option.
For macOS the best choice is CP2102-based UART devices. Connect motherboard \texttt{TX}
to USB UART \texttt{RX}, and motherboard \texttt{GND} to USB UART \texttt{GND}. Use
\texttt{screen} utility to get the output, or download GUI software, such as
\href{https://freeware.the-meiers.org}{CoolTerm}.

\emph{Note}: On several motherboards (and possibly USB UART dongles) PIN naming may be
incorrect. It is very common to have \texttt{GND} swapped with \texttt{RX}, thus,
motherboard ``\texttt{TX}'' must be connected to USB UART \texttt{GND}, and motherboard ``\texttt{GND}''
to USB UART \texttt{RX}.

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
\texttt{debug=0x8} boot argument is needed.

\subsection{Tips and Tricks}\label{troubleshootingtricks}

\begin{enumerate}
\item
  \textbf{How to debug boot failure?}

  Normally it is enough to obtain the actual error message. For this
  ensure that:
  \begin{itemize}
  \tightlist
  \item A \texttt{DEBUG} or \texttt{NOOPT} version of OpenCore is used.
  \item Logging is enabled (\texttt{1}) and shown onscreen (\texttt{2}):
  \texttt{Misc} $\rightarrow$ \texttt{Debug} $\rightarrow$ \texttt{Target}
  $=$ \texttt{3}.
  \item Logged messages from at least \texttt{DEBUG\_ERROR}
  (\texttt{0x80000000}), \texttt{DEBUG\_WARN} (\texttt{0x00000002}), and
  \texttt{DEBUG\_INFO} (\texttt{0x00000040}) levels are visible onscreen:
  \texttt{Misc} $\rightarrow$ \texttt{Debug} $\rightarrow$ \texttt{DisplayLevel}
  $=$ \texttt{0x80000042}.
  \item Critical error messages, such as \texttt{DEBUG\_ERROR}, stop booting:
  \texttt{Misc} $\rightarrow$ \texttt{Security}
  $\rightarrow$ \texttt{HaltLevel} $=$ \texttt{0x80000000}.
  \item Watch Dog is disabled to prevent automatic reboot:
  \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}.
  \end{itemize}

  If there is no obvious error, check the available hacks in \texttt{Quirks} sections
  one by one. For early boot troubleshooting, for instance, when OpenCore menu does not appear,
  using \texttt{UEFI Shell} (bundled with OpenCore) may help to see
  early debug messages.

\item
  \textbf{How to debug macOS boot failure?}

  \begin{itemize}
  \tightlist
  \item Refer to \texttt{boot-args} values such as \texttt{debug=0x100}, \texttt{keepsyms=1},
    \texttt{-v}, and similar.
  \item Do not forget about \texttt{AppleDebug} and \texttt{ApplePanic} properties.
  \item Take care of \texttt{Booter}, \texttt{Kernel}, and \texttt{UEFI} quirks.
  \item Consider using serial port to inspect early kernel boot failures. For this
    \texttt{debug=0x108}, \texttt{serial=5}, and \texttt{msgbuf=1048576} boot arguments are needed.
    Refer to the patches in Sample.plist when dying before serial init.
  \item Always read the logs carefully.
  \end{itemize}

\item
  \textbf{How to customise boot entries?}

  OpenCore follows standard Apple Bless model and extracts the entry name
  from \texttt{.contentDetails} and \texttt{.disk\_label.contentDetails} files in the
  booter directory if present. These files contain an ASCII string with an entry title,
  which may then be customised by the user.

\item
  \textbf{How to choose the default boot entry?}

  OpenCore uses the primary UEFI boot option to select the default entry. This choice
  can be altered from UEFI Setup, with the macOS
  \href{https://support.apple.com/HT202796}{Startup Disk} preference, or the Windows
  \href{https://support.apple.com/guide/bootcamp-control-panel/start-up-your-mac-in-windows-or-macos-bcmp29b8ac66/mac}{Boot Camp} Control Panel.
  Since choosing OpenCore's \texttt{BOOTx64.EFI} as a primary boot option limits this
  functionality in addition to several types of firmware deleting incompatible boot options,
  potentially including those created by macOS, users are strongly encouraged to use the
  \texttt{RequestBootVarRouting} quirk, which will preserve the selection made in
  the operating system within the OpenCore variable space. Note, that \texttt{RequestBootVarRouting}
  requires a separate driver for functioning.

\item \label{reinstallmacos}
  \textbf{What is the simplest way to install macOS?}

  Copy online recovery image (\texttt{*.dmg} and \texttt{*.chunklist} files)
  to \texttt{com.apple.recovery.boot} directory on a FAT32 partition with OpenCore.
  Load OpenCore Boot Picker and choose the entry, it will have a \texttt{(dmg)} suffix.
  Custom name may be created by providing \texttt{.contentDetails} file.

  To download recovery online
  \href{https://github.com/acidanthera/OpenCorePkg/blob/master/Utilities/macrecovery/macrecovery.py}{macrecovery.py}
  can be used.

  For offline installation refer to
  \href{https://support.apple.com/HT201372}{How to create a bootable installer for macOS}
  article. Apart from App Store and \texttt{softwareupdate} utility there also are
  \href{https://github.com/corpnewt/gibMacOS}{third-party utilities} to download an offline image.

\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.

\item
  \textbf{Can I use this on Apple hardware or virtual machines?}

  Sure, most relatively modern Mac models including \texttt{MacPro5,1} and virtual machines
  are fully supported. Even though there are little to none specific details relevant to
  Mac hardware, some ongoing instructions can be found on
  \href{https://forums.macrumors.com/threads/opencore-on-the-mac-pro.2207814}{MacRumors.com}.

\item
  \textbf{Why must Find\&Replace patches be equal in size?}

  For machine code (x86 code) it is not possible to do differently sized 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} or in the ACPI section of this document.

\item
  \textbf{How can I decide which \texttt{Booter} quirks to use?}

  These quirks originate from \texttt{AptioMemoryFix} driver but provide a wider
  set of changes specific to modern systems. Note, that \texttt{OpenRuntime}
  driver is required for most configurations. To get a configuration similar
  to \texttt{AptioMemoryFix} the following set of quirks should be enabled:
  \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{ProtectMemoryRegions}
  \item \texttt{ProvideCustomSlide}
  \item \texttt{RebuildAppleMemoryMap}
  \item \texttt{SetupVirtualMap}
  \end{itemize}

  However, as of today, such set is strongly discouraged as some of these quirks
  are not necessary to be enabled or need additional quirks. For example,
  \texttt{DevirtualiseMmio} and \texttt{ProtectUefiServices} are often required,
  while \texttt{DiscardHibernateMap} and \texttt{ForceExitBootServices} are rarely
  necessary.

  Unfortunately for some quirks such as \texttt{RebuildAppleMemoryMap},
  \texttt{EnableWriteUnprotector}, \texttt{ProtectMemoryRegions},
  \texttt{SetupVirtualMap}, and \texttt{SyncRuntimePermissions} there
  is no definite approach even on similar systems, so trying all their
  combinations may be required for optimal setup. Refer to individual quirk
  descriptions in this document for more details.

\end{enumerate}

\end{document}