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