NetworkPkg/HttpBootDxe/HttpBootDxe.h

   1 /** @file
   2   UEFI HTTP boot driver's private data structure and interfaces declaration.
   3
   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.
  10
  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.
  13
  14 **/
  15
  16 #ifndef __EFI_HTTP_BOOT_DXE_H__
  17 #define __EFI_HTTP_BOOT_DXE_H__
  18
  19 #include <Uefi.h>
  20
  21 #include <IndustryStandard/Http11.h>
  22 #include <IndustryStandard/Dhcp.h>
  23
  24 //
  25 // Libraries
  26 //
  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>
  40
  41 //
  42 // UEFI Driver Model Protocols
  43 //
  44 #include <Protocol/DriverBinding.h>
  45 #include <Protocol/ComponentName2.h>
  46 #include <Protocol/ComponentName.h>
  47
  48 //
  49 // Consumed Protocols
  50 //
  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 //
  62 // Produced Protocols
  63 //
  64 #include <Protocol/LoadFile.h>
  65 #include <Protocol/HttpBootCallback.h>
  66
  67 //
  68 // Consumed Guids
  69 //
  70 #include <Guid/HttpBootConfigHii.h>
  71
  72 //
  73 // Driver Version
  74 //
  75 #define HTTP_BOOT_DXE_VERSION  0xa
  76
  77 //
  78 // Standard Media Types defined in
  79 // http://www.iana.org/assignments/media-types
  80 //
  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"
  84
  85 //
  86 // Protocol instances
  87 //
  88 extern EFI_DRIVER_BINDING_PROTOCOL  gHttpBootDxeDriverBinding;
  89 extern EFI_COMPONENT_NAME2_PROTOCOL gHttpBootDxeComponentName2;
  90 extern EFI_COMPONENT_NAME_PROTOCOL  gHttpBootDxeComponentName;
  91
  92 //
  93 // Private data structure
  94 //
  95 typedef struct _HTTP_BOOT_PRIVATE_DATA      HTTP_BOOT_PRIVATE_DATA;
  96 typedef struct _HTTP_BOOT_VIRTUAL_NIC       HTTP_BOOT_VIRTUAL_NIC;
  97
  98 typedef enum  {
  99   ImageTypeEfi,
 100   ImageTypeVirtualCd,
 101   ImageTypeVirtualDisk,
 102   ImageTypeMax
 103 } HTTP_BOOT_IMAGE_TYPE;
 104
 105 //
 106 // Include files with internal function prototypes
 107 //
 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"
 115
 116 typedef union {
 117   HTTP_BOOT_DHCP4_PACKET_CACHE              Dhcp4;
 118   HTTP_BOOT_DHCP6_PACKET_CACHE              Dhcp6;
 119 } HTTP_BOOT_DHCP_PACKET_CACHE;
 120
 121 struct _HTTP_BOOT_VIRTUAL_NIC {
 122   UINT32                                    Signature;
 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;
 128 };
 129
 130 #define HTTP_BOOT_PRIVATE_DATA_FROM_CALLBACK_INFO(Callback) \
 131   CR ( \
 132   Callback, \
 133   HTTP_BOOT_PRIVATE_DATA, \
 134   CallbackInfo, \
 135   HTTP_BOOT_PRIVATE_DATA_SIGNATURE \
 136   )
 137
 138 #define HTTP_BOOT_PRIVATE_DATA_FROM_CALLBACK_PROTOCOL(CallbackProtocol) \
 139     CR ( \
 140     CallbackProtocol, \
 141     HTTP_BOOT_PRIVATE_DATA, \
 142     LoadFileCallback, \
 143     HTTP_BOOT_PRIVATE_DATA_SIGNATURE \
 144     )
 145
 146 struct _HTTP_BOOT_PRIVATE_DATA {
 147   UINT32                                    Signature;
 148   EFI_HANDLE                                Controller;
 149
 150   HTTP_BOOT_VIRTUAL_NIC                     *Ip4Nic;
 151   HTTP_BOOT_VIRTUAL_NIC                     *Ip6Nic;
 152
 153   //
 154   // Cousumed children
 155   //
 156   EFI_HANDLE                                Ip6Child;
 157   EFI_HANDLE                                Dhcp4Child;
 158   EFI_HANDLE                                Dhcp6Child;
 159   HTTP_IO                                   HttpIo;
 160   BOOLEAN                                   HttpCreated;
 161
 162   //
 163   // Consumed protocol
 164   //
 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;
 172
 173
 174   //
 175   // Produced protocol
 176   //
 177   EFI_LOAD_FILE_PROTOCOL                    LoadFile;
 178   EFI_DEVICE_PATH_PROTOCOL                  *DevicePath;
 179   UINT32                                    Id;
 180   EFI_HTTP_BOOT_CALLBACK_PROTOCOL           *HttpBootCallback;
 181   EFI_HTTP_BOOT_CALLBACK_PROTOCOL           LoadFileCallback;
 182
 183   //
 184   // Data for the default HTTP Boot callback protocol
 185   //
 186   UINT64                                    FileSize;
 187   UINT64                                    ReceivedSize;
 188   UINT32                                    Percentage;
 189
 190   //
 191   // HII callback info block
 192   //
 193   HTTP_BOOT_FORM_CALLBACK_INFO              CallbackInfo;
 194
 195   //
 196   // Mode data
 197   //
 198   BOOLEAN                                   UsingIpv6;
 199   BOOLEAN                                   Started;
 200   EFI_IP_ADDRESS                            StationIp;
 201   EFI_IP_ADDRESS                            SubnetMask;
 202   EFI_IP_ADDRESS                            GatewayIp;
 203   EFI_IP_ADDRESS                            ServerIp;
 204   UINT16                                    Port;
 205
 206   //
 207   // The URI string attempt to download through HTTP, may point to
 208   // the memory in cached DHCP offer, or to the memory in FilePathUri.
 209   //
 210   CHAR8                                     *BootFileUri;
 211   VOID                                      *BootFileUriParser;
 212   UINTN                                     BootFileSize;
 213   BOOLEAN                                   NoGateway;
 214   HTTP_BOOT_IMAGE_TYPE                      ImageType;
 215
 216   //
 217   // URI string extracted from the input FilePath parameter.
 218   //
 219   CHAR8                                     *FilePathUri;
 220   VOID                                      *FilePathUriParser;
 221
 222   //
 223   // Cached HTTP data
 224   //
 225   LIST_ENTRY                                CacheList;
 226
 227   //
 228   // Cached DHCP offer
 229   //
 230   // OfferIndex records the index of DhcpOffer[] buffer, and OfferCount records the num of each type of offer.
 231   //
 232   // It supposed that
 233   //
 234   //   OfferNum:    8
 235   //   OfferBuffer: [ProxyNameUri, DhcpNameUri, DhcpIpUri, ProxyNameUri, ProxyIpUri, DhcpOnly, DhcpIpUri, DhcpNameUriDns]
 236   //   (OfferBuffer is 0-based.)
 237   //
 238   // And assume that (DhcpIpUri is the first priority actually.)
 239   //
 240   //   SelectIndex:     5
 241   //   SelectProxyType: HttpOfferTypeProxyIpUri
 242   //   (SelectIndex is 1-based, and 0 means no one is selected.)
 243   //
 244   // So it should be
 245   //
 246   //                 DhcpIpUri  DhcpNameUriDns  DhcpDns  DhcpOnly  ProxyNameUri  ProxyIpUri  DhcpNameUri
 247   //   OfferCount:  [       2,              1,       0,        1,            2,          1,            1]
 248   //
 249   //   OfferIndex: {[       2,              7,       0,        5,            0,         *4,            1]
 250   //                [       6,              0,       0,        0,            3,          0,            0]
 251   //                [       0,              0,       0,        0,            0,          0,            0]
 252   //                ...                                                                                 ]}
 253   //   (OfferIndex is 0-based.)
 254   //
 255   //
 256   UINT32                                    SelectIndex;
 257   UINT32                                    SelectProxyType;
 258   HTTP_BOOT_DHCP_PACKET_CACHE               OfferBuffer[HTTP_BOOT_OFFER_MAX_NUM];
 259   UINT32                                    OfferNum;
 260   UINT32                                    OfferCount[HttpOfferTypeMax];
 261   UINT32                                    OfferIndex[HttpOfferTypeMax][HTTP_BOOT_OFFER_MAX_NUM];
 262 };
 263
 264 #define HTTP_BOOT_PRIVATE_DATA_SIGNATURE          SIGNATURE_32 ('H', 'B', 'P', 'D')
 265 #define HTTP_BOOT_VIRTUAL_NIC_SIGNATURE           SIGNATURE_32 ('H', 'B', 'V', 'N')
 266 #define HTTP_BOOT_PRIVATE_DATA_FROM_LOADFILE(a)   CR (a, HTTP_BOOT_PRIVATE_DATA, LoadFile, HTTP_BOOT_PRIVATE_DATA_SIGNATURE)
 267 #define HTTP_BOOT_PRIVATE_DATA_FROM_ID(a)         CR (a, HTTP_BOOT_PRIVATE_DATA, Id, HTTP_BOOT_PRIVATE_DATA_SIGNATURE)
 268 #define HTTP_BOOT_VIRTUAL_NIC_FROM_LOADFILE(a)    CR (a, HTTP_BOOT_VIRTUAL_NIC, LoadFile, HTTP_BOOT_VIRTUAL_NIC_SIGNATURE)
 269 extern EFI_LOAD_FILE_PROTOCOL               gHttpBootDxeLoadFile;
 270
 271 /**
 272   Tests to see if this driver supports a given controller. If a child device is provided,
 273   it further tests to see if this driver supports creating a handle for the specified child device.
 274
 275   This function checks to see if the driver specified by This supports the device specified by
 276   ControllerHandle. Drivers will typically use the device path attached to
 277   ControllerHandle and/or the services from the bus I/O abstraction attached to
 278   ControllerHandle to determine if the driver supports ControllerHandle. This function
 279   may be called many times during platform initialization. In order to reduce boot times, the tests
 280   performed by this function must be very small, and take as little time as possible to execute. This
 281   function must not change the state of any hardware devices, and this function must be aware that the
 282   device specified by ControllerHandle may already be managed by the same driver or a
 283   different driver. This function must match its calls to AllocatePages() with FreePages(),
 284   AllocatePool() with FreePool(), and OpenProtocol() with CloseProtocol().
 285   Because ControllerHandle may have been previously started by the same driver, if a protocol is
 286   already in the opened state, then it must not be closed with CloseProtocol(). This is required
 287   to guarantee the state of ControllerHandle is not modified by this function.
 288
 289   @param[in]  This                 A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
 290   @param[in]  ControllerHandle     The handle of the controller to test. This handle
 291                                    must support a protocol interface that supplies
 292                                    an I/O abstraction to the driver.
 293   @param[in]  RemainingDevicePath  A pointer to the remaining portion of a device path.  This
 294                                    parameter is ignored by device drivers, and is optional for bus
 295                                    drivers. For bus drivers, if this parameter is not NULL, then
 296                                    the bus driver must determine if the bus controller specified
 297                                    by ControllerHandle and the child controller specified
 298                                    by RemainingDevicePath are both supported by this
 299                                    bus driver.
 300
 301   @retval EFI_SUCCESS              The device specified by ControllerHandle and
 302                                    RemainingDevicePath is supported by the driver specified by This.
 303   @retval EFI_ALREADY_STARTED      The device specified by ControllerHandle and
 304                                    RemainingDevicePath is already being managed by the driver
 305                                    specified by This.
 306   @retval EFI_ACCESS_DENIED        The device specified by ControllerHandle and
 307                                    RemainingDevicePath is already being managed by a different
 308                                    driver or an application that requires exclusive access.
 309                                    Currently not implemented.
 310   @retval EFI_UNSUPPORTED          The device specified by ControllerHandle and
 311                                    RemainingDevicePath is not supported by the driver specified by This.
 312 **/
 313 EFI_STATUS
 314 EFIAPI
 315 HttpBootIp4DxeDriverBindingSupported (
 316   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
 317   IN EFI_HANDLE                   ControllerHandle,
 318   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath OPTIONAL
 319   );
 320
 321 /**
 322   Starts a device controller or a bus controller.
 323
 324   The Start() function is designed to be invoked from the EFI boot service ConnectController().
 325   As a result, much of the error checking on the parameters to Start() has been moved into this
 326   common boot service. It is legal to call Start() from other locations,
 327   but the following calling restrictions must be followed, or the system behavior will not be deterministic.
 328   1. ControllerHandle must be a valid EFI_HANDLE.
 329   2. If RemainingDevicePath is not NULL, then it must be a pointer to a naturally aligned
 330      EFI_DEVICE_PATH_PROTOCOL.
 331   3. Prior to calling Start(), the Supported() function for the driver specified by This must
 332      have been called with the same calling parameters, and Supported() must have returned EFI_SUCCESS.
 333
 334   @param[in]  This                 A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
 335   @param[in]  ControllerHandle     The handle of the controller to start. This handle
 336                                    must support a protocol interface that supplies
 337                                    an I/O abstraction to the driver.
 338   @param[in]  RemainingDevicePath  A pointer to the remaining portion of a device path.  This
 339                                    parameter is ignored by device drivers, and is optional for bus
 340                                    drivers. For a bus driver, if this parameter is NULL, then handles
 341                                    for all the children of Controller are created by this driver.
 342                                    If this parameter is not NULL and the first Device Path Node is
 343                                    not the End of Device Path Node, then only the handle for the
 344                                    child device specified by the first Device Path Node of
 345                                    RemainingDevicePath is created by this driver.
 346                                    If the first Device Path Node of RemainingDevicePath is
 347                                    the End of Device Path Node, no child handle is created by this
 348                                    driver.
 349
 350   @retval EFI_SUCCESS              The device was started.
 351   @retval EFI_DEVICE_ERROR         The device could not be started due to a device error.Currently not implemented.
 352   @retval EFI_OUT_OF_RESOURCES     The request could not be completed due to a lack of resources.
 353   @retval Others                   The driver failded to start the device.
 354
 355 **/
 356 EFI_STATUS
 357 EFIAPI
 358 HttpBootIp4DxeDriverBindingStart (
 359   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
 360   IN EFI_HANDLE                   ControllerHandle,
 361   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath OPTIONAL
 362   );
 363
 364 /**
 365   Stops a device controller or a bus controller.
 366
 367   The Stop() function is designed to be invoked from the EFI boot service DisconnectController().
 368   As a result, much of the error checking on the parameters to Stop() has been moved
 369   into this common boot service. It is legal to call Stop() from other locations,
 370   but the following calling restrictions must be followed, or the system behavior will not be deterministic.
 371   1. ControllerHandle must be a valid EFI_HANDLE that was used on a previous call to this
 372      same driver's Start() function.
 373   2. The first NumberOfChildren handles of ChildHandleBuffer must all be a valid
 374      EFI_HANDLE. In addition, all of these handles must have been created in this driver's
 375      Start() function, and the Start() function must have called OpenProtocol() on
 376      ControllerHandle with an Attribute of EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER.
 377
 378   @param[in]  This              A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
 379   @param[in]  ControllerHandle  A handle to the device being stopped. The handle must
 380                                 support a bus specific I/O protocol for the driver
 381                                 to use to stop the device.
 382   @param[in]  NumberOfChildren  The number of child device handles in ChildHandleBuffer.
 383   @param[in]  ChildHandleBuffer An array of child handles to be freed. May be NULL
 384                                 if NumberOfChildren is 0.
 385
 386   @retval EFI_SUCCESS           The device was stopped.
 387   @retval EFI_DEVICE_ERROR      The device could not be stopped due to a device error.
 388
 389 **/
 390 EFI_STATUS
 391 EFIAPI
 392 HttpBootIp4DxeDriverBindingStop (
 393   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
 394   IN EFI_HANDLE                   ControllerHandle,
 395   IN UINTN                        NumberOfChildren,
 396   IN EFI_HANDLE                   *ChildHandleBuffer OPTIONAL
 397   );
 398
 399 /**
 400   Tests to see if this driver supports a given controller. If a child device is provided,
 401   it further tests to see if this driver supports creating a handle for the specified child device.
 402
 403   This function checks to see if the driver specified by This supports the device specified by
 404   ControllerHandle. Drivers will typically use the device path attached to
 405   ControllerHandle and/or the services from the bus I/O abstraction attached to
 406   ControllerHandle to determine if the driver supports ControllerHandle. This function
 407   may be called many times during platform initialization. In order to reduce boot times, the tests
 408   performed by this function must be very small, and take as little time as possible to execute. This
 409   function must not change the state of any hardware devices, and this function must be aware that the
 410   device specified by ControllerHandle may already be managed by the same driver or a
 411   different driver. This function must match its calls to AllocatePages() with FreePages(),
 412   AllocatePool() with FreePool(), and OpenProtocol() with CloseProtocol().
 413   Because ControllerHandle may have been previously started by the same driver, if a protocol is
 414   already in the opened state, then it must not be closed with CloseProtocol(). This is required
 415   to guarantee the state of ControllerHandle is not modified by this function.
 416
 417   @param[in]  This                 A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
 418   @param[in]  ControllerHandle     The handle of the controller to test. This handle
 419                                    must support a protocol interface that supplies
 420                                    an I/O abstraction to the driver.
 421   @param[in]  RemainingDevicePath  A pointer to the remaining portion of a device path.  This
 422                                    parameter is ignored by device drivers, and is optional for bus
 423                                    drivers. For bus drivers, if this parameter is not NULL, then
 424                                    the bus driver must determine if the bus controller specified
 425                                    by ControllerHandle and the child controller specified
 426                                    by RemainingDevicePath are both supported by this
 427                                    bus driver.
 428
 429   @retval EFI_SUCCESS              The device specified by ControllerHandle and
 430                                    RemainingDevicePath is supported by the driver specified by This.
 431   @retval EFI_ALREADY_STARTED      The device specified by ControllerHandle and
 432                                    RemainingDevicePath is already being managed by the driver
 433                                    specified by This.
 434   @retval EFI_ACCESS_DENIED        The device specified by ControllerHandle and
 435                                    RemainingDevicePath is already being managed by a different
 436                                    driver or an application that requires exclusive access.
 437                                    Currently not implemented.
 438   @retval EFI_UNSUPPORTED          The device specified by ControllerHandle and
 439                                    RemainingDevicePath is not supported by the driver specified by This.
 440 **/
 441 EFI_STATUS
 442 EFIAPI
 443 HttpBootIp6DxeDriverBindingSupported (
 444   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
 445   IN EFI_HANDLE                   ControllerHandle,
 446   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath OPTIONAL
 447   );
 448
 449 /**
 450   Starts a device controller or a bus controller.
 451
 452   The Start() function is designed to be invoked from the EFI boot service ConnectController().
 453   As a result, much of the error checking on the parameters to Start() has been moved into this
 454   common boot service. It is legal to call Start() from other locations,
 455   but the following calling restrictions must be followed, or the system behavior will not be deterministic.
 456   1. ControllerHandle must be a valid EFI_HANDLE.
 457   2. If RemainingDevicePath is not NULL, then it must be a pointer to a naturally aligned
 458      EFI_DEVICE_PATH_PROTOCOL.
 459   3. Prior to calling Start(), the Supported() function for the driver specified by This must
 460      have been called with the same calling parameters, and Supported() must have returned EFI_SUCCESS.
 461
 462   @param[in]  This                 A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
 463   @param[in]  ControllerHandle     The handle of the controller to start. This handle
 464                                    must support a protocol interface that supplies
 465                                    an I/O abstraction to the driver.
 466   @param[in]  RemainingDevicePath  A pointer to the remaining portion of a device path.  This
 467                                    parameter is ignored by device drivers, and is optional for bus
 468                                    drivers. For a bus driver, if this parameter is NULL, then handles
 469                                    for all the children of Controller are created by this driver.
 470                                    If this parameter is not NULL and the first Device Path Node is
 471                                    not the End of Device Path Node, then only the handle for the
 472                                    child device specified by the first Device Path Node of
 473                                    RemainingDevicePath is created by this driver.
 474                                    If the first Device Path Node of RemainingDevicePath is
 475                                    the End of Device Path Node, no child handle is created by this
 476                                    driver.
 477
 478   @retval EFI_SUCCESS              The device was started.
 479   @retval EFI_DEVICE_ERROR         The device could not be started due to a device error.Currently not implemented.
 480   @retval EFI_OUT_OF_RESOURCES     The request could not be completed due to a lack of resources.
 481   @retval Others                   The driver failded to start the device.
 482
 483 **/
 484 EFI_STATUS
 485 EFIAPI
 486 HttpBootIp6DxeDriverBindingStart (
 487   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
 488   IN EFI_HANDLE                   ControllerHandle,
 489   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath OPTIONAL
 490   );
 491
 492 /**
 493   Stops a device controller or a bus controller.
 494
 495   The Stop() function is designed to be invoked from the EFI boot service DisconnectController().
 496   As a result, much of the error checking on the parameters to Stop() has been moved
 497   into this common boot service. It is legal to call Stop() from other locations,
 498   but the following calling restrictions must be followed, or the system behavior will not be deterministic.
 499   1. ControllerHandle must be a valid EFI_HANDLE that was used on a previous call to this
 500      same driver's Start() function.
 501   2. The first NumberOfChildren handles of ChildHandleBuffer must all be a valid
 502      EFI_HANDLE. In addition, all of these handles must have been created in this driver's
 503      Start() function, and the Start() function must have called OpenProtocol() on
 504      ControllerHandle with an Attribute of EFI_OPEN_PROTOCOL_BY_CHILD_CONTROLLER.
 505
 506   @param[in]  This              A pointer to the EFI_DRIVER_BINDING_PROTOCOL instance.
 507   @param[in]  ControllerHandle  A handle to the device being stopped. The handle must
 508                                 support a bus specific I/O protocol for the driver
 509                                 to use to stop the device.
 510   @param[in]  NumberOfChildren  The number of child device handles in ChildHandleBuffer.
 511   @param[in]  ChildHandleBuffer An array of child handles to be freed. May be NULL
 512                                 if NumberOfChildren is 0.
 513
 514   @retval EFI_SUCCESS           The device was stopped.
 515   @retval EFI_DEVICE_ERROR      The device could not be stopped due to a device error.
 516
 517 **/
 518 EFI_STATUS
 519 EFIAPI
 520 HttpBootIp6DxeDriverBindingStop (
 521   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
 522   IN EFI_HANDLE                   ControllerHandle,
 523   IN UINTN                        NumberOfChildren,
 524   IN EFI_HANDLE                   *ChildHandleBuffer OPTIONAL
 525   );
 526 #endif