08415f6e0c3cd596b0132ee10f60858067b8c50d
[mirror_edk2.git] / NetworkPkg / HttpBootDxe / HttpBootDxe.h
1 /** @file
2 UEFI HTTP boot driver's private data structure and interfaces declaration.
3
4 Copyright (c) 2015, Intel Corporation. All rights reserved.<BR>
5 This program and the accompanying materials are licensed and made available under
6 the terms and conditions of the BSD License that accompanies this distribution.
7 The full text of the license may be found at
8 http://opensource.org/licenses/bsd-license.php.
9
10 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
11 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
12
13 **/
14
15 #ifndef __EFI_HTTP_BOOT_DXE_H__
16 #define __EFI_HTTP_BOOT_DXE_H__
17
18 #include <Uefi.h>
19
20 //
21 // Libraries
22 //
23 #include <Library/UefiBootServicesTableLib.h>
24 #include <Library/MemoryAllocationLib.h>
25 #include <Library/BaseLib.h>
26 #include <Library/UefiLib.h>
27 #include <Library/DevicePathLib.h>
28 #include <Library/DebugLib.h>
29 #include <Library/NetLib.h>
30 #include <Library/HttpLib.h>
31
32 //
33 // UEFI Driver Model Protocols
34 //
35 #include <Protocol/DriverBinding.h>
36 #include <Protocol/ComponentName2.h>
37 #include <Protocol/ComponentName.h>
38
39 //
40 // Consumed Protocols
41 //
42 #include <Protocol/NetworkInterfaceIdentifier.h>
43 #include <Protocol/Dhcp4.h>
44 #include <Protocol/Http.h>
45 #include <Protocol/Ip4Config2.h>
46
47 //
48 // Produced Protocols
49 //
50 #include <Protocol/LoadFile.h>
51
52 //
53 // Driver Version
54 //
55 #define HTTP_BOOT_DXE_VERSION 0xa
56
57 //
58 // Protocol instances
59 //
60 extern EFI_DRIVER_BINDING_PROTOCOL gHttpBootDxeDriverBinding;
61 extern EFI_COMPONENT_NAME2_PROTOCOL gHttpBootDxeComponentName2;
62 extern EFI_COMPONENT_NAME_PROTOCOL gHttpBootDxeComponentName;
63
64 //
65 // Private data structure
66 //
67 typedef struct _HTTP_BOOT_PRIVATE_DATA HTTP_BOOT_PRIVATE_DATA;
68
69 //
70 // Include files with internal function prototypes
71 //
72 #include "HttpBootComponentName.h"
73 #include "HttpBootDhcp4.h"
74 #include "HttpBootImpl.h"
75 #include "HttpBootSupport.h"
76 #include "HttpBootClient.h"
77
78 typedef union {
79 HTTP_BOOT_DHCP4_PACKET_CACHE Dhcp4;
80 } HTTP_BOOT_DHCP_PACKET_CACHE;
81
82 struct _HTTP_BOOT_PRIVATE_DATA {
83 UINT32 Signature;
84 EFI_HANDLE Controller;
85 EFI_HANDLE Image;
86
87 //
88 // Cousumed children
89 //
90 EFI_HANDLE Dhcp4Child;
91 HTTP_IO HttpIo;
92 BOOLEAN HttpCreated;
93
94 //
95 // Consumed protocol
96 //
97 EFI_NETWORK_INTERFACE_IDENTIFIER_PROTOCOL *Nii;
98 EFI_IP4_CONFIG2_PROTOCOL *Ip4Config2;
99 EFI_DHCP4_PROTOCOL *Dhcp4;
100 EFI_DEVICE_PATH_PROTOCOL *ParentDevicePath;
101
102 //
103 // Produced children
104 //
105 EFI_HANDLE ChildHandle;
106
107 //
108 // Produced protocol
109 //
110 EFI_LOAD_FILE_PROTOCOL LoadFile;
111 EFI_DEVICE_PATH_PROTOCOL *DevicePath;
112 UINT32 Id;
113
114 //
115 // Mode data
116 //
117 BOOLEAN UsingIpv6;
118 BOOLEAN Started;
119 EFI_IP_ADDRESS StationIp;
120 EFI_IP_ADDRESS SubnetMask;
121 EFI_IP_ADDRESS GatewayIp;
122 UINT16 Port;
123 CHAR8 *BootFileUri;
124 VOID *BootFileUriParser;
125 UINTN BootFileSize;
126
127 //
128 // Cached HTTP data
129 //
130 LIST_ENTRY CacheList;
131
132 //
133 // Cached DHCP offer
134 //
135 // OfferIndex records the index of DhcpOffer[] buffer, and OfferCount records the num of each type of offer.
136 //
137 // It supposed that
138 //
139 // OfferNum: 8
140 // OfferBuffer: [ProxyNameUri, DhcpNameUri, DhcpIpUri, ProxyNameUri, ProxyIpUri, DhcpOnly, DhcpIpUri, DhcpNameUriDns]
141 // (OfferBuffer is 0-based.)
142 //
143 // And assume that (DhcpIpUri is the first priority actually.)
144 //
145 // SelectIndex: 5
146 // SelectProxyType: HttpOfferTypeProxyIpUri
147 // (SelectIndex is 1-based, and 0 means no one is selected.)
148 //
149 // So it should be
150 //
151 // DhcpIpUri DhcpNameUriDns DhcpDns DhcpOnly ProxyNameUri ProxyIpUri DhcpNameUri
152 // OfferCount: [ 2, 1, 0, 1, 2, 1, 1]
153 //
154 // OfferIndex: {[ 2, 7, 0, 5, 0, *4, 1]
155 // [ 6, 0, 0, 0, 3, 0, 0]
156 // [ 0, 0, 0, 0, 0, 0, 0]
157 // ... ]}
158 // (OfferIndex is 0-based.)
159 //
160 //
161 UINT32 SelectIndex;
162 UINT32 SelectProxyType;
163 HTTP_BOOT_DHCP_PACKET_CACHE OfferBuffer[HTTP_BOOT_OFFER_MAX_NUM];
164 UINT32 OfferNum;
165 UINT32 OfferCount[HttpOfferTypeMax];
166 UINT32 OfferIndex[HttpOfferTypeMax][HTTP_BOOT_OFFER_MAX_NUM];
167 };
168
169 #define HTTP_BOOT_PRIVATE_DATA_SIGNATURE SIGNATURE_32 ('H', 'B', 'P', 'D')
170 #define HTTP_BOOT_PRIVATE_DATA_FROM_LOADFILE(a) CR (a, HTTP_BOOT_PRIVATE_DATA, LoadFile, HTTP_BOOT_PRIVATE_DATA_SIGNATURE)
171 #define HTTP_BOOT_PRIVATE_DATA_FROM_ID(a) CR (a, HTTP_BOOT_PRIVATE_DATA, Id, HTTP_BOOT_PRIVATE_DATA_SIGNATURE)
172
173 extern EFI_LOAD_FILE_PROTOCOL gHttpBootDxeLoadFile;
174
175 /**
176 Tests to see if this driver supports a given controller. If a child device is provided,
177 it further tests to see if this driver supports creating a handle for the specified child device.
178
179 This function checks to see if the driver specified by This supports the device specified by
180 ControllerHandle. Drivers will typically use the device path attached to
181 ControllerHandle and/or the services from the bus I/O abstraction attached to
182 ControllerHandle to determine if the driver supports ControllerHandle. This function
183 may be called many times during platform initialization. In order to reduce boot times, the tests
184 performed by this function must be very small, and take as little time as possible to execute. This
185 function must not change the state of any hardware devices, and this function must be aware that the
186 device specified by ControllerHandle may already be managed by the same driver or a
187 different driver. This function must match its calls to AllocatePages() with FreePages(),
188 AllocatePool() with FreePool(), and OpenProtocol() with CloseProtocol().
189 Because ControllerHandle may have been previously started by the same driver, if a protocol is
190 already in the opened state, then it must not be closed with CloseProtocol(). This is required
191 to guarantee the state of ControllerHandle is not modified by this function.
192
193 @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
194 @param[in] ControllerHandle The handle of the controller to test. This handle
195 must support a protocol interface that supplies
196 an I/O abstraction to the driver.
197 @param[in] RemainingDevicePath A pointer to the remaining portion of a device path. This
198 parameter is ignored by device drivers, and is optional for bus
199 drivers. For bus drivers, if this parameter is not NULL, then
200 the bus driver must determine if the bus controller specified
201 by ControllerHandle and the child controller specified
202 by RemainingDevicePath are both supported by this
203 bus driver.
204
205 @retval EFI_SUCCESS The device specified by ControllerHandle and
206 RemainingDevicePath is supported by the driver specified by This.
207 @retval EFI_ALREADY_STARTED The device specified by ControllerHandle and
208 RemainingDevicePath is already being managed by the driver
209 specified by This.
210 @retval EFI_ACCESS_DENIED The device specified by ControllerHandle and
211 RemainingDevicePath is already being managed by a different
212 driver or an application that requires exclusive access.
213 Currently not implemented.
214 @retval EFI_UNSUPPORTED The device specified by ControllerHandle and
215 RemainingDevicePath is not supported by the driver specified by This.
216 **/
217 EFI_STATUS
218 EFIAPI
219 HttpBootIp4DxeDriverBindingSupported (
220 IN EFI_DRIVER_BINDING_PROTOCOL *This,
221 IN EFI_HANDLE ControllerHandle,
222 IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath OPTIONAL
223 );
224
225 /**
226 Starts a device controller or a bus controller.
227
228 The Start() function is designed to be invoked from the EFI boot service ConnectController().
229 As a result, much of the error checking on the parameters to Start() has been moved into this
230 common boot service. It is legal to call Start() from other locations,
231 but the following calling restrictions must be followed, or the system behavior will not be deterministic.
232 1. ControllerHandle must be a valid EFI_HANDLE.
233 2. If RemainingDevicePath is not NULL, then it must be a pointer to a naturally aligned
234 EFI_DEVICE_PATH_PROTOCOL.
235 3. Prior to calling Start(), the Supported() function for the driver specified by This must
236 have been called with the same calling parameters, and Supported() must have returned EFI_SUCCESS.
237
238 @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
239 @param[in] ControllerHandle The handle of the controller to start. This handle
240 must support a protocol interface that supplies
241 an I/O abstraction to the driver.
242 @param[in] RemainingDevicePath A pointer to the remaining portion of a device path. This
243 parameter is ignored by device drivers, and is optional for bus
244 drivers. For a bus driver, if this parameter is NULL, then handles
245 for all the children of Controller are created by this driver.
246 If this parameter is not NULL and the first Device Path Node is
247 not the End of Device Path Node, then only the handle for the
248 child device specified by the first Device Path Node of
249 RemainingDevicePath is created by this driver.
250 If the first Device Path Node of RemainingDevicePath is
251 the End of Device Path Node, no child handle is created by this
252 driver.
253
254 @retval EFI_SUCCESS The device was started.
255 @retval EFI_DEVICE_ERROR The device could not be started due to a device error.Currently not implemented.
256 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
257 @retval Others The driver failded to start the device.
258
259 **/
260 EFI_STATUS
261 EFIAPI
262 HttpBootIp4DxeDriverBindingStart (
263 IN EFI_DRIVER_BINDING_PROTOCOL *This,
264 IN EFI_HANDLE ControllerHandle,
265 IN EFI_DEVICE_PATH_PROTOCOL *RemainingDevicePath OPTIONAL
266 );
267
268 /**
269 Stops a device controller or a bus controller.
270
271 The Stop() function is designed to be invoked from the EFI boot service DisconnectController().
272 As a result, much of the error checking on the parameters to Stop() has been moved
273 into this common boot service. It is legal to call Stop() from other locations,
274 but the following calling restrictions must be followed, or the system behavior will not be deterministic.
275 1. ControllerHandle must be a valid EFI_HANDLE that was used on a previous call to this
276 same driver's Start() function.
277 2. The first NumberOfChildren handles of ChildHandleBuffer must all be a valid
278 EFI_HANDLE. In addition, all of these handles must have been created in this driver's
279 Start() function, and the Start() function must have called OpenProtocol() on
280 ControllerHandle with an Attribute of EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER.
281
282 @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
283 @param[in] ControllerHandle A handle to the device being stopped. The handle must
284 support a bus specific I/O protocol for the driver
285 to use to stop the device.
286 @param[in] NumberOfChildren The number of child device handles in ChildHandleBuffer.
287 @param[in] ChildHandleBuffer An array of child handles to be freed. May be NULL
288 if NumberOfChildren is 0.
289
290 @retval EFI_SUCCESS The device was stopped.
291 @retval EFI_DEVICE_ERROR The device could not be stopped due to a device error.
292
293 **/
294 EFI_STATUS
295 EFIAPI
296 HttpBootIp4DxeDriverBindingStop (
297 IN EFI_DRIVER_BINDING_PROTOCOL *This,
298 IN EFI_HANDLE ControllerHandle,
299 IN UINTN NumberOfChildren,
300 IN EFI_HANDLE *ChildHandleBuffer OPTIONAL
301 );
302
303 #endif