Bump version

Docs/Configuration.md5

-0a5f00c225c3bc5a7e0a5a57143640f7
+234bf876a6e9ec92239d908af9aae409

Docs/Configuration.tex

@@ -94,7 +94,7 @@
 
        \vspace{0.2in}
 
-       Reference Manual (0.7.8)
+       Reference Manual (0.7.9)
 
        \vspace{0.2in}
 

Docs/Differences/PreviousConfiguration.tex

@@ -94,7 +94,7 @@
 
        \vspace{0.2in}
 
-       Reference Manual (0.7.7)
+       Reference Manual (0.7.8)
 
        \vspace{0.2in}
 
@@ -3260,6 +3260,34 @@ the default boot entry choice will remain changed until the next manual reconfig
   option. Therefore, for significant implementation updates, such as was the case with OpenCore 0.6.4,
   an NVRAM reset should be executed with \texttt{Bootstrap} disabled, after which it can be re-enabled.
 
+  \emph{Note 3}: Some versions of Intel Visual BIOS (e.g. on Intel NUC) have an unfortunate bug whereby if any boot
+  option is added referring to a path on a USB drive, from then on that is the only boot option which will be shown
+  when any USB drive is inserted. If OpenCore is started from a USB drive on this firmware with
+  \texttt{LauncherOption} set to \texttt{Full} or \texttt{Short}, this applies and only the OpenCore boot entry will be
+  seen afterwards, when any other USB is inserted (this highly non-standard BIOS behaviour affects other software as well).
+  The best way to avoid this is to leave \texttt{LauncherOption} set to \texttt{Disabled} or \texttt{System} on any
+  version of OpenCore which will be started from a USB drive on this firmware. If the problem has already
+  occurred the quickest reliable fix is:
+  \begin{itemize}
+  \tightlist
+    \item Enable the system UEFI Shell in Intel Visual BIOS
+    \item With power off, insert an OpenCore USB
+    \item Power up and select the system UEFI Shell
+    \item Since the system shell does not include \texttt{bcfg}, use the system shell to start OpenCore's OpenShell
+    (e.g. by entering the command \texttt{FS2:\textbackslash EFI\textbackslash OC\textbackslash Tools\textbackslash OpenShell.efi} ,
+    but you will need to work out which drive is correct for OpenCore and modify the drive number \texttt{FS\#:} accordingly)
+    \item Within OpenShell, use \texttt{bcfg boot dump} to display the NVRAM boot options and then use \texttt{bcfg boot rm \#}
+    (where \texttt{\#} is the number of the OpenCore boot entry) to remove the OpenCore entry
+  \end{itemize}
+  It is alternatively possible to start OpenShell directly from the OpenCore boot menu, if you have
+  a working configured OpenCore for the system. In that case, and if OpenCore has \texttt{RequestBootVarRouting} enabled, it will be
+  necessary to run the command \texttt{\textbackslash EFI\textbackslash OC\textbackslash Tools\textbackslash OpenControl.efi disable}
+  before using \texttt{bcfg}. (After \texttt{OpenControl disable}, it is necessary to either reboot or run \texttt{OpenControl restore},
+  before booting an operating system.)
+  It is also possible to use \texttt{efibootmgr} within Linux to remove the offending entry, if you have a working
+  version of Linux on the machine. Linux must be started either not via OpenCore, or via OpenCore with \texttt{RequestBootVarRouting} disabled
+  for this to work.
+  
 \item
   \texttt{LauncherPath}\\
   \textbf{Type}: \texttt{plist\ string}\\
@@ -3314,12 +3342,13 @@ the default boot entry choice will remain changed until the next manual reconfig
     OpenCore 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
+  \item \texttt{0x0002} --- \texttt{OC\_ATTR\_USE\_DISK\_LABEL\_FILE}, use custom
     prerendered titles for boot entries from \texttt{.disk\_label} (\texttt{.disk\_label\_2x})
     file next to the bootloader for all filesystems.
-    Prerendered labels can be generated via the \texttt{disklabel} utility or the \texttt{bless} command.
-    When disabled or missing, label text in (\texttt{.contentDetails}
-    or \texttt{.disk\_label.contentDetails}) will be rendered if present instead, otherwise
+    These labels can be generated via the \texttt{disklabel} utility or the
+    \texttt{bless -{}-folder \{FOLDER\_PATH\} -{}-label \{LABEL\_TEXT\}} command.
+    When prerendered labels are disabled or missing, use label text in \texttt{.contentDetails}
+    (or \texttt{.disk\_label.contentDetails}) file next to bootloader if present instead, otherwise
     the entry name itself will be rendered.
   \item \texttt{0x0004} --- \texttt{OC\_ATTR\_USE\_GENERIC\_LABEL\_IMAGE}, provides predefined
     label images for boot entries without custom entries. This may however give less detail for
@@ -3346,10 +3375,11 @@ the default boot entry choice will remain changed until the next manual reconfig
     \begin{itemize}
     \tightlist
       \item For a Tool the value is read from \texttt{Flavour} field.
-      \item For an automatically discovered entry it is read from the \texttt{.contentFlavour}
+      \item For an automatically discovered entry, including for boot entry protocol entries such as those
+      generated by the OpenLinuxBoot driver, it is read from the \texttt{.contentFlavour}
       file next to the bootloader, if present.
-      \item For a custom entry it is read from the \texttt{.contentFlavour} file next to the
-      bootloader if \texttt{Flavour} is \texttt{Auto}, otherwise specified via the \texttt{Flavour}
+      \item For a custom entry specified in the \texttt{Entries} section it is read from the \texttt{.contentFlavour} file next to the
+      bootloader if \texttt{Flavour} is \texttt{Auto}, otherwise it is specified via the \texttt{Flavour}
       value itself.
       \item If read flavour is \texttt{Auto} or there is no \texttt{.contentFlavour}, entry
       flavour is chosen based on the entry type (e.g. Windows automatically gets Windows flavour).
@@ -3852,30 +3882,27 @@ nvram 4D1FDA02-38C7-4A6A-9CC6-4BCCA8B30102:boot-log |
   entry for disabling and enabling System Integrity Protection in OpenCore picker.
 
   This will toggle Apple NVRAM variable \texttt{csr-active-config} between \texttt{0} for
-  SIP Enabled and a practical default value for SIP Disabled (currently \texttt{0x26F}).
+  SIP Enabled and a practical default value for SIP Disabled.
 
   \emph{Note 1}: It is strongly recommended not to make a habit of running macOS with
   SIP disabled. Use of this boot option may make it easier to quickly disable SIP
   protection when genuinely needed - it should be re-enabled again afterwards.
 
-  \emph{Note 2}: OpenCore uses \texttt{0x26F} even though \texttt{csrutil disable} on Big Sur
-  sets \texttt{0x7F}. To explain the choice:
+  \emph{Note 2}: OpenCore uses \texttt{0x27F} while \texttt{csrutil disable} on macOS Big Sur
+  and Monterey sets \texttt{0x7F}.
   \begin{itemize}
   \tightlist
-  \item \texttt{csrutil disable -{}-no-internal} actually sets \texttt{0x6F}, and this is
-  preferable because \texttt{CSR\_ALLOW\_APPLE\_INTERNAL} (\texttt{0x10}) prevents updates
-  (unless you are running an internal build of macOS).
   \item \texttt{CSR\_ALLOW\_UNAPPROVED\_KEXTS} (\texttt{0x200}) is generally useful, in the case
-  where you do need to have SIP disabled, as it allows installing unsigned kexts without manual
-  approval in System Preferences.
-  \item \texttt{CSR\_ALLOW\_UNAUTHENTICATED\_ROOT} (\texttt{0x800}) is not practical as it prevents
-  incremental (non-full) OTA updates.
+  where you do need to have SIP disabled anyway, as it allows installing unsigned kexts without
+  manual approval in System Preferences.
+  \item \texttt{CSR\_ALLOW\_UNAUTHENTICATED\_ROOT} (\texttt{0x800}) is not included, as it is
+  very easy when using it to inadvertently break OS seal and prevent incremental OTA updates.
   \end{itemize}
 
   \emph{Note3}: For any other value which you may need to use, it is possible to
   configure \texttt{CsrUtil.efi} as a \texttt{TextMode} \texttt{Tools} entry to configure a
-  different value, e.g. use \texttt{toggle\ 0x6F} in \texttt{Arguments} to toggle the
-  SIP disabled value set by default by \texttt{csrutil disable -{}-no-internal} in Big Sur.
+  different value, e.g. use \texttt{toggle\ 0x77} in \texttt{Arguments} to toggle the
+  SIP disabled value set by default in macOS Catalina.
 
 \item
   \texttt{ApECID}\\
@@ -6322,19 +6349,32 @@ failure (typically halting with a black screen) of the Linux kernel, due to a fi
 firmware released after 2017. When present and not mitigated by this quirk, this affects booting
 via OpenCore with or without OpenLinuxBoot.
 
-After installing OpenLinuxBoot, it is recommended to compare the Linux boot options (shown with \texttt{cat /proc/cmdline})
-seen when booting via OpenLinuxBoot and via the distro's original bootloader. If the default bootloader
-is GRUB, expect the options generated by OpenLinuxBoot not to
-contain a \texttt{BOOT\_IMAGE=...} value where the GRUB options do, and to contain an
-\texttt{initrd=...} value while the GRUB options do not.
-All remaining options should match (option order does not matter) -- perhaps excluding less important graphics
-handover options (such as in the Ubuntu example given in \texttt{autoopts} below). If they do not, it is recommended
-to manually add the missing options, e.g. with \texttt{partuuidopts:\{partuuid\}+=\{opts\}} to target a specific
-distro (or just with \texttt{autoopts+=\{opts\}}, which applies to all installed distros, if only one distro is in use).
+After installing OpenLinuxBoot, it is recommended to compare the options shown in the OpenCore debug
+log when booting (or attempting to boot) a given distro against the options seen using the shell command
+\texttt{cat /proc/cmdline} when the same distro has been booted via its native bootloader.
+In general (for safety and security of the running distro) these options should match, and if they do not
+it is recommended to use the driver arguments below (in particular \texttt{LINUX\_BOOT\_ADD\_RO},
+\texttt{LINUX\_BOOT\_ADD\_RW}, \texttt{partuuidopts} and \texttt{autoopts}) to modify the options as required.
+Note however that the following differences are normal and do not need to be fixed:
+\begin{itemize}
+\tightlist
+  \item
+  If the default bootloader is GRUB then the options generated by OpenLinuxBoot will not contain a
+  \texttt{BOOT\_IMAGE=...} value where the GRUB options do, and will contain an \texttt{initrd=...}
+  value where the GRUB options do not.
+  \item
+  OpenLinuxBoot uses \texttt{PARTUUID} rather than filesystem \texttt{UUID} to identify the location
+  of \texttt{initrd}, this is by design as UEFI filesystem drivers do not make Linux filesystem
+  \texttt{UUID} values available.
+  \item
+  Less important graphics handover options (such as discussed in the Ubuntu example
+  given in \texttt{autoopts} below) will not match exactly, this is not important as long
+  as distro boots successfully.
+\end{itemize}
 
 If using OpenLinuxBoot with Secure Boot, users may wish to use the \texttt{shim-to-cert.tool} included in OpenCore
-utilities, which can be used to extract the required public key to validate a distro's kernels directly, rather
-than via shim. For non-GRUB distros, the required public key must be found by user research.
+utilities, which can be used to extract the public key needed to boot a distro's kernels directly, as done when using OpenCore
+with OpenLinuxBoot, rather than via GRUB shim. For non-GRUB distros, the required public key must be found by user research.
 
 \subsubsection{Configuration}
 
@@ -6390,13 +6430,24 @@ options for the driver may be specified in \texttt{UEFI/Drivers/Arguments}:
 	  \emph{Note}: This option is recommended on all systems. \medskip
 
 	  \item \texttt{0x00000400} (bit \texttt{10}) --- \texttt{LINUX\_BOOT\_ADD\_RO},
-	  This option applies to autodetected Linux only (i.e. to Debian-style distrubutions, not to BLSpec and
-    Fedora-style distributions with \texttt{/loader/entries/*.conf} files).
-    Some distrubtions run a filesystem check on loading which requires the root
-    filesystem to initially be mounted read-only via the \texttt{ro} kernel option. Set this bit to add this
+	  This option applies to autodetected Linux only (i.e. not to BLSpec or
+    Fedora-style distributions which have \texttt{/loader/entries/*.conf} files).
+    Some distributions run a filesystem check on loading which requires the root
+    filesystem to initially be mounted read-only via the \texttt{ro} kernel option, which requires this
+    option to be added to the autodetected options. Set this bit to add this
     option on autodetected distros; should be harmless but very slightly slow down boot time (due to requried
-    remount as read-write) on distros which do not require it. To specify this option for specific
-    distros only, use \texttt{partuuidopts:\{partuuid\}+=ro} instead of this flag.
+    remount as read-write) on distros which do not require it.
+    When there are multiple distros and it is required to specify this option for specific distros only, use
+    \texttt{partuuidopts:\{partuuid\}+=ro} to manually add the option where required, instead of using this flag.
+
+	  \item \texttt{0x00000800} (bit \texttt{11}) --- \texttt{LINUX\_BOOT\_ADD\_RW},
+	  Like \texttt{LINUX\_BOOT\_ADD\_RO}, this option applies to autodetected Linux only. It is not
+    required for most distros (which usually require either \texttt{ro} or nothing to be added to
+    detected boot options), but is required on some Arch-derived distros, e.g. EndeavourOS.
+    When there are multiple distros and it is required to specify this option for specific distros only, use
+    \texttt{partuuidopts:\{partuuid\}+=rw} to manually add the option where required, instead of using this flag.
+    If this option and \texttt{LINUX\_BOOT\_ADD\_RO} are both specified, only this option is applied
+    and \texttt{LINUX\_BOOT\_ADD\_RO} is ignored.
 
 	  \item \texttt{0x00002000} (bit \texttt{13}) --- \texttt{LINUX\_BOOT\_ALLOW\_CONF\_AUTO\_ROOT},
 	  In some instances of \texttt{BootLoaderSpecByDefault} in combination with \texttt{ostree}, the
@@ -6414,7 +6465,9 @@ options for the driver may be specified in \texttt{UEFI/Drivers/Arguments}:
   \end{itemize} \medskip
 
 	Flag values can be specified in hexadecimal beginning with \texttt{0x} or in decimal,
-  e.g. \texttt{flags=0x80} or \texttt{flags=128}. \medskip
+  e.g. \texttt{flags=0x80} or \texttt{flags=128}. It is also possible to specify flags to
+  add or remove, using syntax such as \texttt{flags+=0xC000} to add all debugging
+  options or \texttt{flags-=0x400} to remove the \texttt{LINUX\_BOOT\_ADD\_RO} option. \medskip
 
 	\item \texttt{partuuidopts:\{partuuid\}[+]="\{options\}"} - Default: not set. \medskip
 

Include/Acidanthera/Library/OcMainLib.h

@@ -31,7 +31,7 @@
   OpenCore version reported to log and NVRAM.
   OPEN_CORE_VERSION must follow X.Y.Z format, where X.Y.Z are single digits.
 **/
-#define OPEN_CORE_VERSION          "0.7.8"
+#define OPEN_CORE_VERSION          "0.7.9"
 
 /**
   OpenCore build type reported to log and NVRAM.