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   UINT64                                    FileSize;
 183   UINT64                                    ReceivedSize;
 184   UINT32                                    Percentage;
 185
 186   //
 187   // HII callback info block
 188   //
 189   HTTP_BOOT_FORM_CALLBACK_INFO              CallbackInfo;
 190
 191   //
 192   // Mode data
 193   //
 194   BOOLEAN                                   UsingIpv6;
 195   BOOLEAN                                   Started;
 196   EFI_IP_ADDRESS                            StationIp;
 197   EFI_IP_ADDRESS                            SubnetMask;
 198   EFI_IP_ADDRESS                            GatewayIp;
 199   EFI_IP_ADDRESS                            ServerIp;
 200   UINT16                                    Port;
 201
 202   //
 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.
 205   //
 206   CHAR8                                     *BootFileUri;
 207   VOID                                      *BootFileUriParser;
 208   UINTN                                     BootFileSize;
 209   BOOLEAN                                   NoGateway;
 210   HTTP_BOOT_IMAGE_TYPE                      ImageType;
 211
 212   //
 213   // URI string extracted from the input FilePath parameter.
 214   //
 215   CHAR8                                     *FilePathUri;
 216   VOID                                      *FilePathUriParser;
 217
 218   //
 219   // Cached HTTP data
 220   //
 221   LIST_ENTRY                                CacheList;
 222
 223   //
 224   // Cached DHCP offer
 225   //
 226   // OfferIndex records the index of DhcpOffer[] buffer, and OfferCount records the num of each type of offer.
 227   //
 228   // It supposed that
 229   //
 230   //   OfferNum:    8
 231   //   OfferBuffer: [ProxyNameUri, DhcpNameUri, DhcpIpUri, ProxyNameUri, ProxyIpUri, DhcpOnly, DhcpIpUri, DhcpNameUriDns]
 232   //   (OfferBuffer is 0-based.)
 233   //
 234   // And assume that (DhcpIpUri is the first priority actually.)
 235   //
 236   //   SelectIndex:     5
 237   //   SelectProxyType: HttpOfferTypeProxyIpUri
 238   //   (SelectIndex is 1-based, and 0 means no one is selected.)
 239   //
 240   // So it should be
 241   //
 242   //                 DhcpIpUri  DhcpNameUriDns  DhcpDns  DhcpOnly  ProxyNameUri  ProxyIpUri  DhcpNameUri
 243   //   OfferCount:  [       2,              1,       0,        1,            2,          1,            1]
 244   //
 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]
 248   //                ...                                                                                 ]}
 249   //   (OfferIndex is 0-based.)
 250   //
 251   //
 252   UINT32                                    SelectIndex;
 253   UINT32                                    SelectProxyType;
 254   HTTP_BOOT_DHCP_PACKET_CACHE               OfferBuffer[HTTP_BOOT_OFFER_MAX_NUM];
 255   UINT32                                    OfferNum;
 256   UINT32                                    OfferCount[HttpOfferTypeMax];
 257   UINT32                                    OfferIndex[HttpOfferTypeMax][HTTP_BOOT_OFFER_MAX_NUM];
 258 };
 259
 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;
 266
 267 /**
 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.
 270
 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.
 284
 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
 295                                    bus driver.
 296
 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
 301                                    specified by This.
 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.
 308 **/
 309 EFI_STATUS
 310 EFIAPI
 311 HttpBootIp4DxeDriverBindingSupported (
 312   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
 313   IN EFI_HANDLE                   ControllerHandle,
 314   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath OPTIONAL
 315   );
 316
 317 /**
 318   Starts a device controller or a bus controller.
 319
 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.
 329
 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
 344                                    driver.
 345
 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.
 350
 351 **/
 352 EFI_STATUS
 353 EFIAPI
 354 HttpBootIp4DxeDriverBindingStart (
 355   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
 356   IN EFI_HANDLE                   ControllerHandle,
 357   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath OPTIONAL
 358   );
 359
 360 /**
 361   Stops a device controller or a bus controller.
 362
 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.
 373
 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.
 381
 382   @retval EFI_SUCCESS           The device was stopped.
 383   @retval EFI_DEVICE_ERROR      The device could not be stopped due to a device error.
 384
 385 **/
 386 EFI_STATUS
 387 EFIAPI
 388 HttpBootIp4DxeDriverBindingStop (
 389   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
 390   IN EFI_HANDLE                   ControllerHandle,
 391   IN UINTN                        NumberOfChildren,
 392   IN EFI_HANDLE                   *ChildHandleBuffer OPTIONAL
 393   );
 394
 395 /**
 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.
 398
 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.
 412
 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
 423                                    bus driver.
 424
 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
 429                                    specified by This.
 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.
 436 **/
 437 EFI_STATUS
 438 EFIAPI
 439 HttpBootIp6DxeDriverBindingSupported (
 440   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
 441   IN EFI_HANDLE                   ControllerHandle,
 442   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath OPTIONAL
 443   );
 444
 445 /**
 446   Starts a device controller or a bus controller.
 447
 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.
 457
 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
 472                                    driver.
 473
 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.
 478
 479 **/
 480 EFI_STATUS
 481 EFIAPI
 482 HttpBootIp6DxeDriverBindingStart (
 483   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
 484   IN EFI_HANDLE                   ControllerHandle,
 485   IN EFI_DEVICE_PATH_PROTOCOL     *RemainingDevicePath OPTIONAL
 486   );
 487
 488 /**
 489   Stops a device controller or a bus controller.
 490
 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.
 501
 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.
 509
 510   @retval EFI_SUCCESS           The device was stopped.
 511   @retval EFI_DEVICE_ERROR      The device could not be stopped due to a device error.
 512
 513 **/
 514 EFI_STATUS
 515 EFIAPI
 516 HttpBootIp6DxeDriverBindingStop (
 517   IN EFI_DRIVER_BINDING_PROTOCOL  *This,
 518   IN EFI_HANDLE                   ControllerHandle,
 519   IN UINTN                        NumberOfChildren,
 520   IN EFI_HANDLE                   *ChildHandleBuffer OPTIONAL
 521   );
 522 #endif