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