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>
64 #include <Protocol/LoadFile.h>
65 #include <Protocol/HttpBootCallback.h>
70 #include <Guid/HttpBootConfigHii.h>
75 #define HTTP_BOOT_DXE_VERSION 0xa
78 // Standard Media Types defined in
79 // http://www.iana.org/assignments/media-types
81 #define HTTP_CONTENT_TYPE_APP_EFI "application/efi"
82 #define HTTP_CONTENT_TYPE_APP_IMG "application/vnd.efi-img"
83 #define HTTP_CONTENT_TYPE_APP_ISO "application/vnd.efi-iso"
88 extern EFI_DRIVER_BINDING_PROTOCOL gHttpBootDxeDriverBinding
;
89 extern EFI_COMPONENT_NAME2_PROTOCOL gHttpBootDxeComponentName2
;
90 extern EFI_COMPONENT_NAME_PROTOCOL gHttpBootDxeComponentName
;
93 // Private data structure
95 typedef struct _HTTP_BOOT_PRIVATE_DATA HTTP_BOOT_PRIVATE_DATA
;
96 typedef struct _HTTP_BOOT_VIRTUAL_NIC HTTP_BOOT_VIRTUAL_NIC
;
101 ImageTypeVirtualDisk
,
103 } HTTP_BOOT_IMAGE_TYPE
;
106 // Include files with internal function prototypes
108 #include "HttpBootComponentName.h"
109 #include "HttpBootDhcp4.h"
110 #include "HttpBootDhcp6.h"
111 #include "HttpBootImpl.h"
112 #include "HttpBootSupport.h"
113 #include "HttpBootClient.h"
114 #include "HttpBootConfig.h"
117 HTTP_BOOT_DHCP4_PACKET_CACHE Dhcp4
;
118 HTTP_BOOT_DHCP6_PACKET_CACHE Dhcp6
;
119 } HTTP_BOOT_DHCP_PACKET_CACHE
;
121 struct _HTTP_BOOT_VIRTUAL_NIC
{
123 EFI_HANDLE Controller
;
124 EFI_HANDLE ImageHandle
;
125 EFI_LOAD_FILE_PROTOCOL LoadFile
;
126 EFI_DEVICE_PATH_PROTOCOL
*DevicePath
;
127 HTTP_BOOT_PRIVATE_DATA
*Private
;
130 #define HTTP_BOOT_PRIVATE_DATA_FROM_CALLBACK_INFO(Callback) \
133 HTTP_BOOT_PRIVATE_DATA, \
135 HTTP_BOOT_PRIVATE_DATA_SIGNATURE \
138 #define HTTP_BOOT_PRIVATE_DATA_FROM_CALLBACK_PROTOCOL(CallbackProtocol) \
141 HTTP_BOOT_PRIVATE_DATA, \
143 HTTP_BOOT_PRIVATE_DATA_SIGNATURE \
146 struct _HTTP_BOOT_PRIVATE_DATA
{
148 EFI_HANDLE Controller
;
150 HTTP_BOOT_VIRTUAL_NIC
*Ip4Nic
;
151 HTTP_BOOT_VIRTUAL_NIC
*Ip6Nic
;
157 EFI_HANDLE Dhcp4Child
;
158 EFI_HANDLE Dhcp6Child
;
165 EFI_NETWORK_INTERFACE_IDENTIFIER_PROTOCOL
*Nii
;
166 EFI_IP6_PROTOCOL
*Ip6
;
167 EFI_IP4_CONFIG2_PROTOCOL
*Ip4Config2
;
168 EFI_IP6_CONFIG_PROTOCOL
*Ip6Config
;
169 EFI_DHCP4_PROTOCOL
*Dhcp4
;
170 EFI_DHCP6_PROTOCOL
*Dhcp6
;
171 EFI_DEVICE_PATH_PROTOCOL
*ParentDevicePath
;
177 EFI_LOAD_FILE_PROTOCOL LoadFile
;
178 EFI_DEVICE_PATH_PROTOCOL
*DevicePath
;
180 EFI_HTTP_BOOT_CALLBACK_PROTOCOL
*HttpBootCallback
;
181 EFI_HTTP_BOOT_CALLBACK_PROTOCOL LoadFileCallback
;
187 // HII callback info block
189 HTTP_BOOT_FORM_CALLBACK_INFO CallbackInfo
;
196 EFI_IP_ADDRESS StationIp
;
197 EFI_IP_ADDRESS SubnetMask
;
198 EFI_IP_ADDRESS GatewayIp
;
199 EFI_IP_ADDRESS ServerIp
;
203 // The URI string attempt to download through HTTP, may point to
204 // the memory in cached DHCP offer, or to the memory in FilePathUri.
207 VOID
*BootFileUriParser
;
210 HTTP_BOOT_IMAGE_TYPE ImageType
;
213 // URI string extracted from the input FilePath parameter.
216 VOID
*FilePathUriParser
;
221 LIST_ENTRY CacheList
;
226 // OfferIndex records the index of DhcpOffer[] buffer, and OfferCount records the num of each type of offer.
231 // OfferBuffer: [ProxyNameUri, DhcpNameUri, DhcpIpUri, ProxyNameUri, ProxyIpUri, DhcpOnly, DhcpIpUri, DhcpNameUriDns]
232 // (OfferBuffer is 0-based.)
234 // And assume that (DhcpIpUri is the first priority actually.)
237 // SelectProxyType: HttpOfferTypeProxyIpUri
238 // (SelectIndex is 1-based, and 0 means no one is selected.)
242 // DhcpIpUri DhcpNameUriDns DhcpDns DhcpOnly ProxyNameUri ProxyIpUri DhcpNameUri
243 // OfferCount: [ 2, 1, 0, 1, 2, 1, 1]
245 // OfferIndex: {[ 2, 7, 0, 5, 0, *4, 1]
246 // [ 6, 0, 0, 0, 3, 0, 0]
247 // [ 0, 0, 0, 0, 0, 0, 0]
249 // (OfferIndex is 0-based.)
253 UINT32 SelectProxyType
;
254 HTTP_BOOT_DHCP_PACKET_CACHE OfferBuffer
[HTTP_BOOT_OFFER_MAX_NUM
];
256 UINT32 OfferCount
[HttpOfferTypeMax
];
257 UINT32 OfferIndex
[HttpOfferTypeMax
][HTTP_BOOT_OFFER_MAX_NUM
];
260 #define HTTP_BOOT_PRIVATE_DATA_SIGNATURE SIGNATURE_32 ('H', 'B', 'P', 'D')
261 #define HTTP_BOOT_VIRTUAL_NIC_SIGNATURE SIGNATURE_32 ('H', 'B', 'V', 'N')
262 #define HTTP_BOOT_PRIVATE_DATA_FROM_LOADFILE(a) CR (a, HTTP_BOOT_PRIVATE_DATA, LoadFile, HTTP_BOOT_PRIVATE_DATA_SIGNATURE)
263 #define HTTP_BOOT_PRIVATE_DATA_FROM_ID(a) CR (a, HTTP_BOOT_PRIVATE_DATA, Id, HTTP_BOOT_PRIVATE_DATA_SIGNATURE)
264 #define HTTP_BOOT_VIRTUAL_NIC_FROM_LOADFILE(a) CR (a, HTTP_BOOT_VIRTUAL_NIC, LoadFile, HTTP_BOOT_VIRTUAL_NIC_SIGNATURE)
265 extern EFI_LOAD_FILE_PROTOCOL gHttpBootDxeLoadFile
;
268 Tests to see if this driver supports a given controller. If a child device is provided,
269 it further tests to see if this driver supports creating a handle for the specified child device.
271 This function checks to see if the driver specified by This supports the device specified by
272 ControllerHandle. Drivers will typically use the device path attached to
273 ControllerHandle and/or the services from the bus I/O abstraction attached to
274 ControllerHandle to determine if the driver supports ControllerHandle. This function
275 may be called many times during platform initialization. In order to reduce boot times, the tests
276 performed by this function must be very small, and take as little time as possible to execute. This
277 function must not change the state of any hardware devices, and this function must be aware that the
278 device specified by ControllerHandle may already be managed by the same driver or a
279 different driver. This function must match its calls to AllocatePages() with FreePages(),
280 AllocatePool() with FreePool(), and OpenProtocol() with CloseProtocol().
281 Because ControllerHandle may have been previously started by the same driver, if a protocol is
282 already in the opened state, then it must not be closed with CloseProtocol(). This is required
283 to guarantee the state of ControllerHandle is not modified by this function.
285 @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
286 @param[in] ControllerHandle The handle of the controller to test. This handle
287 must support a protocol interface that supplies
288 an I/O abstraction to the driver.
289 @param[in] RemainingDevicePath A pointer to the remaining portion of a device path. This
290 parameter is ignored by device drivers, and is optional for bus
291 drivers. For bus drivers, if this parameter is not NULL, then
292 the bus driver must determine if the bus controller specified
293 by ControllerHandle and the child controller specified
294 by RemainingDevicePath are both supported by this
297 @retval EFI_SUCCESS The device specified by ControllerHandle and
298 RemainingDevicePath is supported by the driver specified by This.
299 @retval EFI_ALREADY_STARTED The device specified by ControllerHandle and
300 RemainingDevicePath is already being managed by the driver
302 @retval EFI_ACCESS_DENIED The device specified by ControllerHandle and
303 RemainingDevicePath is already being managed by a different
304 driver or an application that requires exclusive access.
305 Currently not implemented.
306 @retval EFI_UNSUPPORTED The device specified by ControllerHandle and
307 RemainingDevicePath is not supported by the driver specified by This.
311 HttpBootIp4DxeDriverBindingSupported (
312 IN EFI_DRIVER_BINDING_PROTOCOL
*This
,
313 IN EFI_HANDLE ControllerHandle
,
314 IN EFI_DEVICE_PATH_PROTOCOL
*RemainingDevicePath OPTIONAL
318 Starts a device controller or a bus controller.
320 The Start() function is designed to be invoked from the EFI boot service ConnectController().
321 As a result, much of the error checking on the parameters to Start() has been moved into this
322 common boot service. It is legal to call Start() from other locations,
323 but the following calling restrictions must be followed, or the system behavior will not be deterministic.
324 1. ControllerHandle must be a valid EFI_HANDLE.
325 2. If RemainingDevicePath is not NULL, then it must be a pointer to a naturally aligned
326 EFI_DEVICE_PATH_PROTOCOL.
327 3. Prior to calling Start(), the Supported() function for the driver specified by This must
328 have been called with the same calling parameters, and Supported() must have returned EFI_SUCCESS.
330 @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
331 @param[in] ControllerHandle The handle of the controller to start. This handle
332 must support a protocol interface that supplies
333 an I/O abstraction to the driver.
334 @param[in] RemainingDevicePath A pointer to the remaining portion of a device path. This
335 parameter is ignored by device drivers, and is optional for bus
336 drivers. For a bus driver, if this parameter is NULL, then handles
337 for all the children of Controller are created by this driver.
338 If this parameter is not NULL and the first Device Path Node is
339 not the End of Device Path Node, then only the handle for the
340 child device specified by the first Device Path Node of
341 RemainingDevicePath is created by this driver.
342 If the first Device Path Node of RemainingDevicePath is
343 the End of Device Path Node, no child handle is created by this
346 @retval EFI_SUCCESS The device was started.
347 @retval EFI_DEVICE_ERROR The device could not be started due to a device error.Currently not implemented.
348 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
349 @retval Others The driver failded to start the device.
354 HttpBootIp4DxeDriverBindingStart (
355 IN EFI_DRIVER_BINDING_PROTOCOL
*This
,
356 IN EFI_HANDLE ControllerHandle
,
357 IN EFI_DEVICE_PATH_PROTOCOL
*RemainingDevicePath OPTIONAL
361 Stops a device controller or a bus controller.
363 The Stop() function is designed to be invoked from the EFI boot service DisconnectController().
364 As a result, much of the error checking on the parameters to Stop() has been moved
365 into this common boot service. It is legal to call Stop() from other locations,
366 but the following calling restrictions must be followed, or the system behavior will not be deterministic.
367 1. ControllerHandle must be a valid EFI_HANDLE that was used on a previous call to this
368 same driver's Start() function.
369 2. The first NumberOfChildren handles of ChildHandleBuffer must all be a valid
370 EFI_HANDLE. In addition, all of these handles must have been created in this driver's
371 Start() function, and the Start() function must have called OpenProtocol() on
372 ControllerHandle with an Attribute of EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER.
374 @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
375 @param[in] ControllerHandle A handle to the device being stopped. The handle must
376 support a bus specific I/O protocol for the driver
377 to use to stop the device.
378 @param[in] NumberOfChildren The number of child device handles in ChildHandleBuffer.
379 @param[in] ChildHandleBuffer An array of child handles to be freed. May be NULL
380 if NumberOfChildren is 0.
382 @retval EFI_SUCCESS The device was stopped.
383 @retval EFI_DEVICE_ERROR The device could not be stopped due to a device error.
388 HttpBootIp4DxeDriverBindingStop (
389 IN EFI_DRIVER_BINDING_PROTOCOL
*This
,
390 IN EFI_HANDLE ControllerHandle
,
391 IN UINTN NumberOfChildren
,
392 IN EFI_HANDLE
*ChildHandleBuffer OPTIONAL
396 Tests to see if this driver supports a given controller. If a child device is provided,
397 it further tests to see if this driver supports creating a handle for the specified child device.
399 This function checks to see if the driver specified by This supports the device specified by
400 ControllerHandle. Drivers will typically use the device path attached to
401 ControllerHandle and/or the services from the bus I/O abstraction attached to
402 ControllerHandle to determine if the driver supports ControllerHandle. This function
403 may be called many times during platform initialization. In order to reduce boot times, the tests
404 performed by this function must be very small, and take as little time as possible to execute. This
405 function must not change the state of any hardware devices, and this function must be aware that the
406 device specified by ControllerHandle may already be managed by the same driver or a
407 different driver. This function must match its calls to AllocatePages() with FreePages(),
408 AllocatePool() with FreePool(), and OpenProtocol() with CloseProtocol().
409 Because ControllerHandle may have been previously started by the same driver, if a protocol is
410 already in the opened state, then it must not be closed with CloseProtocol(). This is required
411 to guarantee the state of ControllerHandle is not modified by this function.
413 @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
414 @param[in] ControllerHandle The handle of the controller to test. This handle
415 must support a protocol interface that supplies
416 an I/O abstraction to the driver.
417 @param[in] RemainingDevicePath A pointer to the remaining portion of a device path. This
418 parameter is ignored by device drivers, and is optional for bus
419 drivers. For bus drivers, if this parameter is not NULL, then
420 the bus driver must determine if the bus controller specified
421 by ControllerHandle and the child controller specified
422 by RemainingDevicePath are both supported by this
425 @retval EFI_SUCCESS The device specified by ControllerHandle and
426 RemainingDevicePath is supported by the driver specified by This.
427 @retval EFI_ALREADY_STARTED The device specified by ControllerHandle and
428 RemainingDevicePath is already being managed by the driver
430 @retval EFI_ACCESS_DENIED The device specified by ControllerHandle and
431 RemainingDevicePath is already being managed by a different
432 driver or an application that requires exclusive access.
433 Currently not implemented.
434 @retval EFI_UNSUPPORTED The device specified by ControllerHandle and
435 RemainingDevicePath is not supported by the driver specified by This.
439 HttpBootIp6DxeDriverBindingSupported (
440 IN EFI_DRIVER_BINDING_PROTOCOL
*This
,
441 IN EFI_HANDLE ControllerHandle
,
442 IN EFI_DEVICE_PATH_PROTOCOL
*RemainingDevicePath OPTIONAL
446 Starts a device controller or a bus controller.
448 The Start() function is designed to be invoked from the EFI boot service ConnectController().
449 As a result, much of the error checking on the parameters to Start() has been moved into this
450 common boot service. It is legal to call Start() from other locations,
451 but the following calling restrictions must be followed, or the system behavior will not be deterministic.
452 1. ControllerHandle must be a valid EFI_HANDLE.
453 2. If RemainingDevicePath is not NULL, then it must be a pointer to a naturally aligned
454 EFI_DEVICE_PATH_PROTOCOL.
455 3. Prior to calling Start(), the Supported() function for the driver specified by This must
456 have been called with the same calling parameters, and Supported() must have returned EFI_SUCCESS.
458 @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
459 @param[in] ControllerHandle The handle of the controller to start. This handle
460 must support a protocol interface that supplies
461 an I/O abstraction to the driver.
462 @param[in] RemainingDevicePath A pointer to the remaining portion of a device path. This
463 parameter is ignored by device drivers, and is optional for bus
464 drivers. For a bus driver, if this parameter is NULL, then handles
465 for all the children of Controller are created by this driver.
466 If this parameter is not NULL and the first Device Path Node is
467 not the End of Device Path Node, then only the handle for the
468 child device specified by the first Device Path Node of
469 RemainingDevicePath is created by this driver.
470 If the first Device Path Node of RemainingDevicePath is
471 the End of Device Path Node, no child handle is created by this
474 @retval EFI_SUCCESS The device was started.
475 @retval EFI_DEVICE_ERROR The device could not be started due to a device error.Currently not implemented.
476 @retval EFI_OUT_OF_RESOURCES The request could not be completed due to a lack of resources.
477 @retval Others The driver failded to start the device.
482 HttpBootIp6DxeDriverBindingStart (
483 IN EFI_DRIVER_BINDING_PROTOCOL
*This
,
484 IN EFI_HANDLE ControllerHandle
,
485 IN EFI_DEVICE_PATH_PROTOCOL
*RemainingDevicePath OPTIONAL
489 Stops a device controller or a bus controller.
491 The Stop() function is designed to be invoked from the EFI boot service DisconnectController().
492 As a result, much of the error checking on the parameters to Stop() has been moved
493 into this common boot service. It is legal to call Stop() from other locations,
494 but the following calling restrictions must be followed, or the system behavior will not be deterministic.
495 1. ControllerHandle must be a valid EFI_HANDLE that was used on a previous call to this
496 same driver's Start() function.
497 2. The first NumberOfChildren handles of ChildHandleBuffer must all be a valid
498 EFI_HANDLE. In addition, all of these handles must have been created in this driver's
499 Start() function, and the Start() function must have called OpenProtocol() on
500 ControllerHandle with an Attribute of EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER.
502 @param[in] This A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
503 @param[in] ControllerHandle A handle to the device being stopped. The handle must
504 support a bus specific I/O protocol for the driver
505 to use to stop the device.
506 @param[in] NumberOfChildren The number of child device handles in ChildHandleBuffer.
507 @param[in] ChildHandleBuffer An array of child handles to be freed. May be NULL
508 if NumberOfChildren is 0.
510 @retval EFI_SUCCESS The device was stopped.
511 @retval EFI_DEVICE_ERROR The device could not be stopped due to a device error.
516 HttpBootIp6DxeDriverBindingStop (
517 IN EFI_DRIVER_BINDING_PROTOCOL
*This
,
518 IN EFI_HANDLE ControllerHandle
,
519 IN UINTN NumberOfChildren
,
520 IN EFI_HANDLE
*ChildHandleBuffer OPTIONAL