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