Update for v0.13.3.AD Release

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -12,7 +12,7 @@ body:
       label: RefindPlus Version
       description: Which version of RefindPlus is affected?
       options:
-        - 'v0.13.3.AC Release'
+        - 'v0.13.3.AD Release'
         - 'Older Released Version'
         - 'Pre-Release Code Build'
     validations:

NEWS.txt

@@ -1,4 +1,4 @@
-0.13.3.AD (PRE_RELEASE):
+0.13.3.AD (07 Mar 23):
 -----------------------
 - Fixes Manual Stanza SubMenuEntries
   * A memory conflict meant that including such entries resulted in RefindPlus hanging
@@ -27,9 +27,11 @@
 - Improves Misc Graphics Handling
   * Improves graphics related memory management
   * Improves UGA support via new `PassGopThrough` feature (Not user configurable)
-- Amends `Big Selection Image` Size Filtering
+- Amends `Selection Image` Size Filtering
   * The maximum Big Selection image size is increased to 320px from 256px
   * The Small Selection image maximum is maintained at 256px
+  * The default selection image is now used when a defined image cannot be found
+    - Previously used a scaled version of the small image when the big one was missing
 - Amends `Invalid UEFI Versions` Handling
   * Now accounts for such by reducing the amendment threshold to UEFI 2.0
   * Still amends to UEFI 2.3 when UEFI amendments happen
@@ -43,10 +45,6 @@
   * General optimisation
   * Memory management improvements and fixes
   * Log file handling tweaks
-- Amends `ScanAllESP` Feature
-  * Now aligned with upstream implementation and scans all ESPs by default
-  * Hence, the "Opt-Out" `decline_esp_filter` token has been replaced by an "Opt-In `enable_esp_filter` token
-  * A previous issue where the token operated the wrong way round has been fixed
 
 
 0.13.3.AC (06 Dec 2022):

README-Dev.md

@@ -11,7 +11,7 @@ The main development focus is on the following units:
 - **Xserve2,1**: Early 2008 Xserve
 - **Xserve3,1**: Early 2009 Xserve
 
-However, the enhancements added to RefindPlus are not limited in scope to those units and include several fixes and features relevant to UEFI-PCs and Apple Macs that may be of interest to anyone requiring a capable and flexible boot manager.
+However, the enhancements added to RefindPlus are not limited in scope to those units and include several UEFI-PC and other Apple Mac related enhancements that may be of interest to anyone requiring a capable and flexible boot manager.
 
 ## Headline Features
 - Maintains feature and configuration parity with the base upstream version.
@@ -61,6 +61,7 @@ decline_apfs_load     |Disables built in 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_esp_filter    |Allows other ESPs other than the RefindPlus ESP to be scanned for loaders
 decline_help_tags     |Disables feature that ensures hidden tags 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
@@ -70,7 +71,6 @@ disable_amfi          |Disables AMFI Checks on MacOS if required
 disable_compat_check  |Disables Mac version compatibility checks if required
 disable_nvram_paniclog|Disables MacOS kernel panic logging to NVRAM
 disable_rescan_dxe    |Disables scanning for newly revealed DXE drivers when connecting handles
-enable_esp_filter     |Blocks scanning other ESPs, other than that with RefindPlus, for loaders
 follow_symlinks       |Allows following symbolic links to loaders (Ignored by default)
 force_trim            |Forces `TRIM` on non-Apple SSDs on Macs if required
 hidden_icons_external |Allows scanning for `.VolumeIcon` icons on external volumes

README.md

@@ -41,13 +41,13 @@ However, the enhancements added to RefindPlus are not limited in scope to those
     - As opposed to generic and difficult to distinguish `PreBoot` volumes.
 
 ## Installation
-[MyBootMgr](https://www.dakanji.com/creations/index.html) is recommended to automate installing RefindPlus on Mac OS. Alternatively, as the RefindPlus efi file can function as a drop-in replacement for the upstream efi file, you can install the [rEFInd package](https://www.rodsbooks.com/refind/installing.html) first and replace the efi file with the RefindPlus efi file. (Ensure you rename the RefindPlus efi file to match). This manual process allows installing RefindPlus on any operating systems supported upstream. On Mac OS, MyBootMgr can optionally be used to set a RefindPlus|OpenCore chain-loading arrangement up on MacPro3,1 to MacPro5,1 as well as on Xserve2,1 and Xserve3,1.
+[MyBootMgr](https://www.dakanji.com/creations/index.html) is recommended to automate installing RefindPlus on Mac OS. Alternatively, as the RefindPlus efi file can function as a drop-in replacement for the upstream efi file, you can install the [rEFInd package](https://www.rodsbooks.com/refind/installing.html) first and replace its efi file with the RefindPlus efi file. (Ensure you rename the RefindPlus efi file to match). This manual process allows installing RefindPlus on any operating systems supported upstream. On Mac OS, MyBootMgr can optionally be used to set a RefindPlus|OpenCore chain-loading arrangement up on MacPro3,1 to MacPro5,1 as well as on Xserve2,1 and Xserve3,1.
 
 Users may also want to replace upstream filesystem drivers with those packaged with RefindPlus as these are always either exactly the same as upstream versions or have had fixes applied.
 
 RefindPlus will function with the upstream configuration file, `refind.conf`, but users may wish to replace this with the RefindPlus configuration file, `config.conf`, to configure the additional options provided by RefindPlus. A sample RefindPlus configuration file is available here: [config.conf-sample](https://github.com/dakanji/RefindPlus/blob/GOPFix/config.conf-sample). RefindPlus-Specific options can also be added to a refind.conf file and used that way if preferred.
 
-Note that if you run RefindPlus without activating the additional options, as will be the case if using an unmodified upstream configuration file, a RefindPlus run will be equivalent to running the upstream version it is based on, currently v0.13.3. That is, the additional options provided in RefindPlus must be actively enabled if they are required. This equivalence is subject to a few divergent items in RefindPlus as outlined under the [Divergence](https://github.com/dakanji/RefindPlus#divergence) section below. NB: Upstream post-release code updates are typically ported to RefindPlus as they happen and as such, RefindPlus releases are actually at the state of the upstream release version plus any such updates.
+Note that if you run RefindPlus without activating the additional options, as will be the case if using an unmodified upstream configuration file, a RefindPlus run will be equivalent to running the upstream version it is based on, currently v0.13.3. That is, the additional options provided in RefindPlus must be actively enabled if they are required. This equivalence is subject to a few divergent items in RefindPlus as outlined under the [Divergence](https://github.com/dakanji/RefindPlus#divergence) section below. NB: Upstream post-release code updates are typically ported to RefindPlus as they happen and as such, RefindPlus releases are actually at the state of the base upstream release version plus any such updates and typically include updates for subsequent upstream release versions since the base version.
 
 ## Additional Functionality
 RefindPlus-Specific funtionality can be configured by adding the tokens below to the upstream configuration file. Additional information is provided in the sample RefindPlus configuration file.
@@ -128,8 +128,9 @@ Implementation differences with the upstream base version v0.13.3 are:
 - **APFS Verbose Text Suppression:** RefindPlus defaults to always suppresses verbose text output associated with loading APFS functionality by the built in `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.
-- **ESP Scanning:** Other ESPs separate from that containing the active efi file are now also scanned for loaders by rEFInd. The earlier behaviour, where all other ESPs were treated as duplicates and ignored, has been considered an error and changed. This earlier behaviour is preferred and maintained in RefindPlus. However, users have the option to override this behaviour, in favour of the new upstream behaviour, by activating the RefindPlus-Specific `decline_esp_filter` configuration token.
 - **Disabled Manual Stanzas:** The processing of a user configured boot stanza is halted once a `Disabled` setting is encountered and the `Entry` object returned 'as is'. The outcome is the same as upstream, which always proceeds to create and return a fully built object in such cases (subsequently discarded), and RefindPlus, which may return a partial object (similarly discarded). However, 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/fc18306b33b64d8473c96364cca6a557cc53530f/config.conf-sample#L1124-L1130) file). This also applies to `submenuentry` items which can be enabled or disabled separately.
+- **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. The 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.
 - **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

config.conf-sample

@@ -43,12 +43,12 @@
 #
 #csr_normalise
 
-# Supply APFS filesystem capability. By default, RefindPlus is set up to jumpstart
-# 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.
+# Supply APFS filesystem capability. By default, RefindPlus is set up to jump start
+# Mac OS APFS filesystem drivers, apfs.efi, which are available in system folders of
+# Mac OS 10.13 (High Sierra) and later. The drivers are loaded to match each specific
+# Mac OS version which ensures that any changes made to APFS drivers for each specific
+# Mac OS version are accommodated, compared to using one driver no matter what specific
+# Mac OS 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
@@ -203,14 +203,14 @@
 #
 #disable_nvram_paniclog
 
-# Check to see if it is possible to dispatch additional DXE drivers.
+# 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
 # automatically went into a loop to install such revealed DXE drivers
-# until all such were installed. This loop and installation may result
-# in unwanted drivers being installed and also slows the loading speed
-# while not being required on most types of firmware. Hence, an option
-# to skip this process is desirable when running most types of firmware
+# until all such were installed. This installation loop *MAY* end with
+# unwanted DXE drivers being installed, and also reduces loading speed
+# while not being required on some types of firmware. Hence, an option
+# to skip the process *MAY* be desirable on affected types of firmware.
 #
 # Inactive when commented out (Does not stop rescans for DXE drivers)
 #
@@ -1010,8 +1010,7 @@
 #scan_all_linux_kernels
 
 # Delay for the specified number of seconds before scanning disks.
-# This can help some users who find that some of their disks
-# are not detected until after pressing the "ESC" key.
+# This may help when disks are not detected until "ESC" is pressed.
 #
 # Inactive when commented out (Does not wait before scanning disks)
 #
@@ -1032,18 +1031,24 @@
 
 # Custom background image for selected item. There is a big one (144 x 144)
 # for the OS icons, and a small one (64 x 64) for the function icons in the
-# second row. If only a small image is given, that one is also used for the
-# big icons by stretching it in the middle. If only a big one is given, the
-# built-in default will be used for the small icons. If an image other than
-# an optimally sized one is specified, this may be scaled in an "ugly" way.
+# second row. When images other than optimally sized ones are specified, they
+# may be scaled in an "ugly" way. When a specified image is not available, the
+# built-in default will be used instead. This replacement with a default image
+# applies to both the specified "small" and "big" selection images separately.
 #
 # As with the "banner" setting below, these options take filenames of
 # uncompressed BMP, JPEG, PNG or ICNS image files with a colour depth
 # of 24, 8, 4, or 1 bits. PNG or ICNS image files are required for
 # transparency support. As with the "banner" setting below, paths
 # are relative to the directory containing the RefindPlus efi.
 #
-# Uses default selection background images when commented out
+# NB: The file used for 'selection_small' must be no more
+# than 256px on the longest side while that used as the
+# 'selection_big' image must be no larger than 320px.
+# Custom selection images larger these thresholds
+# will be replaced with default embedded images.
+#
+# Uses default selection images when commented out
 #
 #selection_big icons/selection-big.png
 #selection_small icons/selection-small.png
@@ -1116,11 +1121,20 @@
 # file is loaded as if its tokens appeared at the point of the "include"
 # option. So, to override a setting in the main file, the secondary file
 # must be referenced AFTER the setting to be overridden. NB: A secondary
-# configuration file cannot "include" a tertiary configuration file.
+# configuration file CANNOT "include" tertiary configuration files.
+#
+# Manual configuration stanzas (see next item) may also be specified within
+# separate files and loaded as if their tokens appeared at the point of the
+# "include" option. Multiple such manual configuration stanza files can be
+# defined in addition to, or instead of, secondary configuration files as
+# described above. NB: Included manual configuration stanza files cannot
+# "include" tertiary, or other manual configuration stanza, files.
 #
 # Inactive when commented out (secondary file is not loaded)
 #
 #include manual.conf
+#include stanza-01.conf
+#include stanza-02.conf
 
 # Manual configuration stanzas. Each one begins with a "menuentry"
 # keyword followed by a name that will appear in the menu screen
@@ -1147,7 +1161,6 @@
 #                quotes if more than one option should be passed or
 #                if any options use characters that might be changed
 #                by RefindPlus' parsing procedures (=, /, #, or tab).
-#
 #  add_options - As "options" above but only applicable when under a
 #                "submenuentry" keyword. It adds the options to those
 #                set for the main "menuentry" keyword.

config.conf-sample-Dev

@@ -95,6 +95,14 @@
 #
 #decline_apple_fb
 
+# Allow scans of multiple ESPs. When this option is active, RefindPlus
+# will make other ESPs, separate from that containing RefindPlus,
+# available to be scanned for kernels and loaders.
+#
+# Scans of other ESPs are prevented when commented out
+#
+#decline_esp_filter
+
 # 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
@@ -208,14 +216,6 @@
 #
 #disable_rescan_dxe
 
-# Limit scan of ESPs for kernels and loaders. When this option is active,
-# RefindPlus will ignore kernels and loaders in any other ESP
-# separate from the ESP that contains RefindPlus.
-#
-# Scans of other ESPs are allowed when commented out
-#
-#enable_esp_filter
-
 # When this option is activated, RefindPlus will process symlinked loaders.
 # Symlinks are ignored by default as they may result in undesirable outcomes.
 # This token may however be useful on Linux setups that use symlinked loaders.

include/version.h

@@ -16,4 +16,4 @@
  * Modifications distributed under the preceding terms.
  */
 
-#define REFINDPLUS_VERSION L"0.13.3.AD (PRE-RELEASE)"
+#define REFINDPLUS_VERSION L"0.13.3.AD"