feat(fwu): add platform hook for getting the boot index

Add a platform hook for returning the boot index, i.e. the bank from
which the platform has booted the updatable firmware images. This
value will be passed to the Update Agent.

Signed-off-by: Sughosh Ganu <sughosh.ganu@linaro.org>
Change-Id: Ic7bef21071c48cfc7b69c50e89df9ff758d95b00

docs/getting_started/porting-guide.rst

@@ -932,6 +932,25 @@ It returns '0' on success, otherwise a negative error value on error.
 Alongside, returns device handle and image specification from the I/O policy
 of the requested FWU metadata image.
 
+Function : plat_fwu_get_boot_idx() [when PSA_FWU_SUPPORT == 1]
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+::
+
+    Argument : void
+    Return   : uint32_t
+
+This function is mandatory when PSA_FWU_SUPPORT is enabled. It provides the
+means to retrieve the boot index value from the platform. The boot index is the
+bank from which the platform has booted the firmware images.
+
+By default, the platform will read the metadata structure and try to boot from
+the active bank. If the platform fails to boot from the active bank due to
+reasons like an Authentication failure, or on crossing a set number of watchdog
+resets while booting from the active bank, the platform can then switch to boot
+from a different bank. This function then returns the bank that the platform
+should boot its images from.
+
 Common optional modifications
 -----------------------------
 

include/plat/common/platform.h

@@ -390,5 +390,6 @@ int plat_fwu_set_metadata_image_source(unsigned int image_id,
 				       uintptr_t *dev_handle,
 				       uintptr_t *image_spec);
 void plat_fwu_set_images_source(const struct fwu_metadata *metadata);
+uint32_t plat_fwu_get_boot_idx(void);
 
 #endif /* PLATFORM_H */