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