[mirror_edk2.git] / FmpDevicePkg / FmpDxe / VariableSupport.h

/** @file\r
  UEFI variable support functions for Firmware Management Protocol based\r
  firmware updates.\r
\r
  Copyright (c) 2016, Microsoft Corporation. All rights reserved.<BR>\r
  Copyright (c) 2018 - 2019, Intel Corporation. All rights reserved.<BR>\r
\r
  SPDX-License-Identifier: BSD-2-Clause-Patent\r
\r
**/\r
\r
#ifndef __VARIABLE_SUPPORT_H__\r
#define __VARIABLE_SUPPORT_H__\r
\r
///\r
/// Default values for FMP Controller State information\r
///\r
#define DEFAULT_VERSION                 0x1\r
#define DEFAULT_LOWESTSUPPORTEDVERSION  0x0\r
#define DEFAULT_LASTATTEMPTSTATUS       0x0\r
#define DEFAULT_LASTATTEMPTVERSION      0x0\r
\r
///\r
/// Base UEFI Variable names for FMP Controller State information stored in\r
/// separate variables.\r
///\r
#define VARNAME_VERSION                 L"FmpVersion"\r
#define VARNAME_LSV                     L"FmpLsv"\r
#define VARNAME_LASTATTEMPTSTATUS       L"LastAttemptStatus"\r
#define VARNAME_LASTATTEMPTVERSION      L"LastAttemptVersion"\r
\r
///\r
/// Base UEFI Variable name for FMP Controller State information stored in a\r
/// merged UEFI Variable.  If the separate UEFI Variables above are detected,\r
/// then they are merged into a single variable and the separate variables are\r
/// deleted.\r
///\r
#define VARNAME_FMPSTATE                L"FmpState"\r
\r
///\r
/// FMP Controller State structure that is used to store the state of\r
/// a controller in one combined UEFI Variable.\r
///\r
typedef struct {\r
  BOOLEAN  VersionValid;\r
  BOOLEAN  LsvValid;\r
  BOOLEAN  LastAttemptStatusValid;\r
  BOOLEAN  LastAttemptVersionValid;\r
  UINT32   Version;\r
  UINT32   Lsv;\r
  UINT32   LastAttemptStatus;\r
  UINT32   LastAttemptVersion;\r
} FMP_CONTROLLER_STATE;\r
\r
/**\r
  Generate the names of the UEFI Variables used to store state information for\r
  a managed controller.  The UEFI Variables names are a combination of a base\r
  name and an optional hardware instance value as a 16 character hex value.  If\r
  the hardware instance value is 0, then the 16 character hex value is not\r
  included.  These storage for the UEFI Variable names are allocated using the\r
  UEFI Boot Service AllocatePool() and the pointers are stored in the Private.\r
  The following are examples of variable names produces for hardware instance\r
  value 0 and value 0x1234567812345678.\r
\r
    FmpVersion\r
    FmpLsv\r
    LastAttemptStatus\r
    LastAttemptVersion\r
    FmpDxe\r
\r
    FmpVersion1234567812345678\r
    FmpLsv1234567812345678\r
    LastAttemptStatus1234567812345678\r
    LastAttemptVersion1234567812345678\r
    FmpDxe1234567812345678\r
\r
  @param[in,out] Private  Private context structure for the managed controller.\r
**/\r
VOID\r
GenerateFmpVariableNames (\r
  IN OUT FIRMWARE_MANAGEMENT_PRIVATE_DATA  *Private\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.  The value is read from a UEFI\r
  variable.  If the UEFI variables does not exist, then a default version value\r
  is returned.\r
\r
  UEFI Variable accessed: GUID = gEfiCallerIdGuid, Name = L"FmpDxe"\r
\r
  @param[in] Private  Private context structure for the managed controller.\r
\r
  @return  The version of the firmware image in the firmware device.\r
**/\r
UINT32\r
GetVersionFromVariable (\r
  IN FIRMWARE_MANAGEMENT_PRIVATE_DATA  *Private\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.  The value is read from a UEFI\r
  variable.  If the UEFI variables does not exist, then a default lowest\r
  supported version value is returned.\r
\r
  UEFI Variable accessed: GUID = gEfiCallerIdGuid, Name = L"FmpDxe"\r
\r
  @param[in] Private  Private context structure for the managed controller.\r
\r
  @return  The lowest supported version of the firmware image in the firmware\r
           device.\r
**/\r
UINT32\r
GetLowestSupportedVersionFromVariable (\r
  IN FIRMWARE_MANAGEMENT_PRIVATE_DATA  *Private\r
  );\r
\r
/**\r
  Returns the value used to fill in the LastAttemptStatus field of the\r
  EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the GetImageInfo()\r
  service of the Firmware Management Protocol.  The value is read from a UEFI\r
  variable.  If the UEFI variables does not exist, then a default last attempt\r
  status value is returned.\r
\r
  UEFI Variable accessed: GUID = gEfiCallerIdGuid, Name = L"FmpDxe"\r
\r
  @param[in] Private  Private context structure for the managed controller.\r
\r
  @return  The last attempt status value for the most recent capsule update.\r
**/\r
UINT32\r
GetLastAttemptStatusFromVariable (\r
  IN FIRMWARE_MANAGEMENT_PRIVATE_DATA  *Private\r
  );\r
\r
/**\r
  Returns the value used to fill in the LastAttemptVersion field of the\r
  EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the GetImageInfo()\r
  service of the Firmware Management Protocol.  The value is read from a UEFI\r
  variable.  If the UEFI variables does not exist, then a default last attempt\r
  version value is returned.\r
\r
  UEFI Variable accessed: GUID = gEfiCallerIdGuid, Name = L"FmpDxe"\r
\r
  @param[in] Private  Private context structure for the managed controller.\r
\r
  @return  The last attempt version value for the most recent capsule update.\r
**/\r
UINT32\r
GetLastAttemptVersionFromVariable (\r
  IN FIRMWARE_MANAGEMENT_PRIVATE_DATA  *Private\r
  );\r
\r
/**\r
  Saves the version current of the firmware image in the firmware device to a\r
  UEFI variable.\r
\r
  UEFI Variable accessed: GUID = gEfiCallerIdGuid, Name = L"FmpDxe"\r
\r
  @param[in] Private  Private context structure for the managed controller.\r
  @param[in] Version  The version of the firmware image in the firmware device.\r
**/\r
VOID\r
SetVersionInVariable (\r
  IN FIRMWARE_MANAGEMENT_PRIVATE_DATA  *Private,\r
  IN UINT32                            Version\r
  );\r
\r
/**\r
  Saves the lowest supported version current of the firmware image in the\r
  firmware device to a UEFI variable.\r
\r
  UEFI Variable accessed: GUID = gEfiCallerIdGuid, Name = L"FmpDxe"\r
\r
  @param[in] Private                 Private context structure for the managed\r
                                     controller.\r
  @param[in] LowestSupportedVersion  The lowest supported version of the\r
                                     firmware image in the firmware device.\r
**/\r
VOID\r
SetLowestSupportedVersionInVariable (\r
  IN FIRMWARE_MANAGEMENT_PRIVATE_DATA  *Private,\r
  IN UINT32                            LowestSupportedVersion\r
  );\r
\r
/**\r
  Saves the last attempt status value of the most recent FMP capsule update to a\r
  UEFI variable.\r
\r
  UEFI Variable accessed: GUID = gEfiCallerIdGuid, Name = L"FmpDxe"\r
\r
  @param[in] Private            Private context structure for the managed\r
                                controller.\r
  @param[in] LastAttemptStatus  The last attempt status of the most recent FMP\r
                                capsule update.\r
**/\r
VOID\r
SetLastAttemptStatusInVariable (\r
  IN FIRMWARE_MANAGEMENT_PRIVATE_DATA  *Private,\r
  IN UINT32                            LastAttemptStatus\r
  );\r
\r
/**\r
  Saves the last attempt version value of the most recent FMP capsule update to\r
  a UEFI variable.\r
\r
  UEFI Variable accessed: GUID = gEfiCallerIdGuid, Name = L"FmpDxe"\r
\r
  @param[in] Private             Private context structure for the managed\r
                                 controller.\r
  @param[in] LastAttemptVersion  The last attempt version value of the most\r
                                 recent FMP capsule update.\r
**/\r
VOID\r
SetLastAttemptVersionInVariable (\r
  IN FIRMWARE_MANAGEMENT_PRIVATE_DATA  *Private,\r
  IN UINT32                            LastAttemptVersion\r
  );\r
\r
/**\r
  Locks all the UEFI Variables that use gEfiCallerIdGuid of the currently\r
  executing module.\r
\r
  @param[in] Private  Private context structure for the managed controller.\r
\r
  @retval  EFI_SUCCESS      All UEFI variables are locked.\r
  @retval  EFI_UNSUPPORTED  Variable Lock Protocol not found.\r
  @retval  Other            One of the UEFI variables could not be locked.\r
**/\r
EFI_STATUS\r
LockAllFmpVariables (\r
  IN FIRMWARE_MANAGEMENT_PRIVATE_DATA  *Private\r
  );\r
\r
#endif\r
Commit	Line	Data
	1	/** @file\r
	2	UEFI variable support functions for Firmware Management Protocol based\r
	3	firmware updates.\r
	4	\r
	5	Copyright (c) 2016, Microsoft Corporation. All rights reserved.<BR>\r
	6	Copyright (c) 2018 - 2019, Intel Corporation. All rights reserved.<BR>\r
	7	\r
	8	SPDX-License-Identifier: BSD-2-Clause-Patent\r
	9	\r
	10	**/\r
	11	\r
	12	#ifndef __VARIABLE_SUPPORT_H__\r
	13	#define __VARIABLE_SUPPORT_H__\r
	14	\r
	15	///\r
	16	/// Default values for FMP Controller State information\r
	17	///\r
	18	#define DEFAULT_VERSION 0x1\r
	19	#define DEFAULT_LOWESTSUPPORTEDVERSION 0x0\r
	20	#define DEFAULT_LASTATTEMPTSTATUS 0x0\r
	21	#define DEFAULT_LASTATTEMPTVERSION 0x0\r
	22	\r
	23	///\r
	24	/// Base UEFI Variable names for FMP Controller State information stored in\r
	25	/// separate variables.\r
	26	///\r
	27	#define VARNAME_VERSION L"FmpVersion"\r
	28	#define VARNAME_LSV L"FmpLsv"\r
	29	#define VARNAME_LASTATTEMPTSTATUS L"LastAttemptStatus"\r
	30	#define VARNAME_LASTATTEMPTVERSION L"LastAttemptVersion"\r
	31	\r
	32	///\r
	33	/// Base UEFI Variable name for FMP Controller State information stored in a\r
	34	/// merged UEFI Variable. If the separate UEFI Variables above are detected,\r
	35	/// then they are merged into a single variable and the separate variables are\r
	36	/// deleted.\r
	37	///\r
	38	#define VARNAME_FMPSTATE L"FmpState"\r
	39	\r
	40	///\r
	41	/// FMP Controller State structure that is used to store the state of\r
	42	/// a controller in one combined UEFI Variable.\r
	43	///\r
	44	typedef struct {\r
	45	BOOLEAN VersionValid;\r
	46	BOOLEAN LsvValid;\r
	47	BOOLEAN LastAttemptStatusValid;\r
	48	BOOLEAN LastAttemptVersionValid;\r
	49	UINT32 Version;\r
	50	UINT32 Lsv;\r
	51	UINT32 LastAttemptStatus;\r
	52	UINT32 LastAttemptVersion;\r
	53	} FMP_CONTROLLER_STATE;\r
	54	\r
	55	/**\r
	56	Generate the names of the UEFI Variables used to store state information for\r
	57	a managed controller. The UEFI Variables names are a combination of a base\r
	58	name and an optional hardware instance value as a 16 character hex value. If\r
	59	the hardware instance value is 0, then the 16 character hex value is not\r
	60	included. These storage for the UEFI Variable names are allocated using the\r
	61	UEFI Boot Service AllocatePool() and the pointers are stored in the Private.\r
	62	The following are examples of variable names produces for hardware instance\r
	63	value 0 and value 0x1234567812345678.\r
	64	\r
	65	FmpVersion\r
	66	FmpLsv\r
	67	LastAttemptStatus\r
	68	LastAttemptVersion\r
	69	FmpDxe\r
	70	\r
	71	FmpVersion1234567812345678\r
	72	FmpLsv1234567812345678\r
	73	LastAttemptStatus1234567812345678\r
	74	LastAttemptVersion1234567812345678\r
	75	FmpDxe1234567812345678\r
	76	\r
	77	@param[in,out] Private Private context structure for the managed controller.\r
	78	**/\r
	79	VOID\r
	80	GenerateFmpVariableNames (\r
	81	IN OUT FIRMWARE_MANAGEMENT_PRIVATE_DATA *Private\r
	82	);\r
	83	\r
	84	/**\r
	85	Returns the value used to fill in the Version field of the\r
	86	EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the GetImageInfo()\r
	87	service of the Firmware Management Protocol. The value is read from a UEFI\r
	88	variable. If the UEFI variables does not exist, then a default version value\r
	89	is returned.\r
	90	\r
	91	UEFI Variable accessed: GUID = gEfiCallerIdGuid, Name = L"FmpDxe"\r
	92	\r
	93	@param[in] Private Private context structure for the managed controller.\r
	94	\r
	95	@return The version of the firmware image in the firmware device.\r
	96	**/\r
	97	UINT32\r
	98	GetVersionFromVariable (\r
	99	IN FIRMWARE_MANAGEMENT_PRIVATE_DATA *Private\r
	100	);\r
	101	\r
	102	/**\r
	103	Returns the value used to fill in the LowestSupportedVersion field of the\r
	104	EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the GetImageInfo()\r
	105	service of the Firmware Management Protocol. The value is read from a UEFI\r
	106	variable. If the UEFI variables does not exist, then a default lowest\r
	107	supported version value is returned.\r
	108	\r
	109	UEFI Variable accessed: GUID = gEfiCallerIdGuid, Name = L"FmpDxe"\r
	110	\r
	111	@param[in] Private Private context structure for the managed controller.\r
	112	\r
	113	@return The lowest supported version of the firmware image in the firmware\r
	114	device.\r
	115	**/\r
	116	UINT32\r
	117	GetLowestSupportedVersionFromVariable (\r
	118	IN FIRMWARE_MANAGEMENT_PRIVATE_DATA *Private\r
	119	);\r
	120	\r
	121	/**\r
	122	Returns the value used to fill in the LastAttemptStatus field of the\r
	123	EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the GetImageInfo()\r
	124	service of the Firmware Management Protocol. The value is read from a UEFI\r
	125	variable. If the UEFI variables does not exist, then a default last attempt\r
	126	status value is returned.\r
	127	\r
	128	UEFI Variable accessed: GUID = gEfiCallerIdGuid, Name = L"FmpDxe"\r
	129	\r
	130	@param[in] Private Private context structure for the managed controller.\r
	131	\r
	132	@return The last attempt status value for the most recent capsule update.\r
	133	**/\r
	134	UINT32\r
	135	GetLastAttemptStatusFromVariable (\r
	136	IN FIRMWARE_MANAGEMENT_PRIVATE_DATA *Private\r
	137	);\r
	138	\r
	139	/**\r
	140	Returns the value used to fill in the LastAttemptVersion field of the\r
	141	EFI_FIRMWARE_IMAGE_DESCRIPTOR structure that is returned by the GetImageInfo()\r
	142	service of the Firmware Management Protocol. The value is read from a UEFI\r
	143	variable. If the UEFI variables does not exist, then a default last attempt\r
	144	version value is returned.\r
	145	\r
	146	UEFI Variable accessed: GUID = gEfiCallerIdGuid, Name = L"FmpDxe"\r
	147	\r
	148	@param[in] Private Private context structure for the managed controller.\r
	149	\r
	150	@return The last attempt version value for the most recent capsule update.\r
	151	**/\r
	152	UINT32\r
	153	GetLastAttemptVersionFromVariable (\r
	154	IN FIRMWARE_MANAGEMENT_PRIVATE_DATA *Private\r
	155	);\r
	156	\r
	157	/**\r
	158	Saves the version current of the firmware image in the firmware device to a\r
	159	UEFI variable.\r
	160	\r
	161	UEFI Variable accessed: GUID = gEfiCallerIdGuid, Name = L"FmpDxe"\r
	162	\r
	163	@param[in] Private Private context structure for the managed controller.\r
	164	@param[in] Version The version of the firmware image in the firmware device.\r
	165	**/\r
	166	VOID\r
	167	SetVersionInVariable (\r
	168	IN FIRMWARE_MANAGEMENT_PRIVATE_DATA *Private,\r
	169	IN UINT32 Version\r
	170	);\r
	171	\r
	172	/**\r
	173	Saves the lowest supported version current of the firmware image in the\r
	174	firmware device to a UEFI variable.\r
	175	\r
	176	UEFI Variable accessed: GUID = gEfiCallerIdGuid, Name = L"FmpDxe"\r
	177	\r
	178	@param[in] Private Private context structure for the managed\r
	179	controller.\r
	180	@param[in] LowestSupportedVersion The lowest supported version of the\r
	181	firmware image in the firmware device.\r
	182	**/\r
	183	VOID\r
	184	SetLowestSupportedVersionInVariable (\r
	185	IN FIRMWARE_MANAGEMENT_PRIVATE_DATA *Private,\r
	186	IN UINT32 LowestSupportedVersion\r
	187	);\r
	188	\r
	189	/**\r
	190	Saves the last attempt status value of the most recent FMP capsule update to a\r
	191	UEFI variable.\r
	192	\r
	193	UEFI Variable accessed: GUID = gEfiCallerIdGuid, Name = L"FmpDxe"\r
	194	\r
	195	@param[in] Private Private context structure for the managed\r
	196	controller.\r
	197	@param[in] LastAttemptStatus The last attempt status of the most recent FMP\r
	198	capsule update.\r
	199	**/\r
	200	VOID\r
	201	SetLastAttemptStatusInVariable (\r
	202	IN FIRMWARE_MANAGEMENT_PRIVATE_DATA *Private,\r
	203	IN UINT32 LastAttemptStatus\r
	204	);\r
	205	\r
	206	/**\r
	207	Saves the last attempt version value of the most recent FMP capsule update to\r
	208	a UEFI variable.\r
	209	\r
	210	UEFI Variable accessed: GUID = gEfiCallerIdGuid, Name = L"FmpDxe"\r
	211	\r
	212	@param[in] Private Private context structure for the managed\r
	213	controller.\r
	214	@param[in] LastAttemptVersion The last attempt version value of the most\r
	215	recent FMP capsule update.\r
	216	**/\r
	217	VOID\r
	218	SetLastAttemptVersionInVariable (\r
	219	IN FIRMWARE_MANAGEMENT_PRIVATE_DATA *Private,\r
	220	IN UINT32 LastAttemptVersion\r
	221	);\r
	222	\r
	223	/**\r
	224	Locks all the UEFI Variables that use gEfiCallerIdGuid of the currently\r
	225	executing module.\r
	226	\r
	227	@param[in] Private Private context structure for the managed controller.\r
	228	\r
	229	@retval EFI_SUCCESS All UEFI variables are locked.\r
	230	@retval EFI_UNSUPPORTED Variable Lock Protocol not found.\r
	231	@retval Other One of the UEFI variables could not be locked.\r
	232	**/\r
	233	EFI_STATUS\r
	234	LockAllFmpVariables (\r
	235	IN FIRMWARE_MANAGEMENT_PRIVATE_DATA *Private\r
	236	);\r
	237	\r
	238	#endif\r