board/ctrl: Add BOARDIOC_BOOT_IMAGE for booting a new application image

This command enables the application to perform the final steps of the
booting process prior to finally switching the execution to another
firmware image.

Signed-off-by: Gustavo Henrique Nihei <gustavo.nihei@espressif.com>

boards/Kconfig

@@ -3399,6 +3399,17 @@ config BOARDCTL_SWITCH_BOOT
 		once a firmware updated successfully, this boardctl can be used to
 		modify FLASH bank selection.
 
+config BOARDCTL_BOOT_IMAGE
+	bool "Boot a new application firmware image"
+	default n
+	---help---
+		Boot a new application firmware image.
+		Architecture-specific logic must provide the board_boot_image()
+		interface for executing the required actions for booting a new
+		application firmware image (e.g. deinitialize peripherals, load the
+		Program Counter register with the application firmware image entry
+		point address).
+
 config BOARDCTL_MKRD
 	bool "Enable application space creation of RAM disks"
 	default n

boards/boardctl.c

@@ -452,6 +452,31 @@ int boardctl(unsigned int cmd, uintptr_t arg)
         break;
 #endif
 
+#ifdef CONFIG_BOARDCTL_BOOT_IMAGE
+      /* CMD:           BOARDIOC_BOOT_IMAGE
+       * DESCRIPTION:   Boot a new application firmware image.
+       *                Execute the required actions for booting a new
+       *                application firmware image (e.g. deinitialize
+       *                peripherals, load the Program Counter register with
+       *                the application firmware image entry point address).
+       * ARG:           Pointer to a read-only instance of struct
+       *                boardioc_boot_info_s.
+       * DEPENDENCIES:  Board logic must provide the board_boot_image()
+       *                interface.
+       */
+
+      case BOARDIOC_BOOT_IMAGE:
+        {
+          FAR const struct boardioc_boot_info_s *info =
+            (FAR const struct boardioc_boot_info_s *)arg;
+
+          DEBUGASSERT(info != NULL);
+
+          ret = board_boot_image(info->path, info->header_size);
+        }
+        break;
+#endif
+
 #ifdef CONFIG_BOARDCTL_MKRD
       /* CMD:           BOARDIOC_MKRD
        * DESCRIPTION:   Create a RAM disk

include/nuttx/board.h

@@ -331,6 +331,32 @@ int board_uniquekey(FAR uint8_t *uniquekey);
 int board_switch_boot(FAR const char *system);
 #endif
 
+/****************************************************************************
+ * Name:  board_boot_image
+ *
+ * Description:
+ *   Boot a new application firmware image. Execute the required actions for
+ *   booting a new application firmware image (e.g. deinitialize peripherals,
+ *   load the Program Counter register with the application firmware image
+ *   entry point address).
+ *
+ * Input Parameters:
+ *   path     - Path to the new application firmware image to be booted.
+ *   hdr_size - Image header size in bytes. This value may be useful for
+ *              skipping metadata information preprended to the application
+ *              image.
+ *
+ * Returned Value:
+ *   If this function returns, then it was not possible to load the
+ *   application firmware image due to some constraints. The return value in
+ *   this case is a board-specific reason for the failure.
+ *
+ ****************************************************************************/
+
+#ifdef CONFIG_BOARDCTL_BOOT_IMAGE
+int board_boot_image(FAR const char *path, uint32_t hdr_size);
+#endif
+
 /****************************************************************************
  * Name:  board_timerhook
  *

include/sys/boardctl.h

@@ -202,6 +202,7 @@
 #define BOARDIOC_TESTSET           _BOARDIOC(0x0011)
 #define BOARDIOC_UNIQUEKEY         _BOARDIOC(0x0012)
 #define BOARDIOC_SWITCH_BOOT       _BOARDIOC(0x0013)
+#define BOARDIOC_BOOT_IMAGE        _BOARDIOC(0x0014)
 
 /* If CONFIG_BOARDCTL_IOCTL=y, then board-specific commands will be support.
  * In this case, all commands not recognized by boardctl() will be forwarded
@@ -210,7 +211,7 @@
  * User defined board commands may begin with this value:
  */
 
-#define BOARDIOC_USER              _BOARDIOC(0x0014)
+#define BOARDIOC_USER              _BOARDIOC(0x0015)
 
 /****************************************************************************
  * Public Type Definitions
@@ -392,6 +393,17 @@ struct boardioc_nxterm_ioctl_s
 };
 #endif /* CONFIG_NXTERM */
 
+#ifdef CONFIG_BOARDCTL_BOOT_IMAGE
+
+/* Structure containing the arguments to the BOARDIOC_BOOT_IMAGE command */
+
+struct boardioc_boot_info_s
+{
+  FAR const char *path;           /* Path to application firmware image */
+  uint32_t        header_size;    /* Size of the image header in bytes */
+};
+#endif
+
 /****************************************************************************
  * Public Data
  ****************************************************************************/