From 78bf05d551025ad6f5973c784d59565cbd584ba3 Mon Sep 17 00:00:00 2001 From: dakanji Date: Tue, 3 Oct 2023 05:24:46 +0300 Subject: [PATCH] Update for v0.14.0.AB Release --- .github/ISSUE_TEMPLATE/bug_report.yml | 2 +- NEWS.txt | 2 +- README-Dev.md | 2 +- README.md | 33 +-- config.conf-sample | 352 ++++++++++++++------------ include/version.h | 2 +- 6 files changed, 208 insertions(+), 185 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml index 90342f7c..956c26f0 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.yml +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -12,7 +12,7 @@ body: label: RefindPlus Version description: Which version of RefindPlus is affected? options: - - 'v0.14.0.AA Release' + - 'v0.14.0.AB Release' - 'Older Released Version' - 'Pre-Release Code Build' validations: diff --git a/NEWS.txt b/NEWS.txt index 5095c11d..bcc1d455 100644 --- a/NEWS.txt +++ b/NEWS.txt @@ -1,4 +1,4 @@ -0.14.0.AB (PRE-RELEASE): +0.14.0.AB (03 Oct 2023): ----------------------- - Adds `HelpScan` Feature * Ensures that some typically unwanted loaders are not displayed in the first row diff --git a/README-Dev.md b/README-Dev.md index 66270d51..d4255d16 100644 --- a/README-Dev.md +++ b/README-Dev.md @@ -134,7 +134,7 @@ Implementation differences with the upstream v0.14.0 base are: - **Apple NVRAM Protection:** RefindPlus always prevents UEFI Windows Secure Boot from saving certificates to Apple NVRAM as this can result in damage and an inability to boot. Blocking these certificates does not impact the operation of UEFI Windows on Apple Macs. This filtering only happens when Apple firmware is detected and is not applied to other types of firmware. Users that prefer not to use this feature can activate the RefindPlus-Specific `disable_nvram_protect` configuration token to switch it off. - **Secondary Configuration Files:** While the upstream documentation prohibits including tertiary configuration files from secondary configuration files, there is no mechanism enforcing this prohibition. Hence, tertiary, quaternary, quinary, and more, configuration files can in fact be included. RefindPlus enforces a limitation to secondary configuration files. - **Included Manual Stanza Files:** The upstream implementation has an undocumented feature whereby files containing manual configuration stanzas could be `included` similar to a secondary configuration file. This is documented in the RefindPlus config file along with the documentation for including secondary configuration files. While the RefindPlus implementation also allows multiple `include` lines for such, it differs from the undocumented upstream implementation in that included manual configuration stanza files cannot include other such files in turn, similar to the implementation for secondary configuration files. -- **Disabled Manual Stanzas:** The processing of a user configured boot stanza is halted, and the `Entry` object immediately discarded, once a `Disabled` setting is encountered. The outcome is the same as upstream, which always continues to create and return a fully built object in such cases to be discarded later. The approach adopted in RefindPlus allows for an optimised loading process particularly when such `Disabled` tokens are placed immediately after the `menuentry` line (see examples in the [config.conf-sample-Dev](https://github.com/dakanji/RefindPlus/blob/27ad097947f67fbf372ac1a302ad813a029b927f/config.conf-sample-Dev#L1224-L1249) file). This also applies to `submenuentry` items which can be enabled or disabled separately. +- **Disabled Manual Stanzas:** The processing of a user configured boot stanza is halted, and the `Entry` object immediately discarded, once a `Disabled` setting is encountered. The outcome is the same as upstream, which always continues to create and return a fully built object in such cases to be discarded later. The approach adopted in RefindPlus allows for an optimised loading process particularly when such `Disabled` tokens are placed immediately after the `menuentry` line (see examples in the [config.conf-sample-Dev](https://github.com/dakanji/RefindPlus/blob/9dcd45ae85255e46719143138514575fa9bc35e8/config.conf-sample-Dev#L1306-L1331) file). This also applies to `submenuentry` items which can be enabled or disabled separately. - **Pointer Priority:** The upstream implementation of pointer priority is based on how the tokens appear in the configuration file(s) when both pointer control tokens, `enable_mouse` and `enable_touch`, are active. The last token read in the main configuration file and/or any supplementary/override configuration file will be used and the other disregarded. In RefindPlus however, the `enable_touch` token always takes priority when both tokens are active without regard to the order of appearance in the configuration file(s). This means that to use a mouse in RefindPlus, the `enable_touch` token must be disabled (default) in addition to enabling the `enable_mouse` token. ## Roll Your Own diff --git a/README.md b/README.md index 0c3bd639..f97fa7ce 100644 --- a/README.md +++ b/README.md @@ -57,19 +57,20 @@ Token | Functionality continue_on_warning |Proceed as if a key was pressed after screen warnings (for unattended boot) csr_dynamic |Actively enables or disables the SIP Policy on Macs csr_normalise |Removes the `APPLE_INTERNAL` bit, when present, to permit OTA updates -decline_apfs_load |Disables inbuilt provision of APFS filesystem capability -decline_apfs_mute |Disables suppression of verbose APFS text on boot -decline_apfs_sync |Disables feature allowing direct APFS/FileVault boot (Without "PreBoot") -decline_apple_fb |Disables provision under some circumstances of missing AppleFramebuffers decline_help_icon |Disables feature that may improve loading speed by preferring generic icons decline_help_tags |Disables feature that ensures hidden display entries can always be unhidden decline_help_text |Disables complementary text colours if not required -decline_nvram_protect |Disables blocking of potentially harmful write attempts to Legacy Mac NVRAM -decline_reload_gop |Disables reinstallation of UEFI 2.x GOP drivers on EFI 1.x units +decline_help_scan |Disables feature that skips showing misc typically unwanted loaders decouple_key_f10 |Unmaps the `F10` key from native screenshots (the `\` key remains mapped) disable_amfi |Disables AMFI Checks on macOS if required +disable_apfs_load |Disables inbuilt provision of APFS filesystem capability +disable_apfs_mute |Disables suppression of verbose APFS text on boot +disable_apfs_sync |Disables feature allowing direct APFS/FileVault boot (Without "PreBoot") disable_compat_check |Disables Mac version compatibility checks if required disable_nvram_paniclog|Disables macOS kernel panic logging to NVRAM +disable_nvram_protect |Disables blocking of potentially harmful write attempts to Legacy Mac NVRAM +disable_provide_fb |Disables provision under some circumstances of missing AppleFramebuffers +disable_reload_gop |Disables reinstallation of UEFI 2.x GOP drivers on EFI 1.x units disable_rescan_dxe |Disables scanning for newly revealed DXE drivers when connecting handles enable_esp_filter |Prevents other ESPs other than the RefindPlus ESP being scanned for loaders force_trim |Forces `TRIM` on non-Apple SSDs on Macs if required @@ -120,21 +121,21 @@ In addition to the new functionality listed above, the following upstream tokens ## Divergence Implementation differences with the upstream v0.14.0 base are: +- **GZipped Loaders:** RefindPlus only provides stub support for handling GZipped loaders as this is largely relevant for units on the ARM architecture. This stub support only used for debug logging in RefindPlus and can be activated using the same `support_gzipped_loaders` configuration token as upstream. - **Screenshots:** These are saved in the PNG format with a significantly smaller file size. Additionally, the file naming is slightly different and the files are always saved to the same ESP as the RefindPlus efi file. - **UI Scaling:** WQHD monitors are correctly determined not to be HiDPI monitors and UI elements are not scaled up on such monitors when the RefindPlus-Specific `scale_ui` configuration token is set to automatically detect the screen resolution. RefindPlus also takes vertically orientated screens into account and additionally scales UI elements down when low resolution screens (less than 1025px on the longest edge) are detected. -- **Hidden Tags:** RefindPlus always makes the "hidden_tags" tool available (even when the tool is not specified in the "showtools" list). This is done to ensure that when users hide items (always possible), such items can also be unhidden (only possible when the "hidden_tags" tool is available). Users that prefer not to use this feature can activate the RefindPlus-Specific `decline_help_tags` configuration token to switch it off. -- **GOP Driver Provision:** RefindPlus attempts to ensure that UEFI 2.x GOP drivers are available on EFI 1.x units by attempting to reload such drivers when it detects an absence of GOP on such units to permit the use of modern GPUs on legacy units. Users that prefer not to use this feature can activate the RefindPlus-Specific `decline_reload_gop` configuration token to switch it off. -- **AppleFramebuffer Provision:** RefindPlus defaults to always providing Apple framebuffers on Macs, when not available under certain circumstances. This is done using an inbuilt `SupplyAppleFB` feature. Users that prefer not to use this feature can activate the RefindPlus-Specific `decline_apple_fb` configuration token to switch it off. -- **APFS Filesystem Provision:** RefindPlus defaults to always providing APFS Filesystem capability, when not available but is required, without a need to load an APFS driver. This is done using an inbuilt `SupplyAPFS` feature. Users that prefer not to use this feature can activate the RefindPlus-Specific `decline_apfs_load` configuration token to switch it off. -- **APFS Verbose Text Suppression:** RefindPlus defaults to always suppresses verbose text output associated with loading APFS functionality by the inbuilt `SupplyAPFS` feature. Users that prefer not to use this feature can activate the RefindPlus-Specific `decline_apfs_mute` configuration token to switch it off. -- **APFS PreBoot Volumes:** RefindPlus always synchronises APFS System and PreBoot partitions transparently such that the Preboot partitions of APFS volumes are always used to boot APFS formatted macOS. Hence, a single option for booting macOS on APFS volumes is presented in RefindPlus to provide maximum APFS compatibility, consistent with Apple's implementation. Users that prefer not to use this feature can activate the RefindPlus-Specific `decline_apfs_sync` configuration token to switch it off. -- **Apple NVRAM Protection:** RefindPlus always prevents UEFI Windows Secure Boot from saving certificates to Apple NVRAM as this can result in damage and an inability to boot. Blocking these certificates does not impact the operation of UEFI Windows on Apple Macs. This filtering only happens when Apple firmware is detected and is not applied to other types of firmware. Users that prefer not to use this feature can activate the RefindPlus-Specific `decline_nvram_protect` configuration token to switch it off. +- **Hidden Tag:** RefindPlus always makes the "hidden_tags" tool available (even when the tool is not specified in the "showtools" list). This is done to ensure that when users hide items (always possible), such items can also be unhidden (only possible when the "hidden_tags" tool is available). Users that prefer not to use this feature can activate the RefindPlus-Specific `decline_help_tags` configuration token to switch it off. +- **Loader Icons:** RefindPlus defaults to preferring generic icons for loaders ahead of custom icons where possible. The upstream icon search implementation involves only loading such icons after a search for custom icons has not turned anything up. Users can activate the RefindPlus-Specific `decline_help_icon` configuration token to use the upstream icon search implementation instead of the RefindPlus default. +- **GOP Driver Provision:** RefindPlus attempts to ensure that UEFI 2.x GOP drivers are available on EFI 1.x units by attempting to reload such drivers when it detects an absence of GOP on such units to permit the use of modern GPUs on legacy units. Users that prefer not to use this feature can activate the RefindPlus-Specific `disable_reload_gop` configuration token to switch it off. +- **AppleFramebuffer Provision:** RefindPlus defaults to always providing Apple framebuffers on Macs, when not available under certain circumstances. This is done using an inbuilt `SupplyAppleFB` feature. Users that prefer not to use this feature can activate the RefindPlus-Specific `disable_provide_fb` configuration token to switch it off. +- **APFS Filesystem Provision:** RefindPlus defaults to always providing APFS Filesystem capability, when not available but is required, without a need to load an APFS driver. This is done using an inbuilt `SupplyAPFS` feature. Users that prefer not to use this feature can activate the RefindPlus-Specific `disable_apfs_load` configuration token to switch it off. +- **APFS Verbose Text Suppression:** RefindPlus defaults to always suppresses verbose text output associated with loading APFS functionality by the inbuilt `SupplyAPFS` feature. Users that prefer not to use this feature can activate the RefindPlus-Specific `disable_apfs_mute` configuration token to switch it off. +- **APFS PreBoot Volumes:** RefindPlus always synchronises APFS System and PreBoot partitions transparently such that the Preboot partitions of APFS volumes are always used to boot APFS formatted macOS. Hence, a single option for booting macOS on APFS volumes is presented in RefindPlus to provide maximum APFS compatibility, consistent with Apple's implementation. Users that prefer not to use this feature can activate the RefindPlus-Specific `disable_apfs_sync` configuration token to switch it off. +- **Apple NVRAM Protection:** RefindPlus always prevents UEFI Windows Secure Boot from saving certificates to Apple NVRAM as this can result in damage and an inability to boot. Blocking these certificates does not impact the operation of UEFI Windows on Apple Macs. This filtering only happens when Apple firmware is detected and is not applied to other types of firmware. Users that prefer not to use this feature can activate the RefindPlus-Specific `disable_nvram_protect` configuration token to switch it off. - **Secondary Configuration Files:** While the upstream documentation prohibits including tertiary configuration files from secondary configuration files, there is no mechanism enforcing this prohibition. Hence, tertiary, quaternary, quinary, and more, configuration files can in fact be included. RefindPlus enforces a limitation to secondary configuration files. - **Included Manual Stanza Files:** The upstream implementation has an undocumented feature whereby files containing manual configuration stanzas could be `included` similar to a secondary configuration file. This is documented in the RefindPlus config file along with the documentation for including secondary configuration files. While the RefindPlus implementation also allows multiple `include` lines for such, it differs from the undocumented upstream implementation in that included manual configuration stanza files cannot include other such files in turn, similar to the implementation for secondary configuration files. -- **Disabled Manual Stanzas:** The processing of a user configured boot stanza is halted, and the `Entry` object immediately discarded, once a `Disabled` setting is encountered. The outcome is the same as upstream, which always continues to create and return a fully built object in such cases to be discarded later. The approach adopted in RefindPlus allows for an optimised loading process particularly when such `Disabled` tokens are placed immediately after the `menuentry` line (see examples in the [config.conf-sample](https://github.com/dakanji/RefindPlus/blob/27ad097947f67fbf372ac1a302ad813a029b927f/config.conf-sample#L1224-L1249) file). This also applies to `submenuentry` items which can be enabled or disabled separately. +- **Disabled Manual Stanzas:** The processing of a user configured boot stanza is halted, and the `Entry` object immediately discarded, once a `Disabled` setting is encountered. The outcome is the same as upstream, which always continues to create and return a fully built object in such cases to be discarded later. The approach adopted in RefindPlus allows for an optimised loading process particularly when such `Disabled` tokens are placed immediately after the `menuentry` line (see examples in the [config.conf-sample](https://github.com/dakanji/RefindPlus/blob/9dcd45ae85255e46719143138514575fa9bc35e8/config.conf-sample-Dev#L1306-L1331) file). This also applies to `submenuentry` items which can be enabled or disabled separately. - **Pointer Priority:** The upstream implementation of pointer priority is based on how the tokens appear in the configuration file(s) when both pointer control tokens, `enable_mouse` and `enable_touch`, are active. The last token read in the main configuration file and/or any supplementary/override configuration file will be used and the other disregarded. In RefindPlus however, the `enable_touch` token always takes priority when both tokens are active without regard to the order of appearance in the configuration file(s). This means that to use a mouse in RefindPlus, the `enable_touch` token must be disabled (default) in addition to enabling the `enable_mouse` token. -- **GZipped Loaders:** RefindPlus only provides stub support for handling GZipped loaders as this is largely relevant for units on the ARM architecture. This stub support can be activated using the same `support_gzipped_loaders` configuration token as upstream. -- **Loader Icons:** RefindPlus defaults to preferring generic icons for loaders ahead of custom icons where possible. The upstream icon search implementation involves only loading such icons after a search for custom icons has not turned anything up. Users can activate the RefindPlus-Specific `decline_help_icon` configuration token to use the upstream icon search implementation instead of the RefindPlus default. ## Roll Your Own Refer to [BUILDING.md](https://github.com/dakanji/RefindPlus/blob/GOPFix/BUILDING.md) for build instructions (x86_64 Only). diff --git a/config.conf-sample b/config.conf-sample index 57003414..bfed127e 100644 --- a/config.conf-sample +++ b/config.conf-sample @@ -17,10 +17,11 @@ # #continue_on_warning -# This token allows actively enabling or disabling the System Integrity Protection (SIP) and -# Sealed System Volume (SSV) settings defined under the "csr_values" option. When this token is -# active, RefindPlus will actively set the CSR Policy as defined. This is done when RefindPlus is -# loaded but users can manually toggle the set values "ON" or "OFF" by using the "Rotate CSR" tool. +# Allow actively enabling/disabling the System Integrity Protection (SIP) and +# Sealed System Volume (SSV) settings defined under the "csr_values" option. +# When active, RefindPlus will actively set the CSR Policy as defined. This +# is done when RefindPlus is loaded but users can manually toggle the set +# values "ON" or "OFF" by using the "Rotate CSR" tool on the main menu. # The following options are available: # 1 - Always Enable SIP (and SSV on macOS 11.x or later) # 0 - Take no Action @@ -43,65 +44,13 @@ # #csr_normalise -# Offer APFS filesystem capability. By default, RefindPlus is set up to jump start -# macOS APFS filesystem drivers, apfs.efi, which are available in system folders of -# macOS 10.13 (High Sierra) and later. The drivers are loaded to match each specific -# macOS version which ensures that any changes made to APFS drivers for each specific -# macOS version are accommodated, compared to using one driver no matter what specific -# macOS version is being loaded. This default is deactivated whenever this token is set. -# NB: This functionality is only available on TianoCore builds. -# -# APFS filesystem capability is provided (if required) via "SupplyAPFS" when commented out -# -#decline_apfs_load - -# Suppress verbose APFS loading text output. By default, RefindPlus is configured to always -# suppress verbose text output from APFS drivers loaded via its "SupplyAPFS" functionality. -# This feature only acts on apfs drivers loaded via the default "SupplyAPFS" functionality. -# This feature may impact other text output however, and should be disabled by activating -# this option if such negative effects are observed. This setting only applies to macOS. -# NB: This functionality is only available on TianoCore builds. -# -# Verbose APFS text is suppressed (if generated) when commented out -# -#decline_apfs_mute - -# Apple has partially enforced the use of the "PreBoot" Loader stored in the "PreBoot" partition -# of APFS volumes by requiring this to run the Mac Boot Loader, starting with macOS v11.0, when -# SIP is enabled. Attempts to run such macOS Boot Loaders directly when SIP is enabled result -# in kernel panics. The default setting in RefindPlus is to always map APFS volumes to their -# respective "PreBoot" partitions, which will be used to boot such macOS instances and the -# associated "PreBoot" partitions will be hidden from view. This arrangement also permits -# booting into FileVault encrypted APFS volumes with their volume labels (not PreBoot). -# When this option is enabled however, the RefindPlus "SyncAPFS" feature is disabled. -# -# NB: Maintain the default naming pattern for APFS data volumes, "VolName - Data", -# to improve the reliability of "SyncAPFS" distinguishing between APFS volumes. -# Also, avoid the use of special characters in macOS volume names and limit -# names to alphanumeric characters. Dashes, underscores and/or spaces can -# be used in combination with alphanumeric characters without issue. -# -# APFS partition synchronisation is provided (if required) when commented out -# -#decline_apfs_sync - -# Replace the Apple FramebufferInfo protocol with a builtin version. By default, RefindPlus -# is configured to always install the Apple FramebufferInfo protocol when missing on Macs. -# This feature can be disabled by activating this token. It is only active when the UGA -# protocol is available and is inactive when running a GPU with the GOP protocol. -# NB: This functionality is only available on TianoCore builds. -# -# Apple FramebufferInfo protocol is provided (if required) when commented out -# -#decline_apple_fb - -# The "HelpIcon" feature prefers loading default/generic loader icons which are used -# in most cases. Searches for custom icons are only executed if a generic loader icon -# is not found. This is a change from the original rEFInd implementation; which is the -# other way round (Custom icons are searched for first). This implementation can result -# in significantly faster loading speeds in the best case and should make no difference -# to loading speed in the worst case. The default/generic loader icons searched for will -# be those for the current active theme. That is, the current active theme default icons. +# The "HelpIcon" feature prefers loading default/generic loader icons over custom +# ones and searches for custom loader icons only executed if a generic loader icon +# is not found. This can result in significantly faster loading speeds on some units +# and make no difference at worst. The default/generic loader icons loaded will be +# those for the current active theme. That is, the current theme's default icons. +# ".VolumeIcons" and "VolumeBadges" are disabled when this setting is active. +# When active, generic "linux" icons are used for most linux flavours. # # The "HelpIcon" feature is enabled when commented out # @@ -118,7 +67,7 @@ # #decline_help_tags -# RefindPlus defaults to using complementary colours (of the title banner) for text +# The "HelpText" feature uses complementary colours (of the title banner) for text # to improve legibility. With custom banners however, the base colour is based on the # colour of first pixel in the pixel array (top left pixel). This may not always embody # all pixels in banners with multiple colours. Thus, the selected complementary colour @@ -133,33 +82,15 @@ # #decline_help_text -# Allow/Prevent saving various potentially harmful variables to the NVRAM on Macs. -# By default, RefindPlus will prevent writes of certain items by processes such as -# UEFI Windows Secure Boot (certificates) to the NVRAM on Legacy Macs as these may -# result in an overrun that will damage the BootROM (also stored on the NVRAM) and -# results in an inability to boot. This token is only activated on Apple firmware. +# The "HelpScan" feature always adds program defaults to 'dont_scan-xyz' lists. +# This deviates from the upstream implementation where such program defaults are +# overwritten unless a "+" item is added as the first item of user defined entries. +# These program defaults ensure that certain items are not shown as first row icons. +# Users that wish to disable the default "HelpScan" feature can activate this option. # -# The "NvramProtect" feature is enabled when commented out +# The "HelpScan" feature is enabled when commented out # -#decline_nvram_protect - -# When GOP drivers, which are UEFI 2.x drivers, are implemented in compliance with -# UEFI 2.x requirements, they do not work on legacy devices as the specifications -# mandate that on installation, compliant GOP drivers should confirm devices are -# UEFI 2.x compliant and to fail if they are not. Hence, compliant GOP drivers -# do not activate on classic MacPros for instance, as these are not actually -# UEFI 2.x but EFI 1.x devices to which Apple has added a chunk of, but not -# all of, the UEFI 2.x capabilities. RefindPlus is configured by default to -# amend a device's EFI Revision to v2.x, and then try to reinstall a copy -# of the GPU's Option ROM whenever it detects that GOP is not available. -# This permits running modern GPUs on some legacy units when they would -# otherwise fail to work. The change is reverted automatically once it -# is longer required to allow GPU activation except when the related -# "supply_uefi" setting is activate, as this overrides this revert. -# -# GPU Option ROMs are reinstalled (if required) when commented out -# -#decline_reload_gop +#decline_help_scan # RefindPlus defaults to mapping both 'F10' and '\' (forward slash) to # the inbuilt screenshot feature. When this option is active, the F10 @@ -172,17 +103,61 @@ # #decouple_key_f10 -# Disable Apple Mobile File Integrity (AMFI) checks when booting macOS. When this option -# is active, RefindPlus will add the "amfi_get_out_of_my_way=1" boot argument which along -# with System Integrity Protection (SIP), restricts application access to OS entitlements. -# Note that this setting will create a macOS boot argument the first time it is triggered -# and that this boot argument will remain active until it is explicitly cleared, even if -# this setting is subsequently deactivated. +# Disable Apple Mobile File Integrity (AMFI) checks when booting macOS. When +# this token is active, RefindPlus will add a "amfi_get_out_of_my_way=1" boot +# argument which along with System Integrity Protection (SIP), restricts +# application access to OS entitlements. Note that this setting will +# create a macOS boot argument the first time it is triggered +# and that this boot argument will remain active until +# it is explicitly cleared, even if this setting +# is subsequently deactivated. # # Inactive when commented out (Does not stop AMFI checks) # #disable_amfi +# Offer APFS filesystem capability. By default, RefindPlus is set up to jump start +# macOS APFS filesystem drivers, apfs.efi, which are available in system folders of +# macOS 10.13 (High Sierra) and later. The drivers are loaded to match each specific +# macOS version which ensures that any changes made to APFS drivers for each specific +# macOS version are accommodated, compared to using one driver no matter what specific +# macOS version is being loaded. This default is deactivated whenever this token is set. +# NB: This functionality is only available on TianoCore builds. +# +# APFS filesystem capability is provided (if required) via "SupplyAPFS" when commented out +# +#disable_apfs_load + +# Suppress verbose APFS loading text output. By default, RefindPlus is configured to always +# suppress verbose text output from APFS drivers loaded via its "SupplyAPFS" functionality. +# This feature only acts on apfs drivers loaded via the default "SupplyAPFS" functionality. +# This feature may impact other text output however, and should be disabled by activating +# this option if such negative effects are observed. This setting only applies to macOS. +# NB: This functionality is only available on TianoCore builds. +# +# Verbose APFS text is suppressed (if generated) when commented out +# +#disable_apfs_mute + +# Apple has partially enforced the use of the "PreBoot" Loader stored in the "PreBoot" partition +# of APFS volumes by requiring this to run the Mac Boot Loader, starting with macOS v11.0, when +# SIP is enabled. Attempts to run such macOS Boot Loaders directly when SIP is enabled result +# in kernel panics. The default setting in RefindPlus is to always map APFS volumes to their +# respective "PreBoot" partitions, which will be used to boot such macOS instances and the +# associated "PreBoot" partitions will be hidden from view. This arrangement also permits +# booting into FileVault encrypted APFS volumes with their volume labels (not PreBoot). +# When this option is enabled however, the RefindPlus "SyncAPFS" feature is disabled. +# +# NB: Maintain the default naming pattern for APFS data volumes, "VolName - Data", +# to improve the reliability of "SyncAPFS" distinguishing between APFS volumes. +# Also, avoid the use of special characters in macOS volume names and limit +# names to alphanumeric characters. Dashes, underscores and/or spaces can +# be used in combination with alphanumeric characters without issue. +# +# APFS partition synchronisation is provided (if required) when commented out +# +#disable_apfs_sync + # Disable version compatibility checks when booting macOS. Macs check whether # the current macOS version is supported on the machine when booting, and halt # if not. When this option is active, RefindPlus will add "-no_compat_check" to @@ -207,6 +182,46 @@ # #disable_nvram_paniclog +# Allow/Prevent saving various potentially harmful variables to the NVRAM on Macs. +# By default, RefindPlus will prevent writes of certain items by processes such as +# UEFI Windows Secure Boot (certificates) to the NVRAM on Legacy Macs as these may +# result in an overrun that will damage the BootROM (also stored on the NVRAM) and +# results in an inability to boot. This token is only activated on Apple firmware. +# NB: This feature is always disabled when RefindPlus is loaded via OpenCore. +# +# The "NvramProtect" feature is enabled when commented out +# +#disable_nvram_protect + +# Replace the Apple FramebufferInfo protocol with a builtin version. By default, +# RefindPlus is configured to always install the Apple FramebufferInfo protocol +# when missing on Macs. This feature can be disabled by activating this token. +# It is only active when the UGA protocol is available and is inactive when +# running a GPU with the GOP protocol. +# NB: This functionality is only available on TianoCore builds. +# +# Apple FramebufferInfo protocol is provided (if required) when commented out +# +#disable_provide_fb + +# When GOP drivers, which are UEFI 2.x drivers, are implemented in compliance with +# UEFI 2.x requirements, they do not work on legacy devices as the specifications +# mandate that on installation, compliant GOP drivers should confirm devices are +# UEFI 2.x compliant and to fail if they are not. Hence, compliant GOP drivers +# do not activate on classic MacPros for instance, as these are not actually +# UEFI 2.x but EFI 1.x devices to which Apple has added a chunk of, but not +# all of, the UEFI 2.x capabilities. RefindPlus is configured by default to +# amend a device's EFI Revision to v2.x, and then try to reinstall a copy +# of the GPU's Option ROM whenever it detects that GOP is not available. +# This permits running modern GPUs on some legacy units when they would +# otherwise fail to work. The change is reverted automatically once it +# is longer required to allow GPU activation except when the related +# "supply_uefi" setting is activate, as this overrides this revert. +# +# GPU Option ROMs are reinstalled (if required) when commented out +# +#disable_reload_gop + # Disable dispatching revealed DXE drivers during handle connection. # The Controller/Handle connection exercise may sometimes reveal new # DXE drivers on some firmware. RefindPlus versions before v0.13.2.AP @@ -279,6 +294,9 @@ # # Does not prioritise ".VolumeIcon" images when commented out # +# NOTE: +# 1. This token is overridden by "decline_help_icon" +# #hidden_icons_prefer # Offset the OS icon row position on the main screen vertically from the default. @@ -324,6 +342,7 @@ # When this option is activate, the RefindPlus "NvramProtect" feature will be # extended, if set, to cover booting into macOS and "unknown" UEFI files. # NB: This setting is only active, if set, on Apple firmware. +# This feature is always disabled when RefindPlus is loaded via OpenCore. # # Inactive when commented out (Does not extend NvramProtect) # @@ -419,9 +438,10 @@ # #renderer_text -# RefindPlus will automatically scale icons and text when HiDPI or LoRez screens are detected. -# The detection is basic and based on detecting a minimum 1601px vertical resolution for HiDPI. -# Screens are considered to be LoRez based on detecting a lower than 1025px vertical resolution. +# RefindPlus will automatically scale icons and text when HiDPI or LoRez screens +# are detected. The detection is basic and based on detecting a minimum 1601px +# resolution on the longest edge for HiDPI. Screens are considered to be LoRez +# based on detecting a resolution lower than 1025px on the longest edge. # This setting allows overriding the detection as follows: # 99 - Never scale UI elements # 1 - Always scale UI elements up @@ -465,7 +485,7 @@ #supply_nvme # Emulate UEFI 2.x support. The RefindPlus "SupplyUEFI" feature can -# emulate the "CreateEventEx" feature, introduced in UEFI 2.3, when not +# emulate the "CreateEventEx" feature, introduced in UEFI 2.0, when not # available. It additionally modifies the EFI Revision value to UEFI 2.3. # This may allow running UEFI 2.x tools and drivers on EFI 1.x units such # as Legacy Macs as several such tools only require CreateEventEx to work. @@ -488,10 +508,11 @@ # #transient_boot -# RefindPlus previously simply picked and used the first Unicode Collation Protocol instance -# it finds. This resulted in a lottery where such instances sometimes worked and sometimes -# did not. The proper implementation process however is to first locate every instance -# and select one that supports the English language. This has now been implemented. +# RefindPlus previously simply picked and used the first Unicode Collation +# Protocol instance it finds. This resulted in a lottery where such instances +# sometimes worked and sometimes did not. The proper implementation process +# however is to first locate every instance and select one that supports +# the English language. This has now been implemented. # NB: This functionality is only fully available on TianoCore builds. # # Does not look for Unicode English support when commented out. @@ -506,26 +527,6 @@ ##--------------------------------------------------------------## # # -# When scanning volumes for EFI bootloaders, RefindPlus always looks for -# the macOS and Microsoft Windows bootloaders in their normal locations -# and scans the root directory as well as sub folders under the "EFI" -# folder for more bootloaders (Does not recurse into sub folders). -# -# The "also_scan_dirs" option adds more directories to the scan list and -# directories are specified relative to the volume's root directory. This -# option applies to ALL the volumes that RefindPlus scans UNLESS a volume -# name and a colon are included before the directory name (myvol:/somedir) -# to scan the "somedir" directory only on the filesystem named "myvol". If -# a specified directory does not exist, it is ignored (no error message). -# The "+" symbol denotes appending to the list of scanned directories -# as opposed to overwriting this list. -# -# Scans "boot", "@/boot" and "@root/boot" when commented out -# -#also_scan_dirs boot,ESP2:EFI/linux/kernels -#also_scan_dirs boot,@/boot,@root/boot -#also_scan_dirs +,@/kernels - # Set the CSR values for Apple's System Integrity Protection (SIP) and # Sealed System Volume (SSV) features that define access levels on macOS. # Values are hexadecimal numbers that define which specific security features @@ -619,26 +620,28 @@ # gdisk - Disk Partitioning Utility. # NB: Requires external program # See documentation for details -# clean_nvram - reset NVRAM from RefindPlus. +# clean_nvram - Enables NVRAM Reset from RefindPlus. # NB: Needs External program. -# apple_recovery - loads Apple Mac Recovery partitions, if present -# windows_recovery - boots an OEM Windows recovery tool, if present. +# apple_recovery - Loads Apple Mac Recovery partitions, if present +# windows_recovery - Boots an OEM Windows recovery tool, if present. # NB: Also refer to the "windows_recovery_files" option -# mok_tool - makes available the Machine Owner Key (MOK) maintenance tool, +# mok_tool - Enables the Machine Owner Key (MOK) maintenance tool, # MokManager.efi, used on Secure Boot systems -# csr_rotate - adjusts Apple System Integrity Protection (SIP) policy. +# csr_rotate - Adjusts Apple's System Integrity Protection (SIP) policy. # NB: Requires "csr_values" to be set. -# install - an option to install RefindPlus from the current location to another ESP -# bootorder - adjust the firmware's boot order variables -# about - an "About This Program" option -# hidden_tags - manage hidden tags -# exit - a tag to exit RefindPlus -# shutdown - shuts down the computer (a bug causes this to reboot many UEFI systems) -# reboot - a tag to reboot the computer normally -# firmware - a tag to reboot the computer into the firmware's user interface. +# install - Enables option to install RefindPlus from the current +# location to another ESP +# bootorder - Adjust firmware boot order variables +# about - An "About This Program" option +# hidden_tags - Manage hidden tags +# exit - A tag to exit RefindPlus +# shutdown - Shuts the computer down. +# NB: A bug causes this to reboot many UEFI systems +# reboot - A tag to reboot the computer normally +# firmware - A tag to reboot the computer into the firmware's user interface. # NB: Ignored on older computers. -# fwupdate - a tag to update the firmware; launches the fwupx64.efi (or similar) program -# netboot - launch the ipxe.efi tool for network (PXE) booting +# fwupdate - A tag to update the firmware; launches the fwupx64.efi (or similar) program +# netboot - Launch the ipxe.efi tool for network (PXE) booting # # The default setting is shell, memtest, gdisk, apple_recovery, windows_recovery, mok_tool, about, hidden_tags, shutdown, reboot, firmware, fwupdate # @@ -718,6 +721,23 @@ ##--------------------------------------------------------------## # # +# When scanning volumes for EFI bootloaders, RefindPlus always looks for +# the macOS and Microsoft Windows bootloaders in their normal locations +# and scans the root directory as well as sub folders under the "EFI" +# folder for more bootloaders (Does not recurse into sub folders). +# +# The "also_scan_dirs" option adds more directories to the scan list and +# directories are specified relative to the volume's root directory. This +# option applies to ALL the volumes that RefindPlus scans UNLESS a volume +# name and a colon are included before the directory name (myvol:/somedir) +# to scan the "somedir" directory only on the filesystem named "myvol". If +# a specified directory does not exist, it is ignored (no error message). +# +# Scans "boot" and "@/boot" when commented out +# +#also_scan_dirs ESP2:EFI/linux/kernels +#also_scan_dirs @/kernels,@/root/boot + # Use a custom title banner and not the default (embedded) banner. The # file path is relative to the directory where the RefindPlus binary is # located. The colour of the top left corner of the image is used for the @@ -766,26 +786,31 @@ # #default_selection 1 #default_selection Microsoft -#default_selection "+,bzImage,vmlinuz" +#default_selection "bzImage,vmlinuz" #default_selection Maintenance 23:30 2:00 #default_selection "Maintenance,macOS" 1:00 2:30 -# Directories that should *NOT* be scanned for boot loaders. By default, -# RefindPlus does not scan its own directory, the com.apple.recovery.boot, -# EFI/tools, EFI/memtest and EFI/memtest86 directories. The "dont_scan_dirs" -# option enables blocking other directories. However, "+" must be used as the -# first element to continue blocking existing directories. This option can be +# Directories that should *NOT* be scanned for boot loaders. This option can be # used to keep EFI/boot/bootx64.efi out of the menu if that is a duplicate of # another boot loader, to exclude directories holding drivers or to exclude # directories with non-bootloader utilities from a hardware manufacturer. +# # This token takes precedence if a directory is listed both here and in # "also_scan_dirs". Note that this applies to ALL the filesystems that # RefindPlus scans, and not just the ESP, unless the directory name # is preceded by a filesystem name or partition unique GUID, such -# as "myvol:EFI/somedir", to exclude EFI/somedirfrom the scan +# as "myvol:EFI/somedir", to exclude EFI/somedir from the scan # on the "myvol" volume but not on other volumes. # -# Inactive when commented out (Allows additional directories) +# The default setting is L"EFI/tools_{arch},EFI\tools, +# EFI\tools_{arch}\memtest86,EFI\tools_{arch}\memtest,EFI\tools_{arch}\memtest86p, +# EFI\tools\memtest86,EFI\tools\memtest,EFI\tools\memtest86p, +# EFI\BOOT\tools_{arch}\memtest86,EFI\BOOT\tools_{arch}\memtest, +# EFI\BOOT\tools_{arch}\memtest86p,EFI\BOOT\tools\memtest86,EFI\BOOT\tools\memtest, +# EFI\BOOT\tools\memtest86p,EFI\BOOT\memtest86,EFI\BOOT\memtest,EFI\BOOT\memtest86p, +# EFI\memtest86,EFI\memtest,EFI\memtest86p" ("{arch}" is the architecture, such as "x64"). +# +# Uses default setting when commented out # #dont_scan_dirs ESP:/EFI/boot,EFI/Dell,EFI/memtest86 @@ -802,18 +827,13 @@ # pathname with volume, such as "SOMEDISK:/EFI/somedir/notme.efi" # or 2C17D5ED-850D-4F76-BA31-47A561740082:/EFI/somedir/notme.efi". # OS tags hidden via the "Delete" or "-" key in the RefindPlus menu -# are added to this list, but stored in NVRAM. -# -# The default setting is shim.efi,shim-fedora.efi,shimx64.efi,PreLoader.efi, -# TextMode.efi,ebounce.efi,GraphicsConsole.efi,MokManager.efi,HashTool.efi, -# HashTool-signed.efi,bootmgr.efi,fb{arch}.efi -# (where "{arch}" is the architecture code, like "x64"). +# are added to this list, but stored in NVRAM (Hardware or Emulated). # -# To keep these defaults but add to them, ensure "+" is -# specified as the first item in the new list. If not, -# items from the default list are likely to appear. +# The default setting is L"shim-fedora.efi,shim-centos.efi,PreLoader.efi, +# TextMode.efi,ebounce.efi,GraphicsConsole.efi,bootmgr.efi,shim.efi,fb.efi, +# shim{arch}.efi,fb{arch}.efi" ("{arch}" is the architecture, such as "x64"). # -# Inactive when commented out (Allows additional files) +# Uses default setting when commented out # #dont_scan_files shim.efi,MokManager.efi @@ -826,6 +846,8 @@ # Specifying "shell" will override the automatic inclusion of # built-in EFI shells. # +# Has an empty list (nothing is excluded) when commented out +# #dont_scan_firmware HARDDISK,shell,"Removable Device" # Tool binaries to be excluded from the tools line, even when the @@ -852,9 +874,11 @@ # description (displayed when the option is highlighted) can be # used for legacy-mode scans. # -# Set to LRS_ESP when commented out +# The default setting is "LRS_ESP" +# +# Uses default setting when commented out # -#dont_scan_volumes "System Reserved" +#dont_scan_volumes "Boot OS X" # Enable VMX bit and lock the CPU MSR if unlocked. On some # Intel Apple computers, the firmware does not lock the MSR 0x3A. @@ -982,12 +1006,10 @@ # Filename prefixes that indicate a file is a Linux kernel. Files that # begin with any of these strings are treated as Linux kernels, if they -# are also EFI boot loaders. To include the default string, use "+" -# Default is "vmlinuz,bzImage,kernel", except on ARM64, where it is -# "vmlinuz,Image,kernel". +# are also EFI boot loaders. Default is "vmlinuz,bzImage,kernel", +# except on ARM64, where it is "vmlinuz,Image,kernel". # -#linux_prefixes vmlinuz,bzImage,kernel -#linux_prefixes +,zImage +#linux_prefixes zImage # Set the maximum number of tags that can be displayed on the screen at # any time. If more loaders are discovered than this value, RefindPlus shows @@ -1052,8 +1074,8 @@ # The netboot option is experimental and relies on the ipxe.efi and # ipxe_discover.efi program files. # -# On UEFI PCs, the default setting is internal,external,optical,manual -# On Macs, the default setting is internal,hdbios,external,biosexternal,optical,cd,manual +# On UEFI PC, the default setting is internal,external,optical,manual +# On Mac, the default is internal,hdbios,external,biosexternal,optical,cd,manual # #scanfor internal,external,optical,manual diff --git a/include/version.h b/include/version.h index c8fea406..2de98f12 100644 --- a/include/version.h +++ b/include/version.h @@ -16,4 +16,4 @@ * Modifications distributed under the preceding terms. */ -#define REFINDPLUS_VERSION L"0.14.0.AB (Pre-Release)" +#define REFINDPLUS_VERSION L"0.14.0.AB"