fw_metadata: Rename fw_metadata to fw_info

Including configs, functions, types etc.

Signed-off-by: Øyvind Rønningstad <[email protected]>

Author: oyvindronningstad

CODEOWNERS

@@ -64,7 +64,7 @@ subsys/debug/CMakeLists.txt               @nordic-krch
 /subsys/dfu/                              @hakonfam @sigvartmh
 /subsys/enhanced_shockburst/              @Raane @lemrey
 /subsys/event_manager/                    @pdunaj
-/subsys/fw_metadata/                      @hakonfam
+/subsys/fw_info/                          @hakonfam
 /subsys/net/                              @rlubos
 /subsys/nfc/                              @grochu @anangl
 /subsys/partition_manager/                @hakonfam

include/bl_crypto.h

@@ -8,7 +8,7 @@
 #define BOOTLOADER_CRYPTO_H__
 
 #include <zephyr/types.h>
-#include <fw_metadata.h>
+#include <fw_info.h>
 
 /* Placeholder defines. Values should be updated, if no existing errors can be
  * used instead. */
@@ -155,14 +155,14 @@ EXT_ABI_FUNCTION(int, bl_secp256r1_validate, const u8_t *hash,
 					     const u8_t *public_key);
 
 struct bl_rot_verify_abi {
-	struct fw_abi_info header;
+	struct fw_info_abi header;
 	struct {
 		bl_root_of_trust_verify_t bl_root_of_trust_verify;
 	} abi;
 };
 
 struct bl_sha256_abi {
-	struct fw_abi_info header;
+	struct fw_info_abi header;
 	struct {
 		bl_sha256_init_t bl_sha256_init;
 		bl_sha256_update_t bl_sha256_update;
@@ -173,7 +173,7 @@ struct bl_sha256_abi {
 };
 
 struct bl_secp256r1_abi {
-	struct fw_abi_info header;
+	struct fw_info_abi header;
 	struct {
 		bl_secp256r1_validate_t bl_secp256r1_validate;
 	} abi;

include/bl_validation.h

@@ -8,9 +8,9 @@
 #define BL_VALIDATION_H__
 
 #include <stdbool.h>
-#include <fw_metadata.h>
+#include <fw_info.h>
 
 bool bl_validate_firmware_local(u32_t fw_address,
-				const struct fw_firmware_info *fw_info);
+				const struct fw_info *fwinfo);
 
 #endif /* BL_VALIDATION_H__ */

include/fw_metadata.h renamed to include/fw_info.h

@@ -4,8 +4,8 @@
  * SPDX-License-Identifier: LicenseRef-BSD-5-Clause-Nordic
  */
 
-#ifndef FW_METADATA_H__
-#define FW_METADATA_H__
+#ifndef FW_INFO_H__
+#define FW_INFO_H__
 
 /*
  * The package will consist of (firmware | (padding) | validation_info),
@@ -30,9 +30,9 @@
 #include <pm_config.h>
 #endif
 
-#define MAGIC_LEN_WORDS (CONFIG_FW_MAGIC_LEN / sizeof(u32_t))
+#define MAGIC_LEN_WORDS (CONFIG_FW_INFO_MAGIC_LEN / sizeof(u32_t))
 
-struct fw_abi_info;
+struct fw_info_abi;
 
 /**@brief Function that returns an ABI.
  *
@@ -46,14 +46,20 @@ struct fw_abi_info;
  * @retval -EBADF   index too large.
  * @retval -EFAULT  abi was NULL.
  */
-typedef int (*fw_abi_getter)(u32_t id, u32_t index,
-				const struct fw_abi_info **abi);
-
-struct __packed fw_firmware_info {
-	/* Magic value to verify that the struct has the correct type. */
+typedef int (*fw_info_abi_getter)(u32_t id, u32_t index,
+				const struct fw_info_abi **abi);
+
+/**
+ * This is a data structure that is placed at a specific offset inside a
+ * firmware image so it can be consistently read by external parties. The
+ * specific offset makes it easy to find, and the magic value at the start
+ * guarantees that it contains data of a specific format.
+ */
+struct __packed fw_info {
+	/* Magic value to verify that the struct has the correct format. */
 	u32_t magic[MAGIC_LEN_WORDS];
 
-	/* Size without validation_info pointer and padding. */
+	/* Size of the firmware image code. */
 	u32_t firmware_size;
 
 	/* Monotonically increasing version counter.*/
@@ -63,10 +69,10 @@ struct __packed fw_firmware_info {
 	u32_t firmware_address;
 
 	/* Where to place the getter for the ABI provided to this firmware. */
-	fw_abi_getter *abi_in;
+	fw_info_abi_getter *abi_in;
 
 	/* This firmware's ABI getter. */
-	const fw_abi_getter abi_out;
+	const fw_info_abi_getter abi_out;
 };
 
 
@@ -75,23 +81,24 @@ struct __packed fw_firmware_info {
 				#member " has wrong offset")
 
 /* Static asserts to ensure compatibility */
-OFFSET_CHECK(struct fw_firmware_info, magic, 0);
-OFFSET_CHECK(struct fw_firmware_info, firmware_size, CONFIG_FW_MAGIC_LEN);
-OFFSET_CHECK(struct fw_firmware_info, firmware_version,
-	(CONFIG_FW_MAGIC_LEN + 4));
-OFFSET_CHECK(struct fw_firmware_info, firmware_address,
-	(CONFIG_FW_MAGIC_LEN + 8));
+OFFSET_CHECK(struct fw_info, magic, 0);
+OFFSET_CHECK(struct fw_info, firmware_size, CONFIG_FW_INFO_MAGIC_LEN);
+OFFSET_CHECK(struct fw_info, firmware_version,
+	(CONFIG_FW_INFO_MAGIC_LEN + 4));
+OFFSET_CHECK(struct fw_info, firmware_address,
+	(CONFIG_FW_INFO_MAGIC_LEN + 8));
 
 /* For declaring this firmware's firmware info. */
 #define __fw_info Z_GENERIC_SECTION(.firmware_info) __attribute__((used)) const
 
-/* This struct is meant to serve as a header before a list of function pointers
+/**
+ * This struct is meant to serve as a header before a list of function pointers
  * (or something else) that constitute the actual ABI. How to use the ABI, such
  * as the signatures of all the functions in the list must be unambiguous for an
  * ID/version combination.
  */
-struct __packed fw_abi_info {
-	/* Magic value to verify that the struct has the correct type. */
+struct __packed fw_info_abi {
+	/* Magic value to verify that the struct has the correct format. */
 	u32_t magic[MAGIC_LEN_WORDS];
 
 	/* The id of the ABI. */
@@ -116,10 +123,11 @@ struct __packed fw_abi_info {
 
 #define __ext_abi(type, name) \
 	OFFSET_CHECK_EXT_ABI(type, magic, 0); \
-	OFFSET_CHECK_EXT_ABI(type, abi_id, CONFIG_FW_MAGIC_LEN); \
-	OFFSET_CHECK_EXT_ABI(type, abi_flags, (CONFIG_FW_MAGIC_LEN + 4)); \
-	OFFSET_CHECK_EXT_ABI(type, abi_version, (CONFIG_FW_MAGIC_LEN + 8)); \
-	OFFSET_CHECK_EXT_ABI(type, abi_len, (CONFIG_FW_MAGIC_LEN + 12)); \
+	OFFSET_CHECK_EXT_ABI(type, abi_id, CONFIG_FW_INFO_MAGIC_LEN); \
+	OFFSET_CHECK_EXT_ABI(type, abi_flags, (CONFIG_FW_INFO_MAGIC_LEN + 4)); \
+	OFFSET_CHECK_EXT_ABI(type, abi_version,\
+				(CONFIG_FW_INFO_MAGIC_LEN + 8)); \
+	OFFSET_CHECK_EXT_ABI(type, abi_len, (CONFIG_FW_INFO_MAGIC_LEN + 12)); \
 	BUILD_ASSERT_MSG((sizeof(type) % 4) == 0, \
 			"ext_abi " #type " is not word-aligned"); \
 	extern const type name; \
@@ -130,7 +138,7 @@ struct __packed fw_abi_info {
 
 
 
-#define ABI_INFO_INIT(id, flags, version, total_size) \
+#define FW_INFO_ABI_INIT(id, flags, version, total_size) \
 	{ \
 		.magic = {ABI_INFO_MAGIC}, \
 		.abi_id = id, \
@@ -192,14 +200,13 @@ static inline bool memeq(const void *expected, const void *actual, u32_t len)
  *
  * @return pointer if valid, NULL if not.
  */
-static inline const struct fw_firmware_info *
-fw_check_firmware_info(u32_t fw_info_addr)
+static inline const struct fw_info *fw_info_check(u32_t fw_info_addr)
 {
-	const struct fw_firmware_info *finfo;
-	const u32_t firmware_info_magic[] = {FIRMWARE_INFO_MAGIC};
+	const struct fw_info *finfo;
+	const u32_t fw_info_magic[] = {FIRMWARE_INFO_MAGIC};
 
-	finfo = (const struct fw_firmware_info *)(fw_info_addr);
-	if (memeq(finfo->magic, firmware_info_magic, CONFIG_FW_MAGIC_LEN)) {
+	finfo = (const struct fw_info *)(fw_info_addr);
+	if (memeq(finfo->magic, fw_info_magic, CONFIG_FW_INFO_MAGIC_LEN)) {
 		return finfo;
 	}
 	return NULL;
@@ -226,7 +233,7 @@ fw_check_firmware_info(u32_t fw_info_addr)
 	#define VECTOR_OFFSET 0
 #endif
 
-#define CURRENT_OFFSET (CONFIG_FW_FIRMWARE_INFO_OFFSET + VECTOR_OFFSET)
+#define CURRENT_OFFSET (CONFIG_FW_INFO_OFFSET + VECTOR_OFFSET)
 
 static const u32_t allowed_offsets[] = {FW_INFO_OFFSET0, FW_INFO_OFFSET1,
 					FW_INFO_OFFSET2};
@@ -237,17 +244,16 @@ BUILD_ASSERT_MSG(ARRAY_SIZE(allowed_offsets) == FW_INFO_OFFSET_COUNT,
 #if (FW_INFO_OFFSET_COUNT != 3) || ((CURRENT_OFFSET) != (FW_INFO_OFFSET0) && \
 				(CURRENT_OFFSET) != (FW_INFO_OFFSET1) && \
 				(CURRENT_OFFSET) != (FW_INFO_OFFSET2))
-	#error FW_FIRMWARE_INFO_OFFSET not set to one of the allowed values.
+	#error FW_INFO_OFFSET not set to one of the allowed values.
 #endif
 
 /* Search for the firmware_info structure inside the firmware. */
-static inline const struct fw_firmware_info *
-fw_find_firmware_info(u32_t firmware_address)
+static inline const struct fw_info *fw_info_find(u32_t firmware_address)
 {
-	const struct fw_firmware_info *finfo;
+	const struct fw_info *finfo;
 
 	for (u32_t i = 0; i < FW_INFO_OFFSET_COUNT; i++) {
-		finfo = fw_check_firmware_info(firmware_address +
+		finfo = fw_info_check(firmware_address +
 						allowed_offsets[i]);
 		if (finfo) {
 			return finfo;
@@ -257,31 +263,37 @@ fw_find_firmware_info(u32_t firmware_address)
 }
 
 
-/* Check a fw_abi_info pointer. */
-static inline bool fw_abi_info_check(const struct fw_abi_info *abi_info)
+/* Check a fw_info_abi pointer. */
+static inline bool fw_info_abi_check(const struct fw_info_abi *abi_info)
 {
 	const u32_t abi_info_magic[] = {ABI_INFO_MAGIC};
-	return(memeq(abi_info->magic, abi_info_magic, CONFIG_FW_MAGIC_LEN));
+	return memeq(abi_info->magic, abi_info_magic, CONFIG_FW_INFO_MAGIC_LEN);
 }
 
 
-/* Expose ABIs to the firmware at this address. This is meant to be called
- * immediately before booting the aforementioned firmware since it will likely
- * corrupt the memory of the running firmware.
+/**Expose ABIs to another firmware
+ *
+ * Populate the other firmware's @c abi_in with a internal ABI getter function
+ * which serves all ABIs created with __ext_abi.
+ *
+ * @note This is should be called immediately before booting the other firmware
+ *       since it will likely corrupt the memory of the running firmware.
+ *
+ * @param[in]  fw_info  Pointer to the other firmware's information structure.
  */
-void fw_abi_provide(const struct fw_firmware_info *fw_info);
+void fw_info_abi_provide(const struct fw_info *fw_info);
 
-/* Get a single ABI.
+/**Get a single ABI.
  *
  * @param[in]    id      Which ABI to get.
  * @param[in]    index   If there are multiple ABIs available with the same ID,
  *                       retrieve the different ones with this.
  *
  * @return The ABI, or NULL, if it wasn't found.
  */
-const struct fw_abi_info *fw_abi_get(u32_t id, u32_t index);
+const struct fw_info_abi *fw_info_abi_get(u32_t id, u32_t index);
 
-/* Find an ABI based on a version range.
+/**Find an ABI based on a version range.
  *
  * @param[in]  id           The ID of the ABI to find.
  * @param[in]  flags        The required flags of the ABI to find. The returned
@@ -291,7 +303,7 @@ const struct fw_abi_info *fw_abi_get(u32_t id, u32_t index);
  *
  * @return The ABI, or NULL if none was found.
  */
-const struct fw_abi_info *fw_abi_find(u32_t id, u32_t flags, u32_t min_version,
-					u32_t max_version);
+const struct fw_info_abi *fw_info_abi_find(u32_t id, u32_t flags,
+					u32_t min_version, u32_t max_version);
 
 #endif

include/secure_services.h

@@ -22,7 +22,7 @@
 
 #include <stddef.h>
 #include <zephyr/types.h>
-#include <fw_metadata.h>
+#include <fw_info.h>
 
 #ifdef __cplusplus
 extern "C" {
@@ -75,7 +75,7 @@ int spm_request_read(void *destination, u32_t addr, size_t len);
  * @retval -EINVAL  If info is NULL.
  * @retval -EFAULT  If no info is found.
  */
-int spm_firmware_info(u32_t fw_address, struct fw_firmware_info *info);
+int spm_firmware_info(u32_t fw_address, struct fw_info *info);
 
 #ifdef __cplusplus
 }

samples/bootloader/src/main.c

@@ -13,7 +13,7 @@
 #include <pm_config.h>
 #include <bl_validation.h>
 #include <bl_crypto.h>
-#include <fw_metadata.h>
+#include <fw_info.h>
 #include <drivers/fprotect.h>
 #include <provision.h>
 #ifdef CONFIG_UART_NRFX
@@ -44,7 +44,7 @@ extern u32_t _vector_table_pointer;
 #define VTOR SCB->VTOR
 #endif
 
-static void boot_from(const struct fw_firmware_info *fw_info)
+static void boot_from(const struct fw_info *fw_info)
 {
 	u32_t *vector_table = (u32_t *)fw_info->firmware_address;
 
@@ -99,7 +99,7 @@ static void boot_from(const struct fw_firmware_info *fw_info)
 
 	VTOR = fw_info->firmware_address;
 
-	fw_abi_provide(fw_info);
+	fw_info_abi_provide(fw_info);
 
 	/* Set MSP to the new address and clear any information from PSP */
 	__set_MSP(vector_table[0]);
@@ -121,8 +121,8 @@ void main(void)
 
 	u32_t s0_addr = s0_address_read();
 	u32_t s1_addr = s1_address_read();
-	const struct fw_firmware_info *s0_info = fw_find_firmware_info(s0_addr);
-	const struct fw_firmware_info *s1_info = fw_find_firmware_info(s1_addr);
+	const struct fw_info *s0_info = fw_info_find(s0_addr);
+	const struct fw_info *s1_info = fw_info_find(s1_addr);
 
 	if (!s1_info || (s0_info->firmware_version >=
 			 s1_info->firmware_version)) {

samples/nrf9160/secure_services/src/main.c

@@ -10,7 +10,7 @@
 #include <secure_services.h>
 #include <kernel.h>
 #include <pm_config.h>
-#include <fw_metadata.h>
+#include <fw_info.h>
 
 void print_hex_number(u8_t *num, size_t len)
 {
@@ -29,7 +29,7 @@ void print_random_number(u8_t *num, size_t len)
 
 void main(void)
 {
-	struct fw_firmware_info info_app;
+	struct fw_info info_app;
 	const int sleep_time_s = 5;
 	const int random_number_count = 16;
 	const int random_number_len = 144;

samples/nrf9160/spm/prj.conf

@@ -4,5 +4,5 @@
 # SPDX-License-Identifier: LicenseRef-BSD-5-Clause-Nordic
 #
 CONFIG_IS_SPM=y
-CONFIG_FW_METADATA=y
+CONFIG_FW_INFO=y
 CONFIG_GPIO=n

subsys/CMakeLists.txt

@@ -28,7 +28,7 @@ if (CONFIG_NRFXLIB_NFC     OR
         add_subdirectory(nfc)
 endif()
 
-add_subdirectory_ifdef(CONFIG_FW_METADATA	fw_metadata)
+add_subdirectory_ifdef(CONFIG_FW_INFO	fw_info)
 add_subdirectory_ifdef(CONFIG_SHELL_BT_NUS	shell)
 
 add_subdirectory(debug)

subsys/Kconfig

@@ -23,7 +23,7 @@ rsource "profiler/Kconfig"
 
 rsource "spm/Kconfig"
 
-rsource "fw_metadata/Kconfig"
+rsource "fw_info/Kconfig"
 
 rsource "debug/Kconfig"