Add fw_directory component
The fw_directory provides the update agent with a catalogue of
updatable images for a device. The contents of the fw_directory
is populated by a fw_inspector.
Signed-off-by: Julian Hall <julian.hall@arm.com>
Change-Id: I681ca2aabd95f7cea8b9631a00fb5c92f81ef8b3
diff --git a/components/service/fwu/agent/fw_directory.h b/components/service/fwu/agent/fw_directory.h
new file mode 100644
index 0000000..119f5bc
--- /dev/null
+++ b/components/service/fwu/agent/fw_directory.h
@@ -0,0 +1,200 @@
+/*
+ * Copyright (c) 2022, Arm Limited. All rights reserved.
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ *
+ */
+
+#ifndef FW_DIRECTORY_H
+#define FW_DIRECTORY_H
+
+#include <stdbool.h>
+#include <stddef.h>
+#include <stdint.h>
+#include <common/uuid/uuid.h>
+#include "install_type.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/**
+ * The default maximum number of images that can be held by the fw_directory.
+ * Can be overridden by an external definition.
+ */
+#ifndef FWU_MAX_FW_DIRECTORY_ENTRIES
+#define FWU_MAX_FW_DIRECTORY_ENTRIES (20)
+#endif
+
+/**
+ * \brief Boot information structure definition
+ *
+ * The boot_info structure holds information obtained from the boot loader
+ * about the most recent boot.
+ */
+struct boot_info {
+ /* Identifies the bank that was used during boot */
+ uint32_t boot_index;
+
+ /* The state of the active_index metadata variable during boot */
+ uint32_t active_index;
+
+ /* The state of the previous_active_index metadata variable during boot */
+ uint32_t previous_active_index;
+};
+
+/**
+ * \brief Image information structure definition
+ *
+ * Information about an updatable image. Firmware may consist of an arbitrary
+ * number of images that may be updated as a single unit. Images may correspond
+ * to individual components, such as the Crypto SP image, or a collection of
+ * components contained within a package understood by firmware such as a FIP.
+ */
+struct image_info {
+ /* Unique identifier for the image type. This corresponds to the UUID/GUID
+ * assigned by the originator of the update package to identify the image.
+ */
+ struct uuid_octets img_type_uuid;
+
+ /* The maximum size that can be accommodated for an image of this type.
+ * A platform integrator will have sized back-end storage to provide
+ * sufficient headroom to accommodate updates.
+ */
+ size_t max_size;
+
+ /* The lowest accepted version number for this image. This will correspond
+ * to the NV anti-rollback counter value associated with the image.
+ */
+ uint32_t lowest_accepted_version;
+
+ /* The version of the currently active version of this image. */
+ uint32_t active_version;
+
+ /* Bitmap of access permissions for this iamge. */
+ uint32_t permissions;
+
+ /* The index [0..n] of the image in the fw directory. */
+ uint32_t image_index;
+
+ /* The location_id assigned by the platform integrator. A fw_store may
+ * be distributed over multiple locations (e.g. different storage partitions).
+ * The location_id is used to associate installers to storage volumes.
+ */
+ uint32_t location_id;
+
+ /* Identifies the type of installation needed for the image. */
+ enum install_type install_type;
+};
+
+/**
+ * \brief Firmware directory structure definition
+ *
+ * The fw_directory holds information about currently active firmware. Information
+ * will have been collected via a trusted pathway. A subset of the information held
+ * is presented to external clients.
+ */
+struct fw_directory {
+ struct boot_info boot_info;
+ size_t num_images;
+ struct image_info entries[FWU_MAX_FW_DIRECTORY_ENTRIES];
+};
+
+/**
+ * \brief Initialise a fw_directory
+ *
+ * Initialises the subject fw_directory. After initialisation, the empty fw_directory
+ * will need to be populated by a trusted agent (the fw_inspector).
+ *
+ * \param[in] fw_directory The subject fw_directory
+ */
+void fw_directory_init(
+ struct fw_directory *fw_directory);
+
+/**
+ * \brief De-initialise a fw_directory
+ *
+ * \param[in] fw_directory The subject fw_directory
+ */
+void fw_directory_deinit(
+ struct fw_directory *fw_directory);
+
+/**
+ * \brief Sets the boot_info held by the fw_directory
+ *
+ * Used by a fw_inspector to set the boot_info for the most recent system boot.
+ *
+ * \param[in] fw_directory The subject fw_directory
+ * \param[in] boot_info boot_info for most recent system boot
+ */
+void fw_directory_set_boot_info(
+ struct fw_directory *fw_directory,
+ const struct boot_info *boot_info);
+
+/**
+ * \brief Adds an image_info to the directory
+ *
+ * Used by a fw_inspector to add an image_info entry to the directory.
+ *
+ * \param[in] fw_directory The subject fw_directory
+ * \param[in] image_info The entry to add
+ *
+ * \return FWU status
+ */
+int fw_directory_add_image_info(
+ struct fw_directory *fw_directory,
+ const struct image_info *image_info);
+
+/**
+ * \brief Find an image_info entry
+ *
+ * Query to find an image_info entry using the image type UUID as the key.
+ *
+ * \param[in] fw_directory The subject fw_directory
+ * \param[in] image_type_uuid Image type UUID
+ *
+ * \return Pointer to image_info or NULL
+ */
+const struct image_info *fw_directory_find_image_info(
+ const struct fw_directory *fw_directory,
+ const struct uuid_octets *img_type_uuid);
+
+/**
+ * \brief Get the boot_info
+ *
+ * \param[in] fw_directory The subject fw_directory
+ *
+ * \return Pointer to the boot_info
+ */
+const struct boot_info *fw_directory_get_boot_info(
+ const struct fw_directory *fw_directory);
+
+/**
+ * \brief Get an image_info by index
+ *
+ * Can be used for iterating over all image_info objects held.
+ *
+ * \param[in] fw_directory The subject fw_directory
+ * \param[in] index Index in range [0..num_images-1]
+ *
+ * \return Pointer to the image_info or NULL if index invalid
+ */
+const struct image_info *fw_directory_get_image_info(
+ const struct fw_directory *fw_directory,
+ size_t index);
+
+/**
+ * \brief Get the number of image_info entries held
+ *
+ * \param[in] fw_directory The subject fw_directory
+ *
+ * \return Number of entries
+ */
+size_t fw_directory_num_images(
+ const struct fw_directory *fw_directory);
+
+#ifdef __cplusplus
+}
+#endif
+
+#endif /* FW_DIRECTORY_H */