Add FWU service access protocol definition
Adds a packed-c protocol definition for the firmware update
service. The protocol defintion aims for alignment with the
ARM FWU-A specification.
Signed-off-by: Julian Hall <julian.hall@arm.com>
Change-Id: I1d7e68058e7ad9447bff862026513aeef25d9ac4
diff --git a/protocols/common/osf/uuid.h b/protocols/common/osf/uuid.h
new file mode 100644
index 0000000..d5cbd9c
--- /dev/null
+++ b/protocols/common/osf/uuid.h
@@ -0,0 +1,23 @@
+/*
+ * Copyright (c) 2022, Arm Limited and Contributors. All rights reserved.
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ *
+ * Common Open Software Foundation (OSF) standards-based definitions
+ */
+
+#ifndef COMMON_OSF_UUID_H
+#define COMMON_OSF_UUID_H
+
+/**
+ * Octet length for standard binary encoded UUID in Big Endian byte order (see RFC4122)
+ */
+#define OSF_UUID_OCTET_LEN (16)
+
+/**
+ * Character length of a canonical form UUID string
+ * e.g. 123e4567-e89b-12d3-a456-426614174000
+ */
+#define OSF_UUID_CANONICAL_FORM_LEN (36)
+
+#endif /* COMMON_OSF_UUID_H */
diff --git a/protocols/service/fwu/packed-c/fwu_proto.h b/protocols/service/fwu/packed-c/fwu_proto.h
new file mode 100644
index 0000000..a1bb644
--- /dev/null
+++ b/protocols/service/fwu/packed-c/fwu_proto.h
@@ -0,0 +1,122 @@
+/*
+ * Copyright (c) 2022-2023, Arm Limited and Contributors. All rights reserved.
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+#ifndef FWU_PROTO_H
+#define FWU_PROTO_H
+
+#include <stdint.h>
+#include <protocols/common/osf/uuid.h>
+#include "opcodes.h"
+#include "status.h"
+
+/**
+ * The major version number of the FWU-A access protocol. It will be incremented
+ * on significant updates that may include breaking changes.
+ */
+#define FWU_PROTOCOL_VERSION_MAJOR 2
+
+/**
+ * The minor version number It will be incremented in
+ * small updates that are unlikely to include breaking changes.
+ */
+#define FWU_PROTOCOL_VERSION_MINOR 0
+
+/**
+ * Protocol GUIDs defined in FWU-A specification
+ */
+#define FWU_UPDATE_AGENT_CANONICAL_UUID "6823a838-1b06-470e-9774-0cce8bfb53fd"
+#define FWU_DIRECTORY_CANONICAL_UUID "deee58d9-5147-4ad3-a290-77666e2341a5"
+#define FWU_METADATA_CANONICAL_UUID "8a7a84a0-8387-40f6-ab41-a8b9a5a60d23"
+
+/**
+ * Image directory
+ */
+#define FWU_READ_PERM (1u << 1)
+#define FWU_WRITE_PERM (1u << 0)
+
+struct __attribute__ ((__packed__)) ts_fwu_image_info_entry
+{
+ uint8_t img_type_uuid[OSF_UUID_OCTET_LEN];
+ uint32_t client_permissions;
+ uint32_t img_max_size;
+ uint32_t lowest_accepted_version;
+ uint32_t img_version;
+ uint32_t accepted;
+ uint32_t reserved;
+};
+
+struct __attribute__ ((__packed__)) ts_fwu_image_directory
+{
+ uint32_t directory_version;
+ uint32_t img_info_offset;
+ uint32_t num_images;
+ uint32_t correct_boot;
+ uint32_t img_info_size;
+ uint32_t reserved;
+ struct ts_fwu_image_info_entry img_info_entry[];
+};
+
+/**
+ * Message parameters
+ */
+
+struct __attribute__ ((__packed__)) ts_fwu_discover_out
+{
+ uint8_t version_major;
+ uint8_t version_minor;
+ uint16_t num_func;
+ uint8_t function_presence[];
+};
+
+struct __attribute__ ((__packed__)) ts_fwu_open_in
+{
+ uint8_t image_type_uuid[OSF_UUID_OCTET_LEN];
+};
+
+struct __attribute__ ((__packed__)) ts_fwu_open_out
+{
+ uint32_t handle;
+};
+
+struct __attribute__ ((__packed__)) ts_fwu_write_stream_in
+{
+ uint32_t handle;
+ uint32_t data_len;
+ uint8_t payload[];
+};
+
+struct __attribute__ ((__packed__)) ts_fwu_read_stream_in
+{
+ uint32_t handle;
+};
+
+struct __attribute__ ((__packed__)) ts_fwu_read_stream_out
+{
+ uint32_t read_bytes;
+ uint32_t total_bytes;
+ uint8_t payload[];
+};
+
+struct __attribute__ ((__packed__)) ts_fwu_commit_in
+{
+ uint32_t handle;
+ uint32_t acceptance_req;
+ uint32_t max_atomic_len;
+};
+
+struct __attribute__ ((__packed__)) ts_fwu_commit_out
+{
+ uint32_t progress;
+ uint32_t total_work;
+};
+
+struct __attribute__ ((__packed__)) ts_fwu_accept_image_in
+{
+ uint32_t reserved;
+ uint8_t image_type_uuid[OSF_UUID_OCTET_LEN];
+};
+
+#endif /* FWU_PROTO_H */
diff --git a/protocols/service/fwu/packed-c/metadata.h b/protocols/service/fwu/packed-c/metadata.h
new file mode 100644
index 0000000..b89cc9e
--- /dev/null
+++ b/protocols/service/fwu/packed-c/metadata.h
@@ -0,0 +1,22 @@
+/*
+ * Copyright (c) 2022-2023, Arm Limited. All rights reserved.
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ *
+ * FWU metadata information as per the specification section 4.1:
+ * https://developer.arm.com/documentation/den0118/a/
+ *
+ */
+
+#ifndef FWU_PROTO_METADATA_H
+#define FWU_PROTO_METADATA_H
+
+/**
+ * The number of banks for different versions of firmware.
+ * With the default configuration, a dual bank A/B scheme is used.
+ */
+#ifndef FWU_METADATA_NUM_BANKS
+#define FWU_METADATA_NUM_BANKS (2)
+#endif
+
+#endif /* FWU_PROTO_METADATA_H */
diff --git a/protocols/service/fwu/packed-c/metadata_v1.h b/protocols/service/fwu/packed-c/metadata_v1.h
new file mode 100644
index 0000000..2271c9b
--- /dev/null
+++ b/protocols/service/fwu/packed-c/metadata_v1.h
@@ -0,0 +1,87 @@
+/*
+ * Copyright (c) 2022-2023, Arm Limited. All rights reserved.
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ *
+ * FWU metadata information as per the specification section 4.1:
+ * https://developer.arm.com/documentation/den0118/a/
+ *
+ */
+
+#ifndef FWU_PROTO_METADATA_V1_H
+#define FWU_PROTO_METADATA_V1_H
+
+#include <stdint.h>
+#include <protocols/common/osf/uuid.h>
+#include "metadata.h"
+
+/**
+ * FWU metadata version corresponding to these structure definitions.
+ */
+#define FWU_METADATA_VERSION (1)
+
+/**
+ * The number of image entries in the metadata structure.
+ */
+#ifndef FWU_METADATA_NUM_IMAGE_ENTRIES
+#define FWU_METADATA_NUM_IMAGE_ENTRIES (1)
+#endif
+
+/* Properties of image in a bank */
+struct __attribute__ ((__packed__)) fwu_image_properties {
+
+ /* UUID of the image in this bank */
+ uint8_t img_uuid[OSF_UUID_OCTET_LEN];
+
+ /* [0]: bit describing the image acceptance status –
+ * 1 means the image is accepted
+ * [31:1]: MBZ
+ */
+ uint32_t accepted;
+
+ /* reserved (MBZ) */
+ uint32_t reserved;
+
+};
+
+/* Image entry information */
+struct __attribute__ ((__packed__)) fwu_image_entry {
+
+ /* UUID identifying the image type */
+ uint8_t img_type_uuid[OSF_UUID_OCTET_LEN];
+
+ /* UUID of the storage volume where the image is located */
+ uint8_t location_uuid[OSF_UUID_OCTET_LEN];
+
+ /* Properties of images with img_type_uuid in the different FW banks */
+ struct fwu_image_properties img_props[FWU_METADATA_NUM_BANKS];
+
+};
+
+/*
+ * FWU metadata filled by the updater and consumed by TF-A for
+ * various purposes as below:
+ * 1. Get active FW bank.
+ * 2. Rollback to previous working FW bank.
+ * 3. Get properties of all images present in all banks.
+ */
+struct __attribute__ ((__packed__)) fwu_metadata {
+
+ /* Metadata CRC value */
+ uint32_t crc_32;
+
+ /* Metadata version */
+ uint32_t version;
+
+ /* Bank index with which device boots */
+ uint32_t active_index;
+
+ /* Previous bank index with which device booted successfully */
+ uint32_t previous_active_index;
+
+ /* Image entry information */
+ struct fwu_image_entry img_entry[FWU_METADATA_NUM_IMAGE_ENTRIES];
+
+};
+
+#endif /* FWU_PROTO_METADATA_V1_H */
diff --git a/protocols/service/fwu/packed-c/opcodes.h b/protocols/service/fwu/packed-c/opcodes.h
new file mode 100644
index 0000000..b900677
--- /dev/null
+++ b/protocols/service/fwu/packed-c/opcodes.h
@@ -0,0 +1,24 @@
+/*
+ * Copyright (c) 2022, Arm Limited and Contributors. All rights reserved.
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+#ifndef FWU_PROTO_OPCODES_H
+#define FWU_PROTO_OPCODES_H
+
+/**
+ * Service-level opcodes
+ */
+#define TS_FWU_OPCODE_BASE (0x10)
+#define TS_FWU_OPCODE_BEGIN_STAGING (TS_FWU_OPCODE_BASE + 0)
+#define TS_FWU_OPCODE_END_STAGING (TS_FWU_OPCODE_BASE + 1)
+#define TS_FWU_OPCODE_CANCEL_STAGING (TS_FWU_OPCODE_BASE + 2)
+#define TS_FWU_OPCODE_OPEN (TS_FWU_OPCODE_BASE + 3)
+#define TS_FWU_OPCODE_WRITE_STREAM (TS_FWU_OPCODE_BASE + 4)
+#define TS_FWU_OPCODE_READ_STREAM (TS_FWU_OPCODE_BASE + 5)
+#define TS_FWU_OPCODE_COMMIT (TS_FWU_OPCODE_BASE + 6)
+#define TS_FWU_OPCODE_ACCEPT_IMAGE (TS_FWU_OPCODE_BASE + 7)
+#define TS_FWU_OPCODE_SELECT_PREVIOUS (TS_FWU_OPCODE_BASE + 8)
+
+#endif /* FWU_PROTO_OPCODES_H */
diff --git a/protocols/service/fwu/packed-c/status.h b/protocols/service/fwu/packed-c/status.h
new file mode 100644
index 0000000..b53e8b8
--- /dev/null
+++ b/protocols/service/fwu/packed-c/status.h
@@ -0,0 +1,23 @@
+/*
+ * Copyright (c) 2022, Arm Limited and Contributors. All rights reserved.
+ *
+ * SPDX-License-Identifier: BSD-3-Clause
+ */
+
+#ifndef FWU_PROTO_STATUS_H
+#define FWU_PROTO_STATUS_H
+
+/**
+ * Service-level status codes
+ */
+#define FWU_STATUS_SUCCESS ((int32_t)0)
+#define FWU_STATUS_UNKNOWN ((int32_t)-1)
+#define FWU_STATUS_BUSY ((int32_t)-2)
+#define FWU_STATUS_OUT_OF_BOUNDS ((int32_t)-3)
+#define FWU_STATUS_AUTH_FAIL ((int32_t)-4)
+#define FWU_STATUS_NO_PERMISSION ((int32_t)-5)
+#define FWU_STATUS_DENIED ((int32_t)-6)
+#define FWU_STATUS_RESUME ((int32_t)-7)
+#define FWU_STATUS_NOT_AVAILABLE ((int32_t)-8)
+
+#endif /* FWU_PROTO_STATUS_H */