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