]> git.proxmox.com Git - mirror_edk2.git/blob - MdePkg/Include/Protocol/FirmwareManagement.h
String Reference Cleanup.
[mirror_edk2.git] / MdePkg / Include / Protocol / FirmwareManagement.h
1 /** @file
2 UEFI Firmware Management Protocol definition
3 Firmware Management Protocol provides an abstraction for device to provide firmware
4 management support. The base requirements for managing device firmware images include
5 identifying firmware image revision level and programming the image into the device.
6
7 GetImageInfo() is the only required function. GetImage(), SetImage(),
8 CheckImage(), GetPackageInfo(), and SetPackageInfo() shall return
9 EFI_UNSUPPORTED if not supported by the driver.
10
11 Copyright (c) 2009 - 2011, Intel Corporation. All rights reserved.<BR>
12 This program and the accompanying materials
13 are licensed and made available under the terms and conditions of the BSD License
14 which accompanies this distribution. The full text of the license may be found at
15 http://opensource.org/licenses/bsd-license.php
16
17 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
18 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
19
20 @par Revision Reference:
21 This Protocol is introduced in UEFI Specification 2.3
22
23 **/
24
25 #ifndef __EFI_FIRMWARE_MANAGEMENT_PROTOCOL_H__
26 #define __EFI_FIRMWARE_MANAGEMENT_PROTOCOL_H__
27
28
29 #define EFI_FIRMWARE_MANAGEMENT_PROTOCOL_GUID \
30 { \
31 0x86c77a67, 0xb97, 0x4633, {0xa1, 0x87, 0x49, 0x10, 0x4d, 0x6, 0x85, 0xc7 } \
32 }
33
34 typedef struct _EFI_FIRMWARE_MANAGEMENT_PROTOCOL EFI_FIRMWARE_MANAGEMENT_PROTOCOL;
35
36 ///
37 /// EFI_FIRMWARE_IMAGE_DESCRIPTOR
38 ///
39 typedef struct {
40 ///
41 /// A unique number identifying the firmware image within the device. The number is
42 /// between 1 and DescriptorCount.
43 ///
44 UINT8 ImageIndex;
45 ///
46 /// A unique number identifying the firmware image type.
47 ///
48 EFI_GUID ImageTypeId;
49 ///
50 /// A unique number identifying the firmware image.
51 ///
52 UINT64 ImageId;
53 ///
54 /// A pointer to a null-terminated string representing the firmware image name.
55 ///
56 CHAR16 *ImageIdName;
57 ///
58 /// Identifies the version of the device firmware. The format is vendor specific and new
59 /// version must have a greater value than an old version.
60 ///
61 UINT32 Version;
62 ///
63 /// A pointer to a null-terminated string representing the firmware image version name.
64 ///
65 CHAR16 *VersionName;
66 ///
67 /// Size of the image in bytes. If size=0, then only ImageIndex and ImageTypeId are valid.
68 ///
69 UINTN Size;
70 ///
71 /// Image attributes that are supported by this device. See 'Image Attribute Definitions'
72 /// for possible returned values of this parameter. A value of 1 indicates the attribute is
73 /// supported and the current setting value is indicated in AttributesSetting. A
74 /// value of 0 indicates the attribute is not supported and the current setting value in
75 /// AttributesSetting is meaningless.
76 ///
77 UINT64 AttributesSupported;
78 ///
79 /// Image attributes. See 'Image Attribute Definitions' for possible returned values of
80 /// this parameter.
81 ///
82 UINT64 AttributesSetting;
83 ///
84 /// Image compatibilities. See 'Image Compatibility Definitions' for possible returned
85 /// values of this parameter.
86 ///
87 UINT64 Compatibilities;
88 } EFI_FIRMWARE_IMAGE_DESCRIPTOR;
89
90
91 //
92 // Image Attribute Definitions
93 //
94 ///
95 /// The attribute IMAGE_ATTRIBUTE_IMAGE_UPDATABLE indicates this device supports firmware
96 /// image update.
97 ///
98 #define IMAGE_ATTRIBUTE_IMAGE_UPDATABLE 0x0000000000000001
99 ///
100 /// The attribute IMAGE_ATTRIBUTE_RESET_REQUIRED indicates a reset of the device is required
101 /// for the new firmware image to take effect after a firmware update. The device is the device hosting
102 /// the firmware image.
103 ///
104 #define IMAGE_ATTRIBUTE_RESET_REQUIRED 0x0000000000000002
105 ///
106 /// The attribute IMAGE_ATTRIBUTE_AUTHENTICATION_REQUIRED indicates authentication is
107 /// required to perform the following image operations: GetImage(), SetImage(), and
108 /// CheckImage(). See 'Image Attribute - Authentication'.
109 ///
110 #define IMAGE_ATTRIBUTE_AUTHENTICATION_REQUIRED 0x0000000000000004
111 ///
112 /// The attribute IMAGE_ATTRIBUTE_IN_USE indicates the current state of the firmware image.
113 /// This distinguishes firmware images in a device that supports redundant images.
114 ///
115 #define IMAGE_ATTRIBUTE_IN_USE 0x0000000000000008
116
117
118 //
119 // Image Compatibility Definitions
120 //
121 /// Values from 0x0000000000000002 thru 0x000000000000FFFF are reserved for future assignments.
122 /// Values from 0x0000000000010000 thru 0xFFFFFFFFFFFFFFFF are used by firmware vendor for
123 /// compatibility check.
124 ///
125 #define IMAGE_COMPATIBILITY_CHECK_SUPPORTED 0x0000000000000001
126
127 ///
128 /// Descriptor Version
129 ///
130 #define EFI_FIRMWARE_IMAGE_DESCRIPTOR_VERSION 1
131
132
133 ///
134 /// Image Attribute -Authentication Required
135 ///
136 typedef struct {
137 ///
138 /// It is included in the signature of AuthInfo. It is used to ensure freshness/no replay.
139 /// It is incremented during each firmware image operation.
140 ///
141 UINT64 MonotonicCount;
142 ///
143 /// Provides the authorization for the firmware image operations. It is a signature across
144 /// the image data and the Monotonic Count value. Caller uses the private key that is
145 /// associated with a public key that has been provisioned via the key exchange.
146 ///
147 WIN_CERTIFICATE_UEFI_GUID AuthInfo;
148 } EFI_FIRMWARE_IMAGE_AUTHENTICATION;
149
150
151 //
152 // ImageUpdatable Definitions
153 //
154 ///
155 /// IMAGE_UPDATABLE_VALID indicates SetImage() will accept the new image and update the
156 /// device with the new image.
157 ///
158 #define IMAGE_UPDATABLE_VALID 0x0000000000000001
159 ///
160 /// IMAGE_UPDATABLE_INVALID indicates SetImage() will reject the new image. No additional
161 /// information is provided for the rejection.
162 ///
163 #define IMAGE_UPDATABLE_INVALID 0x0000000000000002
164 ///
165 /// IMAGE_UPDATABLE_INVALID_TYPE indicates SetImage() will reject the new image. The
166 /// rejection is due to the new image is not a firmware image recognized for this device.
167 ///
168 #define IMAGE_UPDATABLE_INVALID_TYPE 0x0000000000000004
169 ///
170 /// IMAGE_UPDATABLE_INVALID_OLD indicates SetImage() will reject the new image. The
171 /// rejection is due to the new image version is older than the current firmware image
172 /// version in the device. The device firmware update policy does not support firmware
173 /// version downgrade.
174 ///
175 #define IMAGE_UPDATABLE_INVALID_OLD 0x0000000000000008
176
177
178 //
179 // Package Attribute Definitions
180 //
181 ///
182 /// The attribute PACKAGE_ATTRIBUTE_VERSION_UPDATABLE indicates this device supports the
183 /// update of the firmware package version.
184 ///
185 #define PACKAGE_ATTRIBUTE_VERSION_UPDATABLE 0x0000000000000001
186 ///
187 /// The attribute PACKAGE_ATTRIBUTE_RESET_REQUIRED indicates a reset of the device is
188 /// required for the new package info to take effect after an update.
189 ///
190 #define PACKAGE_ATTRIBUTE_RESET_REQUIRED 0x0000000000000002
191 ///
192 /// The attribute PACKAGE_ATTRIBUTE_AUTHENTICATION_REQUIRED indicates authentication
193 /// is required to update the package info.
194 ///
195 #define PACKAGE_ATTRIBUTE_AUTHENTICATION_REQUIRED 0x0000000000000004
196
197 /**
198 Callback funtion to report the process of the firmware updating.
199
200 @param[in] Completion A value between 1 and 100 indicating the current completion
201 progress of the firmware update. Completion progress is
202 reported as from 1 to 100 percent. A value of 0 is used by
203 the driver to indicate that progress reporting is not supported.
204
205 @retval EFI_SUCCESS SetImage() continues to do the callback if supported.
206 @retval other SetImage() discontinues the callback and completes
207 the update and returns.
208
209 **/
210 typedef
211 EFI_STATUS
212 (EFIAPI *EFI_FIRMWARE_MANAGEMENT_UPDATE_IMAGE_PROGRESS)(
213 IN UINTN Completion
214 );
215
216 /**
217 Returns information about the current firmware image(s) of the device.
218
219 This function allows a copy of the current firmware image to be created and saved.
220 The saved copy could later been used, for example, in firmware image recovery or rollback.
221
222 @param[in] This A pointer to the EFI_FIRMWARE_MANAGEMENT_PROTOCOL instance.
223 @param[in, out] ImageInfoSize A pointer to the size, in bytes, of the ImageInfo buffer.
224 On input, this is the size of the buffer allocated by the caller.
225 On output, it is the size of the buffer returned by the firmware
226 if the buffer was large enough, or the size of the buffer needed
227 to contain the image(s) information if the buffer was too small.
228 @param[in, out] ImageInfo A pointer to the buffer in which firmware places the current image(s)
229 information. The information is an array of EFI_FIRMWARE_IMAGE_DESCRIPTORs.
230 @param[out] DescriptorVersion A pointer to the location in which firmware returns the version number
231 associated with the EFI_FIRMWARE_IMAGE_DESCRIPTOR.
232 @param[out] DescriptorCount A pointer to the location in which firmware returns the number of
233 descriptors or firmware images within this device.
234 @param[out] DescriptorSize A pointer to the location in which firmware returns the size, in bytes,
235 of an individual EFI_FIRMWARE_IMAGE_DESCRIPTOR.
236 @param[out] PackageVersion A version number that represents all the firmware images in the device.
237 The format is vendor specific and new version must have a greater value
238 than the old version. If PackageVersion is not supported, the value is
239 0xFFFFFFFF. A value of 0xFFFFFFFE indicates that package version comparison
240 is to be performed using PackageVersionName. A value of 0xFFFFFFFD indicates
241 that package version update is in progress.
242 @param[out] PackageVersionName A pointer to a pointer to a null-terminated string representing the
243 package version name. The buffer is allocated by this function with
244 AllocatePool(), and it is the caller's responsibility to free it with a call
245 to FreePool().
246
247 @retval EFI_SUCCESS The device was successfully updated with the new image.
248 @retval EFI_BUFFER_TOO_SMALL The ImageInfo buffer was too small. The current buffer size
249 needed to hold the image(s) information is returned in ImageInfoSize.
250 @retval EFI_INVALID_PARAMETER ImageInfoSize is NULL.
251 @retval EFI_DEVICE_ERROR Valid information could not be returned. Possible corrupted image.
252
253 **/
254 typedef
255 EFI_STATUS
256 (EFIAPI *EFI_FIRMWARE_MANAGEMENT_PROTOCOL_GET_IMAGE_INFO)(
257 IN EFI_FIRMWARE_MANAGEMENT_PROTOCOL *This,
258 IN OUT UINTN *ImageInfoSize,
259 IN OUT EFI_FIRMWARE_IMAGE_DESCRIPTOR *ImageInfo,
260 OUT UINT32 *DescriptorVersion,
261 OUT UINT8 *DescriptorCount,
262 OUT UINTN *DescriptorSize,
263 OUT UINT32 *PackageVersion,
264 OUT CHAR16 **PackageVersionName
265 );
266
267 /**
268 Retrieves a copy of the current firmware image of the device.
269
270 This function allows a copy of the current firmware image to be created and saved.
271 The saved copy could later been used, for example, in firmware image recovery or rollback.
272
273 @param[in] This A pointer to the EFI_FIRMWARE_MANAGEMENT_PROTOCOL instance.
274 @param[in] ImageIndex A unique number identifying the firmware image(s) within the device.
275 The number is between 1 and DescriptorCount.
276 @param[out] Image Points to the buffer where the current image is copied to.
277 @param[out] ImageSize On entry, points to the size of the buffer pointed to by Image, in bytes.
278 On return, points to the length of the image, in bytes.
279
280 @retval EFI_SUCCESS The device was successfully updated with the new image.
281 @retval EFI_BUFFER_TOO_SMALL The buffer specified by ImageSize is too small to hold the
282 image. The current buffer size needed to hold the image is returned
283 in ImageSize.
284 @retval EFI_INVALID_PARAMETER The Image was NULL.
285 @retval EFI_NOT_FOUND The current image is not copied to the buffer.
286 @retval EFI_UNSUPPORTED The operation is not supported.
287 @retval EFI_SECURITY_VIOLATIO The operation could not be performed due to an authentication failure.
288
289 **/
290 typedef
291 EFI_STATUS
292 (EFIAPI *EFI_FIRMWARE_MANAGEMENT_PROTOCOL_GET_IMAGE)(
293 IN EFI_FIRMWARE_MANAGEMENT_PROTOCOL *This,
294 IN UINT8 ImageIndex,
295 IN OUT VOID *Image,
296 IN OUT UINTN *ImageSize
297 );
298
299 /**
300 Updates the firmware image of the device.
301
302 This function updates the hardware with the new firmware image.
303 This function returns EFI_UNSUPPORTED if the firmware image is not updatable.
304 If the firmware image is updatable, the function should perform the following minimal validations
305 before proceeding to do the firmware image update.
306 - Validate the image authentication if image has attribute
307 IMAGE_ATTRIBUTE_AUTHENTICATION_REQUIRED. The function returns
308 EFI_SECURITY_VIOLATION if the validation fails.
309 - Validate the image is a supported image for this device. The function returns EFI_ABORTED if
310 the image is unsupported. The function can optionally provide more detailed information on
311 why the image is not a supported image.
312 - Validate the data from VendorCode if not null. Image validation must be performed before
313 VendorCode data validation. VendorCode data is ignored or considered invalid if image
314 validation failed. The function returns EFI_ABORTED if the data is invalid.
315
316 VendorCode enables vendor to implement vendor-specific firmware image update policy. Null if
317 the caller did not specify the policy or use the default policy. As an example, vendor can implement
318 a policy to allow an option to force a firmware image update when the abort reason is due to the new
319 firmware image version is older than the current firmware image version or bad image checksum.
320 Sensitive operations such as those wiping the entire firmware image and render the device to be
321 non-functional should be encoded in the image itself rather than passed with the VendorCode.
322 AbortReason enables vendor to have the option to provide a more detailed description of the abort
323 reason to the caller.
324
325 @param[in] This A pointer to the EFI_FIRMWARE_MANAGEMENT_PROTOCOL instance.
326 @param[in] ImageIndex A unique number identifying the firmware image(s) within the device.
327 The number is between 1 and DescriptorCount.
328 @param[in] Image Points to the new image.
329 @param[in] ImageSize Size of the new image in bytes.
330 @param[in] VendorCode This enables vendor to implement vendor-specific firmware image update policy.
331 Null indicates the caller did not specify the policy or use the default policy.
332 @param[in] Progress A function used by the driver to report the progress of the firmware update.
333 @param[out] AbortReason A pointer to a pointer to a null-terminated string providing more
334 details for the aborted operation. The buffer is allocated by this function
335 with AllocatePool(), and it is the caller's responsibility to free it with a
336 call to FreePool().
337
338 @retval EFI_SUCCESS The device was successfully updated with the new image.
339 @retval EFI_ABORTED The operation is aborted.
340 @retval EFI_INVALID_PARAMETER The Image was NULL.
341 @retval EFI_UNSUPPORTED The operation is not supported.
342 @retval EFI_SECURITY_VIOLATIO The operation could not be performed due to an authentication failure.
343
344 **/
345 typedef
346 EFI_STATUS
347 (EFIAPI *EFI_FIRMWARE_MANAGEMENT_PROTOCOL_SET_IMAGE)(
348 IN EFI_FIRMWARE_MANAGEMENT_PROTOCOL *This,
349 IN UINT8 ImageIndex,
350 IN CONST VOID *Image,
351 IN UINTN ImageSize,
352 IN CONST VOID *VendorCode,
353 IN EFI_FIRMWARE_MANAGEMENT_UPDATE_IMAGE_PROGRESS Progress,
354 OUT CHAR16 **AbortReason
355 );
356
357 /**
358 Checks if the firmware image is valid for the device.
359
360 This function allows firmware update application to validate the firmware image without
361 invoking the SetImage() first.
362
363 @param[in] This A pointer to the EFI_FIRMWARE_MANAGEMENT_PROTOCOL instance.
364 @param[in] ImageIndex A unique number identifying the firmware image(s) within the device.
365 The number is between 1 and DescriptorCount.
366 @param[in] Image Points to the new image.
367 @param[in] ImageSize Size of the new image in bytes.
368 @param[out] ImageUpdatable Indicates if the new image is valid for update. It also provides,
369 if available, additional information if the image is invalid.
370
371 @retval EFI_SUCCESS The image was successfully checked.
372 @retval EFI_INVALID_PARAMETER The Image was NULL.
373 @retval EFI_UNSUPPORTED The operation is not supported.
374 @retval EFI_SECURITY_VIOLATIO The operation could not be performed due to an authentication failure.
375
376 **/
377 typedef
378 EFI_STATUS
379 (EFIAPI *EFI_FIRMWARE_MANAGEMENT_PROTOCOL_CHECK_IMAGE)(
380 IN EFI_FIRMWARE_MANAGEMENT_PROTOCOL *This,
381 IN UINT8 ImageIndex,
382 IN CONST VOID *Image,
383 IN UINTN ImageSize,
384 OUT UINT32 *ImageUpdatable
385 );
386
387 /**
388 Returns information about the firmware package.
389
390 This function returns package information.
391
392 @param[in] This A pointer to the EFI_FIRMWARE_MANAGEMENT_PROTOCOL instance.
393 @param[out] PackageVersion A version number that represents all the firmware images in the device.
394 The format is vendor specific and new version must have a greater value
395 than the old version. If PackageVersion is not supported, the value is
396 0xFFFFFFFF. A value of 0xFFFFFFFE indicates that package version
397 comparison is to be performed using PackageVersionName. A value of
398 0xFFFFFFFD indicates that package version update is in progress.
399 @param[out] PackageVersionName A pointer to a pointer to a null-terminated string representing
400 the package version name. The buffer is allocated by this function with
401 AllocatePool(), and it is the caller's responsibility to free it with a
402 call to FreePool().
403 @param[out] PackageVersionNameMaxLen The maximum length of package version name if device supports update of
404 package version name. A value of 0 indicates the device does not support
405 update of package version name. Length is the number of Unicode characters,
406 including the terminating null character.
407 @param[out] AttributesSupported Package attributes that are supported by this device. See 'Package Attribute
408 Definitions' for possible returned values of this parameter. A value of 1
409 indicates the attribute is supported and the current setting value is
410 indicated in AttributesSetting. A value of 0 indicates the attribute is not
411 supported and the current setting value in AttributesSetting is meaningless.
412 @param[out] AttributesSetting Package attributes. See 'Package Attribute Definitions' for possible returned
413 values of this parameter
414
415 @retval EFI_SUCCESS The package information was successfully returned.
416 @retval EFI_UNSUPPORTED The operation is not supported.
417
418 **/
419 typedef
420 EFI_STATUS
421 (EFIAPI *EFI_FIRMWARE_MANAGEMENT_PROTOCOL_GET_PACKAGE_INFO)(
422 IN EFI_FIRMWARE_MANAGEMENT_PROTOCOL *This,
423 OUT UINT32 *PackageVersion,
424 OUT CHAR16 **PackageVersionName,
425 OUT UINT32 *PackageVersionNameMaxLen,
426 OUT UINT64 *AttributesSupported,
427 OUT UINT64 *AttributesSetting
428 );
429
430 /**
431 Updates information about the firmware package.
432
433 This function updates package information.
434 This function returns EFI_UNSUPPORTED if the package information is not updatable.
435 VendorCode enables vendor to implement vendor-specific package information update policy.
436 Null if the caller did not specify this policy or use the default policy.
437
438 @param[in] This A pointer to the EFI_FIRMWARE_MANAGEMENT_PROTOCOL instance.
439 @param[in] Image Points to the authentication image.
440 Null if authentication is not required.
441 @param[in] ImageSize Size of the authentication image in bytes.
442 0 if authentication is not required.
443 @param[in] VendorCode This enables vendor to implement vendor-specific firmware
444 image update policy.
445 Null indicates the caller did not specify this policy or use
446 the default policy.
447 @param[in] PackageVersion The new package version.
448 @param[in] PackageVersionName A pointer to the new null-terminated Unicode string representing
449 the package version name.
450 The string length is equal to or less than the value returned in
451 PackageVersionNameMaxLen.
452
453 @retval EFI_SUCCESS The device was successfully updated with the new package
454 information.
455 @retval EFI_INVALID_PARAMETER The PackageVersionName length is longer than the value
456 returned in PackageVersionNameMaxLen.
457 @retval EFI_UNSUPPORTED The operation is not supported.
458 @retval EFI_SECURITY_VIOLATIO The operation could not be performed due to an authentication failure.
459
460 **/
461 typedef
462 EFI_STATUS
463 (EFIAPI *EFI_FIRMWARE_MANAGEMENT_PROTOCOL_SET_PACKAGE_INFO)(
464 IN EFI_FIRMWARE_MANAGEMENT_PROTOCOL *This,
465 IN CONST VOID *Image,
466 IN UINTN ImageSize,
467 IN CONST VOID *VendorCode,
468 IN UINT32 PackageVersion,
469 IN CONST CHAR16 *PackageVersionName
470 );
471
472 ///
473 /// EFI_FIRMWARE_MANAGEMENT_PROTOCOL
474 /// The protocol for managing firmware provides the following services.
475 /// - Get the attributes of the current firmware image. Attributes include revision level.
476 /// - Get a copy of the current firmware image. As an example, this service could be used by a
477 /// management application to facilitate a firmware roll-back.
478 /// - Program the device with a firmware image supplied by the user.
479 /// - Label all the firmware images within a device with a single version.
480 ///
481 struct _EFI_FIRMWARE_MANAGEMENT_PROTOCOL {
482 EFI_FIRMWARE_MANAGEMENT_PROTOCOL_GET_IMAGE_INFO GetImageInfo;
483 EFI_FIRMWARE_MANAGEMENT_PROTOCOL_GET_IMAGE GetImage;
484 EFI_FIRMWARE_MANAGEMENT_PROTOCOL_SET_IMAGE SetImage;
485 EFI_FIRMWARE_MANAGEMENT_PROTOCOL_CHECK_IMAGE CheckImage;
486 EFI_FIRMWARE_MANAGEMENT_PROTOCOL_GET_PACKAGE_INFO GetPackageInfo;
487 EFI_FIRMWARE_MANAGEMENT_PROTOCOL_SET_PACKAGE_INFO SetPackageInfo;
488 };
489
490 extern EFI_GUID gEfiFirmwareManagementProtocolGuid;
491
492 #endif