[mirror_edk2.git] / IntelFrameworkPkg / Include / Protocol / FrameworkFormCallback.h

/** @file\r
  The EFI_FORM_CALLBACK_PROTOCOL is the defined interface for access to custom\r
  NV storage devices and for communication of user selections in a more\r
  interactive environment.  This protocol should be published by hardware\r
  specific drivers that want to export access to custom hardware storage or\r
  publish IFR that need to call back the original driver.\r
\r
Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>\r
This program and the accompanying materials are licensed and made available under\r
the terms and conditions of the BSD License that accompanies this distribution.\r
The full text of the license may be found at\r
http://opensource.org/licenses/bsd-license.php.\r
\r
THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
\r
  @par Revision Reference:\r
  This protocol is defined in HII spec 0.92.\r
\r
**/\r
\r
#ifndef __FRAMEWORK_FORM_CALLBACK_H__\r
#define __FRAMEWORK_FORM_CALLBACK_H__\r
\r
#include <Protocol/FrameworkHii.h>\r
#include <Protocol/FrameworkFormBrowser.h>\r
\r
#define EFI_FORM_CALLBACK_PROTOCOL_GUID \\r
  { \\r
    0xf3e4543d, 0xcf35, 0x6cef, {0x35, 0xc4, 0x4f, 0xe6, 0x34, 0x4d, 0xfc, 0x54 } \\r
  }\r
\r
//\r
// Forward reference for pure ANSI compatability\r
//\r
typedef struct _EFI_FORM_CALLBACK_PROTOCOL  EFI_FORM_CALLBACK_PROTOCOL;\r
\r
///\r
///  Inconsistent with specification here:\r
///  RESET_REQUIRED, EXIT_REQUIRED, SAVE_REQUIRED, NV_CHANGED and NV_NOT_CHANGED are not\r
///  defined in HII specification. These Flags of EFI_IFR_DATA_ENTRY should be defined\r
///  to describe the standard behavior of the browser after the callback.\r
///\r
/// If this flag is set, the browser will exit and reset after processing callback results.\r
///\r
#define RESET_REQUIRED  1\r
///\r
/// If this flag is set, the browser will exit after processing callback results.\r
///\r
#define EXIT_REQUIRED   2\r
///\r
/// If this flag is set, the browser will save the NV data after processing callback results.\r
///\r
#define SAVE_REQUIRED   4\r
///\r
/// If this flag is set, the browser will turn the NV flag on after processing callback results.\r
///\r
#define NV_CHANGED      8\r
///\r
/// If this flag is set, the browser will turn the NV flag off after processing callback results.\r
///\r
#define NV_NOT_CHANGED  16\r
\r
#pragma pack(1)\r
typedef struct {\r
  UINT8   OpCode;           ///< Likely a string, numeric, or one-of\r
  UINT8   Length;           ///< Length of the EFI_IFR_DATA_ENTRY packet.\r
  UINT16  Flags;            ///< Flags settings to determine what behavior is desired from the browser after the callback.\r
  VOID    *Data;            ///< The data in the form based on the op-code type. This is not a pointer to the data; the data follows immediately.\r
  ///\r
  /// If the OpCode is a OneOf or Numeric type - Data is a UINT16 value.\r
  /// If the OpCode is a String type - Data is a CHAR16[x] type.\r
  /// If the OpCode is a Checkbox type - Data is a UINT8 value.\r
  /// If the OpCode is a NV Access type - Data is a EFI_IFR_NV_DATA structure.\r
  ///\r
} EFI_IFR_DATA_ENTRY;\r
\r
typedef struct {\r
  VOID                *NvRamMap;  ///< If the flag of the op-code specified retrieval of a copy of the NVRAM map.\r
  //\r
  // this is a pointer to a buffer copy\r
  //\r
  UINT32              EntryCount; ///< Number of EFI_IFR_DATA_ENTRY entries.\r
  //\r
  // EFI_IFR_DATA_ENTRY  Data[1];    // The in-line Data entries.\r
  //\r
} EFI_IFR_DATA_ARRAY;\r
\r
\r
typedef union {\r
  EFI_IFR_DATA_ARRAY  DataArray;  ///< Primarily used by those that call back to their drivers and use HII as a repository.\r
  EFI_IFR_PACKET      DataPacket; ///< Primarily used by those that do not use HII as a repository.\r
  CHAR16              String[1];  ///< If returning an error - fill the string with null-terminated contents.\r
} EFI_HII_CALLBACK_PACKET;\r
\r
typedef struct {\r
  FRAMEWORK_EFI_IFR_OP_HEADER Header;\r
  UINT16            QuestionId;   ///< Offset into the map.\r
  UINT8             StorageWidth; ///< Width of the value.\r
  //\r
  // CHAR8             Data[1];      // The Data itself\r
  //\r
} EFI_IFR_NV_DATA;\r
\r
#pragma pack()\r
//\r
// The following types are currently defined:\r
//\r
/**\r
  Returns the value of a variable.\r
\r
  @param  This                  A pointer to the EFI_FORM_CALLBACK_PROTOCOL instance.\r
  @param  VariableName          A NULL-terminated Unicode string that is the\r
                                name of the vendor's variable.\r
  @param  VendorGuid            A unique identifier for the vendor.\r
  @param  Attributes            If not NULL, a pointer to the memory location to\r
                                return the attribute's bit-mask for the variable.\r
  @param  DataSize              The size in bytes of the Buffer. A size of zero causes\r
                                the variable to be deleted.\r
  @param  Buffer                The buffer to return the contents of the variable.\r
\r
  @retval EFI_SUCCESS           The function completed successfully.\r
  @retval EFI_NOT_FOUND         The variable was not found.\r
  @retval EFI_BUFFER_TOO_SMALL  The DataSize is too small for the result.\r
                                DataSize has been updated with the size needed to complete the request.\r
  @retval EFI_INVALID_PARAMETER One of the parameters has an invalid value.\r
  @retval EFI_DEVICE_ERROR      The variable could not be saved due to a hardware failure.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_NV_READ)(\r
  IN     EFI_FORM_CALLBACK_PROTOCOL    *This,\r
  IN     CHAR16                        *VariableName,\r
  IN     EFI_GUID                      *VendorGuid,\r
  OUT    UINT32                        *Attributes OPTIONAL,\r
  IN OUT UINTN                         *DataSize,\r
  OUT    VOID                          *Buffer\r
  );\r
\r
/**\r
  Sets the value of a variable.\r
\r
  @param  This                  A pointer to the EFI_FORM_CALLBACK_PROTOCOL instance.\r
  @param  VariableName          A NULL-terminated Unicode string that is the\r
                                name of the vendor's variable. Each VariableName\r
                                is unique for each VendorGuid.\r
  @param  VendorGuid            A unique identifier for the vendor.\r
  @param  Attributes            Attributes bit-mask to set for the variable.\r
                                Inconsistent with specification here:\r
                                Attributes data type has been changed from\r
                                UINT32 * to UINT32, because the input parameter is\r
                                not necessary to use a pointer date type.\r
  @param  DataSize              The size in bytes of the Buffer. A size of zero causes\r
                                the variable to be deleted.\r
  @param  Buffer                The buffer containing the contents of the variable.\r
  @param  ResetRequired         Returns a value from the driver that abstracts this\r
                                information and will enable a system to know if a\r
                                system reset is required to achieve the configuration\r
                                changes being enabled through this function.\r
\r
  @retval EFI_SUCCESS           The firmware has successfully stored the variable and\r
                                its data as defined by the Attributes.\r
  @retval EFI_OUT_OF_RESOURCES  Not enough storage is available to hold\r
                                the variable and its data.\r
  @retval EFI_INVALID_PARAMETER An invalid combination of Attributes bits\r
                                was supplied, or the DataSize exceeds the maximum allowed.\r
  @retval EFI_DEVICE_ERROR      The variable could not be saved due to a hardware failure.\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_NV_WRITE)(\r
  IN     EFI_FORM_CALLBACK_PROTOCOL    *This,\r
  IN     CHAR16                        *VariableName,\r
  IN     EFI_GUID                      *VendorGuid,\r
  IN     UINT32                        Attributes,\r
  IN     UINTN                         DataSize,\r
  IN     VOID                          *Buffer,\r
  OUT    BOOLEAN                       *ResetRequired\r
  );\r
\r
/**\r
  This function is called to provide results data to the driver.\r
\r
  @param  This                  A pointer to the EFI_FORM_CALLBACK_PROTOCOL instance.\r
  @param  KeyValue              A unique value which is sent to the original exporting\r
                                driver so that it can identify the type of data\r
                                to expect. The format of the data tends to vary based\r
                                on the opcode that generated the callback.\r
  @param  Data                  A pointer to the data being sent to the original exporting driver.\r
  @param  Packet                A pointer to a packet of information that a driver passes\r
                                back to the browser.\r
\r
  @return Status Code\r
\r
**/\r
typedef\r
EFI_STATUS\r
(EFIAPI *EFI_FORM_CALLBACK)(\r
  IN     EFI_FORM_CALLBACK_PROTOCOL    *This,\r
  IN     UINT16                        KeyValue,\r
  IN     EFI_IFR_DATA_ARRAY  *Data,\r
  OUT    EFI_HII_CALLBACK_PACKET       **Packet\r
  );\r
\r
/**\r
  The EFI_FORM_CALLBACK_PROTOCOL is the defined interface for access to\r
  custom NVS devices as well as communication of user selections in a more\r
  interactive environment. This protocol should be published by platform-specific\r
  drivers that want to export access to custom hardware storage or publish IFR\r
  that has a requirement to call back the original driver.\r
**/\r
struct _EFI_FORM_CALLBACK_PROTOCOL {\r
  EFI_NV_READ       NvRead;     ///< The read operation to access the NV data serviced by a hardware-specific driver.\r
  EFI_NV_WRITE      NvWrite;    ///< The write operation to access the NV data serviced by a hardware-specific driver.\r
  EFI_FORM_CALLBACK Callback;   ///< The function that is called from the configuration browser to communicate key value pairs.\r
};\r
\r
extern EFI_GUID gEfiFormCallbackProtocolGuid;\r
\r
#endif\r
Commit	Line	Data
92627141	1	/** @file\r
92627141	2	The EFI_FORM_CALLBACK_PROTOCOL is the defined interface for access to custom\r
5259c97d	3	NV storage devices and for communication of user selections in a more\r
92627141	4	interactive environment. This protocol should be published by hardware\r
5259c97d	5	specific drivers that want to export access to custom hardware storage or\r
5259c97d	6	publish IFR that need to call back the original driver.\r
92627141	7	\r
1c2f052d LG	8	Copyright (c) 2006 - 2018, Intel Corporation. All rights reserved.<BR>\r
	9	This program and the accompanying materials are licensed and made available under\r
	10	the terms and conditions of the BSD License that accompanies this distribution.\r
f22f941e	11	The full text of the license may be found at\r
1c2f052d LG	12	http://opensource.org/licenses/bsd-license.php.\r
	13	\r
	14	THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,\r
f22f941e	15	WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.\r
92627141	16	\r
92627141	17	@par Revision Reference:\r
	18	This protocol is defined in HII spec 0.92.\r
	19	\r
	20	**/\r
	21	\r
108854b2 LG	22	#ifndef __FRAMEWORK_FORM_CALLBACK_H__\r
108854b2 LG	23	#define __FRAMEWORK_FORM_CALLBACK_H__\r
92627141	24	\r
8e5b17b2	25	#include <Protocol/FrameworkHii.h>\r
8e5b17b2	26	#include <Protocol/FrameworkFormBrowser.h>\r
92627141	27	\r
	28	#define EFI_FORM_CALLBACK_PROTOCOL_GUID \\r
	29	{ \\r
	30	0xf3e4543d, 0xcf35, 0x6cef, {0x35, 0xc4, 0x4f, 0xe6, 0x34, 0x4d, 0xfc, 0x54 } \\r
	31	}\r
	32	\r
	33	//\r
	34	// Forward reference for pure ANSI compatability\r
	35	//\r
	36	typedef struct _EFI_FORM_CALLBACK_PROTOCOL EFI_FORM_CALLBACK_PROTOCOL;\r
	37	\r
3f17e6d7	38	///\r
1c2f052d LG	39	/// Inconsistent with specification here:\r
1c2f052d LG	40	/// RESET_REQUIRED, EXIT_REQUIRED, SAVE_REQUIRED, NV_CHANGED and NV_NOT_CHANGED are not\r
33d228aa	41	/// defined in HII specification. These Flags of EFI_IFR_DATA_ENTRY should be defined\r
33d228aa	42	/// to describe the standard behavior of the browser after the callback.\r
3f17e6d7	43	///\r
f22f941e	44	/// If this flag is set, the browser will exit and reset after processing callback results.\r
3f17e6d7	45	///\r
1c2f052d	46	#define RESET_REQUIRED 1\r
3f17e6d7	47	///\r
f22f941e	48	/// If this flag is set, the browser will exit after processing callback results.\r
3f17e6d7 LG	49	///\r
	50	#define EXIT_REQUIRED 2\r
	51	///\r
f22f941e	52	/// If this flag is set, the browser will save the NV data after processing callback results.\r
3f17e6d7 LG	53	///\r
	54	#define SAVE_REQUIRED 4\r
	55	///\r
f22f941e	56	/// If this flag is set, the browser will turn the NV flag on after processing callback results.\r
3f17e6d7 LG	57	///\r
	58	#define NV_CHANGED 8\r
	59	///\r
f22f941e	60	/// If this flag is set, the browser will turn the NV flag off after processing callback results.\r
3f17e6d7 LG	61	///\r
	62	#define NV_NOT_CHANGED 16\r
	63	\r
92627141	64	#pragma pack(1)\r
92627141	65	typedef struct {\r
aa4a31e3	66	UINT8 OpCode; ///< Likely a string, numeric, or one-of\r
f22f941e	67	UINT8 Length; ///< Length of the EFI_IFR_DATA_ENTRY packet.\r
	68	UINT16 Flags; ///< Flags settings to determine what behavior is desired from the browser after the callback.\r
	69	VOID *Data; ///< The data in the form based on the op-code type. This is not a pointer to the data; the data follows immediately.\r
aa4a31e3	70	///\r
f22f941e	71	/// If the OpCode is a OneOf or Numeric type - Data is a UINT16 value.\r
	72	/// If the OpCode is a String type - Data is a CHAR16[x] type.\r
	73	/// If the OpCode is a Checkbox type - Data is a UINT8 value.\r
	74	/// If the OpCode is a NV Access type - Data is a EFI_IFR_NV_DATA structure.\r
aa4a31e3	75	///\r
108854b2	76	} EFI_IFR_DATA_ENTRY;\r
92627141	77	\r
92627141	78	typedef struct {\r
f22f941e	79	VOID *NvRamMap; ///< If the flag of the op-code specified retrieval of a copy of the NVRAM map.\r
aa4a31e3	80	//\r
92627141	81	// this is a pointer to a buffer copy\r
92627141	82	//\r
f22f941e	83	UINT32 EntryCount; ///< Number of EFI_IFR_DATA_ENTRY entries.\r
92627141	84	//\r
108854b2	85	// EFI_IFR_DATA_ENTRY Data[1]; // The in-line Data entries.\r
92627141	86	//\r
108854b2	87	} EFI_IFR_DATA_ARRAY;\r
92627141	88	\r
	89	\r
	90	typedef union {\r
f22f941e	91	EFI_IFR_DATA_ARRAY DataArray; ///< Primarily used by those that call back to their drivers and use HII as a repository.\r
	92	EFI_IFR_PACKET DataPacket; ///< Primarily used by those that do not use HII as a repository.\r
	93	CHAR16 String[1]; ///< If returning an error - fill the string with null-terminated contents.\r
2cec3ea5	94	} EFI_HII_CALLBACK_PACKET;\r
92627141	95	\r
92627141	96	typedef struct {\r
dc7b4a5c	97	FRAMEWORK_EFI_IFR_OP_HEADER Header;\r
f22f941e	98	UINT16 QuestionId; ///< Offset into the map.\r
f22f941e	99	UINT8 StorageWidth; ///< Width of the value.\r
92627141	100	//\r
	101	// CHAR8 Data[1]; // The Data itself\r
	102	//\r
108854b2	103	} EFI_IFR_NV_DATA;\r
92627141	104	\r
	105	#pragma pack()\r
	106	//\r
	107	// The following types are currently defined:\r
	108	//\r
	109	/**\r
	110	Returns the value of a variable.\r
	111	\r
	112	@param This A pointer to the EFI_FORM_CALLBACK_PROTOCOL instance.\r
	113	@param VariableName A NULL-terminated Unicode string that is the\r
	114	name of the vendor's variable.\r
	115	@param VendorGuid A unique identifier for the vendor.\r
	116	@param Attributes If not NULL, a pointer to the memory location to\r
	117	return the attribute's bit-mask for the variable.\r
	118	@param DataSize The size in bytes of the Buffer. A size of zero causes\r
	119	the variable to be deleted.\r
	120	@param Buffer The buffer to return the contents of the variable.\r
	121	\r
	122	@retval EFI_SUCCESS The function completed successfully.\r
	123	@retval EFI_NOT_FOUND The variable was not found.\r
	124	@retval EFI_BUFFER_TOO_SMALL The DataSize is too small for the result.\r
	125	DataSize has been updated with the size needed to complete the request.\r
	126	@retval EFI_INVALID_PARAMETER One of the parameters has an invalid value.\r
	127	@retval EFI_DEVICE_ERROR The variable could not be saved due to a hardware failure.\r
	128	\r
	129	**/\r
	130	typedef\r
	131	EFI_STATUS\r
69686d56	132	(EFIAPI *EFI_NV_READ)(\r
92627141	133	IN EFI_FORM_CALLBACK_PROTOCOL *This,\r
	134	IN CHAR16 *VariableName,\r
	135	IN EFI_GUID *VendorGuid,\r
	136	OUT UINT32 *Attributes OPTIONAL,\r
	137	IN OUT UINTN *DataSize,\r
	138	OUT VOID *Buffer\r
	139	);\r
	140	\r
	141	/**\r
	142	Sets the value of a variable.\r
	143	\r
	144	@param This A pointer to the EFI_FORM_CALLBACK_PROTOCOL instance.\r
	145	@param VariableName A NULL-terminated Unicode string that is the\r
1c2f052d LG	146	name of the vendor's variable. Each VariableName\r
1c2f052d LG	147	is unique for each VendorGuid.\r
92627141	148	@param VendorGuid A unique identifier for the vendor.\r
92627141	149	@param Attributes Attributes bit-mask to set for the variable.\r
1c2f052d LG	150	Inconsistent with specification here:\r
1c2f052d LG	151	Attributes data type has been changed from\r
d6a1c70d	152	UINT32 * to UINT32, because the input parameter is\r
f22f941e	153	not necessary to use a pointer date type.\r
92627141	154	@param DataSize The size in bytes of the Buffer. A size of zero causes\r
	155	the variable to be deleted.\r
	156	@param Buffer The buffer containing the contents of the variable.\r
f22f941e	157	@param ResetRequired Returns a value from the driver that abstracts this\r
	158	information and will enable a system to know if a\r
	159	system reset is required to achieve the configuration\r
	160	changes being enabled through this function.\r
92627141	161	\r
	162	@retval EFI_SUCCESS The firmware has successfully stored the variable and\r
	163	its data as defined by the Attributes.\r
	164	@retval EFI_OUT_OF_RESOURCES Not enough storage is available to hold\r
	165	the variable and its data.\r
	166	@retval EFI_INVALID_PARAMETER An invalid combination of Attributes bits\r
	167	was supplied, or the DataSize exceeds the maximum allowed.\r
	168	@retval EFI_DEVICE_ERROR The variable could not be saved due to a hardware failure.\r
	169	\r
	170	**/\r
	171	typedef\r
	172	EFI_STATUS\r
69686d56	173	(EFIAPI *EFI_NV_WRITE)(\r
92627141	174	IN EFI_FORM_CALLBACK_PROTOCOL *This,\r
	175	IN CHAR16 *VariableName,\r
	176	IN EFI_GUID *VendorGuid,\r
	177	IN UINT32 Attributes,\r
	178	IN UINTN DataSize,\r
	179	IN VOID *Buffer,\r
	180	OUT BOOLEAN *ResetRequired\r
	181	);\r
	182	\r
	183	/**\r
	184	This function is called to provide results data to the driver.\r
	185	\r
	186	@param This A pointer to the EFI_FORM_CALLBACK_PROTOCOL instance.\r
	187	@param KeyValue A unique value which is sent to the original exporting\r
1c2f052d LG	188	driver so that it can identify the type of data\r
1c2f052d LG	189	to expect. The format of the data tends to vary based\r
f22f941e	190	on the opcode that generated the callback.\r
92627141	191	@param Data A pointer to the data being sent to the original exporting driver.\r
f22f941e	192	@param Packet A pointer to a packet of information that a driver passes\r
92627141	193	back to the browser.\r
	194	\r
	195	@return Status Code\r
	196	\r
	197	**/\r
	198	typedef\r
	199	EFI_STATUS\r
69686d56	200	(EFIAPI *EFI_FORM_CALLBACK)(\r
92627141	201	IN EFI_FORM_CALLBACK_PROTOCOL *This,\r
92627141	202	IN UINT16 KeyValue,\r
108854b2	203	IN EFI_IFR_DATA_ARRAY *Data,\r
2cec3ea5	204	OUT EFI_HII_CALLBACK_PACKET **Packet\r
92627141	205	);\r
	206	\r
	207	/**\r
92627141	208	The EFI_FORM_CALLBACK_PROTOCOL is the defined interface for access to\r
92627141	209	custom NVS devices as well as communication of user selections in a more\r
3f17e6d7	210	interactive environment. This protocol should be published by platform-specific\r
92627141	211	drivers that want to export access to custom hardware storage or publish IFR\r
92627141	212	that has a requirement to call back the original driver.\r
92627141	213	**/\r
92627141	214	struct _EFI_FORM_CALLBACK_PROTOCOL {\r
2bbaeb0d	215	EFI_NV_READ NvRead; ///< The read operation to access the NV data serviced by a hardware-specific driver.\r
	216	EFI_NV_WRITE NvWrite; ///< The write operation to access the NV data serviced by a hardware-specific driver.\r
	217	EFI_FORM_CALLBACK Callback; ///< The function that is called from the configuration browser to communicate key value pairs.\r
92627141	218	};\r
	219	\r
	220	extern EFI_GUID gEfiFormCallbackProtocolGuid;\r
	221	\r
	222	#endif\r