app_update: Moved app metadata to new component esp_app_format

components/esp_app_format/CMakeLists.txt

@@ -0,0 +1,26 @@
+idf_component_register(SRCS "esp_app_desc.c"
+                    INCLUDE_DIRS "include")
+
+# esp_app_desc structure is added as an undefined symbol because otherwise the
+# linker will ignore this structure as it has no other files depending on it.
+if(NOT BOOTLOADER_BUILD)
+    target_link_libraries(${COMPONENT_LIB} INTERFACE "-u esp_app_desc")
+endif()
+
+if(CONFIG_APP_PROJECT_VER_FROM_CONFIG)
+    # Ignore current PROJECT_VER (which was set in __project_get_revision()).
+    # Gets the version from the CONFIG_APP_PROJECT_VER.
+    idf_build_set_property(PROJECT_VER "${CONFIG_APP_PROJECT_VER}")
+endif()
+
+# cut PROJECT_VER and PROJECT_NAME to required 32 characters.
+idf_build_get_property(project_ver PROJECT_VER)
+idf_build_get_property(project_name PROJECT_NAME)
+string(SUBSTRING "${project_ver}" 0 31 PROJECT_VER_CUT)
+string(SUBSTRING "${project_name}" 0 31 PROJECT_NAME_CUT)
+message(STATUS "App \"${PROJECT_NAME_CUT}\" version: ${PROJECT_VER_CUT}")
+
+set_source_files_properties(
+    SOURCE "esp_app_desc.c"
+    PROPERTIES COMPILE_DEFINITIONS
+    "PROJECT_VER=\"${PROJECT_VER_CUT}\"; PROJECT_NAME=\"${PROJECT_NAME_CUT}\"")

components/esp_app_format/Kconfig.projbuild

@@ -0,0 +1,49 @@
+menu "Application manager"
+
+    config APP_COMPILE_TIME_DATE
+        bool "Use time/date stamp for app"
+        default y
+        help
+            If set, then the app will be built with the current time/date stamp. It is stored in the app description
+            structure. If not set, time/date stamp will be excluded from app image. This can be useful for getting the
+            same binary image files made from the same source, but at different times.
+
+    config APP_EXCLUDE_PROJECT_VER_VAR
+        bool "Exclude PROJECT_VER from firmware image"
+        default n
+        help
+            The PROJECT_VER variable from the build system will not affect the firmware image.
+            This value will not be contained in the esp_app_desc structure.
+
+    config APP_EXCLUDE_PROJECT_NAME_VAR
+        bool "Exclude PROJECT_NAME from firmware image"
+        default n
+        help
+            The PROJECT_NAME variable from the build system will not affect the firmware image.
+            This value will not be contained in the esp_app_desc structure.
+
+    config APP_PROJECT_VER_FROM_CONFIG
+        bool "Get the project version from Kconfig"
+        default n
+        help
+            If this is enabled, then config item APP_PROJECT_VER will be used for the variable PROJECT_VER.
+            Other ways to set PROJECT_VER will be ignored.
+
+    config APP_PROJECT_VER
+        string "Project version"
+        default "1"
+        depends on APP_PROJECT_VER_FROM_CONFIG
+        help
+            Project version
+
+    config APP_RETRIEVE_LEN_ELF_SHA
+        int "The length of APP ELF SHA is stored in RAM(chars)"
+        default 16
+        range 8 64
+        help
+            At startup, the app will read this many hex characters from the embedded APP ELF SHA-256 hash value
+            and store it in static RAM. This ensures the app ELF SHA-256 value is always available
+            if it needs to be printed by the panic handler code.
+            Changing this value will change the size of a static buffer, in bytes.
+
+endmenu # "Application manager"

components/esp_app_format/esp_app_desc.c

@@ -0,0 +1,103 @@
+/*
+ * SPDX-FileCopyrightText: 2022 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#include <assert.h>
+#include <sys/param.h>
+#include "esp_app_desc.h"
+#include "esp_attr.h"
+#include "sdkconfig.h"
+
+
+// Application version info
+const __attribute__((section(".rodata_desc"))) esp_app_desc_t esp_app_desc = {
+    .magic_word = ESP_APP_DESC_MAGIC_WORD,
+#ifdef CONFIG_APP_EXCLUDE_PROJECT_VER_VAR
+    .version = "",
+#else
+    .version = PROJECT_VER,
+#endif
+
+#ifdef CONFIG_APP_EXCLUDE_PROJECT_NAME_VAR
+    .project_name = "",
+#else
+    .project_name = PROJECT_NAME,
+#endif
+    .idf_ver = IDF_VER,
+
+#ifdef CONFIG_BOOTLOADER_APP_SECURE_VERSION
+    .secure_version = CONFIG_BOOTLOADER_APP_SECURE_VERSION,
+#else
+    .secure_version = 0,
+#endif
+
+#if defined(CONFIG_APP_COMPILE_TIME_DATE) && !defined(CONFIG_APP_REPRODUCIBLE_BUILD)
+    .time = __TIME__,
+    .date = __DATE__,
+#else
+    .time = "",
+    .date = "",
+#endif
+};
+
+
+#ifndef CONFIG_APP_EXCLUDE_PROJECT_VER_VAR
+_Static_assert(sizeof(PROJECT_VER) <= sizeof(esp_app_desc.version), "PROJECT_VER is longer than version field in structure");
+#endif
+_Static_assert(sizeof(IDF_VER) <= sizeof(esp_app_desc.idf_ver), "IDF_VER is longer than idf_ver field in structure");
+#ifndef CONFIG_APP_EXCLUDE_PROJECT_NAME_VAR
+_Static_assert(sizeof(PROJECT_NAME) <= sizeof(esp_app_desc.project_name), "PROJECT_NAME is longer than project_name field in structure");
+#endif
+
+const esp_app_desc_t *esp_app_get_description(void)
+{
+    return &esp_app_desc;
+}
+
+/* The following two functions may be called from the panic handler
+ * or core dump, hence IRAM_ATTR.
+ */
+
+static inline char IRAM_ATTR to_hex_digit(unsigned val)
+{
+    return (val < 10) ? ('0' + val) : ('a' + val - 10);
+}
+
+__attribute__((constructor)) void esp_init_app_elf_sha256(void)
+{
+    esp_app_get_elf_sha256(NULL, 0);
+}
+
+/* The esp_app_desc.app_elf_sha256 should be possible to print in panic handler during cache is disabled.
+ * But because the cache is disabled the reading esp_app_desc.app_elf_sha256 is not right and
+ * can lead to a complete lock-up of the CPU.
+ * For this reason we do a reading of esp_app_desc.app_elf_sha256 while start up in esp_init_app_elf_sha256()
+ * and keep it in the static s_app_elf_sha256 value.
+ */
+int IRAM_ATTR esp_app_get_elf_sha256(char* dst, size_t size)
+{
+    static char s_app_elf_sha256[CONFIG_APP_RETRIEVE_LEN_ELF_SHA / 2];
+    static bool first_call = true;
+    if (first_call) {
+        first_call = false;
+        // At -O2 optimization level, GCC optimizes out the copying of the first byte of the app_elf_sha256,
+        // because it is zero at compile time, and only modified afterwards by esptool.
+        // Casting to volatile disables the optimization.
+        const volatile uint8_t* src = (const volatile uint8_t*)esp_app_desc.app_elf_sha256;
+        for (size_t i = 0; i < sizeof(s_app_elf_sha256); ++i) {
+            s_app_elf_sha256[i] = src[i];
+        }
+    }
+    if (dst == NULL || size == 0) {
+        return 0;
+    }
+    size_t n = MIN((size - 1) / 2, sizeof(s_app_elf_sha256));
+    for (size_t i = 0; i < n; ++i) {
+        dst[2*i] = to_hex_digit(s_app_elf_sha256[i] >> 4);
+        dst[2*i + 1] = to_hex_digit(s_app_elf_sha256[i] & 0xf);
+    }
+    dst[2*n] = 0;
+    return 2*n + 1;
+}

components/esp_app_format/include/esp_app_desc.h

@@ -0,0 +1,61 @@
+/*
+ * SPDX-FileCopyrightText: 2022 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+#pragma once
+
+#include <stdint.h>
+#include <stdbool.h>
+#include <stddef.h>
+#include "esp_err.h"
+
+#ifdef __cplusplus
+extern "C"
+{
+#endif
+
+#define ESP_APP_DESC_MAGIC_WORD (0xABCD5432)  /*!< The magic word for the esp_app_desc structure that is in DROM. */
+
+/**
+ * @brief Description about application.
+ */
+typedef struct {
+    uint32_t magic_word;        /*!< Magic word ESP_APP_DESC_MAGIC_WORD */
+    uint32_t secure_version;    /*!< Secure version */
+    uint32_t reserv1[2];        /*!< reserv1 */
+    char version[32];           /*!< Application version */
+    char project_name[32];      /*!< Project name */
+    char time[16];              /*!< Compile time */
+    char date[16];              /*!< Compile date*/
+    char idf_ver[32];           /*!< Version IDF */
+    uint8_t app_elf_sha256[32]; /*!< sha256 of elf file */
+    uint32_t reserv2[20];       /*!< reserv2 */
+} esp_app_desc_t;
+
+/** @cond */
+_Static_assert(sizeof(esp_app_desc_t) == 256, "esp_app_desc_t should be 256 bytes");
+/** @endcond */
+
+/**
+ * @brief   Return esp_app_desc structure. This structure includes app version.
+ *
+ * Return description for running app.
+ * @return Pointer to esp_app_desc structure.
+ */
+const esp_app_desc_t *esp_app_get_description(void);
+
+/**
+ * @brief   Fill the provided buffer with SHA256 of the ELF file, formatted as hexadecimal, null-terminated.
+ * If the buffer size is not sufficient to fit the entire SHA256 in hex plus a null terminator,
+ * the largest possible number of bytes will be written followed by a null.
+ * @param dst   Destination buffer
+ * @param size  Size of the buffer
+ * @return      Number of bytes written to dst (including null terminator)
+ */
+int esp_app_get_elf_sha256(char* dst, size_t size);
+
+#ifdef __cplusplus
+}
+#endif

components/esp_app_format/test/CMakeLists.txt

@@ -0,0 +1,4 @@
+idf_component_register(SRC_DIRS "."
+                       PRIV_INCLUDE_DIRS "."
+                       PRIV_REQUIRES cmock test_utils app_update bootloader_support nvs_flash driver
+                      )

components/esp_app_format/test/test_app_desc.c

@@ -0,0 +1,55 @@
+/*
+ * SPDX-FileCopyrightText: 2021-2022 Espressif Systems (Shanghai) CO LTD
+ *
+ * SPDX-License-Identifier: Apache-2.0
+ */
+#include <string.h>
+#include "esp_app_desc.h"
+#include "unity.h"
+
+TEST_CASE("esp_get_app_elf_sha256 test", "[esp_app_desc]")
+{
+    const int sha256_hex_len = CONFIG_APP_RETRIEVE_LEN_ELF_SHA;
+    char dst[sha256_hex_len + 2];
+    const char fill = 0xcc;
+    int res;
+    size_t len;
+
+    char ref_sha256[sha256_hex_len + 1];
+    const esp_app_desc_t* desc = esp_get_app_description();
+    for (int i = 0; i < sizeof(ref_sha256) / 2; ++i) {
+        snprintf(ref_sha256 + 2*i, 3, "%02x", desc->app_elf_sha256[i]);
+    }
+    ref_sha256[sha256_hex_len] = 0;
+
+    printf("Ref: %s\n", ref_sha256);
+
+    memset(dst, fill, sizeof(dst));
+    len = sizeof(dst);
+    res = esp_get_app_elf_sha256(dst, len);
+    printf("%d: %s (%d)\n", len, dst, res);
+    TEST_ASSERT_EQUAL(sha256_hex_len + 1, res);
+    TEST_ASSERT_EQUAL(0, memcmp(dst, ref_sha256, res - 1));
+    TEST_ASSERT_EQUAL_HEX(0, dst[sha256_hex_len]);
+    TEST_ASSERT_EQUAL_HEX(fill, dst[sha256_hex_len + 1]);
+
+    memset(dst, fill, sizeof(dst));
+    len = 9;
+    res = esp_get_app_elf_sha256(dst, len);
+    printf("%d: %s (%d)\n", len, dst, res);
+    TEST_ASSERT_EQUAL(9, res);
+    TEST_ASSERT_EQUAL(0, memcmp(dst, ref_sha256, res - 1));
+    TEST_ASSERT_EQUAL_HEX(0, dst[8]);
+    TEST_ASSERT_EQUAL_HEX(fill, dst[9]);
+
+    memset(dst, fill, sizeof(dst));
+    len = 8;
+    res = esp_get_app_elf_sha256(dst, len);
+    printf("%d: %s (%d)\n", len, dst, res);
+    // should output even number of characters plus '\0'
+    TEST_ASSERT_EQUAL(7, res);
+    TEST_ASSERT_EQUAL(0, memcmp(dst, ref_sha256, res - 1));
+    TEST_ASSERT_EQUAL_HEX(0, dst[6]);
+    TEST_ASSERT_EQUAL_HEX(fill, dst[7]);
+    TEST_ASSERT_EQUAL_HEX(fill, dst[8]);
+}