OcBootManagementLib: Add InstanceIdentifier, and ability to target .c…

…ontentVisibility to specific instances

Changelog.md

@@ -1,5 +1,8 @@
 OpenCore Changelog
 ==================
+#### v0.9.4
+- Add `InstanceIdentifier` and option to target `.contentVisibility` to specific instances
+
 #### v0.9.3
 - Added `--force-codec` option to AudioDxe, thx @xCuri0
 - Downgraded additional warning message in normal operation of emulated NVRAM to info

Docs/Configuration.tex

@@ -3125,6 +3125,8 @@ \subsection{Introduction}\label{miscintro}
 \end{itemize} \medskip
 \end{itemize}
 
+\subsubsection{Boot Algorithm}\label{bootalgorithm}
+
 The algorithm to determine boot options behaves as follows:
 
 \begin{enumerate}
@@ -3146,12 +3148,14 @@ \subsection{Introduction}\label{miscintro}
   \item For file device paths, check for presence on the file system directly.
   % Just kill all \EFI\APPLE\ paths.
   \item Exclude entries if there is a \texttt{.contentVisibility} file near the bootloader or
-  inside the boot directory with \texttt{Disabled} contents (ASCII).
+  inside the boot directory with \texttt{Disabled} contents (ASCII) (and if the current
+  \texttt{InstanceIentifier} matches an \texttt{Instance-List} if present, see following).
   \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)
-  or if its \texttt{.contentVisibility} file contains \texttt{Auxiliary}.
+  or if its \texttt{.contentVisibility} file contains \texttt{Auxiliary} (and if the current
+  \texttt{InstanceIentifier} matches an \texttt{Instance-List} if present, see following).
   \end{itemize}
 \item For each partition handle:
   \begin{itemize}
@@ -3169,6 +3173,16 @@ \subsection{Introduction}\label{miscintro}
 \item System entries, such as \texttt{Reset NVRAM}, are added as primary auxiliary options.
 \end{enumerate}
 
+The \texttt{.contentVisibility} file, when present, may optionally target only specific instances
+of OpenCore. Its contents are \texttt{(Disabled|Auxiliary)[:\{Instance-List\}]}.
+If a colon (\texttt{:}) is present, the \texttt{Instance-List} following it is a comma separated
+list of \texttt{InstanceIdentifier} values.
+When this list is present, the specified visibility is only applied if the
+\texttt{InstanceIdentifier} value of the current instance of OpenCore is present in the list.
+When the list is not present, the specified visibility is applied for all instances of OpenCore.
+(For any instance of OpenCore with no \texttt{InstanceIdentifier} value, the specified visibility
+from a \texttt{.contentVisibility} file with an \texttt{Instance-List} will never be applied.)
+
 The display order of the boot options in the OpenCore picker and the boot process
 are determined separately from the scanning algorithm.
 
@@ -3391,6 +3405,17 @@ \subsection{Boot Properties}\label{miscbootprops}
   To display all entries, the picker menu can be reloaded into ``Extended Mode'' by pressing the
   \texttt{Spacebar} key. Hiding auxiliary entries may increase boot performance on multi-disk systems.
 
+
+\item
+  \texttt{InstanceIdentifier}\\
+  \textbf{Type}: \texttt{plist\ string}\\
+  \textbf{Failsafe}: Empty\\
+  \textbf{Description}: An optional identifier for the current instance of OpenCore.
+
+  This should typically be a short alphanumeric string. The current use of this value is
+  to optionally target \texttt{.contentVisibility} files to specific instances of OpenCore,
+  as explained in the \hyperref[bootalgorithm]{Boot Algorithm} section.
+
 \item
   \texttt{LauncherOption}\\
   \textbf{Type}: \texttt{plist\ string}\\

Docs/Sample.plist

@@ -1084,6 +1084,8 @@
 			<false/>
 			<key>HideAuxiliary</key>
 			<true/>
+			<key>InstanceIdentifier</key>
+			<string></string>
 			<key>LauncherOption</key>
 			<string>Disabled</string>
 			<key>LauncherPath</key>

Docs/SampleCustom.plist

@@ -1084,6 +1084,8 @@
 			<false/>
 			<key>HideAuxiliary</key>
 			<true/>
+			<key>InstanceIdentifier</key>
+			<string></string>
 			<key>LauncherOption</key>
 			<string>Disabled</string>
 			<key>LauncherPath</key>

Include/Acidanthera/Library/OcBootManagementLib.h

@@ -31,6 +31,11 @@
 #define OC_TRACE_PARSE_VARS  DEBUG_VERBOSE
 #endif
 
+/**
+  Maximum safe instance identifier size.
+**/
+#define OC_MAX_INSTANCE_IDENTIFIER_SIZE  64
+
 /**
   Primary picker context.
 **/
@@ -935,6 +940,10 @@ struct OC_PICKER_CONTEXT_ {
   //
   CONST CHAR8                 *PickerVariant;
   //
+  // Boot loader instance identifier.
+  //
+  CONST CHAR8                 *InstanceIdentifier;
+  //
   // Enable polling boot arguments.
   //
   BOOLEAN                     PollAppleHotKeys;

Include/Acidanthera/Library/OcConfigurationLib.h

@@ -335,6 +335,7 @@ OC_DECLARE (OC_MISC_BLESS_ARRAY)
 #define OC_MISC_BOOT_FIELDS(_, __) \
   _(OC_STRING                   , PickerMode                  ,     , OC_STRING_CONSTR ("Builtin", _, __) , OC_DESTR (OC_STRING)) \
   _(OC_STRING                   , HibernateMode               ,     , OC_STRING_CONSTR ("None", _, __)    , OC_DESTR (OC_STRING)) \
+  _(OC_STRING                   , InstanceIdentifier          ,     , OC_STRING_CONSTR ("", _, __)        , OC_DESTR (OC_STRING)) \
   _(OC_STRING                   , LauncherOption              ,     , OC_STRING_CONSTR ("Disabled", _, __), OC_DESTR (OC_STRING) ) \
   _(OC_STRING                   , LauncherPath                ,     , OC_STRING_CONSTR ("Default", _, __) , OC_DESTR (OC_STRING) ) \
   _(UINT32                      , ConsoleAttributes           ,     , 0                                   , ())                   \

Include/Acidanthera/Protocol/OcBootEntry.h

@@ -28,7 +28,7 @@
 
   WARNING: This protocol is currently undergoing active design.
 **/
-#define OC_BOOT_ENTRY_PROTOCOL_REVISION  3
+#define OC_BOOT_ENTRY_PROTOCOL_REVISION  4
 
 /**
   Forward declaration of OC_BOOT_ENTRY_PROTOCOL structure.

Include/Acidanthera/Protocol/OcInterface.h

@@ -24,7 +24,7 @@
 
   WARNING: This protocol is currently undergoing active design.
 **/
-#define OC_INTERFACE_REVISION  8
+#define OC_INTERFACE_REVISION  9
 
 /**
   The GUID of the OC_INTERFACE_PROTOCOL.

Library/OcBootManagementLib/BootEntryManagement.c

@@ -200,7 +200,8 @@ STATIC
 INTERNAL_ENTRY_VISIBILITY
 ReadEntryVisibility (
   IN EFI_DEVICE_PATH_PROTOCOL  *DevicePath,
-  IN BOOLEAN                   IsFolder
+  IN BOOLEAN                   IsFolder,
+  IN CONST CHAR8               *InstanceIdentifier
   )
 {
   EFI_STATUS                       Status;
@@ -213,6 +214,8 @@ ReadEntryVisibility (
   CHAR16                           *VisibilityTerminator;
   BOOLEAN                          Result;
   CHAR8                            *Visibility;
+  CHAR8                            *Walker;
+  UINTN                            IdentifierLength;
 
   Status = gBS->LocateDevicePath (
                   &gEfiSimpleFileSystemProtocolGuid,
@@ -280,14 +283,44 @@ ReadEntryVisibility (
   //
   // Note, this guarantees nul-termination.
   //
-  Visibility = OcReadFile (FileSystem, VisibilityPath, NULL, 64);
+  Visibility = OcReadFile (FileSystem, VisibilityPath, NULL, 512);
 
   FreePool (VisibilityPath);
 
   if (Visibility == NULL) {
     return BootEntryNormal;
   }
 
+  Walker = AsciiStrStr (Visibility, ":");
+  if (Walker != NULL) {
+    *Walker++ = '\0';
+    if ((*Walker == '\0') || (*InstanceIdentifier == '\0')) {
+      FreePool (Visibility);
+      return BootEntryNormal;
+    }
+
+    IdentifierLength = AsciiStrLen (InstanceIdentifier);
+    Status           = EFI_NOT_FOUND;
+    do {
+      if (  (AsciiStrnCmp (Walker, InstanceIdentifier, IdentifierLength) == 0)
+         && ((Walker[IdentifierLength] == '\0') || (Walker[IdentifierLength] == ',')))
+      {
+        Status = EFI_SUCCESS;
+        break;
+      }
+
+      Walker = AsciiStrStr (Walker, ",");
+      if (Walker != NULL) {
+        ++Walker;
+      }
+    } while (Walker != NULL);
+
+    if (EFI_ERROR (Status)) {
+      FreePool (Visibility);
+      return BootEntryNormal;
+    }
+  }
+
   if (AsciiStrnCmp (Visibility, "Disabled", L_STR_LEN ("Disabled")) == 0) {
     FreePool (Visibility);
     return BootEntryDisabled;
@@ -487,7 +520,7 @@ AddBootEntryOnFileSystem (
   //
   // Skip disabled entries, like OpenCore bootloader.
   //
-  Visibility = ReadEntryVisibility (DevicePath, IsFolder);
+  Visibility = ReadEntryVisibility (DevicePath, IsFolder, BootContext->PickerContext->InstanceIdentifier);
   if (Visibility == BootEntryDisabled) {
     DEBUG ((DEBUG_INFO, "OCB: Discarding disabled entry by visibility\n"));
     if (IsReallocated) {

Library/OcConfigurationLib/OcConfigurationLib.c

@@ -410,6 +410,7 @@ OC_SCHEMA
   OC_SCHEMA_STRING_IN ("HibernateMode",         OC_GLOBAL_CONFIG, Misc.Boot.HibernateMode),
   OC_SCHEMA_BOOLEAN_IN ("HibernateSkipsPicker", OC_GLOBAL_CONFIG, Misc.Boot.HibernateSkipsPicker),
   OC_SCHEMA_BOOLEAN_IN ("HideAuxiliary",        OC_GLOBAL_CONFIG, Misc.Boot.HideAuxiliary),
+  OC_SCHEMA_STRING_IN ("InstanceIdentifier",    OC_GLOBAL_CONFIG, Misc.Boot.InstanceIdentifier),
   OC_SCHEMA_STRING_IN ("LauncherOption",        OC_GLOBAL_CONFIG, Misc.Boot.LauncherOption),
   OC_SCHEMA_STRING_IN ("LauncherPath",          OC_GLOBAL_CONFIG, Misc.Boot.LauncherPath),
   OC_SCHEMA_INTEGER_IN ("PickerAttributes",     OC_GLOBAL_CONFIG, Misc.Boot.PickerAttributes),

Library/OcMainLib/OpenCoreMisc.c

@@ -790,6 +790,7 @@ OcMiscBoot (
   CHAR16                  **BlessOverride;
   CONST CHAR8             *AsciiPicker;
   CONST CHAR8             *AsciiPickerVariant;
+  CONST CHAR8             *AsciiInstanceIdentifier;
   CONST CHAR8             *AsciiDmg;
 
   AsciiPicker = OC_BLOB_GET (&Config->Misc.Boot.PickerMode);
@@ -805,7 +806,8 @@ OcMiscBoot (
     PickerMode = OcPickerModeBuiltin;
   }
 
-  AsciiPickerVariant = OC_BLOB_GET (&Config->Misc.Boot.PickerVariant);
+  AsciiPickerVariant      = OC_BLOB_GET (&Config->Misc.Boot.PickerVariant);
+  AsciiInstanceIdentifier = OC_BLOB_GET (&Config->Misc.Boot.InstanceIdentifier);
 
   AsciiDmg = OC_BLOB_GET (&Config->Misc.Security.DmgLoading);
 
@@ -934,6 +936,7 @@ OcMiscBoot (
   Context->ConsoleAttributes    = Config->Misc.Boot.ConsoleAttributes;
   Context->PickerAttributes     = Config->Misc.Boot.PickerAttributes;
   Context->PickerVariant        = AsciiPickerVariant;
+  Context->InstanceIdentifier   = AsciiInstanceIdentifier;
   Context->BlacklistAppleUpdate = Config->Misc.Security.BlacklistAppleUpdate;
 
   if ((Config->Misc.Security.ExposeSensitiveData & OCS_EXPOSE_VERSION_UI) != 0) {

Utilities/ocvalidate/ValidateMisc.c

@@ -183,6 +183,42 @@ CheckBlessOverride (
   return ErrorCount;
 }
 
+STATIC
+UINT32
+ValidateInstanceIdentifier (
+  IN CONST CHAR8  *InstanceIdentifier
+  )
+{
+  UINT32  ErrorCount;
+  CHAR8   InstanceIdentifierCopy[OC_MAX_INSTANCE_IDENTIFIER_SIZE];
+  UINTN   Length;
+
+  ErrorCount = 0;
+
+  if (AsciiStrSize (InstanceIdentifier) > OC_MAX_INSTANCE_IDENTIFIER_SIZE) {
+    DEBUG ((DEBUG_WARN, "Misc->Boot->InstanceIdentifier cannot be longer than %d bytes!\n", OC_MAX_INSTANCE_IDENTIFIER_SIZE));
+    ++ErrorCount;
+  } else {
+    if (AsciiStrStr (InstanceIdentifier, ",") != NULL) {
+      DEBUG ((DEBUG_WARN, "Misc->Boot->InstanceIdentifier cannot contain comma (,)!\n"));
+      ++ErrorCount;
+    }
+
+    //
+    // Illegal chars
+    //
+    Length = AsciiStrLen (InstanceIdentifier);
+    AsciiStrnCpyS (InstanceIdentifierCopy, OC_MAX_INSTANCE_IDENTIFIER_SIZE, InstanceIdentifier, Length);
+    AsciiFilterString (InstanceIdentifierCopy, TRUE);
+    if (OcAsciiStrniCmp (InstanceIdentifierCopy, InstanceIdentifier, Length) != 0) {
+      DEBUG ((DEBUG_WARN, "Misc->Boot->InstanceIdentifier cannot contain CR, LF, TAB or any other non-ASCII characters!\n"));
+      ++ErrorCount;
+    }
+  }
+
+  return ErrorCount;
+}
+
 STATIC
 UINT32
 CheckMiscBoot (
@@ -199,6 +235,7 @@ CheckMiscBoot (
   BOOLEAN               HasOpenCanopyEfiDriver;
   CONST CHAR8           *PickerMode;
   CONST CHAR8           *PickerVariant;
+  CONST CHAR8           *InstanceIdentifier;
   UINTN                 PVSumSize;
   UINTN                 PVPathFixedSize;
   BOOLEAN               IsPickerAudioAssistEnabled;
@@ -258,6 +295,9 @@ CheckMiscBoot (
     ++ErrorCount;
   }
 
+  InstanceIdentifier = OC_BLOB_GET (&Config->Misc.Boot.InstanceIdentifier);
+  ErrorCount        += ValidateInstanceIdentifier (InstanceIdentifier);
+
   //
   // Check the length of path relative to OC directory.
   //