summaryrefslogtreecommitdiffstats
path: root/lib/pldmfw/pldmfw_private.h
blob: 687ef22006924343fcc66867bbef00a04f0632a9 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
/* SPDX-License-Identifier: GPL-2.0 */
/* Copyright (C) 2018-2019, Intel Corporation. */

#ifndef _PLDMFW_PRIVATE_H_
#define _PLDMFW_PRIVATE_H_

/* The following data structures define the layout of a firmware binary
 * following the "PLDM For Firmware Update Specification", DMTF standard
 * #DSP0267.
 *
 * pldmfw.c uses these structures to implement a simple engine that will parse
 * a fw binary file in this format and perform a firmware update for a given
 * device.
 *
 * Due to the variable sized data layout, alignment of fields within these
 * structures is not guaranteed when reading. For this reason, all multi-byte
 * field accesses should be done using the unaligned access macros.
 * Additionally, the standard specifies that multi-byte fields are in
 * LittleEndian format.
 *
 * The structure definitions are not made public, in order to keep direct
 * accesses within code that is prepared to deal with the limitation of
 * unaligned access.
 */

/* UUID for PLDM firmware packages: f018878c-cb7d-4943-9800-a02f059aca02 */
static const uuid_t pldm_firmware_header_id =
	UUID_INIT(0xf018878c, 0xcb7d, 0x4943,
		  0x98, 0x00, 0xa0, 0x2f, 0x05, 0x9a, 0xca, 0x02);

/* Revision number of the PLDM header format this code supports */
#define PACKAGE_HEADER_FORMAT_REVISION 0x01

/* timestamp104 structure defined in PLDM Base specification */
#define PLDM_TIMESTAMP_SIZE 13
struct __pldm_timestamp {
	u8 b[PLDM_TIMESTAMP_SIZE];
} __packed __aligned(1);

/* Package Header Information */
struct __pldm_header {
	uuid_t id;			    /* PackageHeaderIdentifier */
	u8 revision;			    /* PackageHeaderFormatRevision */
	__le16 size;			    /* PackageHeaderSize */
	struct __pldm_timestamp release_date; /* PackageReleaseDateTime */
	__le16 component_bitmap_len;	    /* ComponentBitmapBitLength */
	u8 version_type;		    /* PackageVersionStringType */
	u8 version_len;			    /* PackageVersionStringLength */

	/*
	 * DSP0267 also includes the following variable length fields at the
	 * end of this structure:
	 *
	 * PackageVersionString, length is version_len.
	 *
	 * The total size of this section is
	 *   sizeof(pldm_header) + version_len;
	 */
	u8 version_string[];		/* PackageVersionString */
} __packed __aligned(1);

/* Firmware Device ID Record */
struct __pldmfw_record_info {
	__le16 record_len;		/* RecordLength */
	u8 descriptor_count;		/* DescriptorCount */
	__le32 device_update_flags;	/* DeviceUpdateOptionFlags */
	u8 version_type;		/* ComponentImageSetVersionType */
	u8 version_len;			/* ComponentImageSetVersionLength */
	__le16 package_data_len;	/* FirmwareDevicePackageDataLength */

	/*
	 * DSP0267 also includes the following variable length fields at the
	 * end of this structure:
	 *
	 * ApplicableComponents, length is component_bitmap_len from header
	 * ComponentImageSetVersionString, length is version_len
	 * RecordDescriptors, a series of TLVs with 16bit type and length
	 * FirmwareDevicePackageData, length is package_data_len
	 *
	 * The total size of each record is
	 *   sizeof(pldmfw_record_info) +
	 *   component_bitmap_len (converted to bytes!) +
	 *   version_len +
	 *   <length of RecordDescriptors> +
	 *   package_data_len
	 */
	u8 variable_record_data[];
} __packed __aligned(1);

/* Firmware Descriptor Definition */
struct __pldmfw_desc_tlv {
	__le16 type;			/* DescriptorType */
	__le16 size;			/* DescriptorSize */
	u8 data[];			/* DescriptorData */
} __aligned(1);

/* Firmware Device Identification Area */
struct __pldmfw_record_area {
	u8 record_count;		/* DeviceIDRecordCount */
	/* This is not a struct type because the size of each record varies */
	u8 records[];
} __aligned(1);

/* Individual Component Image Information */
struct __pldmfw_component_info {
	__le16 classification;		/* ComponentClassfication */
	__le16 identifier;		/* ComponentIdentifier */
	__le32 comparison_stamp;	/* ComponentComparisonStamp */
	__le16 options;			/* componentOptions */
	__le16 activation_method;	/* RequestedComponentActivationMethod */
	__le32 location_offset;		/* ComponentLocationOffset */
	__le32 size;			/* ComponentSize */
	u8 version_type;		/* ComponentVersionStringType */
	u8 version_len;		/* ComponentVersionStringLength */

	/*
	 * DSP0267 also includes the following variable length fields at the
	 * end of this structure:
	 *
	 * ComponentVersionString, length is version_len
	 *
	 * The total size of this section is
	 *   sizeof(pldmfw_component_info) + version_len;
	 */
	u8 version_string[];		/* ComponentVersionString */
} __packed __aligned(1);

/* Component Image Information Area */
struct __pldmfw_component_area {
	__le16 component_image_count;
	/* This is not a struct type because the component size varies */
	u8 components[];
} __aligned(1);

/**
 * pldm_first_desc_tlv
 * @start: byte offset of the start of the descriptor TLVs
 *
 * Converts the starting offset of the descriptor TLVs into a pointer to the
 * first descriptor.
 */
#define pldm_first_desc_tlv(start)					\
	((const struct __pldmfw_desc_tlv *)(start))

/**
 * pldm_next_desc_tlv
 * @desc: pointer to a descriptor TLV
 *
 * Finds the pointer to the next descriptor following a given descriptor
 */
#define pldm_next_desc_tlv(desc)						\
	((const struct __pldmfw_desc_tlv *)((desc)->data +			\
					     get_unaligned_le16(&(desc)->size)))

/**
 * pldm_for_each_desc_tlv
 * @i: variable to store descriptor index
 * @desc: variable to store descriptor pointer
 * @start: byte offset of the start of the descriptors
 * @count: the number of descriptors
 *
 * for loop macro to iterate over all of the descriptors of a given PLDM
 * record.
 */
#define pldm_for_each_desc_tlv(i, desc, start, count)			\
	for ((i) = 0, (desc) = pldm_first_desc_tlv(start);		\
	     (i) < (count);						\
	     (i)++, (desc) = pldm_next_desc_tlv(desc))

/**
 * pldm_first_record
 * @start: byte offset of the start of the PLDM records
 *
 * Converts a starting offset of the PLDM records into a pointer to the first
 * record.
 */
#define pldm_first_record(start)					\
	((const struct __pldmfw_record_info *)(start))

/**
 * pldm_next_record
 * @record: pointer to a PLDM record
 *
 * Finds a pointer to the next record following a given record
 */
#define pldm_next_record(record)					\
	((const struct __pldmfw_record_info *)				\
	 ((const u8 *)(record) + get_unaligned_le16(&(record)->record_len)))

/**
 * pldm_for_each_record
 * @i: variable to store record index
 * @record: variable to store record pointer
 * @start: byte offset of the start of the records
 * @count: the number of records
 *
 * for loop macro to iterate over all of the records of a PLDM file.
 */
#define pldm_for_each_record(i, record, start, count)			\
	for ((i) = 0, (record) = pldm_first_record(start);		\
	     (i) < (count);						\
	     (i)++, (record) = pldm_next_record(record))

/**
 * pldm_first_component
 * @start: byte offset of the start of the PLDM components
 *
 * Convert a starting offset of the PLDM components into a pointer to the
 * first component
 */
#define pldm_first_component(start)					\
	((const struct __pldmfw_component_info *)(start))

/**
 * pldm_next_component
 * @component: pointer to a PLDM component
 *
 * Finds a pointer to the next component following a given component
 */
#define pldm_next_component(component)						\
	((const struct __pldmfw_component_info *)((component)->version_string +	\
						  (component)->version_len))

/**
 * pldm_for_each_component
 * @i: variable to store component index
 * @component: variable to store component pointer
 * @start: byte offset to the start of the first component
 * @count: the number of components
 *
 * for loop macro to iterate over all of the components of a PLDM file.
 */
#define pldm_for_each_component(i, component, start, count)		\
	for ((i) = 0, (component) = pldm_first_component(start);	\
	     (i) < (count);						\
	     (i)++, (component) = pldm_next_component(component))

#endif