[PATCH 0/2] efi_loader: firmware: decouple dfu_alt_num from image_index

[PATCH 0/2] efi_loader: firmware: decouple dfu_alt_num from image_index

[Balaji Selvanathan via U-Boot]

RAW capsule updates hardcode dfu_alt_num = image_index - 1, which
assumes every board's fw_images[] table is a positionally
ordered mirror of its dfu_alt_info string. That's true for every
board that hand-writes fw_images[], but it breaks down for a platform
that builds the table by scanning its partition layout at boot: the
set of images and their indices can vary per board, with gaps where a
component isn't present, so image_index and dfu_alt_num can't be
assumed to stay in lockstep.

This series moves that calculation into a __weak
efi_firmware_get_dfu_alt_num() a platform can override, the same
pattern already used for efi_firmware_get_image_type_id() and the
efi_reset_system()/efi_get_time() hooks. The default implementation is
the same image_index - 1 every existing board relies on today, so
nothing needs to change anywhere else.

This is infrastructure for a follow-on series that builds fw_images[]
dynamically on Qualcomm boards, which needs this hook to keep
dfu_alt_num correct once the table stops being static.

This work is part of multi-image capsule update support for
Qualcomm boards.

Balaji Selvanathan (2):

efi_loader: firmware: decouple dfu_alt_num from image_index
test: efi_capsule: add sandbox coverage for dfu_alt_num override
---
Balaji Selvanathan (2):
      efi_loader: firmware: decouple dfu_alt_num from image_index
      test: efi_capsule: add sandbox coverage for dfu_alt_num override

 arch/sandbox/dts/sandbox_capsule.dtsi              | 12 ++++++
 board/sandbox/sandbox.c                            | 18 +++++++++
 include/efi_loader.h                               | 17 ++++++++
 include/sandbox_efi_capsule.h                      |  1 +
 lib/efi_loader/efi_firmware.c                      | 21 +++++++++-
 .../test_efi_capsule/test_capsule_firmware_raw.py  | 45 ++++++++++++++++++++++
 6 files changed, 112 insertions(+), 2 deletions(-)
---
base-commit: 36c377b9859ffb53eb1e39ea31e8d96d1e0fe1e5
change-id: 20260811-efi-firmware-dfu-alt-num-1289dae96490

Best regards,
-- 
Balaji Selvanathan <balaji.selvanathan@oss.qualcomm.com>

[PATCH 1/2] efi_loader: firmware: decouple dfu_alt_num from image_index

[Balaji Selvanathan via U-Boot]

RAW capsule updates assume dfu_alt_num is always image_index - 1, i.e.
that fw_images[] is a positionally-ordered mirror of the DFU alt
settings. That holds for every board that builds its fw_images[] table
by hand, but a platform whose image list is discovered at runtime
(varying per board, with gaps for missing components) can't guarantee
image_index and dfu_alt_num stay in lockstep.

Move the (image_index - 1) calculation into a __weak function that
platforms can override, following the pattern already used for
efi_firmware_get_image_type_id(). The default keeps the
existing behaviour, so no other board needs any change.

Signed-off-by: Balaji Selvanathan <balaji.selvanathan@oss.qualcomm.com>
---
 include/efi_loader.h          | 17 +++++++++++++++++
 lib/efi_loader/efi_firmware.c | 21 +++++++++++++++++++--
 2 files changed, 36 insertions(+), 2 deletions(-)

diff --git a/include/efi_loader.h b/include/efi_loader.h
index 3a4d502631c..6626674f738 100644
--- a/include/efi_loader.h
+++ b/include/efi_loader.h
@@ -1187,11 +1187,15 @@ efi_status_t efi_capsule_authenticate(const void *capsule,
  * @fw_name:		Name of the firmware image
  * @image_index:	Image Index, same as value passed to SetImage FMP
  *                      function
+ * @dfu_alt_num:	DFU alt setting number for this image. Only consulted
+ *                      by a platform's efi_firmware_get_dfu_alt_num()
+ *                      override
  */
 struct efi_fw_image {
 	efi_guid_t image_type_id;
 	u16 *fw_name;
 	u8 image_index;
+	u8 dfu_alt_num;
 };
 
 /**
@@ -1240,6 +1244,19 @@ efi_status_t efi_ecpt_register(void);
 efi_status_t efi_esrt_populate(void);
 efi_status_t efi_load_capsule_drivers(void);
 
+/**
+ * efi_firmware_get_dfu_alt_num() - get the DFU alt setting number for an image
+ * @image_index:	image index
+ *
+ * Return the DFU alt setting number to use when writing the image
+ * identified by @image_index. Weak default derives it positionally as
+ * (image_index - 1); a platform whose fw_images[] is not laid out 1:1 with
+ * DFU alt numbers should override this function.
+ *
+ * Return:		DFU alt setting number
+ */
+u8 efi_firmware_get_dfu_alt_num(u8 image_index);
+
 efi_status_t platform_get_eventlog(struct udevice *dev, u64 *addr, u32 *sz);
 
 efi_status_t efi_locate_handle_buffer_int(enum efi_locate_search_type search_type,
diff --git a/lib/efi_loader/efi_firmware.c b/lib/efi_loader/efi_firmware.c
index b41969c70fd..c7339412055 100644
--- a/lib/efi_loader/efi_firmware.c
+++ b/lib/efi_loader/efi_firmware.c
@@ -80,6 +80,22 @@ efi_guid_t *efi_firmware_get_image_type_id(u8 image_index)
 	return NULL;
 }
 
+/**
+ * efi_firmware_get_dfu_alt_num - get the DFU alt setting number for an image
+ * @image_index:	image index
+ *
+ * Return the DFU alt setting number to use when writing the image
+ * identified by @image_index. The generic default derives it positionally
+ * from @image_index; a platform whose fw_images[] is not laid out 1:1 with
+ * DFU alt numbers should override this function.
+ *
+ * Return:		DFU alt setting number
+ */
+u8 __weak efi_firmware_get_dfu_alt_num(u8 image_index)
+{
+	return image_index - 1;
+}
+
 /* Place holder; not supported */
 static
 efi_status_t EFIAPI efi_firmware_get_image_unsupported(
@@ -768,9 +784,10 @@ efi_status_t EFIAPI efi_firmware_raw_set_image(
 	/*
 	 * dfu_alt_num is assigned from 0 while image_index starts from 1.
 	 * dfu_alt_num is calculated by (image_index - 1) when multi bank update
-	 * is not used.
+	 * is not used. A platform may override efi_firmware_get_dfu_alt_num()
+	 * if its fw_images[] is not laid out 1:1 with DFU alt numbers.
 	 */
-	dfu_alt_num = image_index - 1;
+	dfu_alt_num = efi_firmware_get_dfu_alt_num(image_index);
 	if (IS_ENABLED(CONFIG_FWU_MULTI_BANK_UPDATE)) {
 		/*
 		 * Based on the value of update bank, derive the

-- 
2.34.1

[PATCH 2/2] test: efi_capsule: add sandbox coverage for dfu_alt_num override

[Balaji Selvanathan via U-Boot]

Add a third sandbox fw_images[] entry (image_index 3) that aliases
onto the same DFU alt setting as image_index 1 through a strong
efi_firmware_get_dfu_alt_num() override, plus the matching capsule
GUID and test case that applies it via ESRT and checks the write
landed. Without the override this would fail, since dfu_alt_info has
no alt number 2 (the default image_index - 1) defined.

Signed-off-by: Balaji Selvanathan <balaji.selvanathan@oss.qualcomm.com>
---
 arch/sandbox/dts/sandbox_capsule.dtsi              | 12 ++++++
 board/sandbox/sandbox.c                            | 18 +++++++++
 include/sandbox_efi_capsule.h                      |  1 +
 .../test_efi_capsule/test_capsule_firmware_raw.py  | 45 ++++++++++++++++++++++
 4 files changed, 76 insertions(+)

diff --git a/arch/sandbox/dts/sandbox_capsule.dtsi b/arch/sandbox/dts/sandbox_capsule.dtsi
index 34d29916b30..e5464df1715 100644
--- a/arch/sandbox/dts/sandbox_capsule.dtsi
+++ b/arch/sandbox/dts/sandbox_capsule.dtsi
@@ -166,4 +166,16 @@
 			};
 		};
 	};
+
+	capsule12 {
+		filename = "Test06";
+		efi-capsule {
+			image-index = <0x3>;
+			image-guid = SANDBOX_ALTIMG_IMAGE_GUID;
+
+			text {
+				text = "u-boot:New";
+			};
+		};
+	};
 };
diff --git a/board/sandbox/sandbox.c b/board/sandbox/sandbox.c
index 13006a0ffc2..8ae7c244a09 100644
--- a/board/sandbox/sandbox.c
+++ b/board/sandbox/sandbox.c
@@ -42,6 +42,16 @@ struct efi_fw_image fw_images[] = {
 		.fw_name = u"SANDBOX-UBOOT-ENV",
 		.image_index = 2,
 	},
+	{
+		/*
+		 * Aliases image_index 3 onto the same DFU alt setting (0) as
+		 * SANDBOX-UBOOT above, to exercise the
+		 * efi_firmware_get_dfu_alt_num() override below and prove it
+		 * is consulted instead of the default (image_index - 1 = 2).
+		 */
+		.fw_name = u"SANDBOX-ALTIMG",
+		.image_index = 3,
+	},
 #elif defined(CONFIG_EFI_CAPSULE_FIRMWARE_FIT)
 	{
 		.fw_name = u"SANDBOX-FIT",
@@ -57,6 +67,14 @@ struct efi_capsule_update_info update_info = {
 	.images = fw_images,
 };
 
+u8 efi_firmware_get_dfu_alt_num(u8 image_index)
+{
+	if (image_index == 3)
+		return 0;
+
+	return image_index - 1;
+}
+
 #endif /* EFI_HAVE_CAPSULE_SUPPORT */
 
 #if !CONFIG_IS_ENABLED(OF_PLATDATA)
diff --git a/include/sandbox_efi_capsule.h b/include/sandbox_efi_capsule.h
index 84d45ec5cfd..848f1bdc4aa 100644
--- a/include/sandbox_efi_capsule.h
+++ b/include/sandbox_efi_capsule.h
@@ -10,6 +10,7 @@
 #define SANDBOX_UBOOT_ENV_IMAGE_GUID	"9e339473-c2eb-530a-a69b-0cd6bbbed40e"
 #define SANDBOX_FIT_IMAGE_GUID		"46610520-469e-59dc-a8dd-c11832b877ea"
 #define SANDBOX_INCORRECT_GUID		"058b7d83-50d5-4c47-a195-60d86ad341c4"
+#define SANDBOX_ALTIMG_IMAGE_GUID	"2d137324-092d-5f04-a62c-a7b2442cb0ee"
 
 #define UBOOT_FIT_IMAGE			"u-boot_bin_env.itb"
 
diff --git a/test/py/tests/test_efi_capsule/test_capsule_firmware_raw.py b/test/py/tests/test_efi_capsule/test_capsule_firmware_raw.py
index b8cb483b380..6c1cc3c6cc8 100644
--- a/test/py/tests/test_efi_capsule/test_capsule_firmware_raw.py
+++ b/test/py/tests/test_efi_capsule/test_capsule_firmware_raw.py
@@ -238,3 +238,48 @@ class TestEfiCapsuleFirmwareRaw:
             check_file_removed(ubman, disk_img, capsule_files)
 
             verify_content(ubman, '100000', 'u-boot:Old')
+
+    def test_efi_capsule_fw6(
+            self, u_boot_config, ubman, efi_capsule_data):
+        """ Test Case 6
+        Update U-Boot on SPI Flash via an image_index whose DFU alt number
+        is resolved through board/sandbox/sandbox.c's
+        efi_firmware_get_dfu_alt_num() override rather than the default
+        (image_index - 1), proving the override is honored.
+        0x100000-0x150000: U-Boot binary (but dummy)
+        """
+        disk_img = efi_capsule_data
+        capsule_files = ['Test06']
+        with ubman.log.section('Test Case 6-a, before reboot'):
+            capsule_setup(ubman, disk_img, '0x0000000000000004')
+            init_content(ubman, '100000', 'u-boot.bin.old', 'Old')
+            place_capsule_file(ubman, capsule_files)
+
+        capsule_early = u_boot_config.buildconfig.get(
+            'config_efi_capsule_on_disk_early')
+        capsule_auth = u_boot_config.buildconfig.get(
+            'config_efi_capsule_authenticate')
+
+        # reboot
+        ubman.restart_uboot(expect_reset = capsule_early)
+
+        with ubman.log.section('Test Case 6-b, after reboot'):
+            if not capsule_early:
+                exec_manual_update(ubman, disk_img, capsule_files)
+
+            # make sure the dfu_alt_info exists because it is required for making ESRT.
+            output = ubman.run_command_list([
+                'env set dfu_alt_info "sf 0:0=u-boot-bin raw 0x100000 0x50000;u-boot-env raw 0x150000 0x200000"',
+                'efidebug capsule esrt'])
+
+            # ensure that SANDBOX_ALTIMG_IMAGE_GUID is in the ESRT.
+            assert '2D137324-092D-5F04-A62C-A7B2442CB0EE' in ''.join(output)
+
+            check_file_removed(ubman, disk_img, capsule_files)
+
+            # the override maps image_index 3 to dfu_alt_num 0, the same
+            # alt as SANDBOX-UBOOT (image_index 1). Without the override,
+            # the default (image_index - 1 = 2) does not exist in
+            # dfu_alt_info and the write would fail, leaving content 'Old'.
+            expected = 'u-boot:Old' if capsule_auth else 'u-boot:New'
+            verify_content(ubman, '100000', expected)

-- 
2.34.1

Re: [PATCH 0/2] efi_loader: firmware: decouple dfu_alt_num from image_index

[Balaji Selvanathan]

Hi Ilias,

Request your opinion on this series.

Regards,

Balaji

On 8/13/2026 11:23 AM, Balaji Selvanathan wrote:
> RAW capsule updates hardcode dfu_alt_num = image_index - 1, which
> assumes every board's fw_images[] table is a positionally
> ordered mirror of its dfu_alt_info string. That's true for every
> board that hand-writes fw_images[], but it breaks down for a platform
> that builds the table by scanning its partition layout at boot: the
> set of images and their indices can vary per board, with gaps where a
> component isn't present, so image_index and dfu_alt_num can't be
> assumed to stay in lockstep.
>
> This series moves that calculation into a __weak
> efi_firmware_get_dfu_alt_num() a platform can override, the same
> pattern already used for efi_firmware_get_image_type_id() and the
> efi_reset_system()/efi_get_time() hooks. The default implementation is
> the same image_index - 1 every existing board relies on today, so
> nothing needs to change anywhere else.
>
> This is infrastructure for a follow-on series that builds fw_images[]
> dynamically on Qualcomm boards, which needs this hook to keep
> dfu_alt_num correct once the table stops being static.
>
> This work is part of multi-image capsule update support for
> Qualcomm boards.
>
> Balaji Selvanathan (2):
>
> efi_loader: firmware: decouple dfu_alt_num from image_index
> test: efi_capsule: add sandbox coverage for dfu_alt_num override
> ---
> Balaji Selvanathan (2):
>        efi_loader: firmware: decouple dfu_alt_num from image_index
>        test: efi_capsule: add sandbox coverage for dfu_alt_num override
>
>   arch/sandbox/dts/sandbox_capsule.dtsi              | 12 ++++++
>   board/sandbox/sandbox.c                            | 18 +++++++++
>   include/efi_loader.h                               | 17 ++++++++
>   include/sandbox_efi_capsule.h                      |  1 +
>   lib/efi_loader/efi_firmware.c                      | 21 +++++++++-
>   .../test_efi_capsule/test_capsule_firmware_raw.py  | 45 ++++++++++++++++++++++
>   6 files changed, 112 insertions(+), 2 deletions(-)
> ---
> base-commit: 36c377b9859ffb53eb1e39ea31e8d96d1e0fe1e5
> change-id: 20260811-efi-firmware-dfu-alt-num-1289dae96490
>
> Best regards,

Re: [PATCH 0/2] efi_loader: firmware: decouple dfu_alt_num from image_index

[Casey Connolly]

Hi Balaji,

On 13/08/2026 07:53, Balaji Selvanathan via U-Boot wrote:
> RAW capsule updates hardcode dfu_alt_num = image_index - 1, which
> assumes every board's fw_images[] table is a positionally
> ordered mirror of its dfu_alt_info string. That's true for every
> board that hand-writes fw_images[], but it breaks down for a platform
> that builds the table by scanning its partition layout at boot: the
> set of images and their indices can vary per board, with gaps where a
> component isn't present, so image_index and dfu_alt_num can't be
> assumed to stay in lockstep.
> 
> This series moves that calculation into a __weak
> efi_firmware_get_dfu_alt_num() a platform can override, the same
> pattern already used for efi_firmware_get_image_type_id() and the
> efi_reset_system()/efi_get_time() hooks. The default implementation is
> the same image_index - 1 every existing board relies on today, so
> nothing needs to change anywhere else.

Please tame your LLM, this isn't a sales pitch. I'd much rather see a
succint explanation from yourself, same goes for the code comments in
these patches. Please follow the tone of the project and avoid leaking
implementation details in function comments.

> 
> This is infrastructure for a follow-on series that builds fw_images[]
> dynamically on Qualcomm boards, which needs this hook to keep
> dfu_alt_num correct once the table stops being static.
> 
> This work is part of multi-image capsule update support for
> Qualcomm boards.
> 
> Balaji Selvanathan (2):
> 
> efi_loader: firmware: decouple dfu_alt_num from image_index
> test: efi_capsule: add sandbox coverage for dfu_alt_num override
> ---
> Balaji Selvanathan (2):
>       efi_loader: firmware: decouple dfu_alt_num from image_index
>       test: efi_capsule: add sandbox coverage for dfu_alt_num override
> 
>  arch/sandbox/dts/sandbox_capsule.dtsi              | 12 ++++++
>  board/sandbox/sandbox.c                            | 18 +++++++++
>  include/efi_loader.h                               | 17 ++++++++
>  include/sandbox_efi_capsule.h                      |  1 +
>  lib/efi_loader/efi_firmware.c                      | 21 +++++++++-
>  .../test_efi_capsule/test_capsule_firmware_raw.py  | 45 ++++++++++++++++++++++
>  6 files changed, 112 insertions(+), 2 deletions(-)
> ---
> base-commit: 36c377b9859ffb53eb1e39ea31e8d96d1e0fe1e5
> change-id: 20260811-efi-firmware-dfu-alt-num-1289dae96490
> 
> Best regards,

-- 
// Casey (she/her)

Re: [PATCH 1/2] efi_loader: firmware: decouple dfu_alt_num from image_index

[Ilias Apalodimas]

Hi Balaji,


On Thu Aug 13, 2026 at 8:53 AM EEST, Balaji Selvanathan wrote:
> RAW capsule updates assume dfu_alt_num is always image_index - 1, i.e.
> that fw_images[] is a positionally-ordered mirror of the DFU alt
> settings. That holds for every board that builds its fw_images[] table
> by hand, but a platform whose image list is discovered at runtime
> (varying per board, with gaps for missing components) can't guarantee
> image_index and dfu_alt_num stay in lockstep.
>
> Move the (image_index - 1) calculation into a __weak function that
> platforms can override, following the pattern already used for
> efi_firmware_get_image_type_id(). The default keeps the
> existing behaviour, so no other board needs any change.

*efi_firmware_get_image_type_id() was always static, which funtion did you mean?
fwu_plat_get_alt_num()?

>
> Signed-off-by: Balaji Selvanathan <balaji.selvanathan@oss.qualcomm.com>
> ---
>  include/efi_loader.h          | 17 +++++++++++++++++
>  lib/efi_loader/efi_firmware.c | 21 +++++++++++++++++++--
>  2 files changed, 36 insertions(+), 2 deletions(-)
>
> diff --git a/include/efi_loader.h b/include/efi_loader.h
> index 3a4d502631c..6626674f738 100644
> --- a/include/efi_loader.h
> +++ b/include/efi_loader.h
> @@ -1187,11 +1187,15 @@ efi_status_t efi_capsule_authenticate(const void *capsule,
>   * @fw_name:		Name of the firmware image
>   * @image_index:	Image Index, same as value passed to SetImage FMP
>   *                      function
> + * @dfu_alt_num:	DFU alt setting number for this image. Only consulted
> + *                      by a platform's efi_firmware_get_dfu_alt_num()
> + *                      override
>   */
>  struct efi_fw_image {
>  	efi_guid_t image_type_id;
>  	u16 *fw_name;
>  	u8 image_index;
> +	u8 dfu_alt_num;

Why do we need the extra struct member? The code doesn't update it to store any updates values.
Can't we just use the runtime result every time?

>  };
>
>  /**
> @@ -1240,6 +1244,19 @@ efi_status_t efi_ecpt_register(void);
>  efi_status_t efi_esrt_populate(void);
>  efi_status_t efi_load_capsule_drivers(void);
>
> +/**
> + * efi_firmware_get_dfu_alt_num() - get the DFU alt setting number for an image
> + * @image_index:	image index
> + *
> + * Return the DFU alt setting number to use when writing the image
> + * identified by @image_index. Weak default derives it positionally as
> + * (image_index - 1); a platform whose fw_images[] is not laid out 1:1 with
> + * DFU alt numbers should override this function.
> + *
> + * Return:		DFU alt setting number
> + */
> +u8 efi_firmware_get_dfu_alt_num(u8 image_index);
> +
>  efi_status_t platform_get_eventlog(struct udevice *dev, u64 *addr, u32 *sz);
>
>  efi_status_t efi_locate_handle_buffer_int(enum efi_locate_search_type search_type,
> diff --git a/lib/efi_loader/efi_firmware.c b/lib/efi_loader/efi_firmware.c
> index b41969c70fd..c7339412055 100644
> --- a/lib/efi_loader/efi_firmware.c
> +++ b/lib/efi_loader/efi_firmware.c
> @@ -80,6 +80,22 @@ efi_guid_t *efi_firmware_get_image_type_id(u8 image_index)
>  	return NULL;
>  }
>
> +/**
> + * efi_firmware_get_dfu_alt_num - get the DFU alt setting number for an image
> + * @image_index:	image index
> + *
> + * Return the DFU alt setting number to use when writing the image
> + * identified by @image_index. The generic default derives it positionally
> + * from @image_index; a platform whose fw_images[] is not laid out 1:1 with
> + * DFU alt numbers should override this function.
> + *
> + * Return:		DFU alt setting number
> + */
> +u8 __weak efi_firmware_get_dfu_alt_num(u8 image_index)
> +{
> +	return image_index - 1;
> +}

This is one of the things you need to support swapping image indexes on the fly, but there's way
more. One of the compromises we had to make to plug in capsuile updates via DFU is that the image
index *must* match the dfu command array member. IOW if you define the array with this

{guid_a, "u-boot", 1}, {guid_b, "u-boot-env", 2}
the dfu_string *must* list u-boot first and u-boot-env second.

IIRC we already check for a mismatch of GUID/Index in FWU code, but in the normal code we only have
a check in the efi_fmp_find(). The way you are switching happens after the check so you might end up
updating the partition with the wrond kind of firmware.

[...]

Cheers
/Ilias