2 UEFI HTTP boot driver's private data structure and interfaces declaration.
4 Copyright (c) 2015 - 2017, Intel Corporation. All rights reserved.<BR>
5 (C) Copyright 2016 Hewlett Packard Enterprise Development LP<BR>
6 This program and the accompanying materials are licensed and made available under
7 the terms and conditions of the BSD License that accompanies this distribution.
8 The full text of the license may be found at
9 http://opensource.org/licenses/bsd-license.php.
11 THE PROGRAM IS DISTRIBUTED UNDER THE BSD LICENSE ON AN "AS IS" BASIS,
12 WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, EITHER EXPRESS OR IMPLIED.
16 #ifndef __EFI_HTTP_BOOT_DXE_H__
17 #define __EFI_HTTP_BOOT_DXE_H__
21 #include <IndustryStandard/Http11.h>
22 #include <IndustryStandard/Dhcp.h>
27 #include <Library/UefiBootServicesTableLib.h>
28 #include <Library/UefiHiiServicesLib.h>
29 #include <Library/UefiRuntimeServicesTableLib.h>
30 #include <Library/MemoryAllocationLib.h>
31 #include <Library/BaseLib.h>
32 #include <Library/UefiLib.h>
33 #include <Library/DevicePathLib.h>
34 #include <Library/DebugLib.h>
35 #include <Library/NetLib.h>
36 #include <Library/HttpLib.h>
37 #include <Library/HiiLib.h>
38 #include <Library/PrintLib.h>
39 #include <Library/DpcLib.h>
42 // UEFI Driver Model Protocols
44 #include <Protocol/DriverBinding.h>
45 #include <Protocol/ComponentName2.h>
46 #include <Protocol/ComponentName.h>
51 #include <Protocol/ServiceBinding.h>
52 #include <Protocol/HiiConfigAccess.h>
53 #include <Protocol/NetworkInterfaceIdentifier.h>
54 #include <Protocol/Dhcp4.h>
55 #include <Protocol/Dhcp6.h>
56 #include <Protocol/Dns6.h>
57 #include <Protocol/Http.h>
58 #include <Protocol/Ip4Config2.h>
59 #include <Protocol/Ip6Config.h>
60 #include <Protocol/RamDisk.h>
61 #include <Protocol/AdapterInformation.h>
66 #include <Protocol/LoadFile.h>
67 #include <Protocol/HttpBootCallback.h>
72 #include <Guid/HttpBootConfigHii.h>
77 #define HTTP_BOOT_DXE_VERSION 0xa
80 // Standard Media Types defined in
81 // http://www.iana.org/assignments/media-types
83 #define HTTP_CONTENT_TYPE_APP_EFI "application/efi"
84 #define HTTP_CONTENT_TYPE_APP_IMG "application/vnd.efi-img"
85 #define HTTP_CONTENT_TYPE_APP_ISO "application/vnd.efi-iso"
90 extern EFI_DRIVER_BINDING_PROTOCOL gHttpBootDxeDriverBinding
;
91 extern EFI_COMPONENT_NAME2_PROTOCOL gHttpBootDxeComponentName2
;
92 extern EFI_COMPONENT_NAME_PROTOCOL gHttpBootDxeComponentName
;
95 // Private data structure
97 typedef struct _HTTP_BOOT_PRIVATE_DATA HTTP_BOOT_PRIVATE_DATA
;
98 typedef struct _HTTP_BOOT_VIRTUAL_NIC HTTP_BOOT_VIRTUAL_NIC
;
103 ImageTypeVirtualDisk
,
105 } HTTP_BOOT_IMAGE_TYPE
;
108 // Include files with internal function prototypes
110 #include "HttpBootComponentName.h"
111 #include "HttpBootDhcp4.h"
112 #include "HttpBootDhcp6.h"
113 #include "HttpBootImpl.h"
114 #include "HttpBootSupport.h"
115 #include "HttpBootClient.h"
116 #include "HttpBootConfig.h"
119 HTTP_BOOT_DHCP4_PACKET_CACHE Dhcp4
;
120 HTTP_BOOT_DHCP6_PACKET_CACHE Dhcp6
;
121 } HTTP_BOOT_DHCP_PACKET_CACHE
;
123 struct _HTTP_BOOT_VIRTUAL_NIC
{
125 EFI_HANDLE Controller
;
126 EFI_HANDLE ImageHandle
;
127 EFI_LOAD_FILE_PROTOCOL LoadFile
;
128 EFI_DEVICE_PATH_PROTOCOL
*DevicePath
;
129 HTTP_BOOT_PRIVATE_DATA
*Private
;
132 #define HTTP_BOOT_PRIVATE_DATA_FROM_CALLBACK_INFO(Callback) \
135 HTTP_BOOT_PRIVATE_DATA, \
137 HTTP_BOOT_PRIVATE_DATA_SIGNATURE \
140 #define HTTP_BOOT_PRIVATE_DATA_FROM_CALLBACK_PROTOCOL(CallbackProtocol) \
143 HTTP_BOOT_PRIVATE_DATA, \
145 HTTP_BOOT_PRIVATE_DATA_SIGNATURE \
148 struct _HTTP_BOOT_PRIVATE_DATA
{
150 EFI_HANDLE Controller
;
152 HTTP_BOOT_VIRTUAL_NIC
*Ip4Nic
;
153 HTTP_BOOT_VIRTUAL_NIC
*Ip6Nic
;
159 EFI_HANDLE Dhcp4Child
;
160 EFI_HANDLE Dhcp6Child
;
167 EFI_NETWORK_INTERFACE_IDENTIFIER_PROTOCOL
*Nii
;
168 EFI_IP6_PROTOCOL
*Ip6
;
169 EFI_IP4_CONFIG2_PROTOCOL
*Ip4Config2
;
170 EFI_IP6_CONFIG_PROTOCOL
*Ip6Config
;
171 EFI_DHCP4_PROTOCOL
*Dhcp4
;
172 EFI_DHCP6_PROTOCOL
*Dhcp6
;
173 EFI_DEVICE_PATH_PROTOCOL
*ParentDevicePath
;
179 EFI_LOAD_FILE_PROTOCOL LoadFile
;
180 EFI_DEVICE_PATH_PROTOCOL
*DevicePath
;
182 EFI_HTTP_BOOT_CALLBACK_PROTOCOL
*HttpBootCallback
;
183 EFI_HTTP_BOOT_CALLBACK_PROTOCOL LoadFileCallback
;
186 // Data for the default HTTP Boot callback protocol
193 // HII callback info block
195 HTTP_BOOT_FORM_CALLBACK_INFO CallbackInfo
;
202 EFI_IP_ADDRESS StationIp
;
203 EFI_IP_ADDRESS SubnetMask
;
204 EFI_IP_ADDRESS GatewayIp
;
205 EFI_IP_ADDRESS ServerIp
;
207 UINT32 DnsServerCount
;
208 EFI_IP_ADDRESS
*DnsServerIp
;
211 // The URI string attempt to download through HTTP, may point to
212 // the memory in cached DHCP offer, or to the memory in FilePathUri.
215 VOID
*BootFileUriParser
;
218 HTTP_BOOT_IMAGE_TYPE ImageType
;
221 // URI string extracted from the input FilePath parameter.
224 VOID
*FilePathUriParser
;
229 LIST_ENTRY CacheList
;
234 // OfferIndex records the index of DhcpOffer[] buffer, and OfferCount records the num of each type of offer.
239 // OfferBuffer: [ProxyNameUri, DhcpNameUri, DhcpIpUri, ProxyNameUri, ProxyIpUri, DhcpOnly, DhcpIpUri, DhcpNameUriDns]
240 // (OfferBuffer is 0-based.)
242 // And assume that (DhcpIpUri is the first priority actually.)
245 // SelectProxyType: HttpOfferTypeProxyIpUri
246 // (SelectIndex is 1-based, and 0 means no one is selected.)
250 // DhcpIpUri DhcpNameUriDns DhcpDns DhcpOnly ProxyNameUri ProxyIpUri DhcpNameUri
251 // OfferCount: [ 2, 1, 0, 1, 2, 1, 1]
253 // OfferIndex: {[ 2, 7, 0, 5, 0, *4, 1]
254 // [ 6, 0, 0, 0, 3, 0, 0]
255 // [ 0, 0, 0, 0, 0, 0, 0]
257 // (OfferIndex is 0-based.)
261 UINT32 SelectProxyType
;
262 HTTP_BOOT_DHCP_PACKET_CACHE OfferBuffer
[HTTP_BOOT_OFFER_MAX_NUM
];
264 UINT32 OfferCount
[HttpOfferTypeMax
];
265 UINT32 OfferIndex
[HttpOfferTypeMax
][HTTP_BOOT_OFFER_MAX_NUM
];
268 #define HTTP_BOOT_PRIVATE_DATA_SIGNATURE SIGNATURE_32 ('H', 'B', 'P', 'D')
269 #define HTTP_BOOT_VIRTUAL_NIC_SIGNATURE SIGNATURE_32 ('H', 'B', 'V', 'N')
270 #define HTTP_BOOT_PRIVATE_DATA_FROM_LOADFILE(a) CR (a, HTTP_BOOT_PRIVATE_DATA, LoadFile, HTTP_BOOT_PRIVATE_DATA_SIGNATURE)
271 #define HTTP_BOOT_PRIVATE_DATA_FROM_ID(a) CR (a, HTTP_BOOT_PRIVATE_DATA, Id, HTTP_BOOT_PRIVATE_DATA_SIGNATURE)
272 #define HTTP_BOOT_VIRTUAL_NIC_FROM_LOADFILE(a) CR (a, HTTP_BOOT_VIRTUAL_NIC, LoadFile, HTTP_BOOT_VIRTUAL_NIC_SIGNATURE)
273 extern EFI_LOAD_FILE_PROTOCOL gHttpBootDxeLoadFile
;
276 Tests to see if this driver supports a given controller. If a child device is provided,
277 it further tests to see if this driver supports creating a handle for the specified child device.
279 This function checks to see if the driver specified by This supports the device specified by
280 ControllerHandle. Drivers will typically use the device path attached to
281 ControllerHandle and/or the services from the bus I/O abstraction attached to
282 ControllerHandle to determine if the driver supports ControllerHandle. This function
283 may be called many times during platform initialization. In order to reduce boot times, the tests
284 performed by this function must be very small, and take as little time as possible to execute. This
285 function must not change the state of any hardware devices, and this function must be aware that the
286 device specified by ControllerHandle may already be managed by the same driver or a
287 different driver. This function must match its calls to AllocatePages() with FreePages(),
288 AllocatePool() with FreePool(), and OpenProtocol() with CloseProtocol().
289 Because ControllerHandle may have been previously started by the same driver, if a protocol is
290 already in the opened state, then it must not be closed with CloseProtocol(). This is required
291 to guarantee the state of ControllerHandle is not modified by this function.
293 @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
294 @param[in] ControllerHandle The handle of the controller to test. This handle
295 must support a protocol interface that supplies
296 an I/O abstraction to the driver.
297 @param[in] RemainingDevicePath A pointer to the remaining portion of a device path. This
298 parameter is ignored by device drivers, and is optional for bus
299 drivers. For bus drivers, if this parameter is not NULL, then
300 the bus driver must determine if the bus controller specified
301 by ControllerHandle and the child controller specified
302 by RemainingDevicePath are both supported by this
305 @retval EFI_SUCCESS The device specified by ControllerHandle and
306 RemainingDevicePath is supported by the driver specified by This.
307 @retval EFI_ALREADY_STARTED The device specified by ControllerHandle and
308 RemainingDevicePath is already being managed by the driver
310 @retval EFI_ACCESS_DENIED The device specified by ControllerHandle and
311 RemainingDevicePath is already being managed by a different
312 driver or an application that requires exclusive access.
313 Currently not implemented.
314 @retval EFI_UNSUPPORTED The device specified by ControllerHandle and
315 RemainingDevicePath is not supported by the driver specified by This.
319 HttpBootIp4DxeDriverBindingSupported (
320 IN EFI_DRIVER_BINDING_PROTOCOL
*This
,
321 IN EFI_HANDLE ControllerHandle
,
322 IN EFI_DEVICE_PATH_PROTOCOL
*RemainingDevicePath OPTIONAL
326 Starts a device controller or a bus controller.
328 The Start() function is designed to be invoked from the EFI boot service ConnectController().
329 As a result, much of the error checking on the parameters to Start() has been moved into this
330 common boot service. It is legal to call Start() from other locations,
331 but the following calling restrictions must be followed, or the system behavior will not be deterministic.
332 1. ControllerHandle must be a valid EFI_HANDLE.
333 2. If RemainingDevicePath is not NULL, then it must be a pointer to a naturally aligned
334 EFI_DEVICE_PATH_PROTOCOL.
335 3. Prior to calling Start(), the Supported() function for the driver specified by This must
336 have been called with the same calling parameters, and Supported() must have returned EFI_SUCCESS.
338 @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
339 @param[in] ControllerHandle The handle of the controller to start. This handle
340 must support a protocol interface that supplies
341 an I/O abstraction to the driver.
342 @param[in] RemainingDevicePath A pointer to the remaining portion of a device path. This
343 parameter is ignored by device drivers, and is optional for bus
344 drivers. For a bus driver, if this parameter is NULL, then handles
345 for all the children of Controller are created by this driver.
346 If this parameter is not NULL and the first Device Path Node is
347 not the End of Device Path Node, then only the handle for the
348 child device specified by the first Device Path Node of
349 RemainingDevicePath is created by this driver.
350 If the first Device Path Node of RemainingDevicePath is
351 the End of Device Path Node, no child handle is created by this
354 @retval EFI_SUCCESS The device was started.
355 @retval EFI_DEVICE_ERROR The device could not be started due to a device error.Currently not implemented.
356 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
357 @retval Others The driver failded to start the device.
362 HttpBootIp4DxeDriverBindingStart (
363 IN EFI_DRIVER_BINDING_PROTOCOL
*This
,
364 IN EFI_HANDLE ControllerHandle
,
365 IN EFI_DEVICE_PATH_PROTOCOL
*RemainingDevicePath OPTIONAL
369 Stops a device controller or a bus controller.
371 The Stop() function is designed to be invoked from the EFI boot service DisconnectController().
372 As a result, much of the error checking on the parameters to Stop() has been moved
373 into this common boot service. It is legal to call Stop() from other locations,
374 but the following calling restrictions must be followed, or the system behavior will not be deterministic.
375 1. ControllerHandle must be a valid EFI_HANDLE that was used on a previous call to this
376 same driver's Start() function.
377 2. The first NumberOfChildren handles of ChildHandleBuffer must all be a valid
378 EFI_HANDLE. In addition, all of these handles must have been created in this driver's
379 Start() function, and the Start() function must have called OpenProtocol() on
380 ControllerHandle with an Attribute of EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER.
382 @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
383 @param[in] ControllerHandle A handle to the device being stopped. The handle must
384 support a bus specific I/O protocol for the driver
385 to use to stop the device.
386 @param[in] NumberOfChildren The number of child device handles in ChildHandleBuffer.
387 @param[in] ChildHandleBuffer An array of child handles to be freed. May be NULL
388 if NumberOfChildren is 0.
390 @retval EFI_SUCCESS The device was stopped.
391 @retval EFI_DEVICE_ERROR The device could not be stopped due to a device error.
396 HttpBootIp4DxeDriverBindingStop (
397 IN EFI_DRIVER_BINDING_PROTOCOL
*This
,
398 IN EFI_HANDLE ControllerHandle
,
399 IN UINTN NumberOfChildren
,
400 IN EFI_HANDLE
*ChildHandleBuffer OPTIONAL
404 Tests to see if this driver supports a given controller. If a child device is provided,
405 it further tests to see if this driver supports creating a handle for the specified child device.
407 This function checks to see if the driver specified by This supports the device specified by
408 ControllerHandle. Drivers will typically use the device path attached to
409 ControllerHandle and/or the services from the bus I/O abstraction attached to
410 ControllerHandle to determine if the driver supports ControllerHandle. This function
411 may be called many times during platform initialization. In order to reduce boot times, the tests
412 performed by this function must be very small, and take as little time as possible to execute. This
413 function must not change the state of any hardware devices, and this function must be aware that the
414 device specified by ControllerHandle may already be managed by the same driver or a
415 different driver. This function must match its calls to AllocatePages() with FreePages(),
416 AllocatePool() with FreePool(), and OpenProtocol() with CloseProtocol().
417 Because ControllerHandle may have been previously started by the same driver, if a protocol is
418 already in the opened state, then it must not be closed with CloseProtocol(). This is required
419 to guarantee the state of ControllerHandle is not modified by this function.
421 @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
422 @param[in] ControllerHandle The handle of the controller to test. This handle
423 must support a protocol interface that supplies
424 an I/O abstraction to the driver.
425 @param[in] RemainingDevicePath A pointer to the remaining portion of a device path. This
426 parameter is ignored by device drivers, and is optional for bus
427 drivers. For bus drivers, if this parameter is not NULL, then
428 the bus driver must determine if the bus controller specified
429 by ControllerHandle and the child controller specified
430 by RemainingDevicePath are both supported by this
433 @retval EFI_SUCCESS The device specified by ControllerHandle and
434 RemainingDevicePath is supported by the driver specified by This.
435 @retval EFI_ALREADY_STARTED The device specified by ControllerHandle and
436 RemainingDevicePath is already being managed by the driver
438 @retval EFI_ACCESS_DENIED The device specified by ControllerHandle and
439 RemainingDevicePath is already being managed by a different
440 driver or an application that requires exclusive access.
441 Currently not implemented.
442 @retval EFI_UNSUPPORTED The device specified by ControllerHandle and
443 RemainingDevicePath is not supported by the driver specified by This.
447 HttpBootIp6DxeDriverBindingSupported (
448 IN EFI_DRIVER_BINDING_PROTOCOL
*This
,
449 IN EFI_HANDLE ControllerHandle
,
450 IN EFI_DEVICE_PATH_PROTOCOL
*RemainingDevicePath OPTIONAL
454 Starts a device controller or a bus controller.
456 The Start() function is designed to be invoked from the EFI boot service ConnectController().
457 As a result, much of the error checking on the parameters to Start() has been moved into this
458 common boot service. It is legal to call Start() from other locations,
459 but the following calling restrictions must be followed, or the system behavior will not be deterministic.
460 1. ControllerHandle must be a valid EFI_HANDLE.
461 2. If RemainingDevicePath is not NULL, then it must be a pointer to a naturally aligned
462 EFI_DEVICE_PATH_PROTOCOL.
463 3. Prior to calling Start(), the Supported() function for the driver specified by This must
464 have been called with the same calling parameters, and Supported() must have returned EFI_SUCCESS.
466 @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
467 @param[in] ControllerHandle The handle of the controller to start. This handle
468 must support a protocol interface that supplies
469 an I/O abstraction to the driver.
470 @param[in] RemainingDevicePath A pointer to the remaining portion of a device path. This
471 parameter is ignored by device drivers, and is optional for bus
472 drivers. For a bus driver, if this parameter is NULL, then handles
473 for all the children of Controller are created by this driver.
474 If this parameter is not NULL and the first Device Path Node is
475 not the End of Device Path Node, then only the handle for the
476 child device specified by the first Device Path Node of
477 RemainingDevicePath is created by this driver.
478 If the first Device Path Node of RemainingDevicePath is
479 the End of Device Path Node, no child handle is created by this
482 @retval EFI_SUCCESS The device was started.
483 @retval EFI_DEVICE_ERROR The device could not be started due to a device error.Currently not implemented.
484 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
485 @retval Others The driver failded to start the device.
490 HttpBootIp6DxeDriverBindingStart (
491 IN EFI_DRIVER_BINDING_PROTOCOL
*This
,
492 IN EFI_HANDLE ControllerHandle
,
493 IN EFI_DEVICE_PATH_PROTOCOL
*RemainingDevicePath OPTIONAL
497 Stops a device controller or a bus controller.
499 The Stop() function is designed to be invoked from the EFI boot service DisconnectController().
500 As a result, much of the error checking on the parameters to Stop() has been moved
501 into this common boot service. It is legal to call Stop() from other locations,
502 but the following calling restrictions must be followed, or the system behavior will not be deterministic.
503 1. ControllerHandle must be a valid EFI_HANDLE that was used on a previous call to this
504 same driver's Start() function.
505 2. The first NumberOfChildren handles of ChildHandleBuffer must all be a valid
506 EFI_HANDLE. In addition, all of these handles must have been created in this driver's
507 Start() function, and the Start() function must have called OpenProtocol() on
508 ControllerHandle with an Attribute of EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER.
510 @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
511 @param[in] ControllerHandle A handle to the device being stopped. The handle must
512 support a bus specific I/O protocol for the driver
513 to use to stop the device.
514 @param[in] NumberOfChildren The number of child device handles in ChildHandleBuffer.
515 @param[in] ChildHandleBuffer An array of child handles to be freed. May be NULL
516 if NumberOfChildren is 0.
518 @retval EFI_SUCCESS The device was stopped.
519 @retval EFI_DEVICE_ERROR The device could not be stopped due to a device error.
524 HttpBootIp6DxeDriverBindingStop (
525 IN EFI_DRIVER_BINDING_PROTOCOL
*This
,
526 IN EFI_HANDLE ControllerHandle
,
527 IN UINTN NumberOfChildren
,
528 IN EFI_HANDLE
*ChildHandleBuffer OPTIONAL