OcMainLib: Add UEFI/Unload config option to unload existing firmware …

…drivers

Changelog.md

@@ -2,6 +2,7 @@ OpenCore Changelog
 ==================
 #### v1.0.2
 - Fixed error in macrecovery when running headless, thx @mkorje
+- Added `UEFI` `Unload` option to unload existing firmware drivers
 
 #### v1.0.1
 - Updated code and added progress bar to macrecovery, thx @soyeonswife63

Docs/Configuration.tex

@@ -7560,6 +7560,40 @@ \subsection{Properties}\label{uefiprops}
   could be the second 256 MB corrupted by the Intel HD 3000 or an area with faulty RAM.
   Refer to the \hyperref[uefirsvdprops]{ReservedMemory Properties} section below for details.
 
+\item
+  \texttt{Unload}\\
+  \textbf{Type}: \texttt{plist\ array}\\
+  \textbf{Failsafe}: Empty\\
+  \textbf{Description}: Unload specified firmware drivers.
+
+  To be filled with \texttt{plist\ string} entries containing
+  the names of firmware drivers to unload before loading the
+  \texttt{Drivers} section.
+  This setting is typically only required if a user-provided driver is a variant of
+  an existing system firmware driver, and if the new driver would detect itself
+  as partially loaded, or otherwise fail to operate correctly, if the old
+  driver is not unloaded first.
+
+  \textbf{Warning}: Unloading system firmware drivers is usually not required
+  and not recommended. Poorly written drivers may crash when
+  unloaded, or cause subsequent crashes (e.g by allowing themselves to be
+  unloaded even though they have active dependencies). However standard UEFI
+  network stack drivers should unload cleanly.
+
+  \emph{Note 1}: See \texttt{SysReport/Drivers/DriverImageNames.txt} for the
+  list of drivers which this option can attempt to unload.
+  The relevant name is the driver component name. Drivers are only listed if they
+  implement \texttt{DriverBindingProtocol} and \texttt{LoadedImageProtocol},
+  and have an available component name.
+
+  \emph{Note 2}: The NVRAM \texttt{Lang} and \texttt{PlatformLang} variables
+  are ignored when determining the driver component names recognised by this
+  option, and listed in the \texttt{SysReport} file. This is in order to make
+  unloading images stable across changes in these variables.
+  The UEFI Shell \texttt{dh} command takes account of these variables,
+  so in some circumstances may display different driver component names from
+  those listed for this option, unless these variables are cleared.
+
 \end{enumerate}
 
 \subsection{APFS Properties}\label{uefiapfsprops}

Docs/Sample.plist

@@ -2051,6 +2051,8 @@
 				<string>RuntimeCode</string>
 			</dict>
 		</array>
+		<key>Unload</key>
+		<array/>
 	</dict>
 </dict>
 </plist>

Docs/SampleCustom.plist

@@ -2419,6 +2419,8 @@
 				<string>RuntimeCode</string>
 			</dict>
 		</array>
+		<key>Unload</key>
+		<array/>
 	</dict>
 </dict>
 </plist>

Include/Acidanthera/Library/OcConfigurationLib.h

@@ -606,6 +606,13 @@ OC_DECLARE (OC_PLATFORM_CONFIG)
   Uefi section
 **/
 
+///
+/// Array of driver names to unload.
+///
+#define OC_UEFI_UNLOAD_ARRAY_FIELDS(_, __) \
+  OC_ARRAY (OC_STRING, _, __)
+OC_DECLARE (OC_UEFI_UNLOAD_ARRAY)
+
 ///
 /// Drivers is an ordered array of drivers to load.
 ///
@@ -782,7 +789,8 @@ OC_DECLARE (OC_UEFI_RSVD_ARRAY)
   _(OC_UEFI_OUTPUT              , Output            ,     , OC_CONSTR2 (OC_UEFI_OUTPUT, _, __)             , OC_DESTR (OC_UEFI_OUTPUT)) \
   _(OC_UEFI_PROTOCOL_OVERRIDES  , ProtocolOverrides ,     , OC_CONSTR2 (OC_UEFI_PROTOCOL_OVERRIDES, _, __) , OC_DESTR (OC_UEFI_PROTOCOL_OVERRIDES)) \
   _(OC_UEFI_QUIRKS              , Quirks            ,     , OC_CONSTR2 (OC_UEFI_QUIRKS, _, __)             , OC_DESTR (OC_UEFI_QUIRKS)) \
-  _(OC_UEFI_RSVD_ARRAY          , ReservedMemory    ,     , OC_CONSTR2 (OC_UEFI_RSVD_ARRAY, _, __)         , OC_DESTR (OC_UEFI_RSVD_ARRAY))
+  _(OC_UEFI_RSVD_ARRAY          , ReservedMemory    ,     , OC_CONSTR2 (OC_UEFI_RSVD_ARRAY, _, __)         , OC_DESTR (OC_UEFI_RSVD_ARRAY)) \
+  _(OC_UEFI_UNLOAD_ARRAY        , Unload            ,     , OC_CONSTR2 (OC_UEFI_UNLOAD_ARRAY, _, __)       , OC_DESTR (OC_UEFI_UNLOAD_ARRAY))
 OC_DECLARE (OC_UEFI_CONFIG)
 
 /**

Include/Acidanthera/Library/OcMainLib.h

@@ -428,4 +428,26 @@ OcPlatformIs64BitSupported (
   IN UINT32  KernelVersion
   );
 
+/**
+  Unload loaded images by name.
+
+  @param[in]  Config     OpenCore configuration.
+**/
+VOID
+OcUnloadDrivers (
+  IN  OC_GLOBAL_CONFIG  *Config
+  );
+
+/**
+  Dump loaded image driver info to the specified directory.
+
+  @param[in]  Root     Directory to write CPU data.
+
+  @retval EFI_SUCCESS on success.
+**/
+EFI_STATUS
+OcDriverInfoDump (
+  IN EFI_FILE_PROTOCOL  *Root
+  );
+
 #endif // OC_MAIN_LIB

Library/OcConfigurationLib/OcConfigurationLib.c

@@ -73,6 +73,7 @@ OC_STRUCTORS (OC_PLATFORM_NVRAM_CONFIG, ())
 OC_STRUCTORS (OC_PLATFORM_SMBIOS_CONFIG, ())
 OC_STRUCTORS (OC_PLATFORM_CONFIG, ())
 
+OC_ARRAY_STRUCTORS (OC_UEFI_UNLOAD_ARRAY)
 OC_STRUCTORS (OC_UEFI_DRIVER_ENTRY, ())
 OC_ARRAY_STRUCTORS (OC_UEFI_DRIVER_ARRAY)
 OC_STRUCTORS (OC_UEFI_APFS, ())
@@ -852,6 +853,10 @@ STATIC
 OC_SCHEMA
   mUefiReservedMemorySchema = OC_SCHEMA_DICT (NULL, mUefiReservedMemoryEntrySchema);
 
+STATIC
+OC_SCHEMA
+  mMiscUnloadImagesSchema = OC_SCHEMA_STRING (NULL);
+
 STATIC
 OC_SCHEMA
   mUefiConfigurationSchema[] = {
@@ -865,6 +870,7 @@ OC_SCHEMA
   OC_SCHEMA_DICT ("ProtocolOverrides",    mUefiProtocolOverridesSchema),
   OC_SCHEMA_DICT ("Quirks",               mUefiQuirksSchema),
   OC_SCHEMA_ARRAY_IN ("ReservedMemory",   OC_GLOBAL_CONFIG,             Uefi.ReservedMemory, &mUefiReservedMemorySchema),
+  OC_SCHEMA_ARRAY_IN ("Unload",           OC_GLOBAL_CONFIG,             Uefi.Unload,         &mMiscUnloadImagesSchema),
 };
 
 //

Library/OcMainLib/OcMainLib.inf

@@ -31,6 +31,7 @@
   OpenCoreUefi.c
   OpenCoreUefiAudio.c
   OpenCoreUefiInOut.c
+  OpenCoreUefiUnloadDrivers.c
   OpenCoreVault.c
 
 [Packages]
@@ -47,6 +48,7 @@
   gEfiAudioDecodeProtocolGuid         ## SOMETIMES_CONSUMES
   gEfiDevicePathProtocolGuid          ## CONSUMES
   gEfiDevicePathProtocolGuid          ## CONSUMES
+  gEfiDriverBindingProtocolGuid       ## CONSUMES
   gEfiSimplePointerProtocolGuid       ## SOMETIMES_CONSUMES
   gEfiLoadedImageProtocolGuid         ## CONSUMES
   gEfiSimpleFileSystemProtocolGuid    ## CONSUMES

Library/OcMainLib/OpenCoreUefi.c

@@ -897,6 +897,8 @@ OcLoadUefiSupport (
   EFI_EVENT   Event;
   BOOLEAN     AccelEnabled;
 
+  OcUnloadDrivers (Config);
+
   OcReinstallProtocols (Config);
 
   OcImageLoaderInit (Config->Booter.Quirks.ProtectUefiServices, Config->Booter.Quirks.FixupAppleEfiImages);