1 /*
2  * Copyright (c) 2023-2024, Arm Limited. All rights reserved.
3  *
4  * SPDX-License-Identifier: BSD-3-Clause
5  *
6  * FWU metadata information as per the specification section 4.1:
7  * https://developer.arm.com/documentation/den0118/a/
8  *
9  */
10 
11 #ifndef FWU_PROTO_METADATA_V2_H
12 #define FWU_PROTO_METADATA_V2_H
13 
14 #include <stdint.h>
15 
16 #include "metadata.h"
17 #include "protocols/common/osf/uuid.h"
18 
19 /* Bank state definitions */
20 #define FWU_METADATA_V2_NUM_BANK_STATES	    (4)
21 #define FWU_METADATA_V2_BANK_STATE_INVALID  (0xff)
22 #define FWU_METADATA_V2_BANK_STATE_VALID    (0xfe)
23 #define FWU_METADATA_V2_BANK_STATE_ACCEPTED (0xfc)
24 
25 /*
26  * Version 2 FWU metadata data structure (mandatory)
27  *
28  * The metadata structure is variable length. The actual length is determined
29  * from the metadata_size member.
30  */
31 struct __attribute__((__packed__)) fwu_metadata {
32 	/* Metadata CRC value */
33 	uint32_t crc_32;
34 
35 	/* Metadata version */
36 	uint32_t version;
37 
38 	/* Active bank index as directed by update agent [0..n] */
39 	uint32_t active_index;
40 
41 	/* Previous active bank index [0..n] */
42 	uint32_t previous_active_index;
43 
44 	/* The overall metadata size */
45 	uint32_t metadata_size;
46 
47 	/* The size in bytes of the fixed size header */
48 	uint16_t descriptor_offset;
49 
50 	uint16_t reserved_16;
51 
52 	/* Bank state bitmaps */
53 	uint8_t bank_state[FWU_METADATA_V2_NUM_BANK_STATES];
54 
55 	uint32_t reserved_1c;
56 };
57 
58 /* Properties of image in a bank */
59 struct __attribute__((__packed__)) fwu_img_bank_info {
60 	/* UUID of the image in this bank */
61 	uint8_t img_uuid[OSF_UUID_OCTET_LEN];
62 
63 	/* [0]: bit describing the image acceptance status –
64 	 *      1 means the image is accepted
65 	 * [31:1]: MBZ
66 	 */
67 	uint32_t accepted;
68 
69 	/* reserved (MBZ) */
70 	uint32_t reserved;
71 };
72 
73 /* Image entry information */
74 struct __attribute__((__packed__)) fwu_image_entry {
75 	/* UUID identifying the image type */
76 	uint8_t img_type_uuid[OSF_UUID_OCTET_LEN];
77 
78 	/* UUID of the storage volume where the image is located (e.g. a disk UUID) */
79 	uint8_t location_uuid[OSF_UUID_OCTET_LEN];
80 
81 	/* Per-bank info related to the image */
82 	struct fwu_img_bank_info img_bank_info[FWU_METADATA_NUM_BANKS];
83 };
84 
85 /*
86  * Firmware store descriptor
87  *
88  * FWU metadata may optionally include a description of the firmware store
89  * to direct the bootloader during boot. If a bootloader uses an alternative
90  * method to determine where to boot from, the fw_store_desc structure is
91  * not required. The fw_store_desc is assumed to be present if metadata_size
92  * > header_size.
93  */
94 struct __attribute__((__packed__)) fwu_fw_store_desc {
95 	/* Number of banks */
96 	uint8_t num_banks;
97 
98 	uint8_t reserved_01;
99 
100 	/* Number of images listed in the img_entry array */
101 	uint16_t num_images;
102 
103 	/* The size of the img_entry data structure */
104 	uint16_t img_entry_size;
105 
106 	/* The size of bytes of the bank_entry data structure */
107 	uint16_t bank_info_entry_size;
108 
109 	/* Array of image_entry structures */
110 	struct fwu_image_entry img_entry[];
111 };
112 
113 #endif /* FWU_PROTO_METADATA_V2_H */
114