1 /* SPDX-License-Identifier: GPL-2.0 */ 2 /* Copyright (C) 2018-2019, Intel Corporation. */ 3 4 #ifndef _PLDMFW_PRIVATE_H_ 5 #define _PLDMFW_PRIVATE_H_ 6 7 /* The following data structures define the layout of a firmware binary 8 * following the "PLDM For Firmware Update Specification", DMTF standard 9 * #DSP0267. 10 * 11 * pldmfw.c uses these structures to implement a simple engine that will parse 12 * a fw binary file in this format and perform a firmware update for a given 13 * device. 14 * 15 * Due to the variable sized data layout, alignment of fields within these 16 * structures is not guaranteed when reading. For this reason, all multi-byte 17 * field accesses should be done using the unaligned access macros. 18 * Additionally, the standard specifies that multi-byte fields are in 19 * LittleEndian format. 20 * 21 * The structure definitions are not made public, in order to keep direct 22 * accesses within code that is prepared to deal with the limitation of 23 * unaligned access. 24 */ 25 26 /* UUID for PLDM firmware packages: f018878c-cb7d-4943-9800-a02f059aca02 */ 27 static const uuid_t pldm_firmware_header_id = 28 UUID_INIT(0xf018878c, 0xcb7d, 0x4943, 29 0x98, 0x00, 0xa0, 0x2f, 0x05, 0x9a, 0xca, 0x02); 30 31 /* Revision number of the PLDM header format this code supports */ 32 #define PACKAGE_HEADER_FORMAT_REVISION 0x01 33 34 /* timestamp104 structure defined in PLDM Base specification */ 35 #define PLDM_TIMESTAMP_SIZE 13 36 struct __pldm_timestamp { 37 u8 b[PLDM_TIMESTAMP_SIZE]; 38 } __packed __aligned(1); 39 40 /* Package Header Information */ 41 struct __pldm_header { 42 uuid_t id; /* PackageHeaderIdentifier */ 43 u8 revision; /* PackageHeaderFormatRevision */ 44 __le16 size; /* PackageHeaderSize */ 45 struct __pldm_timestamp release_date; /* PackageReleaseDateTime */ 46 __le16 component_bitmap_len; /* ComponentBitmapBitLength */ 47 u8 version_type; /* PackageVersionStringType */ 48 u8 version_len; /* PackageVersionStringLength */ 49 50 /* 51 * DSP0267 also includes the following variable length fields at the 52 * end of this structure: 53 * 54 * PackageVersionString, length is version_len. 55 * 56 * The total size of this section is 57 * sizeof(pldm_header) + version_len; 58 */ 59 u8 version_string[]; /* PackageVersionString */ 60 } __packed __aligned(1); 61 62 /* Firmware Device ID Record */ 63 struct __pldmfw_record_info { 64 __le16 record_len; /* RecordLength */ 65 u8 descriptor_count; /* DescriptorCount */ 66 __le32 device_update_flags; /* DeviceUpdateOptionFlags */ 67 u8 version_type; /* ComponentImageSetVersionType */ 68 u8 version_len; /* ComponentImageSetVersionLength */ 69 __le16 package_data_len; /* FirmwareDevicePackageDataLength */ 70 71 /* 72 * DSP0267 also includes the following variable length fields at the 73 * end of this structure: 74 * 75 * ApplicableComponents, length is component_bitmap_len from header 76 * ComponentImageSetVersionString, length is version_len 77 * RecordDescriptors, a series of TLVs with 16bit type and length 78 * FirmwareDevicePackageData, length is package_data_len 79 * 80 * The total size of each record is 81 * sizeof(pldmfw_record_info) + 82 * component_bitmap_len (converted to bytes!) + 83 * version_len + 84 * <length of RecordDescriptors> + 85 * package_data_len 86 */ 87 u8 variable_record_data[]; 88 } __packed __aligned(1); 89 90 /* Firmware Descriptor Definition */ 91 struct __pldmfw_desc_tlv { 92 __le16 type; /* DescriptorType */ 93 __le16 size; /* DescriptorSize */ 94 u8 data[]; /* DescriptorData */ 95 } __aligned(1); 96 97 /* Firmware Device Identification Area */ 98 struct __pldmfw_record_area { 99 u8 record_count; /* DeviceIDRecordCount */ 100 /* This is not a struct type because the size of each record varies */ 101 u8 records[]; 102 } __aligned(1); 103 104 /* Individual Component Image Information */ 105 struct __pldmfw_component_info { 106 __le16 classification; /* ComponentClassfication */ 107 __le16 identifier; /* ComponentIdentifier */ 108 __le32 comparison_stamp; /* ComponentComparisonStamp */ 109 __le16 options; /* componentOptions */ 110 __le16 activation_method; /* RequestedComponentActivationMethod */ 111 __le32 location_offset; /* ComponentLocationOffset */ 112 __le32 size; /* ComponentSize */ 113 u8 version_type; /* ComponentVersionStringType */ 114 u8 version_len; /* ComponentVersionStringLength */ 115 116 /* 117 * DSP0267 also includes the following variable length fields at the 118 * end of this structure: 119 * 120 * ComponentVersionString, length is version_len 121 * 122 * The total size of this section is 123 * sizeof(pldmfw_component_info) + version_len; 124 */ 125 u8 version_string[]; /* ComponentVersionString */ 126 } __packed __aligned(1); 127 128 /* Component Image Information Area */ 129 struct __pldmfw_component_area { 130 __le16 component_image_count; 131 /* This is not a struct type because the component size varies */ 132 u8 components[]; 133 } __aligned(1); 134 135 /** 136 * pldm_first_desc_tlv 137 * @start: byte offset of the start of the descriptor TLVs 138 * 139 * Converts the starting offset of the descriptor TLVs into a pointer to the 140 * first descriptor. 141 */ 142 #define pldm_first_desc_tlv(start) \ 143 ((const struct __pldmfw_desc_tlv *)(start)) 144 145 /** 146 * pldm_next_desc_tlv 147 * @desc: pointer to a descriptor TLV 148 * 149 * Finds the pointer to the next descriptor following a given descriptor 150 */ 151 #define pldm_next_desc_tlv(desc) \ 152 ((const struct __pldmfw_desc_tlv *)((desc)->data + \ 153 get_unaligned_le16(&(desc)->size))) 154 155 /** 156 * pldm_for_each_desc_tlv 157 * @i: variable to store descriptor index 158 * @desc: variable to store descriptor pointer 159 * @start: byte offset of the start of the descriptors 160 * @count: the number of descriptors 161 * 162 * for loop macro to iterate over all of the descriptors of a given PLDM 163 * record. 164 */ 165 #define pldm_for_each_desc_tlv(i, desc, start, count) \ 166 for ((i) = 0, (desc) = pldm_first_desc_tlv(start); \ 167 (i) < (count); \ 168 (i)++, (desc) = pldm_next_desc_tlv(desc)) 169 170 /** 171 * pldm_first_record 172 * @start: byte offset of the start of the PLDM records 173 * 174 * Converts a starting offset of the PLDM records into a pointer to the first 175 * record. 176 */ 177 #define pldm_first_record(start) \ 178 ((const struct __pldmfw_record_info *)(start)) 179 180 /** 181 * pldm_next_record 182 * @record: pointer to a PLDM record 183 * 184 * Finds a pointer to the next record following a given record 185 */ 186 #define pldm_next_record(record) \ 187 ((const struct __pldmfw_record_info *) \ 188 ((const u8 *)(record) + get_unaligned_le16(&(record)->record_len))) 189 190 /** 191 * pldm_for_each_record 192 * @i: variable to store record index 193 * @record: variable to store record pointer 194 * @start: byte offset of the start of the records 195 * @count: the number of records 196 * 197 * for loop macro to iterate over all of the records of a PLDM file. 198 */ 199 #define pldm_for_each_record(i, record, start, count) \ 200 for ((i) = 0, (record) = pldm_first_record(start); \ 201 (i) < (count); \ 202 (i)++, (record) = pldm_next_record(record)) 203 204 /** 205 * pldm_first_component 206 * @start: byte offset of the start of the PLDM components 207 * 208 * Convert a starting offset of the PLDM components into a pointer to the 209 * first component 210 */ 211 #define pldm_first_component(start) \ 212 ((const struct __pldmfw_component_info *)(start)) 213 214 /** 215 * pldm_next_component 216 * @component: pointer to a PLDM component 217 * 218 * Finds a pointer to the next component following a given component 219 */ 220 #define pldm_next_component(component) \ 221 ((const struct __pldmfw_component_info *)((component)->version_string + \ 222 (component)->version_len)) 223 224 /** 225 * pldm_for_each_component 226 * @i: variable to store component index 227 * @component: variable to store component pointer 228 * @start: byte offset to the start of the first component 229 * @count: the number of components 230 * 231 * for loop macro to iterate over all of the components of a PLDM file. 232 */ 233 #define pldm_for_each_component(i, component, start, count) \ 234 for ((i) = 0, (component) = pldm_first_component(start); \ 235 (i) < (count); \ 236 (i)++, (component) = pldm_next_component(component)) 237 238 #endif 239