[mirror_edk2.git] / FmpDevicePkg / Library / FmpDeviceLibNull / FmpDeviceLib.c

/** @file\r
  Provides firmware device specific services to support updates of a firmware\r
  image stored in a firmware device.\r
\r
  Copyright (c) 2016, Microsoft Corporation. All rights reserved.<BR>\r
  Copyright (c) 2018, Intel Corporation. All rights reserved.<BR>\r
\r
  SPDX-License-Identifier: BSD-2-Clause-Patent\r
\r
**/\r
\r
#include <PiDxe.h>\r
#include <Library/FmpDeviceLib.h>\r
\r
/**\r
  Provide a function to install the Firmware Management Protocol instance onto a\r
  device handle when the device is managed by a driver that follows the UEFI\r
  Driver Model.  If the device is not managed by a driver that follows the UEFI\r
  Driver Model, then EFI_UNSUPPORTED is returned.\r
\r
  @param[in] FmpInstaller  Function that installs the Firmware Management\r
                           Protocol.\r
\r
  @retval EFI_SUCCESS      The device is managed by a driver that follows the\r
                           UEFI Driver Model.  FmpInstaller must be called on\r
                           each Driver Binding Start().\r
  @retval EFI_UNSUPPORTED  The device is not managed by a driver that follows\r
                           the UEFI Driver Model.\r
  @retval other            The Firmware Management Protocol for this firmware\r
                           device is not installed.  The firmware device is\r
                           still locked using FmpDeviceLock().\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
RegisterFmpInstaller (\r
  IN FMP_DEVICE_LIB_REGISTER_FMP_INSTALLER  Function\r
  )\r
{\r
  return EFI_UNSUPPORTED;\r
}\r
\r
/**\r
  Returns the size, in bytes, of the firmware image currently stored in the\r
  firmware device.  This function is used to by the GetImage() and\r
  GetImageInfo() services of the Firmware Management Protocol.  If the image\r
  size can not be determined from the firmware device, then 0 must be returned.\r
\r
  @param[out] Size  Pointer to the size, in bytes, of the firmware image\r
                    currently stored in the firmware device.\r
\r
  @retval EFI_SUCCESS            The size of the firmware image currently\r
                                 stored in the firmware device was returned.\r
  @retval EFI_INVALID_PARAMETER  Size is NULL.\r
  @retval EFI_UNSUPPORTED        The firmware device does not support reporting\r
                                 the size of the currently stored firmware image.\r
  @retval EFI_DEVICE_ERROR       An error occurred attempting to determine the\r
                                 size of the firmware image currently stored in\r
                                 in the firmware device.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
FmpDeviceGetSize (\r
  OUT UINTN  *Size\r
  )\r
{\r
  if (Size == NULL) {\r
    return EFI_INVALID_PARAMETER;\r
  }\r
  *Size = 0;\r
  return EFI_SUCCESS;\r
}\r
\r
/**\r
  Returns the GUID value used to fill in the ImageTypeId field of the\r
  EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the GetImageInfo()\r
  service of the Firmware Management Protocol.  If EFI_UNSUPPORTED is returned,\r
  then the ImageTypeId field is set to gEfiCallerIdGuid.  If EFI_SUCCESS is\r
  returned, then ImageTypeId is set to the Guid returned from this function.\r
\r
  @param[out] Guid  Double pointer to a GUID value that is updated to point to\r
                    to a GUID value.  The GUID value is not allocated and must\r
                    not be modified or freed by the caller.\r
\r
  @retval EFI_SUCCESS      EFI_FIRMWARE_IMAGE_DESCRIPTOR ImageTypeId GUID is set\r
                           to the returned Guid value.\r
  @retval EFI_UNSUPPORTED  EFI_FIRMWARE_IMAGE_DESCRIPTOR ImageTypeId GUID is set\r
                           to gEfiCallerIdGuid.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
FmpDeviceGetImageTypeIdGuidPtr (\r
  OUT EFI_GUID  **Guid\r
  )\r
{\r
  return EFI_UNSUPPORTED;\r
}\r
\r
/**\r
  Returns values used to fill in the AttributesSupported and AttributesSettings\r
  fields of the EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the\r
  GetImageInfo() service of the Firmware Management Protocol.  The following\r
  bit values from the Firmware Management Protocol may be combined:\r
    IMAGE_ATTRIBUTE_IMAGE_UPDATABLE\r
    IMAGE_ATTRIBUTE_RESET_REQUIRED\r
    IMAGE_ATTRIBUTE_AUTHENTICATION_REQUIRED\r
    IMAGE_ATTRIBUTE_IN_USE\r
    IMAGE_ATTRIBUTE_UEFI_IMAGE\r
\r
  @param[out] Supported  Attributes supported by this firmware device.\r
  @param[out] Setting    Attributes settings for this firmware device.\r
\r
  @retval EFI_SUCCESS            The attributes supported by the firmware\r
                                 device were returned.\r
  @retval EFI_INVALID_PARAMETER  Supported is NULL.\r
  @retval EFI_INVALID_PARAMETER  Setting is NULL.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
FmpDeviceGetAttributes (\r
  OUT UINT64    *Supported,\r
  OUT UINT64    *Setting\r
  )\r
{\r
  if (Supported == NULL || Setting == NULL) {\r
    return EFI_INVALID_PARAMETER;\r
  }\r
  *Supported = 0;\r
  *Setting   = 0;\r
  return EFI_SUCCESS;\r
}\r
\r
/**\r
  Returns the value used to fill in the LowestSupportedVersion field of the\r
  EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the GetImageInfo()\r
  service of the Firmware Management Protocol.  If EFI_SUCCESS is returned, then\r
  the firmware device supports a method to report the LowestSupportedVersion\r
  value from the currently stored firmware image.  If the value can not be\r
  reported for the firmware image currently stored in the firmware device, then\r
  EFI_UNSUPPORTED must be returned.  EFI_DEVICE_ERROR is returned if an error\r
  occurs attempting to retrieve the LowestSupportedVersion value for the\r
  currently stored firmware image.\r
\r
  @note It is recommended that all firmware devices support a method to report\r
        the LowestSupportedVersion value from the currently stored firmware\r
        image.\r
\r
  @param[out] LowestSupportedVersion  LowestSupportedVersion value retrieved\r
                                      from the currently stored firmware image.\r
\r
  @retval EFI_SUCCESS       The lowest supported version of currently stored\r
                            firmware image was returned in LowestSupportedVersion.\r
  @retval EFI_UNSUPPORTED   The firmware device does not support a method to\r
                            report the lowest supported version of the currently\r
                            stored firmware image.\r
  @retval EFI_DEVICE_ERROR  An error occurred attempting to retrieve the lowest\r
                            supported version of the currently stored firmware\r
                            image.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
FmpDeviceGetLowestSupportedVersion (\r
  OUT UINT32  *LowestSupportedVersion\r
  )\r
{\r
  return EFI_UNSUPPORTED;\r
}\r
\r
/**\r
  Returns the Null-terminated Unicode string that is used to fill in the\r
  VersionName field of the EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is\r
  returned by the GetImageInfo() service of the Firmware Management Protocol.\r
  The returned string must be allocated using EFI_BOOT_SERVICES.AllocatePool().\r
\r
  @note It is recommended that all firmware devices support a method to report\r
        the VersionName string from the currently stored firmware image.\r
\r
  @param[out] VersionString  The version string retrieved from the currently\r
                             stored firmware image.\r
\r
  @retval EFI_SUCCESS            The version string of currently stored\r
                                 firmware image was returned in Version.\r
  @retval EFI_INVALID_PARAMETER  VersionString is NULL.\r
  @retval EFI_UNSUPPORTED        The firmware device does not support a method\r
                                 to report the version string of the currently\r
                                 stored firmware image.\r
  @retval EFI_DEVICE_ERROR       An error occurred attempting to retrieve the\r
                                 version string of the currently stored\r
                                 firmware image.\r
  @retval EFI_OUT_OF_RESOURCES   There are not enough resources to allocate the\r
                                 buffer for the version string of the currently\r
                                 stored firmware image.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
FmpDeviceGetVersionString (\r
  OUT CHAR16  **VersionString\r
  )\r
{\r
  if (VersionString == NULL) {\r
    return EFI_INVALID_PARAMETER;\r
  }\r
  *VersionString = NULL;\r
  return EFI_UNSUPPORTED;\r
}\r
\r
/**\r
  Returns the value used to fill in the Version field of the\r
  EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the GetImageInfo()\r
  service of the Firmware Management Protocol.  If EFI_SUCCESS is returned, then\r
  the firmware device supports a method to report the Version value from the\r
  currently stored firmware image.  If the value can not be reported for the\r
  firmware image currently stored in the firmware device, then EFI_UNSUPPORTED\r
  must be returned.  EFI_DEVICE_ERROR is returned if an error occurs attempting\r
  to retrieve the LowestSupportedVersion value for the currently stored firmware\r
  image.\r
\r
  @note It is recommended that all firmware devices support a method to report\r
        the Version value from the currently stored firmware image.\r
\r
  @param[out] Version  The version value retrieved from the currently stored\r
                       firmware image.\r
\r
  @retval EFI_SUCCESS       The version of currently stored firmware image was\r
                            returned in Version.\r
  @retval EFI_UNSUPPORTED   The firmware device does not support a method to\r
                            report the version of the currently stored firmware\r
                            image.\r
  @retval EFI_DEVICE_ERROR  An error occurred attempting to retrieve the version\r
                            of the currently stored firmware image.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
FmpDeviceGetVersion (\r
  OUT UINT32  *Version\r
  )\r
{\r
  return EFI_UNSUPPORTED;\r
}\r
\r
/**\r
  Returns a copy of the firmware image currently stored in the firmware device.\r
\r
  @note It is recommended that all firmware devices support a method to retrieve\r
        a copy currently stored firmware image.  This can be used to support\r
        features such as recovery and rollback.\r
\r
  @param[out]     Image     Pointer to a caller allocated buffer where the\r
                            currently stored firmware image is copied to.\r
  @param[in, out] ImageSize Pointer the size, in bytes, of the Image buffer.\r
                            On return, points to the size, in bytes, of firmware\r
                            image currently stored in the firmware device.\r
\r
  @retval EFI_SUCCESS            Image contains a copy of the firmware image\r
                                 currently stored in the firmware device, and\r
                                 ImageSize contains the size, in bytes, of the\r
                                 firmware image currently stored in the\r
                                 firmware device.\r
  @retval EFI_BUFFER_TOO_SMALL   The buffer specified by ImageSize is too small\r
                                 to hold the firmware image currently stored in\r
                                 the firmware device. The buffer size required\r
                                 is returned in ImageSize.\r
  @retval EFI_INVALID_PARAMETER  The Image is NULL.\r
  @retval EFI_INVALID_PARAMETER  The ImageSize is NULL.\r
  @retval EFI_UNSUPPORTED        The operation is not supported.\r
  @retval EFI_DEVICE_ERROR       An error occurred attempting to retrieve the\r
                                 firmware image currently stored in the firmware\r
                                 device.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
FmpDeviceGetImage (\r
  OUT    VOID   *Image,\r
  IN OUT UINTN  *ImageSize\r
  )\r
{\r
  return EFI_UNSUPPORTED;\r
}\r
\r
/**\r
  Checks if a new firmware image is valid for the firmware device.  This\r
  function allows firmware update operation to validate the firmware image\r
  before FmpDeviceSetImage() is called.\r
\r
  @param[in]  Image           Points to a new firmware image.\r
  @param[in]  ImageSize       Size, in bytes, of a new firmware image.\r
  @param[out] ImageUpdatable  Indicates if a new firmware image is valid for\r
                              a firmware update to the firmware device.  The\r
                              following values from the Firmware Management\r
                              Protocol are supported:\r
                                IMAGE_UPDATABLE_VALID\r
                                IMAGE_UPDATABLE_INVALID\r
                                IMAGE_UPDATABLE_INVALID_TYPE\r
                                IMAGE_UPDATABLE_INVALID_OLD\r
                                IMAGE_UPDATABLE_VALID_WITH_VENDOR_CODE\r
\r
  @retval EFI_SUCCESS            The image was successfully checked.  Additional\r
                                 status information is returned in\r
                                 ImageUpdatable.\r
  @retval EFI_INVALID_PARAMETER  Image is NULL.\r
  @retval EFI_INVALID_PARAMETER  ImageUpdatable is NULL.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
FmpDeviceCheckImage (\r
  IN  CONST VOID  *Image,\r
  IN  UINTN       ImageSize,\r
  OUT UINT32      *ImageUpdatable\r
  )\r
{\r
  return EFI_SUCCESS;\r
}\r
\r
/**\r
  Updates a firmware device with a new firmware image.  This function returns\r
  EFI_UNSUPPORTED if the firmware image is not updatable.  If the firmware image\r
  is updatable, the function should perform the following minimal validations\r
  before proceeding to do the firmware image update.\r
    - Validate that the image is a supported image for this firmware device.\r
      Return EFI_ABORTED if the image is not supported.  Additional details\r
      on why the image is not a supported image may be returned in AbortReason.\r
    - Validate the data from VendorCode if is not NULL.  Firmware image\r
      validation must be performed before VendorCode data validation.\r
      VendorCode data is ignored or considered invalid if image validation\r
      fails.  Return EFI_ABORTED if the VendorCode data is invalid.\r
\r
  VendorCode enables vendor to implement vendor-specific firmware image update\r
  policy.  Null if the caller did not specify the policy or use the default\r
  policy.  As an example, vendor can implement a policy to allow an option to\r
  force a firmware image update when the abort reason is due to the new firmware\r
  image version is older than the current firmware image version or bad image\r
  checksum.  Sensitive operations such as those wiping the entire firmware image\r
  and render the device to be non-functional should be encoded in the image\r
  itself rather than passed with the VendorCode.  AbortReason enables vendor to\r
  have the option to provide a more detailed description of the abort reason to\r
  the caller.\r
\r
  @param[in]  Image             Points to the new firmware image.\r
  @param[in]  ImageSize         Size, in bytes, of the new firmware image.\r
  @param[in]  VendorCode        This enables vendor to implement vendor-specific\r
                                firmware image update policy.  NULL indicates\r
                                the caller did not specify the policy or use the\r
                                default policy.\r
  @param[in]  Progress          A function used to report the progress of\r
                                updating the firmware device with the new\r
                                firmware image.\r
  @param[in]  CapsuleFwVersion  The version of the new firmware image from the\r
                                update capsule that provided the new firmware\r
                                image.\r
  @param[out] AbortReason       A pointer to a pointer to a Null-terminated\r
                                Unicode string providing more details on an\r
                                aborted operation. The buffer is allocated by\r
                                this function with\r
                                EFI_BOOT_SERVICES.AllocatePool().  It is the\r
                                caller's responsibility to free this buffer with\r
                                EFI_BOOT_SERVICES.FreePool().\r
\r
  @retval EFI_SUCCESS            The firmware device was successfully updated\r
                                 with the new firmware image.\r
  @retval EFI_ABORTED            The operation is aborted.  Additional details\r
                                 are provided in AbortReason.\r
  @retval EFI_INVALID_PARAMETER  The Image was NULL.\r
  @retval EFI_UNSUPPORTED        The operation is not supported.\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
FmpDeviceSetImage (\r
  IN  CONST VOID                                     *Image,\r
  IN  UINTN                                          ImageSize,\r
  IN  CONST VOID                                     *VendorCode,       OPTIONAL\r
  IN  EFI_FIRMWARE_MANAGEMENT_UPDATE_IMAGE_PROGRESS  Progress,          OPTIONAL\r
  IN  UINT32                                         CapsuleFwVersion,\r
  OUT CHAR16                                         **AbortReason\r
  )\r
{\r
  return EFI_UNSUPPORTED;\r
}\r
\r
/**\r
  Lock the firmware device that contains a firmware image.  Once a firmware\r
  device is locked, any attempts to modify the firmware image contents in the\r
  firmware device must fail.\r
\r
  @note It is recommended that all firmware devices support a lock method to\r
        prevent modifications to a stored firmware image.\r
\r
  @note A firmware device lock mechanism is typically only cleared by a full\r
        system reset (not just sleep state/low power mode).\r
\r
  @retval  EFI_SUCCESS      The firmware device was locked.\r
  @retval  EFI_UNSUPPORTED  The firmware device does not support locking\r
\r
**/\r
EFI_STATUS\r
EFIAPI\r
FmpDeviceLock (\r
  VOID\r
  )\r
{\r
  return EFI_UNSUPPORTED;\r
}\r
Commit	Line	Data
a6d73269	1	/** @file\r
403d4bcd KM	2	Provides firmware device specific services to support updates of a firmware\r
	3	image stored in a firmware device.\r
	4	\r
	5	Copyright (c) 2016, Microsoft Corporation. All rights reserved.<BR>\r
	6	Copyright (c) 2018, Intel Corporation. All rights reserved.<BR>\r
	7	\r
bcef758c	8	SPDX-License-Identifier: BSD-2-Clause-Patent\r
403d4bcd KM	9	\r
	10	**/\r
	11	\r
	12	#include <PiDxe.h>\r
	13	#include <Library/FmpDeviceLib.h>\r
	14	\r
	15	/**\r
	16	Provide a function to install the Firmware Management Protocol instance onto a\r
	17	device handle when the device is managed by a driver that follows the UEFI\r
	18	Driver Model. If the device is not managed by a driver that follows the UEFI\r
	19	Driver Model, then EFI_UNSUPPORTED is returned.\r
	20	\r
	21	@param[in] FmpInstaller Function that installs the Firmware Management\r
	22	Protocol.\r
	23	\r
	24	@retval EFI_SUCCESS The device is managed by a driver that follows the\r
	25	UEFI Driver Model. FmpInstaller must be called on\r
	26	each Driver Binding Start().\r
	27	@retval EFI_UNSUPPORTED The device is not managed by a driver that follows\r
	28	the UEFI Driver Model.\r
	29	@retval other The Firmware Management Protocol for this firmware\r
	30	device is not installed. The firmware device is\r
	31	still locked using FmpDeviceLock().\r
	32	\r
	33	**/\r
	34	EFI_STATUS\r
	35	EFIAPI\r
	36	RegisterFmpInstaller (\r
	37	IN FMP_DEVICE_LIB_REGISTER_FMP_INSTALLER Function\r
	38	)\r
	39	{\r
	40	return EFI_UNSUPPORTED;\r
	41	}\r
	42	\r
	43	/**\r
	44	Returns the size, in bytes, of the firmware image currently stored in the\r
	45	firmware device. This function is used to by the GetImage() and\r
	46	GetImageInfo() services of the Firmware Management Protocol. If the image\r
	47	size can not be determined from the firmware device, then 0 must be returned.\r
	48	\r
	49	@param[out] Size Pointer to the size, in bytes, of the firmware image\r
	50	currently stored in the firmware device.\r
	51	\r
	52	@retval EFI_SUCCESS The size of the firmware image currently\r
	53	stored in the firmware device was returned.\r
	54	@retval EFI_INVALID_PARAMETER Size is NULL.\r
	55	@retval EFI_UNSUPPORTED The firmware device does not support reporting\r
	56	the size of the currently stored firmware image.\r
	57	@retval EFI_DEVICE_ERROR An error occurred attempting to determine the\r
	58	size of the firmware image currently stored in\r
	59	in the firmware device.\r
	60	\r
	61	**/\r
	62	EFI_STATUS\r
	63	EFIAPI\r
	64	FmpDeviceGetSize (\r
a6d73269	65	OUT UINTN *Size\r
403d4bcd KM	66	)\r
	67	{\r
	68	if (Size == NULL) {\r
	69	return EFI_INVALID_PARAMETER;\r
	70	}\r
	71	*Size = 0;\r
	72	return EFI_SUCCESS;\r
	73	}\r
	74	\r
	75	/**\r
	76	Returns the GUID value used to fill in the ImageTypeId field of the\r
	77	EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the GetImageInfo()\r
	78	service of the Firmware Management Protocol. If EFI_UNSUPPORTED is returned,\r
	79	then the ImageTypeId field is set to gEfiCallerIdGuid. If EFI_SUCCESS is\r
	80	returned, then ImageTypeId is set to the Guid returned from this function.\r
	81	\r
	82	@param[out] Guid Double pointer to a GUID value that is updated to point to\r
	83	to a GUID value. The GUID value is not allocated and must\r
	84	not be modified or freed by the caller.\r
	85	\r
	86	@retval EFI_SUCCESS EFI_FIRMWARE_IMAGE_DESCRIPTOR ImageTypeId GUID is set\r
	87	to the returned Guid value.\r
	88	@retval EFI_UNSUPPORTED EFI_FIRMWARE_IMAGE_DESCRIPTOR ImageTypeId GUID is set\r
	89	to gEfiCallerIdGuid.\r
	90	\r
	91	**/\r
	92	EFI_STATUS\r
	93	EFIAPI\r
	94	FmpDeviceGetImageTypeIdGuidPtr (\r
	95	OUT EFI_GUID **Guid\r
	96	)\r
	97	{\r
	98	return EFI_UNSUPPORTED;\r
	99	}\r
	100	\r
	101	/**\r
	102	Returns values used to fill in the AttributesSupported and AttributesSettings\r
	103	fields of the EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the\r
	104	GetImageInfo() service of the Firmware Management Protocol. The following\r
	105	bit values from the Firmware Management Protocol may be combined:\r
	106	IMAGE_ATTRIBUTE_IMAGE_UPDATABLE\r
	107	IMAGE_ATTRIBUTE_RESET_REQUIRED\r
	108	IMAGE_ATTRIBUTE_AUTHENTICATION_REQUIRED\r
	109	IMAGE_ATTRIBUTE_IN_USE\r
	110	IMAGE_ATTRIBUTE_UEFI_IMAGE\r
	111	\r
	112	@param[out] Supported Attributes supported by this firmware device.\r
	113	@param[out] Setting Attributes settings for this firmware device.\r
	114	\r
	115	@retval EFI_SUCCESS The attributes supported by the firmware\r
	116	device were returned.\r
	117	@retval EFI_INVALID_PARAMETER Supported is NULL.\r
	118	@retval EFI_INVALID_PARAMETER Setting is NULL.\r
	119	\r
	120	**/\r
	121	EFI_STATUS\r
	122	EFIAPI\r
	123	FmpDeviceGetAttributes (\r
a6d73269 SZ	124	OUT UINT64 *Supported,\r
a6d73269 SZ	125	OUT UINT64 *Setting\r
403d4bcd KM	126	)\r
	127	{\r
	128	if (Supported == NULL \|\| Setting == NULL) {\r
	129	return EFI_INVALID_PARAMETER;\r
	130	}\r
	131	*Supported = 0;\r
	132	*Setting = 0;\r
	133	return EFI_SUCCESS;\r
	134	}\r
	135	\r
	136	/**\r
	137	Returns the value used to fill in the LowestSupportedVersion field of the\r
	138	EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the GetImageInfo()\r
	139	service of the Firmware Management Protocol. If EFI_SUCCESS is returned, then\r
	140	the firmware device supports a method to report the LowestSupportedVersion\r
	141	value from the currently stored firmware image. If the value can not be\r
	142	reported for the firmware image currently stored in the firmware device, then\r
	143	EFI_UNSUPPORTED must be returned. EFI_DEVICE_ERROR is returned if an error\r
	144	occurs attempting to retrieve the LowestSupportedVersion value for the\r
	145	currently stored firmware image.\r
	146	\r
	147	@note It is recommended that all firmware devices support a method to report\r
	148	the LowestSupportedVersion value from the currently stored firmware\r
	149	image.\r
	150	\r
	151	@param[out] LowestSupportedVersion LowestSupportedVersion value retrieved\r
	152	from the currently stored firmware image.\r
	153	\r
	154	@retval EFI_SUCCESS The lowest supported version of currently stored\r
	155	firmware image was returned in LowestSupportedVersion.\r
	156	@retval EFI_UNSUPPORTED The firmware device does not support a method to\r
	157	report the lowest supported version of the currently\r
	158	stored firmware image.\r
	159	@retval EFI_DEVICE_ERROR An error occurred attempting to retrieve the lowest\r
	160	supported version of the currently stored firmware\r
	161	image.\r
	162	\r
	163	**/\r
	164	EFI_STATUS\r
	165	EFIAPI\r
	166	FmpDeviceGetLowestSupportedVersion (\r
	167	OUT UINT32 *LowestSupportedVersion\r
	168	)\r
	169	{\r
	170	return EFI_UNSUPPORTED;\r
	171	}\r
	172	\r
	173	/**\r
	174	Returns the Null-terminated Unicode string that is used to fill in the\r
	175	VersionName field of the EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is\r
	176	returned by the GetImageInfo() service of the Firmware Management Protocol.\r
	177	The returned string must be allocated using EFI_BOOT_SERVICES.AllocatePool().\r
	178	\r
	179	@note It is recommended that all firmware devices support a method to report\r
	180	the VersionName string from the currently stored firmware image.\r
	181	\r
	182	@param[out] VersionString The version string retrieved from the currently\r
	183	stored firmware image.\r
	184	\r
	185	@retval EFI_SUCCESS The version string of currently stored\r
	186	firmware image was returned in Version.\r
	187	@retval EFI_INVALID_PARAMETER VersionString is NULL.\r
	188	@retval EFI_UNSUPPORTED The firmware device does not support a method\r
	189	to report the version string of the currently\r
190	stored firmware image.\r
191	@retval EFI_DEVICE_ERROR An error occurred attempting to retrieve the\r
192	version string of the currently stored\r
193	firmware image.\r
194	@retval EFI_OUT_OF_RESOURCES There are not enough resources to allocate the\r
195	buffer for the version string of the currently\r
196	stored firmware image.\r
197	\r
198	**/\r
199	EFI_STATUS\r
200	EFIAPI\r
201	FmpDeviceGetVersionString (\r
202	OUT CHAR16 **VersionString\r
203	)\r
204	{\r
205	if (VersionString == NULL) {\r
206	return EFI_INVALID_PARAMETER;\r
207	}\r
208	*VersionString = NULL;\r
209	return EFI_UNSUPPORTED;\r
210	}\r
211	\r
212	/**\r
213	Returns the value used to fill in the Version field of the\r
214	EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the GetImageInfo()\r
215	service of the Firmware Management Protocol. If EFI_SUCCESS is returned, then\r
216	the firmware device supports a method to report the Version value from the\r
217	currently stored firmware image. If the value can not be reported for the\r
218	firmware image currently stored in the firmware device, then EFI_UNSUPPORTED\r
219	must be returned. EFI_DEVICE_ERROR is returned if an error occurs attempting\r
220	to retrieve the LowestSupportedVersion value for the currently stored firmware\r
221	image.\r
222	\r
223	@note It is recommended that all firmware devices support a method to report\r
224	the Version value from the currently stored firmware image.\r
225	\r
226	@param[out] Version The version value retrieved from the currently stored\r
227	firmware image.\r
228	\r
229	@retval EFI_SUCCESS The version of currently stored firmware image was\r
230	returned in Version.\r
231	@retval EFI_UNSUPPORTED The firmware device does not support a method to\r
232	report the version of the currently stored firmware\r
233	image.\r
234	@retval EFI_DEVICE_ERROR An error occurred attempting to retrieve the version\r
235	of the currently stored firmware image.\r
236	\r
237	**/\r
238	EFI_STATUS\r
239	EFIAPI\r
240	FmpDeviceGetVersion (\r
241	OUT UINT32 *Version\r
242	)\r
243	{\r
244	return EFI_UNSUPPORTED;\r
245	}\r
246	\r
247	/**\r
248	Returns a copy of the firmware image currently stored in the firmware device.\r
249	\r
250	@note It is recommended that all firmware devices support a method to retrieve\r
251	a copy currently stored firmware image. This can be used to support\r
252	features such as recovery and rollback.\r
253	\r
a6d73269	254	@param[out] Image Pointer to a caller allocated buffer where the\r
403d4bcd	255	currently stored firmware image is copied to.\r
a6d73269	256	@param[in, out] ImageSize Pointer the size, in bytes, of the Image buffer.\r
403d4bcd KM	257	On return, points to the size, in bytes, of firmware\r
	258	image currently stored in the firmware device.\r
	259	\r
	260	@retval EFI_SUCCESS Image contains a copy of the firmware image\r
	261	currently stored in the firmware device, and\r
	262	ImageSize contains the size, in bytes, of the\r
	263	firmware image currently stored in the\r
	264	firmware device.\r
	265	@retval EFI_BUFFER_TOO_SMALL The buffer specified by ImageSize is too small\r
	266	to hold the firmware image currently stored in\r
	267	the firmware device. The buffer size required\r
	268	is returned in ImageSize.\r
	269	@retval EFI_INVALID_PARAMETER The Image is NULL.\r
	270	@retval EFI_INVALID_PARAMETER The ImageSize is NULL.\r
	271	@retval EFI_UNSUPPORTED The operation is not supported.\r
	272	@retval EFI_DEVICE_ERROR An error occurred attempting to retrieve the\r
	273	firmware image currently stored in the firmware\r
	274	device.\r
	275	\r
	276	**/\r
	277	EFI_STATUS\r
	278	EFIAPI\r
	279	FmpDeviceGetImage (\r
a6d73269 SZ	280	OUT VOID *Image,\r
a6d73269 SZ	281	IN OUT UINTN *ImageSize\r
403d4bcd KM	282	)\r
	283	{\r
	284	return EFI_UNSUPPORTED;\r
	285	}\r
	286	\r
	287	/**\r
	288	Checks if a new firmware image is valid for the firmware device. This\r
	289	function allows firmware update operation to validate the firmware image\r
	290	before FmpDeviceSetImage() is called.\r
	291	\r
	292	@param[in] Image Points to a new firmware image.\r
	293	@param[in] ImageSize Size, in bytes, of a new firmware image.\r
	294	@param[out] ImageUpdatable Indicates if a new firmware image is valid for\r
	295	a firmware update to the firmware device. The\r
	296	following values from the Firmware Management\r
	297	Protocol are supported:\r
	298	IMAGE_UPDATABLE_VALID\r
	299	IMAGE_UPDATABLE_INVALID\r
	300	IMAGE_UPDATABLE_INVALID_TYPE\r
	301	IMAGE_UPDATABLE_INVALID_OLD\r
	302	IMAGE_UPDATABLE_VALID_WITH_VENDOR_CODE\r
	303	\r
	304	@retval EFI_SUCCESS The image was successfully checked. Additional\r
	305	status information is returned in\r
a6d73269	306	ImageUpdatable.\r
403d4bcd	307	@retval EFI_INVALID_PARAMETER Image is NULL.\r
a6d73269	308	@retval EFI_INVALID_PARAMETER ImageUpdatable is NULL.\r
403d4bcd KM	309	\r
	310	**/\r
	311	EFI_STATUS\r
	312	EFIAPI\r
	313	FmpDeviceCheckImage (\r
	314	IN CONST VOID *Image,\r
	315	IN UINTN ImageSize,\r
a6d73269	316	OUT UINT32 *ImageUpdatable\r
403d4bcd KM	317	)\r
	318	{\r
	319	return EFI_SUCCESS;\r
	320	}\r
	321	\r
	322	/**\r
	323	Updates a firmware device with a new firmware image. This function returns\r
	324	EFI_UNSUPPORTED if the firmware image is not updatable. If the firmware image\r
	325	is updatable, the function should perform the following minimal validations\r
	326	before proceeding to do the firmware image update.\r
	327	- Validate that the image is a supported image for this firmware device.\r
	328	Return EFI_ABORTED if the image is not supported. Additional details\r
	329	on why the image is not a supported image may be returned in AbortReason.\r
	330	- Validate the data from VendorCode if is not NULL. Firmware image\r
	331	validation must be performed before VendorCode data validation.\r
	332	VendorCode data is ignored or considered invalid if image validation\r
	333	fails. Return EFI_ABORTED if the VendorCode data is invalid.\r
	334	\r
	335	VendorCode enables vendor to implement vendor-specific firmware image update\r
	336	policy. Null if the caller did not specify the policy or use the default\r
	337	policy. As an example, vendor can implement a policy to allow an option to\r
	338	force a firmware image update when the abort reason is due to the new firmware\r
	339	image version is older than the current firmware image version or bad image\r
	340	checksum. Sensitive operations such as those wiping the entire firmware image\r
	341	and render the device to be non-functional should be encoded in the image\r
	342	itself rather than passed with the VendorCode. AbortReason enables vendor to\r
	343	have the option to provide a more detailed description of the abort reason to\r
	344	the caller.\r
	345	\r
	346	@param[in] Image Points to the new firmware image.\r
	347	@param[in] ImageSize Size, in bytes, of the new firmware image.\r
	348	@param[in] VendorCode This enables vendor to implement vendor-specific\r
	349	firmware image update policy. NULL indicates\r
	350	the caller did not specify the policy or use the\r
	351	default policy.\r
	352	@param[in] Progress A function used to report the progress of\r
	353	updating the firmware device with the new\r
	354	firmware image.\r
	355	@param[in] CapsuleFwVersion The version of the new firmware image from the\r
	356	update capsule that provided the new firmware\r
	357	image.\r
	358	@param[out] AbortReason A pointer to a pointer to a Null-terminated\r
	359	Unicode string providing more details on an\r
	360	aborted operation. The buffer is allocated by\r
	361	this function with\r
	362	EFI_BOOT_SERVICES.AllocatePool(). It is the\r
	363	caller's responsibility to free this buffer with\r
	364	EFI_BOOT_SERVICES.FreePool().\r
	365	\r
	366	@retval EFI_SUCCESS The firmware device was successfully updated\r
	367	with the new firmware image.\r
	368	@retval EFI_ABORTED The operation is aborted. Additional details\r
	369	are provided in AbortReason.\r
	370	@retval EFI_INVALID_PARAMETER The Image was NULL.\r
	371	@retval EFI_UNSUPPORTED The operation is not supported.\r
	372	\r
	373	**/\r
	374	EFI_STATUS\r
	375	EFIAPI\r
	376	FmpDeviceSetImage (\r
	377	IN CONST VOID *Image,\r
	378	IN UINTN ImageSize,\r
	379	IN CONST VOID *VendorCode, OPTIONAL\r
	380	IN EFI_FIRMWARE_MANAGEMENT_UPDATE_IMAGE_PROGRESS Progress, OPTIONAL\r
381	IN UINT32 CapsuleFwVersion,\r
382	OUT CHAR16 **AbortReason\r
383	)\r
384	{\r
385	return EFI_UNSUPPORTED;\r
386	}\r
387	\r
388	/**\r
389	Lock the firmware device that contains a firmware image. Once a firmware\r
390	device is locked, any attempts to modify the firmware image contents in the\r
391	firmware device must fail.\r
392	\r
393	@note It is recommended that all firmware devices support a lock method to\r
394	prevent modifications to a stored firmware image.\r
395	\r
396	@note A firmware device lock mechanism is typically only cleared by a full\r
397	system reset (not just sleep state/low power mode).\r
398	\r
399	@retval EFI_SUCCESS The firmware device was locked.\r
400	@retval EFI_UNSUPPORTED The firmware device does not support locking\r
401	\r
402	**/\r
403	EFI_STATUS\r
404	EFIAPI\r
405	FmpDeviceLock (\r
406	VOID\r
407	)\r
408	{\r
409	return EFI_UNSUPPORTED;\r
410	}\r